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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely new behavioral context: paged results, visibility scoping ('you can see'), and the exact return payload including totals and per-filter counts. It stops short of describing pagination termination or how accessScope interacts with results, which the schema only partly covers.

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 sentences, each doing distinct work: what it lists, when to use it vs. siblings, and what comes back. The primary purpose is front-loaded in the first clause with no filler.

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 9 optional parameters, no output schema and safety already covered by annotations, the description fills the key gaps by describing the returned row shape and the aggregate totals. Minor gaps remain around pagination behavior (what signals the last page) and the accessScope omission semantics, though the latter is documented in the schema.

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 coverage is 100%, so the baseline is 3. The description goes slightly beyond it by grouping the filter dimensions (owner, Company, source) and by noting that the response includes counts per filter value, which hints at how the filters are meant to be used for faceting. It adds no syntax or edge-case detail the schema lacks, so it sits just above baseline.

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 ('List the Contacts'), scopes it ('you can see in this Workspace'), and characterizes the mode ('one page at a time'). It is clearly distinguishable from get_contact and search, which are named 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?

Names the two competing siblings with the exact condition that selects each: 'use search to find one by name, and get_contact for one person's phone, background and Deals.' It also states the intended use of this tool (filter by owner, Company or source, or sort), so the routing decision is explicit rather than inferred.

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