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

The description goes well beyond the annotations (readOnlyHint, idempotentHint, destructiveHint) by disclosing specific behaviors: the list ACCUMULATES over every check, is deduplicated by URL, and seen_in_checks counts checks not citations. It also explains the semantics of each field (subjects, reach, client_present, controlled, rivals) and gives actionable next steps. This is rich behavioral context that annotations alone do not provide.

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?

The description is a long, dense paragraph, but every sentence carries meaning—explaining accumulation, deduplication, field definitions, reach types, and actions. It is front-loaded with the core object description and weaves in necessary nuances without fluff. It is wordy but efficient for the complexity of the returned data, so it earns a 4 rather than a 5.

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 the rich output with many fields and no output schema provided, the description does a strong job of explaining all key concepts: subjects, reach categories, client_present, seen_in_checks, controlled, and rivals. It also explains how to act on a place. However, some phrases like 'the number that carries the tool' are ambiguous, and it doesn't address pagination or possible empty results. Overall, it is nearly complete but not fully unambiguous.

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?

The single parameter competitor_scan_id is fully described in the schema with 'The UUID of the competitor scan: call list_competitor_scans to find it.' Since schema coverage is 100% and the description does not add any additional parameter-specific details, the baseline score of 3 is appropriate. The description focuses on the response structure rather than the parameter, which is acceptable given the schema already covers it.

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?

The title 'Read a competitor scan' and the description clearly state the action and resource. It distinguishes itself from sibling tools like list_competitor_scans, update_competitor_scan, and create_competitor_scan by focusing on retrieving a single scan's detailed place list. The description explicitly explains what the tool returns and even cross-references create_quest for acting on places, leaving no ambiguity about its function.

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 does not explicitly state when to use this tool versus alternatives. It implies that you use it to inspect the places of a specific scan, and mentions that list_competitor_scans is a way to find the scan ID, but it lacks direct exclusions like 'use list_competitor_scans to get an overview, use this for detailed place data.' The guidance is present but implicit, not explicit.

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