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

Despite annotations covering read-only safety, the description adds substantial behavioral context: matching rules (any spelling, case aside, then prefix), visibility limits (only confirmed persons, only spellings whose source you may open), plan gating (only where the plan includes AI), and full semantics of the 'checked'/'unchecked'/'stale' states.

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 core purpose is front-loaded, but the description is a long run-on that buries the checked/stale taxonomy and multiple behavioral rules in a single sprawling paragraph. The information earns its place, but structure and brevity are weak.

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?

There is no output schema, and the description fully compensates by describing the return shape: every candidate person, each spelling by script and form, each source and quote, and the checked status. An agent can interpret the result without additional documentation.

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, but the description adds real meaning beyond the schema: the spelling must be written 'as found', never with initials completed from memory, and matching is case-insensitive exact-then-prefix. The project parameter is left to the schema, which already documents it.

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 opening line states a specific verb and resource — resolve a name spelling to the person(s) — and the description distinguishes it from the write-path sibling set_person for the 'nothing found' case. It does not explicitly differentiate from close lookup siblings like distinct_persons or list_persons, so it falls short of a full 5.

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?

Explicit when-to-use: 'Ask it BEFORE writing a person's name with initials or in another script', plus an explicit prohibition ('never complete initials from memory'). It also gives the alternative path when nothing is found (use set_person with source and quote) and states the ambiguous-case procedure.

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