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

Goes well beyond the annotations: it discloses that no money moves inside the tool, that payment happens via an external checkout_url as a hold, that the human is only notified after payment, and that a 10-minute acceptance window then starts. It also surfaces the critical state artifact (customer_token) that must be retained. Annotation flags (readOnly=false, idempotent=false, openWorld=true) only hint at mutability, so this description carries the real behavioral burden.

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?

Four tight sentences, front-loaded with the core action and immediately followed by the critical caveat about money not moving. Slightly dense with a capitalized IMPORTANT marker, but every sentence carries distinct information.

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?

For an 11-parameter, non-idempotent, multi-step hiring flow with no output schema, the description supplies what the schema cannot: the return payload (job id, contractor terms, price breakdown, checkout_url) and the asynchronous payment/acceptance lifecycle. Nothing an agent needs to complete the call and hand off correctly is missing.

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 100%, with per-field descriptions including enum meaning for customer_type, price_usd tip semantics, and handle format. The description adds no parameter-level meaning beyond the schema, so the baseline of 3 is appropriate.

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 and resource ('Create a per-job work order for a human') and ties it to the discovery step ('found with search_human'), which cleanly separates it from ask_human, ask_card, and search_human. An agent knows immediately this is the hiring/booking step, not a question-asking step.

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?

Gives a clear prerequisite (the human handle must come from search_human) and implies the follow-on tools by naming status and release as consumers of customer_token. It does not explicitly say when NOT to use this versus ask_human or ask_card, so the sibling routing 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.