Correct fields of an application

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

Annotations already declare a destructive, non-idempotent write, and the description adds substantial context beyond them: user confirmation is required, a dry_run/confirm token flow is specified, expected_version guards against concurrent changes, a backup is taken first, and undo_last_write can revert the write. These details are consistent with the annotations and materially improve safe invocation.

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 front-loaded with the purpose and correction examples, then moves into validation, alternatives, and the confirmation workflow. Despite its length, every sentence carries necessary operational detail for a destructive write tool, with no redundant or filler text.

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 destructive mutation, six parameters, nested fields object, and existing output schema, the description covers everything an agent needs: what can be corrected, which siblings handle related changes, how to preview and confirm writes, how concurrency is guarded, and how undo works. No critical behavioral or procedural gap remains.

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 description coverage is 100%, so the schema already documents each parameter. The description adds useful semantic detail beyond the schema, particularly date validation rules: a submit or reply date cannot be in the future and a reply cannot precede the submit date. It also clarifies that related status and follow-up changes belong to other tools.

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: 'Correct fields of one row by hand' with concrete examples such as a wrong date, typo in company or role, furthest stage, link, or custom column. It also distinguishes the tool from siblings by explicitly routing status changes to set_status and follow-up changes to log_followup or reschedule_followup.

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 gives clear conditions for use (manual corrections to specific fields) and explicitly names alternatives for related operations: set_status for status, log_followup for sent follow-ups, and reschedule_followup for moved follow-ups. The confirmation workflow further clarifies the required invocation sequence with dry_run and confirm.

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