Imports local OpenAPI/Swagger, Postman v2, or WSDL files as untrusted planning data and catalogs operations for test planning without calling endpoints or following external references.
Import a local OpenAPI/Swagger JSON/YAML, Postman v2 collection or WSDL XML as untrusted planning data. Catalogs operations; never calls endpoints or follows external references.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
Changes observed during successful MCP inspections.
v0.4.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false and destructiveHint=true, but the description adds substantive context the annotations don't: input is treated as untrusted planning data, endpoints are never invoked, and external $refs are not followed. This is meaningful safety information. The mild tension with openWorldHint=true (description insists on local-only, no external resolution) is a narrowing rather than a contradiction, and the description never explains what state is written or what 'catalogs' produces.
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?
Two sentences, zero filler, with the capability and the key safety guarantee both front-loaded. Every clause carries information an agent needs.
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 one-parameter import tool with annotations present and no output schema, the description covers formats, trust model, and side-effect boundaries. It leaves out what gets returned or where the cataloged result is stored, which an agent would want before deciding what to do next.
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?
Only one parameter, and schema description coverage is 0% — 'path' has no documented meaning in the schema. The description partially compensates by implying a local file path for one of the listed spec formats, but it doesn't say whether relative or absolute paths are accepted, encoding expectations, or size limits.
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?
States a specific verb (import) and resource (API documents) plus the exact accepted formats: OpenAPI/Swagger JSON/YAML, Postman v2, WSDL XML. 'Catalogs operations; never calls endpoints' distinguishes it from the sibling api_document_read and from api_request.
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?
The phrase 'local ... as untrusted planning data' clearly establishes the context of use and implicitly excludes remote fetching or live API interaction. However, it never names the alternative siblings (api_document_read, requirements_import) or states when to prefer them, which would be needed for a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.