Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and it delivers the single most important trait: this is a read-only preview that writes no files, which is exactly the side-effect information an agent needs before calling. It still omits auth/credential needs and error behavior on invalid specs, keeping it below 5.

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, no filler, and the core guarantee ('without writing any files') plus the intended use are front-loaded before any elaboration.

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 7-param, all-optional tool with no output schema and no annotations, the description covers purpose, the non-destructive guarantee, and the intended workflow. It would be stronger if it sketched the preview's return shape, since no output schema exists to do so.

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?

Schema description coverage is 100% and all 7 parameters carry inline descriptions, so the schema does the heavy lifting. The description only hints at filtering via 'curate (filter/inspect)' without adding syntax or semantics beyond what the schema already documents.

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 ('Parse') plus resource ('OpenAPI or Postman spec') and the output ('preview the MCP tools that would be generated'). The clause 'without writing any files' implicitly distinguishes it from generate_mcp_server, so an agent can route correctly without opening either schema.

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?

'Use this to curate (filter/inspect) before generating' gives a clear usage context and implies the workflow with generate_mcp_server. It does not name the alternative explicitly or state exclusions, so it stops short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does well: it discloses idempotency, that already-present operations are skipped, and that hand-edited tool files are preserved unless force is set. It omits the return/report shape and any permission or failure behavior, but the core mutation semantics are unusually well covered.

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?

Three sentences, front-loaded with the action and precondition, then the idempotency guarantees. The final sentence is mild rationale but is short and doubles as usage context, so nothing is wasted.

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 an 11-parameter mutation tool with no annotations and no output schema, the description covers purpose, preconditions, and the key destructive/preservation behavior. It stops short of describing what the call returns or how partial failures are reported, which is the main remaining gap.

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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by tying projectDir to the .mcp-translator.json manifest and clarifying that force overwrites hand-edited files specifically, which the schema's generic 'Overwrite existing tool files' does not convey.

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 (append) and resource (operations from another spec) and scopes it to 'an already-generated project (identified by its .mcp-translator.json manifest)', which cleanly separates it from the sibling generate_mcp_server that creates new projects.

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 closing sentence 'Enables aggregating multiple APIs into one MCP server' implies the intended scenario, and the existing-project precondition is stated. However, no alternative is named and no when-not condition is given (e.g. 'use generate_mcp_server for a fresh project'), so usage must be inferred.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It does disclose two useful behavioral facts: the tool writes files to outputDir and will refuse/require force for a non-empty directory, which signals destructiveness. But it omits permissions, network access, whether generation is deterministic, and what is actually produced.

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?

Three tight, front-loaded sentences with no filler; the core action comes first and the force caveat last. It is efficient, though arguably undersized for a 16-parameter generator, and the 'TypeScript' framing wastes a few words on an inaccuracy.

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 complex 16-parameter generator with no output schema, the description is thin: it never says what artifacts land in outputDir or how spec/specPath/methods/pathGlob interact with a spec that has no security schemes. Low parameter count relative to schema richness is not the issue here; the missing behavioral context is.

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?

Schema description coverage is 94% across 16 parameters, so the schema already documents nearly everything and the baseline is 3. The description reinforces only outputDir and force and adds no meaning for the higher-leverage options (spec vs specPath, auth, transport, language, pythonVariant).

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 gives a specific verb+resource ('Generate a complete, runnable ... MCP server project') plus the accepted input formats (OpenAPI or Postman), which is enough to separate it from siblings like extend_mcp_server and analyze_spec. However, it hardcodes 'TypeScript' even though the schema supports language: python, so the stated scope contradicts the tool's actual capability.

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 only usage rule given is 'Use force to overwrite a non-empty directory,' which is really a parameter hint rather than when-to-use guidance. Nothing tells the agent when to pick this over analyze_spec (inspect first) or extend_mcp_server (modify an existing project), leaving the sibling routing to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It does disclose the categories of information returned, which is real content rather than tautology, but it says nothing about side-effect freedom, whether the answer is static or environment-dependent, or how the result is structured (and there is no output schema to fall back on).

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?

A single front-loaded sentence with no filler; every clause names a distinct category of supported capability. Appropriate size for a zero-argument tool.

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 no-parameter, no-annotation, no-output-schema informational tool, the sentence effectively doubles as a return-value summary, which is largely sufficient. It could be tightened only by stating when to call it relative to the spec-analysis and server-generation siblings.

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 tool takes zero parameters, so the baseline is 4; the schema is empty and there is nothing further for the description to clarify.

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 (Report) and a concrete resource set (input formats, auth schemes, transports, limits), so an agent knows this is a capability/introspection tool. It does not, however, differentiate itself from the sibling tools (analyze_spec, generate_mcp_server, extend_mcp_server), leaving the boundary between 'report capabilities' and 'analyze a spec' to inference.

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?

Usage is only implied: an agent can guess this is the tool to call to discover what the server supports, but there is no explicit trigger, no ordering guidance (e.g., call before generate_mcp_server), and no statement of when a sibling is the better choice.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.