invoke_operation

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

The description discloses a key behavioral requirement: writes require explicit confirm=true. However, with no annotations, it does not explain other behavioral aspects like idempotency, side effects, or error responses, leaving the agent partially informed.

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 two concise sentences with essential information front-loaded. Every word earns its place, and the critical safety note about writes requiring confirmation is clearly stated.

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 provides a minimal viable explanation for a generic invoke tool, especially since an output schema exists. However, it lacks guidance on how parameters like body, query, and path_params relate to the operation_id, and does not reference how to discover operation details via sibling tools.

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?

With 0% schema description coverage, the description must compensate for all 5 parameters, but it only adds meaning to confirm by clarifying it is required for writes. Other parameters (operation_id, body, query, path_params) receive no explanatory context beyond their raw schema definitions.

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 uses a specific verb 'Call' with a resource 'documented explorer operation', clearly indicating this tool executes an operation. This distinguishes it from sibling tools list_operations and get_operation, which are about discovery and retrieval, not execution.

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 description implies usage for executing operations, contrasting with list/get siblings, but does not explicitly state when to use this tool versus alternatives. The confirm=true instruction gives guidance for write operations but no exclusions or alternative scenarios.

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