Treasury MCP exhibits significant definition quality gaps. Tool descriptions are present but lack LLM-optimization guidance (e.g., catalog_search description is 400+ chars, exceeds 200-char baseline). Input schemas use Zod but lack complete type coverage and parameter descriptions are sparse or missing. The execute, graphql_execute, and sparql_execute tools accept arbitrary code strings with minimal validation guidance. No output schemas are documented. Error handling is absent, no recovery guidance, categorization, or actionable error messages. Security concerns: execute tools run arbitrary code in sandboxed V8 but lack clear permission/scope declarations. Tool composition is weak: catalog_search and search overlap functionally, creating LLM disambiguation burden.

• Consolidate catalog_search and search into a single unified search tool with a 'mode' parameter (catalog vs spec) to eliminate LLM disambiguation burden.
• Document output schemas for all tools. For catalog_search, specify ApiEndpoint structure (fields: path, method, parameters, description, category). For execute/graphql_execute/sparql_execute, define return type contract (e.g., {result: any, staged?: {uri, query_hint}, error?: {code, message, retryable}})
• Add input validation and format guidance to code-execution tools. Example: 'code must be valid JavaScript; use api.get(path, params) for REST calls; return results as JSON-serializable objects. Errors: wrap in try-catch and return {error: message}.'
• Implement error handling with recovery guidance. Pattern: {error: {code, message, retryable, nextSteps}}. Example: 'Invalid endpoint path. Available paths: [list]. Call search() to discover endpoints.'
• Add explicit permission/scope declarations to execute tools. Document: 'Requires: code_execution, api_access. Audit: all calls logged with user, code snippet, timestamp, result. Rate limit: 10 calls/min per user.'