apply_certain_reconciliation_match

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

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses mutation, soft-deletion of the duplicate, the server re-validating against live state, returning a 400 on stale candidates, bumping model version, and emitting an activity event. This goes far beyond a simple 'mutates state' warning.

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 yet information-dense. Every sentence contributes: purpose, mutation consequences, usage context, tier-specific behavior, server-side revalidation, and side effects. There is no redundancy or 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?

The description is complete for a complex mutation tool. It covers when to use, what happens, error conditions (400 on stale state), and side effects. An output schema exists, so return value details are handled there. No significant gaps remain.

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 (83%), so baseline is 3. The description adds meaningful semantics by explaining how own_qid and inherited_qid map to the duplicate and canonical entities, and clarifies that confirm_heuristic acknowledges structural divergence and is required for heuristic-tier candidates. It does not add much for server_version beyond implicit mention of server re-validation, but overall it adds substantive 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 opens with a specific verb and resource: 'Apply a certain-tier reconciliation candidate. Mutates state.' It clearly distinguishes from sibling tools like list_reconciliation_candidates and reject_reconciliation_candidate by explaining that it applies the candidate and soft-deletes the duplicate entity, making the inherited entity canonical.

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?

Explicitly states when to use this tool: 'Use after surveying candidates via list_reconciliation_candidates.' It also clarifies the distinction between certain-tier and heuristic-tier candidates, noting that heuristic-tier requires confirm_heuristic=True and is otherwise refused server-side. This provides clear guidance on when this tool is appropriate versus when operator review is needed.

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