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

Annotations declare it's a non-read-only, open-world, non-idempotent operation, but the description adds the crucial behavioral fact that 'This does NOT take payment: the customer completes payment at that URL' – a non-obvious side effect that prevents misoperation. It also confirms return type (URL).

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 sentences, front-loaded with the action and result, followed by the key non-obvious caveat and the workflow reminder. No filler.

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?

Covers the action, side effect, return value, and a workflow prerequisite. Missing explicit mention of authorization or rate limits, but for a non-destructive creation tool with sibling context, it's nearly complete. A minor gap on how errors or existing sessions are handled.

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 50%, with customer_email already described in the schema. The description doesn't elaborate on job_handle format or customer_email usage beyond what's in the schema. Baseline 3 given partial coverage and no added param detail.

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 (Create), resource (Stripe Checkout session), and return value (URL), plus scopes it to a job. Distinguishes from siblings like hip_get_checkout_status and hip_complete_payment by nailing the exact action.

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?

Clearly establishes when to use it (create a checkout session for a job) and adds a workflow constraint ('Show them the quote first'), implying hip_quote should precede this. Doesn't explicitly name hip_quote or when-not-to-use cases, but the implied sequencing is strong.

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