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

Beyond the readOnly/openWorld/idempotent/destructive annotations, it discloses that no URL fetches, writes or reanalysis occur, spells out the non-obvious semantics of outcome_unknown, and surfaces the durable-idempotency and caller_token prerequisites. This is genuine behavioral context the annotations cannot express.

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?

Four compact sentences, front-loaded with the operation and scope, then prerequisites and the re-execution warning. Dense but every clause carries distinct information; no 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?

For a single-parameter reconciliation tool with an output schema already covering return values, the description supplies everything an agent needs: what it reads, the identity linkage, prerequisites, the no-reanalysis guarantee, and the outcome_unknown caveat.

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?

Top-level schema description coverage registers as 0%, so the description does meaningful work: it explains that lookup uses the 'same caller/key' and that caller_token is required precisely 'for anonymous callers', reinforcing the nested field notes. It adds caller-condition context, though it does not restate the key format or replay/conflict rules that live in the nested schema.

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 sentence gives a specific verb (read-only lookup) and a specific resource (an opt-in analyze_activity submission) and even scopes it to 'the same caller/key'. It explicitly ties itself to the sibling analyze_activity, so an agent can tell the reconciliation read apart from the analysis write without inspecting 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?

It states the selection condition ('same caller/key'), prerequisites ('requires durable idempotency enabled; private caller_token required for anonymous callers'), and a clear when-not rule ('outcome_unknown ... never authorizes a fresh execution'). The only gap is that it never names a sibling to use instead when the lookup fails to resolve.

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