Resolve a phrase (or emem:entity: token) to a canonical object

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description confirms 'Read-only' and explains the behavioral modes: passing `text` yields candidates, `near` narrows, `token` dereferences. This adds useful context beyond the annotations without contradiction.

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?

Two focused paragraphs: first explains the core function and parameters, second gives usage guidelines. Every sentence is informative with no redundancy. Front-loaded with the key action.

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?

For a tool with 5 optional parameters and no output schema, the description covers all input modes, usage context, and the co-referencing problem it solves. An agent has enough information to decide when and how to call it correctly.

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%, but the description goes further by explaining parameter roles: 'Pass `text` (e.g. "the collapsed span at the ford") to get ranked existing candidates; pass `near` to narrow to a place; or pass an `emem:entity:` `token`...'. This clarifies the different invocation modes, adding significant semantic value.

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 purpose: 'Converge a fuzzy phrasing onto the canonical object other agents already minted, so everyone co-refers to the same identity.' It specifies the verb (resolve), resource (phrase to canonical object), and distinguishes it from re-minting. The two use cases (before minting and on receiving a token) further clarify its role.

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 explicitly says 'When to use: Call BEFORE minting when another agent may already have registered the object, or when you receive a `emem:entity:` token...' and advises 'mint only if nothing matches'. This provides clear context for when to use versus alternatives.

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