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

The annotations already indicate read-only and idempotent behavior, and the description adds meaningful characteristics: lexical matching, soft alias handling, coverage-based completeness, no merging by display name, and the fact that a search miss does not prove absence. This helps an agent interpret results appropriately and matches the annotation set.

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 dense and front-loaded, with the core purpose and main constraints stated early. Some repetition occurs, especially around lexical searching and one-keyword-at-a-time guidance, but the additional context is genuinely useful for safe use.

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 no output schema, the description explains the essential return semantics: reviewed vs unreviewed subjects, subject_id/subject_type identity, cursor-based exhaustive retrieval, collection_coverage, and coverage_status=complete as the only basis for claiming absence. It gives an agent all context needed to perform the operation without overclaiming.

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?

Only the cursor parameter has schema-level description coverage; the tool description compensates partially by explaining query behavior, subject_type-only fallback, pagination, and coverage-related result semantics. But limit and include_related are not mapped to their usage meaning, leaving two parameters under-specified for an agent despite the long textual descriptions.

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 'Search reviews plus matching reviewed or unreviewed subjects,' immediately naming the verb, resource, and scope. It further differentiates this tool from siblings by stating it is lexical rather than semantic and by emphasizing that identity is based on subject_id/subject_type rather than display names.

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?

It gives explicit workflow instructions: try one keyword at a time, follow up with exact subject-name searches, paginate using cursor until complete, and fetch each returned review before answering. It also provides when-not-to-stop guidance for location queries and says partial or unknown coverage must be reported as uncertainty, which is strong usage guidance.

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