mcp-nexus exposes 7 tools for managing upstream tool catalogs and endpoint bindings. Tool names follow verb_noun convention (PullTools, ListEndpointTools, BindTool, etc.), which is positive. However, critical gaps undermine quality: (1) Input schemas are inferred from Go struct tags in the code but NOT explicitly visible as JSON Schema definitions in the tool registration layer. (2) Descriptions are present but generic and lack LLM-optimization guidance (e.g., 'Bind a tool from global catalog to an endpoint' does not explain WHEN to use it vs ListBoundTools). (3) No parameter descriptions visible in the source, only struct field names. (4) No documented output schemas. (5) Error handling returns raw database errors ('upsert update failed: ' + err.Error()) without recovery guidance. (6) No evidence of idempotency, pagination, or result limits. Per-tool scores average 42; most tools score 35-50 due to missing schema visibility and weak descriptions.

• Explicitly define JSON Schema for all tool inputs. For each tool, create a schema object with type='object', properties with type and description for each parameter, and required array. Example: `{"type": "object", "properties": {"upstream_tool_id": {"type": "integer", "description": "The numeric ID of the upstream tool to bind. Must exist in the global catalog."}}, "required": ["upstream_tool_id"]}`.
• Expand tool descriptions to 100-200 characters. Include WHAT the tool does, WHEN to use it (vs similar tools), and any prerequisites. Example: 'Bind a single tool from the global catalog to an endpoint. Use this after PullTools to make upstream tools available to an endpoint. Tool names must be unique within the endpoint.'
• Add parameter descriptions to all inputs. For each parameter, explain its purpose, valid range/format, and any constraints. Example: `upstream_tool_id: 'The numeric ID of the upstream tool to bind. Must reference an existing UpstreamTool record.'`
• Document output schemas for all tools. Declare the response structure (object fields, types, required fields). Example: PullTools returns `{"pulled": integer, "errors": [string]}`. ListEndpointTools returns `{"tools": [{"id": integer, "name": string, "description": string, "schema": object}]}`.
• Improve error messages with recovery guidance. Replace 'upsert update failed: <raw error>' with 'Failed to update tool metadata. Verify the upstream tool exists and the database is accessible. Retry with the same upstream_tool_id.' Categorize errors as retryable vs user-fixable.

Inferred effective spec: <=2025-11-25.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry