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

Annotations already cover read-only, idempotent and non-destructive behavior, so the bar is lower. The description still adds two genuinely useful facts beyond them: a connected DealMachine account is required, and counting consumes no credits, which materially affects how aggressively an agent can call it. It stops short of describing the response payload.

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 what is counted and what is required, with the auth and credit notes correctly placed last. The clause 'or with anchor=people their matching contacts' is grammatically tangled and slows parsing of an important behavior.

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?

There is no output schema, so the description should say what comes back, yet it never states whether the result is a single integer, a per-location breakdown, or separate property and contact counts when anchor=people. Auth and cost are covered, and parameter prerequisites (contact_audience required for people) are partly covered, so it is adequate but with a clear 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?

Schema description coverage is only 40%, so the description must carry weight: it does explain that anchor=people shifts the target to contacts, gives a concrete filter example (is_corporate_owned for corporation/LLC/business owners), and ties contact_audience and require_phone to the search tool's semantics. It leaves the location geometry parameters (radius, polygon, bounds, lat/lng) and the filter operator field entirely to 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?

States a specific verb and resource ('Counts properties matching locations and filters') and flags locations as required, plus the anchor=people variant that counts contacts instead. It implicitly separates itself from the search/count siblings by referencing 'the search' as a separate tool, but never names dealmachine_property_search or dealmachine_people_count explicitly.

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 instruction to reuse the same anchor, contact_audience and require_phone as the search implies this is a pre-flight/counting companion to a search call, and 'counting consumes no credits' hints at when it is cheap to use. However, there is no explicit statement of when to use count versus property_search or people_count, and no exclusion conditions.

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