The ebay-mcp server defines 15 tools with explicit schemas and descriptions visible in src/mcp-server/index.ts. All tools have descriptive names starting with action verbs (ebay_create_, ebay_search_, etc.) and contain inline JSON Schema definitions. However, critical gaps exist: (1) Output schemas are completely absent, no documentation of what these tools return, forcing LLMs to guess response structure. (2) Many parameter descriptions lack actionable constraints (e.g., 'categoryId: eBay category ID' provides no format guidance; valid IDs could be numeric, alphanumeric, or hierarchical). (3) No error handling guidance, tools provide no recovery instructions when calls fail (invalid category, SKU conflicts, auth failures). (4) Security concern: config loads EBAY_OAUTH_APPLICATION_TOKEN as a fallback refresh token, but this pattern is not articulated in the tool definitions or parameter safety notes. (5) Most tools have generic descriptions (50-100 chars) that do not explain WHEN to use them vs. similar tools (e.g., ebay_create_offer vs. ebay_publish_offer, the distinction is unclear without reading eBay API docs). The schemas themselves are well-formed with proper types and required arrays, bringing the score into the 'fair' range. Baseline comparison: 194 chars is average for tool descriptions; most here are 80-120, which is acceptable but brief and lacks nuance.

• Add explicit output schemas for every tool. Document response fields, types, and which IDs are returned for chaining (e.g., offerId from create_offer should be used in publish_offer). Use the same format as inputSchema.
• Convert example values in descriptions to enum constraints. Replace 'condition: (e.g., NEW, LIKE_NEW, USED_EXCELLENT)' with a proper enum: ['NEW', 'LIKE_NEW', 'USED_EXCELLENT'].
• Expand tool descriptions to 150 - 250 chars with WHEN/WHY context. E.g., 'Create or update an inventory item in eBay, the first step before creating an offer. Required: sku (unique identifier), title, description, condition, quantity. Returns sku and inventory details for use in ebay_create_offer.'
• Add error recovery guidance to each tool description or in a separate 'errors' field. E.g., 'On SKU conflict, the tool returns error code 3145. Retry with a different SKU or call ebay_search_by_keyword to check existing listings.'
• Define nested schemas for complex parameters. For categoryTypes and shippingOptions, add a $defs section in inputSchema or document the exact object structure required.
• Add pagination parameters (limit, offset/cursor) to search tools with explicit caps. E.g., 'Max limit 100; returns total count and next_cursor for pagination. Default limit: 20.'
• Document per-tool scopes and permissions. Add a 'permissions' field to each tool definition listing required OAuth scopes (e.g., 'sell.inventory:rw', 'sell.fulfillment:rw').
• Mark idempotent tools with a note in the description or via toolAnnotation idempotentHint. E.g., 'This call is idempotent: repeated invocations with the same SKU update the item in place.' For create/update tools that may conflict, add dry-run or upsert guidance.