erup-mcp demonstrates solid tool definition quality with consistent naming, present schemas, and reasonable descriptions. All 8 tools follow verb_noun convention (search_, get_, list_). Input schemas are complete with proper JSON Schema structure including types, enums, and constraints. However, several parameter descriptions lack depth, and output schemas are not explicitly documented in the source code. Error handling is present but generic. No tool annotations (readOnlyHint, destructiveHint, idempotentHint) are visible despite all tools being read-only operations. Parameter descriptions average ~30-40 chars vs. production baseline of 72 chars.

• Add formal output schema documentation for all tools. Document the structure of response objects returned by each tool, including field names, types, and semantic meaning. This enables LLMs to plan multi-step workflows.
• Expand parameter descriptions to 50-150 characters. Include guidance on when each parameter is useful, valid ranges/formats beyond enums, and parameter interactions. E.g., for date_from/date_to in search_entities: 'ISO 8601 date (YYYY-MM-DD). If set without date_to, defaults to today. Used to filter entities registered within this date range.'
• Add readOnlyHint: true to all tool definitions in schema. All 8 tools are read-only queries; explicit annotation helps LLMs determine safe retry and caching strategies.
• Implement structured error responses in client.ts error handling. Categorize errors: retryable (network timeout, rate limit), user-fixable (invalid entity_id, invalid date format), fatal (malformed API response). Include suggested recovery actions.
• Add discovery guidance to tool descriptions. E.g., get_entity should note: 'Typically called after search_entities(), requires an entity_id from search results.' This guides agents toward efficient call sequences.
• Document pagination behavior. search_entities, get_entity_agents, get_entity_branches accept limit/offset. Clarify: Are results sorted? What is the default sort order? Does limit apply to each page? What is the maximum limit?
• Add 'schema' metadata block to each tool definition showing example response structure. E.g., get_entity returns: {entity_id: number, name: string, nip: string, knf_number: string, entity_type: string, status: string, ...}