Retrieve the OpenAPI specification for a selected service to inspect available endpoints, with options to list paths, clear cached specs, and target local or QA environments.
Fetch OpenAPI spec for a service. Services: os-order
| Name | Required | Description | Default |
|---|---|---|---|
| service | Yes | Service name | |
| listPaths | No | ||
| clearCache | No | ||
| environment | No | Target environment | qa |
Changes observed during successful MCP inspections.
v1.0.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It does not mention caching behavior, the meaning of clearCache, whether the fetched spec is the full spec or only paths, or any environment-specific behavior beyond the schema's parameter description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded, with no filler or redundant phrasing. The service list is useful, though it could have been integrated more naturally.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with four parameters, 50% schema description coverage, no annotations, and no output schema, the description is incomplete. It omits key behavioral details such as caching, listPaths behavior, and what the returned OpenAPI spec looks like.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds little beyond the schema: 'Services: os-order' duplicates the enum value for the service parameter. The listPaths and clearCache parameters have no description anywhere, and the tool description does not compensate for those gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Fetch OpenAPI spec for a service,' and further narrows scope with 'Services: os-order.' This clearly differentiates it from siblings like call_api and list_services, which serve adjacent but distinct purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this tool versus alternatives such as call_api or list_services. The description tells the agent what it does, but not when it is the right choice or when another sibling should be preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.