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

Annotations only declare it is an open-world, non-idempotent, non-destructive write. The description goes well beyond that: it discloses that an e-mail is sent, that nothing is built or charged while waitlisted, that a click on a link is required before anything happens, and that a follow-up ticket is returned. That is the behavioral detail the annotations cannot carry.

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?

Purpose is front-loaded and the conditional-state sentences are dense but each carries distinct information (listing vs closed vs e-mail/confirmation flow). Minor verbosity in phrasings like "no house can be had yet", but nothing is padding.

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?

With an output schema present, the description needn't enumerate return fields, and it still notes the returned ticket and the tool to use next (house_status). Combined with annotations covering the safety profile and 100% schema coverage, an agent has everything needed to call this correctly.

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 100%, so size, email, and language are fully documented in the schema with defaults and value meanings. The description adds no parameter-level detail (it never mentions size or language), so this is the baseline case where the schema does all the work.

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 concrete verb and resource ("Ask for a house on its own VM") plus the beneficiary ("the person you act for"), which is enough to separate it from siblings like open_sandbox and house_status. It also names house_status as the follow-up tool, so the agent can place it in the workflow without opening any schema.

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 explicit preconditions ("call it only when they know it is coming") and state-dependent behavior keyed to the about tool: 'desk: waiting-list' means list-only/no build/no cost, 'desk: closed' means an 'accepted: false' answer with nothing sent. This is exactly the when-to-call/when-not-to-call guidance an agent needs.

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