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

With no annotations provided, the description carries the full behavioral burden and does so well: it discloses matching semantics, the exact/approximate match field, the meaning of null, and the necessary follow-up workflow. It omits some operational details such as locale behavior or whether the lookup is read-only, but for a resolution tool the important behavioral traits are covered.

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 front-loaded with the primary action and usage rule, and each sentence carries useful operational information. It is somewhat long and contains layered instructions about null handling and coverage checking, but none of it is redundant 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?

There is no output schema and no annotations, so the description must explain enough for correct invocation and interpretation. It covers purpose, usage, return match semantics, null handling, and escalation to describe_coverage, though it leaves the locale parameter and exact result shape unaddressed.

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 0%, so the description must compensate for both parameters. It adds meaningful constraints for 'query' (pass only the title, in singular, not a full sentence), but says nothing about the 'locale' parameter, leaving half the parameters semantically undocumented.

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 (resolve) and enumerates the resource types it handles: job titles, internal role names, nicknames, and degree names. It also distinguishes itself from siblings by instructing the agent to call it FIRST and by naming describe_coverage as the fallback. An agent can tell what this tool does without opening the schema.

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 gives explicit when-to-use guidance ('Call this FIRST whenever a person names their job'), when-not-to-use guidance ('it does not read sentences'), and concrete alternative routing ('before saying VOLO does not cover it, call describe_coverage'). It even specifies how to interpret a null result and what to do next, leaving little ambiguity.

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