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

The description goes well beyond the annotations, which only say readOnlyHint=false and destructiveHint=false. It discloses that the save is reversible, makes zero provider calls, creates no external account, activates nothing, moves no money, and is idempotent via exact replay. These are concrete behavioral details an agent needs before invoking the tool.

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 first two sentences are high-value and front-loaded, but the description includes generic boilerplate sections like Canonicality, Idempotency, and Confirmation boundary. The confirmation-boundary sentence in particular lists many unrelated action types and does not earn its place for this specific 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?

The description covers prerequisites, exact idempotent behavior, side effects, next-step guidance, and what remains out of scope. Since there is no output schema, mentioning that the agent should trust returned actual_tool_output and context_engineering is helpful, though it does not describe the draft's return payload in detail.

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 only 20%, and the description partially compensates by naming the accepted categories: company, route key, USD, and idempotency key, while explicitly excluding credentials, provider IDs, bank/card data, and production settings. However, it does not explain individual parameters such as routeKey semantics, companyId optionality, or the _corply_context object beyond what the schema already says.

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 opens with a specific verb and resource: 'Create or exactly replay one local sandbox merchant-route draft for Corply's own payment pipeline.' It clearly separates this draft-creation action from activation, provider onboarding, and live enablement, and the 'local sandbox' qualifier distinguishes it from production-oriented sibling tools.

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 states clear usage context: this is for a sandbox merchant-route draft only, cannot accept production settings, requires authenticated active organization access, and should be followed by get_payment_pipeline_status. It also lists actions that are NOT this tool's job. However, it does not explicitly name alternative creation/onboarding sibling tools for direct comparison.

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