toolgraph exposes 3 tools for MCP server introspection and graph execution. Tool naming is clear (introspect, run, health), but descriptions lack depth and parameter documentation is sparse. The 'run' tool has a complex nested schema (graph with nodes/edges) but lacks field-level descriptions. The 'introspect' tool accepts a 'connection' object with 6 properties, but only 3 are documented as required; the 'secrets' object structure is vague. No error handling guidance, no output schema documentation, and no indication of idempotency or side effects. Descriptions are 10-50 chars, below the 50-200 char baseline for LLM-optimized tools.

• Expand tool descriptions to 50-200 characters. For introspect: 'Connects to an MCP server (HTTP or stdio) and retrieves all available tools with their JSON Schemas. Use this to discover what tools a server exposes before building a graph. Returns tool names, descriptions, and input/output schemas.'
• Document every parameter. For 'connection.secrets.headers', specify: 'Custom HTTP headers for authentication. Include Authorization header if the server requires it. E.g., {"Authorization": "Bearer token"}. Headers are never logged or exposed in responses.'
• Add output schema documentation. For introspect, document: 'Returns {tools: [{name, description, inputSchema, outputSchema}]}'. For run, document: 'Returns {success: boolean, results: {[nodeId]: any}, errors: {[nodeId]: string}}'.
• Add error recovery guidance. For introspect: 'If connection fails, verify the server URL is reachable and the transport type matches (http vs stdio). If authentication fails, check the Authorization header in secrets.'
• Clarify side effects. For run: 'This tool executes the graph and may trigger side effects in connected MCP servers (e.g., creating resources, sending messages). Execution is not idempotent, repeated calls with the same graph may produce duplicate results.'