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

The description goes well beyond the annotations: it discloses the 15-minute signed download_url, 7-day file retention, the xdata__job__result recovery path for expired links, idempotency-key reuse semantics, and a per-call token cost. The only tension is that annotations declare readOnlyHint=true while the text describes building a persisted artifact and consuming a token; that is a side-effect nuance rather than a direct contradiction, since no existing payroll data is modified.

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 purpose and result shape are front-loaded and clear, but the tail is bloated and repetitive — the recovery-receipt paragraph restates retention and access scope three times ("grants access to that result only", "Do not publish it", "Losing it cannot be repaired"). That boilerplate is also of doubtful relevance to a tool that takes a platform key only, so it dilutes rather than sharpens the guidance.

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?

With no output schema, the description usefully specifies the return shape: a data summary (attribution_ym, employee_count) plus artifacts[] entries with a signed download_url. Combined with retention, link-expiry recovery and idempotency rules, an agent has enough to call and consume the result; only the semantics of the required workplace identity fields are left implicit.

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 75% and the nested employee fields carry their own ADR-069 notes, so the schema does most of the work. The description reinforces attribution_ym, payment_date, employees[] and rules out account_link_id ("Platform key only"), but says nothing about the required workplace_name, business_registration_no, workplace_address, or the company_name alias.

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 first sentence gives a specific verb and resource ("Build one payroll payslip workbook (xlsx) with one sheet per employee") plus the driving inputs, and explicitly excludes composite merge and Gmail. It does not, however, distinguish itself from the closest sibling, payroll_artifact__register_xlsx, so an agent cannot tell from the text alone which of the two artifact generators to pick.

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?

Usage is implied by the input list (attribution_ym, payment_date, employees[]) and by the negative guidance "not composite merge; not Gmail", but there is no positive statement of when this tool is the right choice over register_xlsx or the payroll_pack generators. The long idempotency and recovery-receipt passages explain how to call it, not when to prefer it.

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