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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds substantial behavioral context beyond that: threshold filtering, ranking, index tagging, legal-form/word-order/obfuscation awareness, and a throw-over-truncate failure mode on oversized inputs. This is valuable and non-redundant.

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?

Three compact sentences with no filler. The main behavior is front-loaded, the relationship to compare_entity_names is given in one clause, and the important error behavior is stated last. Every sentence earns its place.

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?

With no output schema, the description responsibly sketches the output shape: filtered, ranked, indexed results. It also discloses the cardinality limit and failure behavior. It could be slightly more explicit about the return structure (e.g., whether scores are included alongside names), but the description is largely sufficient for an agent to understand and invoke the tool.

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 80%, so the parameters are mostly self-documenting. The description adds minimal parameter-specific meaning: 'up to 750 candidates' echoes the maxItems constraint, and 'threshold' echoes the schema's threshold property. It does not materially deepen understanding of query, candidates, type, or limit.

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 specific verb and resource: score one name against up to 750 candidates, returning those over the threshold ranked and tagged with their index. It also distinguishes this from the sibling compare_entity_names by characterizing it as that comparison applied as a search.

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 tool clearly signals a one-to-many search use case: one query name versus a candidate list. It references the related compare_entity_names tool and states a hard boundary—over 750 candidates throws rather than truncates—so an agent knows not to use it beyond that limit. However, it does not explicitly enumerate when to prefer it over other siblings like deduplicate_entity_names.

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