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

With no annotations, the description usefully discloses the state machine: the row must be READY and the effect is that wages become editable, plus the German UI label for user correlation. However, it never mentions that dry_run defaults to true, which for a mutation tool is the single most important behavioral gotcha — a caller omitting it silently performs no change.

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?

One sentence, front-loaded with the state transition and the effect, with zero filler. The UI label is placed parenthetically rather than intruding on the main clause.

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?

An output schema exists so return values need no explanation, and the precondition is covered. But for a mutation tool with no annotations, 0% schema coverage, and a dry_run default of true, the definition leaves the caller without enough to invoke it safely.

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 0% across four parameters and the description names none of them. 'Payroll employee row' weakly hints at employee_id and payroll_calculation_id, but company_name and dry_run are entirely unaddressed, and dry_run's default semantics are critical here.

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?

States a specific verb (reopen / mark in progress) on a specific resource (payroll employee row) and names the required precondition state (READY). The state gate implicitly distinguishes it from the sibling mark_payroll_employee_ready, though that sibling is never named outright.

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 trailing clause 'so wages can be edited' implies the workflow (call this before update_payroll_employee_wage), but usage is only implied. There is no explicit statement of when not to call it, what to do if the row is not READY, or which sibling closes the loop.

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