Employment Hero Payroll MCP by usefulapi

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

Beyond the annotations, the description discloses the side effects (employee notified, leave applied to pay) and the important limitation that the action cannot be undone through this server. It also includes the endpoint, reinforcing that this is an external write operation.

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 'WRITE' and the primary action, followed by the precheck, irreversibility warning, and endpoint. Every sentence adds useful operational context without waste.

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 destructive, non-idempotent write tool with no output schema, the description covers the action, side effects, reversibility, and required precheck. An agent has enough information to invoke it correctly and 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 100%, so all three required parameters are already documented. The description includes the endpoint path with the same identifiers but does not add new semantic meaning beyond what the schema provides.

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 uses a specific verb and resource: approves a pending leave request. It also clarifies the operational effect—employee notification and application to pay—which distinguishes this write action from sibling read tools such as keypay_get_leave_request.

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 a clear precondition: check the request first with keypay_get_leave_request. It does not explicitly mention the decline alternative or when not to approve, but the intended use context is clear.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the 'WRITE:' classification, the fact that the reason is surfaced to the employee, and the underlying HTTP endpoint. It does not explicitly state that the decline is irreversible or what errors occur on an already-declined request.

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?

Three short sentences, front-loaded with the WRITE classification and the core action, followed by prerequisite and endpoint. Every clause is short and purposeful, though the raw POST path is marginal value for an agent that never constructs URLs itself.

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 destructive mutation with no output schema, the description covers the operation, the prerequisite read, and the user-visible side effect of the reason. It leaves unaddressed what state the request ends in and whether the decline can be undone, which would be worth one more sentence given the destructive hint.

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 all four parameters are already documented, including 'Reason shown to the employee.' The description's 'optional reason the employee sees' largely restates the schema and adds no format or length guidance beyond it. Baseline 3 applies when the schema carries the parameter semantics.

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 ('declines a leave request') and scopes it further with the optional reason visible to the employee. The 'WRITE:' prefix immediately separates it from the read-oriented siblings like keypay_get_leave_request and keypay_list_leave_requests, and the action is inherently distinct from keypay_approve_leave_request.

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 an explicit prerequisite and names the sibling to use for it: 'Check the request first with keypay_get_leave_request.' That is real routing guidance, not just context. It stops short of stating when-not to use this tool (e.g. use approve instead when the request should be granted).

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the field inventory of the response and the underlying endpoint, but says nothing about auth requirements, rate limits, or error behavior for an unknown id — modest added value over the annotations.

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?

Two compact fragments with the resource scope front-loaded and no filler; the endpoint path is a slightly redundant addendum but costs little. Efficient overall, though the field list reads as a raw inventory rather than structured prose.

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 compensates by listing the returned fields, and annotations cover the safety profile. What remains unstated — pagination is irrelevant here, but error handling and prerequisite id sourcing — is minor for a simple read-by-id tool.

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 100% and the single business_id parameter is fully documented in the schema, including its source ('from keypay_list_businesses'). The description's 'by id' adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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 and resource ('One business by id') and enumerates the fields returned (name, legal name, contact, address, ABN, leave year, standard hours, pay cycle), so an agent knows exactly what it retrieves. The singular 'one business by id' implicitly contrasts with keypay_list_businesses, but no sibling is named explicitly, which keeps it short of a 5.

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 only implied: 'by id' signals this is the single-record lookup once an id is known, versus the list variant. There is no explicit when-to-use statement, no precondition (e.g. 'requires an id from keypay_list_businesses'), and no named alternative, so the agent must infer routing.

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

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

Goes well beyond the readOnly/destructive annotations by disclosing the exact data-masking behavior: tax file, national insurance, IRD/NRIC numbers, bank accounts and super member numbers are removed. That redaction notice is critical for an agent reasoning about whether this tool returns sensitive fields, and the underlying endpoint path is also given.

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?

