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

The description discloses important behavioral traits beyond annotations: the cost structure (2/6/10 credits, free when nothing matches), the confirmation flow for size 1000 with quote-first behavior, and the return format (top `limit` keywords by volume, total_count). It also explains what each mode returns. The annotations are sparse (idempotent false), so the description carries the burden and does so thoroughly.

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 compact and organized: mode definitions upfront, cost/quote note, then return format. It is not overly long and each sentence adds distinct information. Slight room for improvement by separating cost details from core behavior, but overall efficient.

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?

Covers modes, cost/credit details, the quote requirement for size 1000, and return structure (top limit keywords with positions and total_count). With an output schema absent arranged by input schema covering all parameters, this is fairly complete. It does not explicitly state that it compares against another domain (actually it does via them). Minor gap: no mention of authentication or rate limits, but annotations show no safety concerns. Overall sufficient.

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 100%, so the baseline is 3. The description adds behavioral context for `limit` and `confirm_quote` by specifying default return size and the quote-flow, but the schema already documents each parameter's meaning. No additional param semantics beyond what the schema provides, except clarifying that size doesn't affect cost? Wait it says size affects cost. Cost is mentioned in description and schema partially. Baseline 3 is appropriate.

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 states a clear verb ('comparison') and resource ('keyword comparison of two domains'), and names the three modes (shared, their_gap, your_gap) that define what the tool computes. This distinguishes it from sibling tools like domain_keywords or domain_overview, which perform different analyses.

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 explains what the tool does but doesn't explicitly say when to use it over alternatives like domain_competitors or serp_analysis. It implies its usage through the mode definitions but provides no direct guidance on selecting this tool versus siblings. The credit/cost info is useful operational context but doesn't substitute for explicit selection criteria.

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