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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description adds substantial behavior beyond that: it probes with ai_visibility_check, ranks by score, surfaces most/least recognized, and returns score/confidence/signal density per entity. It also discloses the first-entry-as-subject narrative nuance. This is rich additional context that goes well beyond the annotations, with no contradiction.

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 four sentences, front-loaded with the main purpose, then method, use case, and return format. Every sentence earns its place with specific information: what it does, how it works, when to use it, and what you get back. There is no fluff or repetition of schema/annotations. Ideal size and structure.

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?

Despite having no output schema, the description covers the key aspects: purpose, internal mechanics (uses ai_visibility_check), return format (ranked list with score/confidence/signal density), use case context, and an important parameter nuance. Annotations cover the safety profile. For a read-only comparison tool with 4 well-documented parameters, this is complete enough for an agent to select and invoke correctly.

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 adds meaningful semantic nuance for the 'entities' parameter: 'First entry treated as the "subject" for narrative; rest are competitors.' This explains the order-dependent behavior not captured in the schema. Other parameter details (models, _apiKey, context) are already fully described in the schema, so this modest addition justifies a 4.

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 description opens with a specific verb+resource: 'Compare AI visibility across multiple entities side-by-side.' It clearly distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison) by specifying the competitive AI-presence audit focus and the ranking behavior. The example use case ('does Claude know about us as well as our competitors?') reinforces the purpose.

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 provides clear context: it is for competitive AI-marketing audits when you want to compare multiple entities. It explains that it probes each entity with ai_visibility_check, implying that for a single entity you'd use the sibling tool, though it doesn't explicitly say 'use ai_visibility_check for single entity.' This is clear context without explicit exclusions, so a 4 is appropriate.

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