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

Annotations already declare the write/idempotent/non-destructive profile, but the description adds what they cannot: "no money moves" clarifies that despite payroll vocabulary this touches configuration not funds, and "Sergio tells the owner after it is made" discloses an outbound notification side effect. It does not cover reversibility or what happens to settings not passed, keeping it below 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?

Dense and front-loaded: the core action and setting list come first, then scope, side effect, and retry advice. Every clause carries information, though the parenthetical value enumerations duplicate the schema and add bulk.

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 mutation tool with a nested object, five parameters, and no output schema, the description covers scope, side effects, retry semantics, and valid setting values. The notable gap is the return value — with no output schema, the agent cannot know what a successful response 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?

Schema coverage is only 40%, so the description must carry weight, and it does list the three value domains (providerPayFallbackPct 0 to 1, providerPayDefault {unit: visit or hour, cents}, payHoursFrom booked or approved_time_logs). However these largely restate enums and ranges already in the schema, without explaining what fallback percentage means or when each source applies. Note the "0 to 1" phrasing slightly softens the schema's exclusiveMinimum of 0.

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 ("Changes one payroll setting per call") and enumerates the three mutually exclusive settings, anchored to the equivalent UI ("Payroll settings on the staff page"). It scopes the tool with "Staff pay settings only," which separates it from general tools like update_settings or set_staff_weekly_hours, though it never names a sibling explicitly.

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?

"One payroll setting per call" tells the agent how to sequence multiple changes, and "Pass the same idempotency_key when retrying" gives explicit retry behavior. The owner-notification note signals this is a consequential change worth a reason. It stops short of naming when to prefer update_settings or set_staff_weekly_hours instead.

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