watchlist_reconcile

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

The annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this by explicitly saying it never resumes, retries or rolls back a mutation, which is behavior beyond what the hints alone convey. It also discloses that recovery entries are exposed, telling the agent what output content to expect. It does not cover permission or rate-limit behavior, so not a 5.

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 compact sentences with no waste, and the core purpose is front-loaded ahead of the behavioral constraint. Every sentence earns its place.

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 read-only reconcile tool with no output schema, the description covers what is read, what is deliberately not done, and what is exposed. The main remaining gap is that it does not describe the shape of the comparison result, but that is minor given the tool's narrow scope.

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 75%, so most parameters are already documented in the schema. The description's mention of 'create/replace' loosely maps to the operation enum, but it adds no syntax or semantics for target_id, idempotency_key or expected_layout_id. Baseline 3 is appropriate when the schema does the heavy lifting.

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 and resource: 'Read a durable create/replace checkpoint and compare it with current account state.' This clearly distinguishes it from mutation siblings like watchlist_create or watchlist_add, since it is a read-only reconciliation step. It falls short of a 5 only because 'durable create/replace checkpoint' is jargon that could leave an agent unsure what exactly is being read.

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 sentence 'Exposes recovery entries but never resumes, retries or rolls back a mutation' sets a clear boundary for when the tool does and does not act, which implicitly tells the agent this is for inspection only. There is no explicit 'use this after X fails' phrasing or named alternative, which keeps it from a 5.

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