Front-loads the core purpose, then the field inventory, then the redaction caveat, then the endpoint. The field list is long but earns its place given there is no output schema; nothing is redundant.

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 field enumeration and the explicit statement of what is stripped make the return shape predictable, which is the main gap this tool had to close. Minor omissions remain (no pagination/auth notes, no error semantics), but they are low-impact for a simple single-record read.

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?

Both parameters are fully documented in the schema (100% coverage, including provenance hints from keypay_list_businesses and keypay_list_employees). The description adds no parameter meaning of its own, so the baseline 3 applies.

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 resource and scope ('One employee's full record') and enumerates the fields returned, which makes the read-one-employee purpose unambiguous. It is distinguishable from keypay_list_employees by the singular scope, though it never names that 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?

Usage is only implied: fetching a single employee's record by id. There is no statement of when to prefer this over keypay_list_employees or keypay_get_user, nor any prerequisite or exclusion. The schema descriptions do point at keypay_list_employees as the id source, but that lives in structured data, not the description.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context (the per-category breakdown and the as-at-date default of today), but says nothing about pagination, empty results, or how the balance unit is expressed.

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?

A single compact sentence front-loads the resource and the return shape, with the optional date qualifier attached. The trailing URL is redundant boilerplate but does not bloat or bury the key content.

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 carries the return-value burden and does so adequately by naming the per-category accrued amount and unit. For a simple read-only lookup with fully-documented parameters, nothing essential is missing, though it could note what happens when no balance exists.

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 all three parameters are already documented in the schema, including the yyyy-mm-dd format and the 'default today' behavior. The description only restates the optional date, so it adds no meaning beyond the schema; baseline 3 is appropriate.

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+resource: retrieving an employee's leave balances broken down per leave category, optionally as at a date. It also discloses the return content (accrued amount and unit), which distinguishes it from list-type siblings, though it never names the closest-looking alternative keypay_report_leave_balances.

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 description gives no when-to-use guidance, no prerequisites (e.g., that business_id and employee_id are required), and does not distinguish this tool from the similarly-named sibling keypay_report_leave_balances. Usage is only inferable from the name and the 'optionally as at a date' wording.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the set of returned fields, which is genuine context beyond the annotations, but says nothing about auth requirements, error behavior, or missing-record handling.

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?

Two short sentences, front-loaded with the returned content rather than the endpoint. The raw REST path adds minor orientation value but is largely redundant given the schema.

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 enumerates what a leave request contains, which is the main thing an agent would otherwise lack. For a simple three-id read tool with full annotation coverage and full schema coverage, this is close to complete.

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 all three parameters (business_id, employee_id, leave_request_id) are already documented in the schema, including where to obtain them. The description adds no parameter meaning beyond the schema, so the baseline 3 applies.

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 resource (a single leave request) and enumerates the fields it carries (employee, category, dates, hours, status, notes), which is clearer than a tautology. It does not explicitly differentiate itself from the plural sibling keypay_list_leave_requests, though the singular framing implies selection by id.

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?

No when-to-use guidance, no prerequisites, and no mention of the obvious alternative keypay_list_leave_requests. The id-based path implies retrieval of one record, but the agent must infer that from the schema's required ids rather than from the description.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description's enumeration of returned fields adds real value given there is no output schema, but it says nothing about error behavior, permissions, or pagination/format.

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?

Two compact clauses, front-loaded with the resource and its scope. The trailing endpoint path is somewhat redundant with the tool name but still useful for API mapping, so the definition is efficiently sized.

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 simple two-parameter read with full schema coverage and safety annotations, the description supplies the missing piece — an indication of what fields come back, since no output schema exists. The field list is a partial sketch rather than a full contract, but nothing critical for correct invocation is absent.

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% and both parameters are documented in the schema with their provenance (business_id from keypay_list_businesses, pay_run_id from keypay_list_pay_runs). The description adds no parameter-level meaning beyond the raw endpoint path, so the baseline of 3 applies.

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 gives a specific verb+resource ('One pay run by id') and enumerates the returned fields (pay schedule, period, date paid, finalised status, notation), which distinguishes it from siblings like keypay_get_pay_run_summary, keypay_get_pay_run_totals, and keypay_get_pay_run_payslips. It stops short of naming an alternative, so it is clear but not fully self-differentiating.

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 (fetch a single pay run when you have its id), and the schema clarifies the id comes from keypay_list_pay_runs. There is no explicit statement of when to prefer this over the summary/totals/payslips siblings, so guidance is only implicit.

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

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

Annotations already declare readOnly/openWorld/non-destructive, and the description adds real value on top: a size warning for large pay runs and explicit disclosure that bank account numbers and tax/identity numbers are redacted. It stops short of describing pagination or how to handle oversized responses.

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?

Three tightly packed sentences with zero filler: return shape first, then cost caveat, then redaction note, then the endpoint. Front-loaded and every sentence earns its place.

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 carries the burden well by enumerating the returned field groups (earnings, deductions, tax, super, leave, gross/net, YTD) and the keying by employee. It leaves large-result handling and pagination unaddressed, which is the only meaningful gap.

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 all three parameters (including show_all_data) are already documented in the schema. The description adds no syntax or format detail about the parameters, so the baseline 3 applies.

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 and resource ('Pay slip data for every employee in a pay run') and scopes it precisely with 'keyed by employee', which distinguishes it from the aggregate siblings like keypay_get_pay_run_summary and keypay_get_pay_run_totals. An agent can tell what it returns 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?

Usage is implied by the scope statement (per-employee detailed payslip data), and 'Large for big pay runs' warns about cost, but there is no explicit when-to-use guidance or routing against overlapping siblings such as get_pay_run_summary or get_pay_run_totals. Adequate but with a clear gap.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower. The description usefully enumerates the returned aggregate fields, but says nothing about permissions, business scoping rules, or whether the pay run must be in a particular state.

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?

Two short, front-loaded sentences: the payload contents come first and the raw REST path second. The endpoint path is mild noise for an agent but does map the tool to the underlying API route.

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 read-only two-parameter getter with no output schema, the description discloses the key aggregate values returned (hours, gross, net) and the required ids are fully specified in the schema. Only the shape of the rest of the payload and any scoping constraints remain unstated.

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% (both ids documented, with business_id even pointing at keypay_list_businesses), so the schema carries the parameter burden. The description adds no format or constraint detail beyond that, making the baseline 3 appropriate.

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 and resource ('One pay run with its total hours, gross wages and net wages'), which separates it from keypay_list_pay_run_summaries. It does not, however, explicitly distinguish itself from the similarly named keypay_get_pay_run_totals, so an agent comparing those two siblings gets no help.

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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as keypay_get_pay_run_totals or keypay_get_pay_run. The agent must infer usage purely from the name and the summary fields listed.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description still adds genuine behavioral context beyond that: bank payment details are redacted from the response, and the returned field set varies by region, both of which affect how an agent should interpret results.

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 tight sentence plus the HTTP route; the payload description is front-loaded and nothing is padded. The trailing endpoint path is mildly redundant with the tool name but is compact and unambiguous.

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 carries the return-value burden and does so reasonably: it names the main totals categories, warns the field set is region-dependent, and notes bank details are stripped. It omits pagination/response-shape details, but for a two-parameter read that is a minor gap.

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% and both required parameters (business_id, pay_run_id) are documented in the schema, including the pointer to keypay_list_businesses. The description adds no parameter syntax or format detail, so the baseline of 3 applies.

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 and resource ('Per-employee totals of a pay run') and enumerates the fields returned (gross, net, tax withheld, super), which is much more informative than the bare title. It does not, however, differentiate itself from the close sibling keypay_get_pay_run_summary, leaving the agent to infer the boundary.

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?

There is no when-to-use guidance at all: no condition, no prerequisites, and no mention of the neighboring tools (pay_run_summary, pay_run_payslips) an agent would have to choose between. The scope is implied by the name and path only.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is fully covered. The description adds nothing behavioral beyond annotations (no auth, rate limit, or not-found behavior); the only extra is the raw HTTP path, which is structural rather than behavioral.

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?

Two short, front-loaded sentences with no filler. The route template is mildly redundant with the schema but useful for cross-referencing the underlying API, so it earns most of its place.

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 read-only single-record get this is mostly adequate, and annotations cover the safety profile. However, with no output schema, the description never hints at what a timesheet line contains or what a missing id returns, leaving a real gap for an agent consuming the result.

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%, with both parameters documented as originating from keypay_list_businesses and keypay_list_timesheets. The description's route template restates the two id slots but adds no format or constraint detail beyond the schema, so the baseline 3 applies.

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 and resource ('One timesheet line by id') and pins down the exact REST route. An agent can tell this retrieves a single timesheet line rather than a collection, though it never names keypay_list_timesheets as the counterpart.

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 'by id' phrasing implies this is the single-record lookup versus the list sibling, but there is no explicit when-to-use statement or condition that selects this over keypay_list_timesheets. Usage is only inferable.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the exact set of returned fields, which is mildly useful, but discloses nothing about auth requirements, error behavior, or response shape beyond the field list.

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?

Front-loaded one-sentence payload that leads with the resource and then enumerates the fields; the trailing 'GET /user' is mildly redundant but confirms the target endpoint. No filler or repetition.

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 partially compensates by naming the returned fields (id, email, display name, time zone). For a parameterless read tool with annotations covering safety, this is close to sufficient; a note on error/empty behavior would make it fully complete.

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?

Zero parameters, so the schema imposes nothing and the baseline is 4. The description correctly signals that no input is needed by framing the call as 'the user this API key belongs to'.

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 clear verb+resource: this retrieves the user the API key belongs to, scoped as 'Employment Hero Payroll user'. It lists the returned fields (id, email, display name, time zone) plus the underlying GET /user endpoint. It's clearly distinguishable from keypay_get_employee, though it never explicitly names that sibling.

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 only implied: the phrase 'this API key belongs to' tells the agent this is the self/current-user call rather than a lookup by id, which subtly separates it from keypay_get_employee and keypay_list_employees. There is no explicit when-to-use, when-not-to-use, or named alternative.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so safety is covered structurally. The description adds genuinely new behavioral context: results are scoped to businesses "this user can access," and it names the underlying endpoint (GET /business, OData), which explains the filter/orderby dialect.

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?

Two sentences, front-loaded with the resource and its key payload fields, followed immediately by the actionable "start here" routing cue. No filler and nothing important buried.

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 enumerates the return fields (id, name, region, legal name, contact details, pay cycle, employee count) and flags the entry-point role. Pagination semantics are left to the schema's top/skip descriptions, which is acceptable but the description could have hinted at paging for a list tool.

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%, and each of top/skip/filter/orderby is already documented with defaults, caps and OData examples. The description adds only "(OData)" as dialect context for filter/orderby, so the baseline 3 applies.

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 (List) and resource (payroll businesses this user can access) and enumerates the returned fields, making it clearly distinct from the singular sibling keypay_get_business. An agent can tell at a glance what it yields 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?

"Start here: most other tools need a business id" gives explicit sequencing guidance that routes the agent to this tool before the many business-id-dependent siblings. It stops short of naming a when-not condition (e.g. use keypay_get_business when the id is already known), so it is strong but not exhaustive.

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

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

The annotations already declare readOnlyHint, destructiveHint, and openWorldHint, so the safety profile is covered. The description adds useful behavioral context by specifying exactly which fields are returned and which sensitive fields are deliberately excluded.

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?

Three sentences, front-loaded with the core purpose, followed by the important field exclusions and a concise filtering example. No wasted words, and the endpoint notation is compact.

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 compensates by listing the returned fields and explicitly stating what is excluded. Pagination is fully covered by the schema parameters, and the annotations cover the safety profile, so an agent has everything needed to call this correctly.

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 all five parameters are already well documented in the schema. The description only repeats an OData filter example that is already present in the filter parameter description, adding no new parameter semantics.

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 ('List the business's employees') and enumerates the basic details returned. It also distinguishes this list from the full employee record by excluding tax file, bank, and super details, which implicitly separates it from keypay_get_employee.

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 usage context for filtering with OData and notes the endpoint, and the exclusions imply when this tool is not appropriate. However, it never explicitly names the alternative tool for full details, so the when-to-use guidance is strong but not complete.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the returned fields and notes the GET/OData endpoint, but omits auth requirements, rate limits, or pagination behavior (though the schema covers pagination parameters). With annotations doing the heavy lifting, a 3 is appropriate.

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 compact sentence front-loads the resource and enumerates key returned fields, then notes the endpoint path. There is no filler or repetition; every part contributes useful context.

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?

No output schema exists, but the description lists the key returned fields, and annotations cover the safety profile while the schema fully documents pagination and filtering. For a simple read-only list tool, this is largely complete, though it could mention pagination behavior or the default result cap to be fully self-contained.

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 all five parameters (top, skip, filter, orderby, business_id) are fully documented in the schema, including OData filter and orderby syntax. The description's mention of OData adds no parameter-level detail beyond what the schema already provides, so the baseline 3 applies.

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 the resource (leave categories of the business) and enumerates returned fields (id, name, unit type, accrual rule), which clearly distinguishes it from sibling list tools like list_leave_requests or list_work_types. The verb 'List' is only in the title, but the purpose remains unambiguous.

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?

No guidance is given on when to use this tool versus alternatives such as get_leave_balances or list_leave_requests. The description only provides resource context and the endpoint path, omitting any prerequisites, exclusions, or comparative routing advice.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered and the description only needs to add context. It does add the shape of the payload (returned fields) but says nothing about pagination, result limits, or default date-range behavior — a meaningful gap for a list endpoint.

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?

Two sentences, zero filler, and the tool's purpose plus returned fields are front-loaded before the filtering options and endpoint. Every clause carries information.

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 read-only list tool with 100% schema coverage, full safety annotations, and no output schema, the description is essentially sufficient — it names the resource, the returns, and the filters. Only pagination/result-size behavior is unaddressed, which is a minor omission rather than a blocker.

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 every parameter is already documented with format and cross-references in the schema. The description restates the filter dimensions (status, dates, category, location, employee) and repeats the status enum values without adding semantics beyond what the schema provides; baseline 3 applies.

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?

Specific verb+resource ('List the business's leave requests') plus an enumeration of the returned fields (employee, category, dates, hours, status, notes) and the underlying endpoint. An agent can distinguish this from keypay_get_leave_request (single record) and the approve/decline siblings without opening any 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?

The description tells the agent it can 'Filter by status, dates, category, location or employee', which implies the retrieval use case, but it never states when to prefer this over keypay_get_leave_request or keypay_report_leave_balances, nor any prerequisites or exclusions. Usage is implied rather than prescribed.

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

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

Annotations already declare readOnlyHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the concrete result fields (id, name, parent, fully qualified name, state) and the OData endpoint shape, which matters since no output schema exists.

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?

A single compact sentence plus the endpoint reference; the resource and its returned fields are front-loaded with no filler. The telegraphic phrasing ('Locations of the business') is terse but readable and nothing is wasted.

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 read-only list tool with a fully documented schema and no output schema, the description covers the resource and return fields adequately; pagination semantics are carried by the schema's skip/top descriptions. Only the parent/hierarchy semantics of the location tree are left unexplained.

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 fully documents top, skip, filter, orderby and business_id with defaults and examples. The description only alludes to OData generally and adds no parameter-level meaning beyond the schema, so the baseline 3 applies.

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 the specific resource (business locations/sites/departments) and enumerates the fields returned, plus the underlying endpoint. It clearly distinguishes itself from siblings like keypay_list_businesses or keypay_list_employees by naming the distinct resource, though it never explicitly contrasts with an alternative.

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?

There is no when-to-use guidance, no prerequisites beyond the schema's note that business_id comes from keypay_list_businesses, and no mention of when a different sibling (e.g. keypay_get_business) would be preferred. Usage must be inferred from the tool name and field list.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the underlying GET /business/{businessId}/paycategory endpoint and that results are OData-backed, which tells the agent filtering/sorting are supported, but says nothing about rate limits or authentication scope. Reasonable but not rich.

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?

A single compact sentence plus an endpoint reference, front-loaded with the resource and its returned fields. Nothing is padded, though the trailing endpoint/parenthetical is more of a documentation flourish than agent-facing 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 field enumeration is genuinely useful and covers what the agent gets back. Pagination (top/skip) and filter syntax live in the schema, so the description doesn't need to repeat them; only default ordering and total-count behavior are unaddressed.

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% – top, skip, filter, orderby and business_id all carry their own semantics in the schema. The only addition is the word 'OData', which signals that filter/orderby follow OData syntax, something the schema already spells out with examples. Baseline 3 is correct.

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 the specific resource (pay categories, glossed as earnings types) and even enumerates the fields returned – id, name, rate unit, loadings, super rate, leave accrual. The 'earnings types' gloss implicitly separates it from keypay_list_leave_categories and keypay_list_work_types, though neither sibling is named.

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?

There is no when-to-use guidance, no prerequisites, and no alternative named. The agent must infer from the name that this is a read of a reference list versus, say, keypay_get_employee for a single record.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds real behavioral context beyond that: the default sort order, that results are the business's pay runs, and that the endpoint is OData-based (implying $filter/$orderby/$top/$skip semantics).

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 the field list are front-loaded, and the endpoint/OData detail is a compact trailing clause. Dense but every element is relevant; the field enumeration is slightly list-heavy but earns its place given there is no output schema.

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 enumerates the returned fields and gives the default sort and endpoint. Combined with the fully documented input schema, an agent has enough to invoke and paginate correctly, though sibling disambiguation is still absent.

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 all five parameters are already documented in the schema. The description reinforces OData semantics and the default ordering but adds no syntax or constraint detail beyond what the schema provides; baseline 3 applies.

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+resource (list the business's pay runs) and enumerates the returned fields, so the agent knows exactly what comes back. It does not explicitly distinguish itself from near-siblings like keypay_list_pay_run_summaries or keypay_get_pay_run, which is the only gap.

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 description states a default ordering ('Newest first with orderby "PayPeriodEnding desc"') but never says when to use this tool versus keypay_list_pay_run_summaries, keypay_get_pay_run, or keypay_list_pay_schedules. Usage is only implied by the tool name and resource.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the useful detail that this is a GET endpoint on the OData summary resource, implying OData query/pagination behavior and no side effects, but it says nothing about permissions (business/API key scope), rate limits, or result size behaviour.

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?

Two tight sentences: the returned payload is front-loaded and the REST/OData endpoint note follows. Nothing is wasted, though the endpoint path is only marginally useful to an agent that already has the schema and could have been replaced with sibling-routing 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 does carry return-value burden and it partially fulfils it by listing the totals returned; however, 'the usual pay run fields' is vague and the field names/serialisation are left implicit. For a five-parameter OData listing tool surrounded by near-synonymous siblings, more routing and result-shape detail would be needed for a higher score.

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 top, skip, filter, orderby and business_id are all documented with types and OData syntax examples and pagination hints directly in the schema. The description adds no parameter-level meaning at all, so the baseline of 3 applies.

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 names the resource (pay runs) and the specific payload it returns (total hours, gross wages, net wages plus standard pay run fields), which is a clear verb+resource statement. It does not, however, distinguish itself from close siblings like keypay_list_pay_runs or keypay_get_pay_run_summary, leaving the agent to infer which 'pay run' variant 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?

There is no explicit guidance on when to use this tool versus keypay_list_pay_runs (list view) or keypay_get_pay_run_summary (single entity). The listing semantics are only implied by the word 'summaries'. No prerequisites, pagination workflow, or exclusions are stated beyond what the schema already shows.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful content beyond that by describing the shape and examples of warnings, but says nothing about pagination, volume of warnings, or auth scoping.

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?

A single tight sentence plus the REST path; the subject ('Warnings on a pay run') is front-loaded with the examples and field list following. Nothing is padded, though the trailing endpoint adds little for an agent that already has the tool name.

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?

No output schema exists, so the description carries the burden of describing the return contents and does so via the type/employee/message enumeration. For a two-parameter read-only tool with full annotation coverage, that is nearly complete; only pagination and warning-count expectations are absent.

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%: both business_id and pay_run_id are documented in the schema, including the pointer to keypay_list_businesses. The description adds no parameter meaning beyond that, so the baseline of 3 applies.

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+resource ('Warnings on a pay run') and enumerates the returned fields (type, employee, message) with concrete examples such as below-award pay or negative net pay. It is clearly distinguishable from siblings like keypay_get_pay_run_summary or keypay_get_pay_run_totals, though it never names an alternative 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?

There is no statement of when to reach for this tool versus the other pay-run tools (summary, totals, payslips), nor any prerequisites beyond the required ids. Usage is only implied by the resource name.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description contributes one genuinely useful behavioral fact — 'Bank and tax account details are removed' — i.e. field-level redaction of sensitive data, which the annotations do not convey; it adds nothing on pagination limits or rate limits beyond what the schema's top/skip text already says.

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?

Two compact fragments with no filler: the resource and returned fields come first, then the endpoint/OData note. Front-loaded and scannable, though the raw GET path adds little beyond what the schema already implies.

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, and the description correctly compensates by listing the returned fields plus the fact that bank/tax details are stripped. Combined with annotations covering read-only safety and the schema covering pagination, an agent has enough to call it correctly; only cross-sibling routing guidance is absent.

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 top, skip, filter, orderby and business_id are all fully documented in the schema, including the next_skip pagination convention and OData v3 filter examples. The description only adds '(OData)' and the path template, which is baseline-level value; no additional parameter meaning is provided.

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+resource (list pay schedules of the business) and enumerates the returned fields (id, name, frequency, last date paid, last pay run), which clearly separates it from siblings like keypay_list_pay_runs or keypay_list_pay_categories. It does not explicitly name those siblings, so a 5 is not warranted.

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?

No guidance on when to choose this over keypay_list_pay_runs (the closest sibling) or on prerequisites beyond the business_id source. The endpoint string and '(OData)' hint imply a filtered list call but do not state usage conditions or exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safe-read profile is covered. The description adds the concrete endpoint (GET /business/{businessId}/timesheet) and the OData query surface, but the pagination cap and defaults it mentions are duplicated in the schema, and it says nothing about result volume or error behavior. Modest added value over the annotations.

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?

Front-loads the purpose, then the filterable fields, then a concrete filter example, then the endpoint and query options. Dense but every clause carries information; the field enumeration is long but justified given there is no output schema.

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 compensates by listing the returned line fields, and it names the pagination mechanism ($top/$skip) that an agent needs to page through results. It is close to complete for a list tool; only the pagination token semantics and any default sort behavior are left to the schema.

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 top, skip, filter, orderby and business_id, including the 1-100 cap and the next_skip chaining hint. The description's added value is marginal — it reinforces that filtering is OData-based and supplies an EmployeeId conjunction example the schema doesn't show — but this is close to a baseline case where the schema does the heavy lifting.

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+resource ('List the business's timesheet lines') and enumerates the fields returned (employee, start/end time, units, work type, location, status, comments, breaks), which is far more specific than the title. It does not explicitly name the sibling keypay_get_timesheet or explain how this list differs from fetching a single timesheet, so it stops short of full sibling differentiation.

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?

Gives concrete usage context: filter by employee or date, with a worked OData example ('EmployeeId eq 123 and StartTime gt datetime''2026-04-01T00:00:00''') and the supported query options ($filter, $orderby, $top, $skip). No exclusions or named alternatives are offered, so it is clear context without routing guidance.

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

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

Annotations already state readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered; the description reinforces this by citing the GET endpoint. It discloses the response field set, which is genuinely additive given there is no output schema, but says nothing about pagination/default page size behavior beyond the '(OData)' tag.

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?

Two terse fragments with the resource front-loaded and no filler. The field enumeration and endpoint path each carry information; the only mild weakness is that it reads as note-style fragments rather than a complete sentence.

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 read-only list tool with a fully documented parameter schema and no output schema, the description covers the essentials by naming the returned fields and the underlying endpoint. It stops short of explaining result ordering defaults or that pagination is driven by skip/top, which would fully round it out.

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 every parameter (top, skip, filter, orderby, business_id) is already documented in the schema with examples and defaults. The description's '(OData)' note only loosely maps to the filter/orderby params and adds no syntax or format detail beyond the schema. Baseline 3 is appropriate.

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 the specific resource (work types of the business) and enumerates the fields returned (id, name, pay category, leave category, short code), which pins down what comes back. It is clearly distinct from siblings like keypay_list_leave_categories or keypay_list_pay_categories, though it doesn't name any 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?

There is no guidance on when to call this versus the other list endpoints, nor any prerequisite or exclusion. The '(OData)' tag hints that filter/orderby/top/skip are supported, but the agent is left to infer the use case.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, so safety is covered. The description adds meaningful non-structured behavior: there is no paging, at most 200 rows are returned, and results must be narrowed to stay within that cap. It doesn't cover auth/permission requirements, but that is a minor gap.

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?

Two dense sentences plus the endpoint path; every clause carries actionable information (report contents, mode selection, row cap, narrowing, endpoint). Front-loaded with purpose and scope, zero filler.

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 enumerates what the report returns (earnings by pay category, tax, deductions, super, net pay) and discloses the 200-row, no-paging behavior. An agent has everything needed to call it correctly.

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 baseline is 3. The description adds selection semantics beyond the schema: pay_run_id is presented as an alternative mode rather than a filter, and narrowing via employee_id/location_id is tied to the 200-row cap, which the schema does not convey.

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 and resource (gross-to-net report per employee) and enumerates the report contents (earnings by pay category, tax, deductions, super, net pay). It is clearly distinguishable from siblings like keypay_report_leave_balances or keypay_get_pay_run_summary.

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 choose either a date range (from_date + to_date) or a single finalised pay run (pay_run_id), and tells the agent how to narrow results (employee_id or location_id). The alternative selection conditions are fully spelled out, not implied.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuinely non-obvious behavior: the report has no paging and is capped at 200 rows, plus the mitigation. It stops short of describing row shape or truncation signaling, but this is real value beyond the annotations.

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?

Three short sentences, zero filler, and the most decision-relevant facts (scope, row cap, sibling alternative) are front-loaded. Every sentence earns its place.

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 a simple 4-parameter read with no output schema, the description covers scope, cardinality limits, mitigation, sibling routing, and the underlying endpoint. Nothing an agent needs to invoke it correctly is missing.

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 100%, so baseline is 3, but the description adds purpose to the two optional filters beyond the schema's terse 'Only this location'/'Only this leave category' – they are the levers for staying under the 200-row cap. That extra semantics justifies a 4.

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+resource+scope: leave balances of all employees as at a date, per leave category. It also distinguishes itself from the single-employee sibling keypay_get_leave_balances, so an agent can route correctly without opening either 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 names the alternative ('For one employee use keypay_get_leave_balances') and gives the condition that selects it. It also tells the agent when to narrow with location_id or leave_category_id, i.e. when the 200-row cap would bite.

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