describe_operation

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

Annotations already mark the tool as read-only and open-world, so no side-effect warning is needed. The description adds valuable behavioral detail beyond those annotations: it discloses that $refs are inlined and that repeated schemas are represented once with a {'$see': name} placeholder, which meaningfully informs an agent about the output shape.

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 with no filler. The first sentence states the core function, and the second adds a necessary, non-obvious detail about schema deduplication. Fully front-loaded.

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?

The description adequately covers the output behavior for a read-only schema-inspection tool, especially given the annotations. However, it does not specify accepted method values or connect to list_operations as the source of valid method/path pairs, leaving a small but real gap for correct invocation.

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 schema documents path well with an explicit format example ('/team/{id}'), but method has no description, no enum, and no format example. Since schema description coverage is only 50%, the tool description needed to compensate by explaining what values method accepts, but it does not.

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 ('Show') and resource ('an operation's parameters and JSON request body schema'), which clearly distinguishes it from execution tools like call_read and enumeration tools like list_operations. The $ref inlining detail further sharpens the purpose.

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 read-only inspection purpose makes it clear this is likely used before invoking a call tool, but the description gives no explicit when-to-use guidance, exclusions, or alternative routing. Usage context is implied rather than stated.

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