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

The annotations only declare readOnly=false, destructive=true, and openWorld=false. The description adds substantial behavior beyond that: partial-update semantics ('Only the fields you pass change'), the refusal when a start date moves past an end date, the headcount impact of overlapping periods, and the full confirmation flow including status='confirmation_required', action_id, plan_token, and confirm_action.

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 front-loads the purpose and primary alternative before moving to validation and confirmation details. It is dense but appropriately sized for a mutating HR tool with a confirmation workflow, and each sentence adds operational value.

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?

There is no output schema, 13 parameters, and no schema-level parameter descriptions, so the description carries a large burden. It covers the mutation workflow, alternatives, validation constraint, and confirmation response well, but it does not adequately explain the full parameter surface or what a successful post-confirmation result looks like.

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?

With 13 parameters and 0% schema description coverage, the description must carry the explanatory burden, but it only gives meaning to a subset: started_on, end date validation, location/shop, position/promotion, and manager. It leaves kind, employment_type, status, schedule, probation_until, personnel_number, org_unit_id, and engagement_id underexplained. It also says ending is not handled here while the schema exposes ended_on and status='ended', creating ambiguity about whether those fields can be set.

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?

Opens with a specific verb and resource ('CORRECT an existing employment period'), gives concrete examples such as a mistyped start date, shop move, promotion, or manager change, and differentiates itself from both opening a new period and hr_close_engagement. An agent can identify the intended operation without opening 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?

Explicitly says to use this rather than opening a second period when the first is wrong, explains the double-counting consequence of overlapping periods, and directs endings to hr_close_engagement. It also explains the confirmation path, so both when-to-use and the workflow alternative are clear.

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