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

Annotations only say readOnlyHint=false, destructiveHint=false, idempotentHint=false; the description adds substantial context the annotations cannot convey: it spends credits, the price comes from get_nyc_property and is usually 3, it is free if already unlocked, it requires prior report unlock, and it demands explicit user confirmation plus honoring do-not-call flags. This is exactly the behavioral load a mutation-with-cost tool needs.

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?

Front-loads the cost consequence, then returns, then prerequisites, then the confirmation workflow. Every sentence carries operational information, though the description is on the longer side and could tighten slightly without loss.

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?

Given a single required param, full schema coverage, an output schema, and non-read-only annotations, the description covers the remaining burden completely: cost model, prerequisite chain, idempotency-adjacent 'free if unlocked' note, and the consent/DNC constraints.

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?

There is one parameter (bbl) at 100% schema coverage, so the schema already documents format and an example. The description adds no parameter-level meaning beyond the schema, which is the expected baseline when coverage is complete.

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+resource ('unlock ... owner contacts') and precisely enumerates the payload: phone numbers with line type and do-not-call flag, emails of the person behind the owner of record, including owner-LLC people. This clearly separates it from get_nyc_property (which supplies the price) and unlock_nyc_property_report (the prerequisite).

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 strong preconditions and workflow: the full report must be unlocked first (naming unlock_nyc_property_report), it is free if already unlocked for the workspace, and the agent must quote cost and get user go-ahead before calling. It does not name alternative sibling tools (e.g. search_nyc_owners) for cases where a cheaper path would do, so it stops short of explicit alternatives.

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