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

Annotations already cover readOnly/idempotent/non-destructive, so the description correctly focuses on the one behavioral fact annotations cannot express: this call is free. That is genuinely valuable billing context. It does not disclose the shape or precision of the result (exact vs. approximate count), which would be the natural complement.

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?

Two tight sentences with the differentiator (no credits) front-loaded. Nothing is wasted, though the second sentence is telegraphic and could be a clause clearer without adding length.

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?

No output schema exists, so the description is the only place an agent could learn what a 'count' response looks like — a bare number, a per-location breakdown, an estimate — and it says nothing. Combined with zero coverage on the locations parameter, the definition is adequate to invoke but not to interpret the result.

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 0% at the top level, so the description must compensate — 'Filters use the people catalog' does add real meaning by telling the agent that filter_id values come from the people catalog (dealmachine_filters), not the property catalog. However, the more complex `locations` parameter (types, polygon/bounds/radius, OR semantics) is given no treatment in the description.

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?

Uses a specific verb+resource ('Count matching people') that clearly separates it from dealmachine_people_search (which returns records) and dealmachine_property_count (which counts a different entity). It stops short of explicitly naming those siblings, so an agent has to infer the routing, but the core purpose is unambiguous.

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?

'Without consuming credits' implies the intended pattern — call this to size a search before spending on dealmachine_people_search — but that workflow and the alternative tool are never stated. Usage is implied rather than prescribed, and there is no guidance on when this tool is inappropriate.

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