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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond these: normalized and case-insensitive matching, role-based visibility (draft vs. published, both languages for admins), locale handling for non-admins, and the inclusion of a canonical URL. This goes beyond the annotations, though it does not cover every behavior (e.g., pagination), but with annotations carrying the safety profile, a 4 is justified.

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 remarkably concise—only two sentences—yet packs in the core search behavior, usage guidance, role-based differences, and locale handling. Every sentence earns its place, with the primary purpose front-loaded. No redundancy or 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?

The description covers purpose, usage, behavioral nuances, and key parameter semantics. With an output schema present, the description does not need to explain return values. It addresses the tool's complexity (role-based results, locale, canonical URL) adequately. Minor missing aspects like limitation/pagination are either obvious from schema or unnecessary. A score of 4 reflects strong completeness without being exhaustive.

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 only 33% (locale), but the description compensates for query by explaining it searches by English term, Arabic term, abbreviation, or slug. It also references locale by saying 'pass the caller's language in locale.' The limit parameter is not explicitly described, but its schema includes defaults and bounds, making its semantics reasonably clear. This is above baseline due to the added query context, though limit remains a minor gap.

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 clearly states the tool's function: 'Searches terminology by English term, Arabic term, abbreviation, or slug using normalized, case-insensitive matching.' This specifies the verb, resource, and search fields, and distinguishes it from sibling tools like search_explainers, which search a different domain. The role-based detail further clarifies scope.

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 explicit guidance: 'should call this before creating a new term to avoid duplicates.' It also explains role-based use cases (administrators vs. other accounts). However, it does not explicitly mention alternatives or when not to use the tool, though the sibling list implies different domains. This is clear context but lacks explicit exclusions, so a score of 4 is appropriate.

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