gridctl exposes a single HTTP-accessible MCP tool 'tools search' with partial schema documentation. The tool has a clear action verb (search) and reasonable description (~120 chars), but parameter documentation is inconsistent: 'query' and 'limit' are well-described, while 'as' (scope label) and 'timeout' (request timeout) lack guidance on typical values or constraints. The 'format' parameter's enum is documented but restricted to 'json' with no rationale. Output schema is completely undocumented, the tool returns tool definitions but callers cannot predict the response structure. Error handling is minimal: no recovery guidance, no classification of retryable vs fatal errors. The tool is READ_ONLY (safe to retry) and follows single-responsibility design (search only, no side effects), but lacks idempotence markers and lacks per-parameter type validation hints.

• Document the output schema: specify that the response is a list of tool objects, each with fields (name: string, description: string, inputSchema: object, risk: enum). Make it clear what agents will receive so they can extract tool names and descriptions for discovery.
• Add actionable parameter constraints: for 'timeout', specify format (e.g., '60s', '5m') and max (e.g., '5m'); for 'as', explain valid formats and typical values (e.g., 'user id', 'session identifier', leave empty if not applicable).
• Add error recovery guidance: document common failure modes (malformed query, timeout, gateway unavailable) and whether each is retryable or requires user intervention.
• Add tool annotations: include 'readOnlyHint: true' and 'idempotentHint: true' in the schema to signal safety and enable agent optimizations.
• Add min/max constraints to schema: use JSON Schema 'minimum' and 'maximum' properties for 'limit' (1 and 200) so LLM input is validated syntactically before runtime.
• Clarify format parameter: either remove it (if JSON is the only option) or document why it exists and when other formats may be supported.