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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds substantial behavioral detail beyond those flags: name-only resolution produces labeled candidates with resolved=false, firm matching tries current registration before prior ones, and the returned card matches get_ria_advisor's summary. This clearly sets expectations for the operation's edge cases and return behavior.

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 compact and efficiently structured: it front-loads the primary purpose in the first sentence, then covers the critical caveat (name alone), the disambiguation order, and the relationship to get_ria_advisor. Every sentence adds value and there is no redundant or filler content.

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 the rich annotations and high schema coverage, the description covers all essential behaviors needed to call the tool correctly: the matching logic, the name-only failure mode, the returned card format, and how to get history. No output schema exists, but the description adequately explains the return concept and the alternative for deeper detail.

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 high at 83%, and the description adds meaningful interpretation of parameters: crd resolves directly, firm can be a name or CRD and is matched against current then prior registrations, and name alone is insufficient. This goes beyond the schema's short descriptions, though limit and state receive no additional clarification.

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 precise verb and resource: 'Resolve an advisor by name AND a firm ... or by individual CRD, to one person card.' It distinguishes itself from siblings by explicitly noting that a name alone is never resolved, and by tying the output to get_ria_advisor's summary card, so an agent can tell it apart from related search and resolve tools.

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 clear context for when to use this tool: it requires firm or CRD for one-person resolution and warns that name-only returns labeled candidates with resolved=false. It also recommends get_ria_advisor(dfx_id) for history, providing an alternative. It does not explicitly name sibling tools like resolve_name or search_people as alternatives, but the guidance is sufficient.

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