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

Annotations declare destructiveHint=true and readOnly=false; the description supplies the missing reason — property data and contacts consume credits, estimate_cost=true previews cost without using credits, and a paid connected account is required. That is meaningful context the annotations cannot convey. It stops short of saying whether an empty result still charges credits, which is the one caveat an agent most 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?

Required inputs and the default return shape come first, then the modifier options, then cost/account caveats — a sensible front-loaded order with no filler. The middle paragraph is a dense semicolon chain that takes a second read to parse, which keeps it below top marks.

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 a 10-parameter search with no output schema, the description covers the account prerequisite, the credit cost model, the two result shapes, and the main toggles — enough to call it with correct expectations. Pagination and field selection are unaddressed, and there is no output schema to fill that gap.

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?

At 40% schema coverage across 10 parameters, the description carries real weight: it explains locations as the required driver, frames filters as IDs from the filter list (with an is_corporate_owned example), and gives behavioral meaning to anchor, contact_audience, require_phone, and estimate_cost. It says nothing about page, per_page, sort, or fields, which remain bare in the schema.

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?

Opens with a specific verb+resource: finds US properties matching locations plus filters, and explicitly states what is returned (properties with owner contacts, or one row per contact with anchor=people). It is clear what the tool does, though it never names a sibling such as dealmachine_property_count or dealmachine_location_search to delineate the boundary.

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?

The description gives useful in-tool guidance on option selection (anchor=people vs default, contact_audience=none to skip contacts, require_phone, estimate_cost=true to preview spend without credits). What it lacks is when to pick this tool versus neighbours like property_count, property_export, or people_search, so the routing guidance 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.