paydirt_setup

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

The description adds critical behavioral details not present in annotations: it never opens a browser or blocks, returns authorization_url plus finish arguments on first call, and returns pending/expired/complete contract on subsequent calls. No contradiction with existing annotations.

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 no fluff. Every sentence earns its place: when to use, what happens in each mode, and what it does not do.

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?

Despite having 8 parameters, the description is complete for the tool's purpose: it defines the compatibility scope, alternative tools, dual-mode behavior, and non-blocking guarantee. The presence of an output schema means return values need not be described.

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 already covers all 8 parameters with 100% description coverage, so baseline is 3. The description adds meaningful semantic detail for session_id, explaining that its presence changes the call to behave like paydirt_finish_setup. This extra context justifies a 4.

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 clearly identifies this as a compatibility wrapper for older clients, distinct from the newer paydirt_begin_setup and paydirt_finish_setup tools. It specifies the core behavior (start setup or check status) and the title 'Compatibility' reinforces 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?

It explicitly states when to use the tool ('when an older client expects the single setup tool'), when not to use it ('New agents should prefer paydirt_begin_setup and paydirt_finish_setup'), and how behavior changes based on presence of session_id. This is exemplary guidance.

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