Jet HR MCP by usefulapi

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

Goes well beyond the annotations by disclosing the key side effect (send_notification makes Jet HR notify approvers/employee, gated by confirm_notification) and the error behavior for kind-specific required fields. Remaining gaps are minor: nothing about duplicate/overlapping requests or how to recover from a failed create beyond the validation message.

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 but front-loaded: the write-mutation warning and codename source come first, followed by request shapes, notification semantics, and error handling. Every sentence carries information, though the single paragraph is packed tight for 18 parameters.

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 no output schema and thin annotations, it covers the write semantics, prerequisite lookups, both request shapes and the notification gate. The one real omission is what the call returns (created request id/object), which matters since no output schema exists to document it.

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 already 100%, so the baseline is 3; the description adds synthesized meaning by grouping parameters into day-based vs hourly request shapes and flagging the send_notification/confirm_notification coupling, which is more than the per-field descriptions convey in isolation.

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 ('Create a leave, sickness, remote-work or other presence/absence request for an employee') plus the exact endpoint, making it unmistakable against siblings like jethr_update_absence_request or jethr_create_expense.

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 routes the agent to prerequisites (codename from jethr_list_absence_policies, employee uuid from jethr_list_employees) and states the two mutually exclusive calling shapes: start_date/end_date for day requests vs start_date+start_time+time_duration for hourly. It also tells the agent what to do when extra fields are needed (retry with the fields the validation error names), which removes the main ambiguity for an 18-param tool.

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=false and destructiveHint=false, so the bar is lower, and the description adds real value by explicitly stating 'WRITES to the company's records as a reimbursement request' and disclosing the POST endpoint. The receipt-file exclusion is a non-obvious workflow constraint that the schema cannot express. It stops short of stating permission requirements or duplicate-handling behavior, which is consistent with the non-idempotent hint but never explained.

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 tight sentences with no filler, the write semantics and receipt exclusion stated up front. The nested parentheticals and trailing endpoint make it slightly dense but 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 14-parameter mutation with no output schema, the description covers the critical ambiguities: that it writes, that receipts are out of scope, and how the two amount fields relate. What is missing is whether a response contains the created expense identifier and how conditional fields (car_km/car_cost_km for KM, subkind when policy defines it) should be selected.

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 the baseline is 3; the description earns a step up by disambiguating the confusing amount/amount_total pair and clarifying that amount is EUR while amount_total is in amount_total_currency and equal for EUR. That is meaningful over what the individual field descriptions convey. It says nothing about the many KM-only car_* fields or kind-dependent required fields, which remains a gap.

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 ('Create an expense reimbursement request for an employee') plus the endpoint, so it is unambiguously distinct from the sibling read tools like jethr_list_expenses. It also front-loads the key scope qualifier that receipt files are not part of this call.

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 one useful usage constraint: receipts are not attached here, they are uploaded in Jet HR, which implies a separate flow. However, it never says when to prefer this over alternatives, what prerequisites to gather first (e.g. employee lookup, expense policy / subkind validity), or whether a matching policy must exist before calling.

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 only flag destructiveHint=true; the description goes further by disclosing the concrete side effects (removal from the employee's calendar and balance), irreversibility, and the required confirm gate. That is genuine behavioral context beyond what the structured fields provide.

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 sentences, front-loaded with the action and its permanence, followed by the confirm requirement and endpoint. No wasted phrasing.

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 two-parameter destructive tool with a fully documented schema and annotations, nothing essential is missing; the agent knows the effect, the irreversibility, and the gating parameter. No output schema is needed for a delete.

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 a 3 is the baseline. The description adds that the delete is permanent unless confirmed via confirm=true, reinforcing the schema's const constraint with intent; minor added value above the schema.

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 ('Permanently delete') and resource ('presence/absence request') plus the REST endpoint. No sibling tool performs deletion, so the agent can distinguish it immediately from jethr_update_absence_request and the list/create tools.

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 a precondition ('needs confirm=true') and a consequence ('cannot be undone'), which implies this is the hard-removal path. However, it never says when to choose it over jethr_update_absence_request (e.g. cancelling vs erasing) and names no alternative or exclusion.

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?

readOnlyHint=true already establishes the safety profile, yet the description still adds real value by enumerating the returned payload fields (codename, approval/note requirement, hour-vs-day mode, duration limits) — significant given there is no output schema. It stops short of describing not-found/error behavior or any permission constraints.

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 with the most useful content (the returned fields) front-loaded. The trailing raw endpoint path is slightly redundant but standard and harmless.

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 single-parameter, read-only lookup with no output schema, the field enumeration is the key missing piece and it is present. Minor gaps remain: no guidance on what happens for an unknown/foreign-company UUID.

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 parameter description itself explains the UUID format and points to jethr_list_absence_policies for sourcing it. The description adds nothing beyond that, 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 names the specific resource (a single absence request kind setting) and enumerates the attributes it exposes, so an agent knows exactly what it retrieves. It does not explicitly contrast itself with the sibling jethr_list_absence_policies, though the singular/plural distinction is inferable.

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 use this tool versus jethr_list_absence_policies or why a single-fetch is preferable. The only routing hint (where to obtain the uuid) lives in the schema's parameter description, not in the tool description itself.

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?

readOnlyHint=true already declares this is a safe read, so the bar is lower. The description does add one useful behavioral fact beyond annotations: the response bundles the contractor's collaborations. It says nothing about not-found handling, auth, or whether the collaborations set is paginated or truncated.

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 fragments, front-loaded with the payload scope before the endpoint. The URL fragment is arguably redundant for an agent but is compact and grounds the resource path.

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 of describing the return value and does so only minimally ("with their collaborations"). For a simple one-param read that is close to adequate, but the shape of the collaborations field and error behavior remain unspecified.

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 the single id parameter is documented in-schema with its UUID pattern and provenance ("from jethr_list_contractors"). The description adds no parameter meaning beyond the schema, so 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 single-item scope ("One contractor with their collaborations") plus the underlying endpoint, which distinguishes it from the sibling jethr_list_contractors. It never uses an explicit verb like "get" or "retrieve", but the singular framing plus the required uuid makes the operation 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?

The description contains no guidance on when to use this versus jethr_list_contractors or jethr_get_employee, and no stated prerequisites (e.g. that the uuid must come from a list call). Usage is only inferable from 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?

The readOnlyHint=true annotation already establishes the safety profile, so the description only needs to add context. It does add one useful detail, that the result includes the device's assignment, plus the underlying endpoint, but says nothing about what happens when the uuid is unknown or about any pagination or tenant scoping constraints.

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?

It is very short and front-loads the resource, which is good, but the second sentence is a bare HTTP endpoint that gives an agent little actionable information, and the first sentence is a fragment rather than a clear statement of behavior.

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 one-parameter read tool with an annotation covering safety, this is close to adequate, but with no output schema the description should describe what the returned device object contains beyond the vague phrase 'with its assignment'. The error behavior for an invalid or missing uuid is also 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%, so the single id parameter is already documented with its format and provenance. The description's '{uuid}' path segment mildly reinforces the identifier semantics but also introduces a naming mismatch with the schema's 'id', adding no real meaning beyond the schema.

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 conveys that the tool returns a single company device along with its assignment, which does distinguish it from jethr_list_devices. However, it is a noun phrase rather than a verb+resource statement, and without the title 'Get a device' the fragment 'One company device with its assignment' is only barely a purpose statement.

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 use this tool versus jethr_list_devices, no prerequisite that the id must first be obtained from a list call, and no when-not-to-use conditions. The only routing signal, 'from jethr_list_devices', lives in the schema rather than 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?

The readOnlyHint annotation already establishes that this is a safe read operation, and the description adds useful context by listing what the returned record includes. It does not disclose auth requirements, error behavior, or other operational details beyond the endpoint path.

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 a single compact sentence with the important returned-record information front-loaded. The API endpoint adds a small amount of useful technical context without bloating the definition.

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 read-only getter with full schema coverage and annotations, the description is largely complete because it enumerates the main record contents. It could better distinguish this from the overview sibling and does not describe return structure, though no output schema is provided.

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 both `id` and `as_of_date` are already documented in the schema. The description does not add additional parameter meaning beyond the endpoint path showing the UUID resource.

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 clearly states it returns one employee's full record and enumerates key included areas such as contract, salary, manager, headquarters, and custom fields. It does not explicitly distinguish itself from the sibling `jethr_get_employee_overview`, so it falls 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?

The description gives no explicit guidance on when to use this tool versus `jethr_list_employees` or `jethr_get_employee_overview`. It implies single-employee retrieval but does not state when-not or point to alternatives.

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?

readOnlyHint=true already establishes the safety profile, so the description need not restate it. It does add value by naming the returned fields (job title, contract dates, manager, headquarters, custom fields), which is real behavioral context. It says nothing about not-found behavior or whether custom fields are always populated, but with annotations in place a 3 is fair.

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 with the payload description front-loaded. The raw REST path adds little for an agent that never constructs URLs, but it costs only a line and introduces no ambiguity.

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 one-parameter, read-only fetch with no output schema, enumerating the returned fields is exactly the missing piece and it is supplied. Annotations cover safe read semantics; the only residual gap is how this differs from jethr_get_employee.

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 schema itself specifies the UUID pattern and points to jethr_list_employee_overviews as the source. The description only mirrors the UUID via the endpoint path, adding no syntax or format detail beyond the structured field.

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 (get) and resource (one employee's overview record) and enumerates the payload fields, so an agent knows exactly what comes back. It stops short of distinguishing itself from jethr_get_employee, which is the nearest ambiguous 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?

"One employee's" implies a single-record fetch versus jethr_list_employee_overviews, but no explicit when-to-use or when-not guidance is given. The more important routing decision — overview vs. the plain jethr_get_employee — is left entirely unaddressed.

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, so the safety profile is covered. The description adds only that status and data are returned, with no detail on error behavior when the uuid is unknown or on response shape.

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 sentences, front-loaded with the resource description and followed by the endpoint path, which usefully anchors the tool to the underlying API. No 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?

For a simple one-parameter read tool with annotations and full schema coverage, the essentials are present. With no output schema, however, the vague 'status and data' leaves the return payload underspecified.

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 id parameter already carries a description with its naming convention pattern and source (jethr_list_hirings). The description adds no further meaning beyond the schema, which is the expected baseline.

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 hiring process') and even gives the REST endpoint, making the singular fetch operation unambiguous. It does not explicitly contrast with jethr_list_hirings, so differentiation is only implicit.

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 singular 'One hiring process' plus the {uuid} path, so an agent can infer this fetches a known record. However, there is no explicit when-to-use guidance or exclusion directing agents to jethr_list_hirings for discovery.

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 readOnlyHint annotation already establishes that this is a safe read operation, and the description adds useful behavioral detail: it returns active request kinds with codename, name, approval and attachment rules, plus assigned employees. It also discloses pagination via next_page and the underlying GET endpoint, though it omits auth or rate-limit context.

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 three tight sentences: what is listed, why the codename matters, and how pagination works. It is front-loaded with the resource and contents, and every sentence contributes useful 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 low-complexity, read-only list tool with one optional parameter and no output schema, the description is complete enough. It explains the returned contents, the create_absence_request cross-reference, and pagination behavior, so an agent has what it needs to invoke the tool 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?

There is only one optional parameter, page, and the schema already has 100% description coverage explaining that it is 1-based and should use next_page from the previous reply. The description repeats the pagination instruction but does not add meaning beyond the schema.

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 company's absence policies' and details what is returned, including active request kinds and assigned employees. It cross-references jethr_create_absence_request for the codename, but does not explicitly distinguish this tool from nearby siblings such as jethr_list_absence_requests or jethr_get_absence_request_kind.

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 clear usage context: the returned codename is what jethr_create_absence_request needs, implying this tool is used to look up policy codenames before creating a request. It does not provide explicit exclusions or route the agent away from alternative list/get tools.

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, so the safety profile is covered. The description adds real behavior beyond that: AND-combined filters, client-side status filtering, and paging via next_page passed as page. It stops short of stating page size or total-count behavior.

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 front-loaded sentences that lead with what is returned, then filter/paging mechanics. The trailing raw endpoint string adds little for an agent but costs only a few tokens.

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 it covers paging and filter combination for a 9-param all-optional tool. Gaps are minor: no default page size and no note that status is not a server-side filter parameter.

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 the baseline is 3. The description still earns credit by explaining filter conjunction semantics and the next_page→page paging convention, which the schema does not express, but it doesn't clarify the date-boundary interplay among the six date params.

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 (presence/absence requests) and enumerates what each item contains: status values, kind, dates, hours, note, approver. The list-vs-create/update/delete split from the sibling tools is 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?

It gives a scoping hint ('filters combine with AND') and a status tip, but never says when to reach for this versus jethr_list_absence_policies or jethr_get_absence_request_kind, which the schema itself references for codenames. Usage is implied rather than spelled out.

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?

readOnlyHint=true already covers the safety profile, and the description adds real value beyond it: pagination semantics ('Paged: pass next_page as page') and the exact endpoint (GET /public-api/v1/bonuses/). It does not mention result ordering or size limits, but no contradiction exists with 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 sentences, front-loaded with the resource and its key fields, then the filtering and paging behavior. No filler and nothing 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 and explains paging and filter scope, which is enough to call it correctly. Minor gaps remain on default ordering and whether unfiltered calls span all employees, but nothing essential 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 description coverage is 100%, so page, year, employee and monthly_pay are already fully documented including the 13/14 tredicesima/quattordicesima convention. The description only gestures at the filters at a high level ('one employee, year or month') and adds no syntax or edge-case detail, so 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 payroll bonuses') plus the returned fields (employee, payroll month, amount, kind, note), which lets an agent distinguish this from jethr_list_bonus_kinds. It stops short of naming that sibling explicitly, so differentiation is inferential rather than stated.

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?

'optionally for one employee, year or month' conveys the filtering use case, so an agent knows when to apply the optional params. There is no explicit guidance on when to prefer this over jethr_list_bonus_kinds or jethr_list_payslips, and no prerequisites are stated.

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?

With readOnlyHint=true already declaring the safety profile, the description's job is to add behavioral context, which it does: it discloses the paging contract ("Paged: pass next_page as page") and the underlying endpoint GET /public-api/v1/bonus-kinds/. It stops short of describing the returned fields or whether next_page is null on the last page, so it is good rather than excellent.

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 sentences with the purpose front-loaded before the operational details, and no filler. The trailing bare endpoint is slightly terse/uneven as a sentence but is genuinely useful and costs almost nothing.

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 one-parameter read-only list tool with full schema coverage and readOnlyHint, the description is close to sufficient; it covers purpose, pagination, and endpoint. The remaining gap is that with no output schema an agent learns nothing about the shape of each bonus-kind record or how end-of-pagination is signalled.

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% for the single optional page parameter, so the baseline is 3. The description's "pass next_page as page" restates the same instruction the schema already carries, adding no syntax, default, or bounds information beyond it.

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 ("List the bonus kinds") and immediately disambiguates the ambiguous term by glossing it as "(categories) the company can use in payroll", which is what separates it from the sibling jethr_list_bonuses. It never names that sibling explicitly, so an agent must infer the kinds-vs-actual-bonuses distinction from semantics alone.

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 rather than declared: the description says what the resource is and that it is paged, but never states when to call this versus jethr_list_bonuses or the fringe-benefit-kinds analogue. The pagination instruction ("pass next_page as page") is a helpful procedural hint, but there is no when-not guidance or prerequisite information.

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?

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description usefully adds the underlying endpoint (GET /public-api/v1/clockings/) and paging behavior, but says nothing about result ordering, page size, or whether multiple filters combine as AND.

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 what the tool returns and followed by the one operational note that matters (paging). No filler. The phrasing 'pass next_page as page' is slightly awkward but not wasteful.

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-shape burden and does so by listing the event kinds and attributes an agent will get back, including workplace and location that are not filter parameters. Remaining gaps – ordering, page size, filter combination semantics – are minor rather than blocking.

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 the 8 parameters is individually documented with type, enum, format and cross-reference. The description recapitulates the filterable fields (method values, employee, timestamps) but adds no syntax or constraint 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?

The definition opens with a specific verb+resource ('List time-clock events') and enumerates the event kinds and returned attributes (employee, timestamp, method, workplace, location). This makes it impossible to confuse with the other list_* siblings such as list_employees or list_absence_requests.

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 only guidance is 'Paged: pass next_page as page', which covers pagination mechanics. There is no statement of when to reach for this tool versus other listing endpoints, nor of any preconditions (e.g. that an employee uuid comes from jethr_list_employees – that hint lives in the schema, 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?

readOnlyHint=true already declares the safety profile, so the bar is lower. The description adds genuinely useful behavior — the result is paged and the reply carries a next_page — but says nothing about page size, total counts, empty-result behavior, or what identifying fields each CCNL record contains.

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 what is listed, then the pagination mechanics. Zero filler. The raw endpoint path is arguably redundant metadata but it is cheap and front-adjacent to the paging note.

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 one-parameter, read-only list tool with a fully described schema, the description covers purpose and paging adequately, and the next_page mention implicitly signals a paged response envelope despite no output schema. Only the shape of an individual CCNL record is 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% and the schema's own text already states '1-based (default 1). Use next_page from the previous reply.', which the description largely repeats. With a single fully documented parameter, the baseline 3 applies; no additional semantics are contributed.

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 (List) plus a precisely named resource (national collective labour agreements / CCNL applied by the company), with the acronym expanded so an agent unfamiliar with Italian payroll terminology understands it. It does not explicitly contrast with the many sibling list_* tools, but the resource is unambiguous enough that confusion is unlikely.

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 name and by 'the company applies' — read the CCNL catalogue for the current company. There is no statement of when to prefer this over a sibling like jethr_get_contractor or jethr_list_payrolls, and no prerequisites or exclusions noted. The pagination instruction is invocation guidance rather than selection 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 declare readOnlyHint=true, so the safety profile is covered. The description adds genuine behavioral context beyond the schema by disclosing that the endpoint is paged and that the cursor is passed back via `next_page` — particularly valuable since there is no output schema to reveal that field.

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, zero filler, with purpose stated first and the pagination mechanics and endpoint last. Every clause (scope, filter, paging, path) 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?

For a simple two-optional-parameter list tool with readOnly annotations, the description covers purpose, filtering, and pagination adequately. Without an output schema the response shape is largely unspecified beyond the `next_page` hint, which is the only 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 coverage is 100%, so both parameters are already documented, including the enum values and the 'next_page from the previous reply' hint on `page`. The description's 'optionally by kind' and 'pass next_page as page' restate the schema rather than adding new meaning, 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 names a specific verb and resource ('List the company's headquarters') and clarifies scope with '(legal and operative sites)', which maps directly to the enum values. No sibling tool lists headquarters, so differentiation is trivially satisfied and the agent can act immediately.

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?

'optionally by kind' implies the filter is discretionary and the pagination sentence implies how to continue, giving some usage context. However, there is no explicit statement of when to filter by kind (e.g., when only legal entities are needed) and no exclusions or alternatives, leaving usage largely inferred.

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?

With readOnlyHint=true already covering the safety profile, the bar is lower, and the description adds real context: results are paged and 'next_page' from the prior reply must be passed as 'page', plus the underlying endpoint. It stops short of describing result shape or any rate/scope limits, which keeps it from 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?

Two sentences with zero waste: purpose and optional filters first, pagination and endpoint second. Nothing is repeated or 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?

For a read-only paged list tool with five optional params and no output schema, the description covers what it returns in general terms ('contractors and their collaborations'), all filter dimensions, and the paging contract. Only a brief note on the response envelope would make it 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 coverage is 100%, so all five parameters are already documented in the schema. The description's phrasing of the date 'window' and the contractor/employee filters restates what the schema says, adding no new formatting or edge-case semantics beyond it.

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 ('List external contractors (collaborators) and their collaborations') and names the filter axes, so the scope is unambiguous. It does not explicitly contrast itself with the sibling jethr_get_contractor, which an agent could confuse for fetching a single contractor's details.

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?

Says the results are 'optionally filtered by contractor, linked employee or a collaboration date window', which implies when the filter params are useful. However, it never states when to use this list tool versus jethr_get_contractor for a single record, nor any exclusions or prerequisites.

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?

readOnlyHint=true already tells the agent this is a safe read. The description adds that results are paged and that next_page is fed back as page, but that pagination contract is also spelled out in the page parameter's own schema description, and nothing is said about page size or what a response contains.

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 plus a trailing endpoint reference; the resource and its filters are front-loaded with no filler. The 'Paged: pass next_page as page' fragment is slightly telegraphic but still 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?

For a zero-required-parameter list tool with readOnlyHint and no output schema, the description covers scope, filtering, pagination, and the underlying endpoint. Missing only a note on what paging returns (e.g. next_page presence) or default ordering.

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, including the pointer to jethr_list_employees for the employee uuid. The description only restates that uuid means device uuid and employee means employee uuid, adding no format or edge-case detail beyond the schema.

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 ('List company devices') plus the returned association ('the employee each is assigned to') and the available filters. The 'list' verb plus the filter caveat implicitly separates it from jethr_get_device, but no sibling is named 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?

Says results can optionally be narrowed by employee or device uuid, which implies when to pass filters, but never states when to use this instead of jethr_get_device or how to handle the employee-vs-uuid choice. Usage is inferable rather than explicit.

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 only declare readOnlyHint=true; the description adds real value by disclosing the pagination model ("Paged: pass next_page as page") and the underlying GET endpoint, so the agent knows this is a safe, paginated read. It does not describe default page size or ordering, which is the remaining 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?

Front-loads the core operation, then filters, then pagination in three compact clauses with no filler. The raw endpoint path ("GET /public-api/v1/documents/") is marginally useful and the only low-value fragment.

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 six-filter, all-optional list tool with no output schema, the description covers what is listed, how to filter, what is returned (document metadata), and how to page – enough to invoke correctly. Defaults for missing filters and result ordering/limits are the only unstated details.

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 filter's format (UUID for employee, YYYY-MM for period, ISO timestamps) is already documented in the schema. The description only restates the filter set at a higher level, adding no syntax or cross-parameter semantics beyond the baseline.

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 ("List documents stored in Jet HR") and gives concrete content examples (payslips, contracts, other files) plus what is returned (metadata per document). It stops short of distinguishing itself from the very similar sibling jethr_list_payslips, which could confuse an agent choosing between them.

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 available filtering dimensions (employee, kind name, payroll period, last-update window), which tells the agent how to narrow results rather than dump everything. It offers no exclusion guidance or routing to alternatives such as jethr_list_payslips, so it sits at clear-context without alternatives.

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 only declare readOnlyHint=true; the description adds real context beyond that — the required employee_overview:read scope, an explicit note that salary and personal contact data are absent, and the paging contract. What's missing is the page size or any total-count behaviour, which matters for a paginated 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 with the field set and scope, then paging, then endpoint — a sensible ordering with no filler. The single dense sentence listing nine fields is a little heavy but every element is informative.

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 enumerated field list is doing essential work, and the scope plus paging note round out what an agent needs to call it. Only page size and end-of-results signalling are unstated, which is a minor gap for a read-only 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 coverage is 100% and the schema already says to use next_page from the previous reply. The description restates that mapping ('pass next_page as page') without adding format or edge-case detail, so it sits at the baseline for schema-covered parameters.

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 verb and resource (list employees) and pins down the exact record variant: the lighter overview record with an enumerated field set. It implicitly separates itself from jethr_list_employees and jethr_get_employee_overview via 'lighter overview record' and the plural list, but it never names those siblings, so the boundary is inferable rather than explicit.

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 lighter payload and single required scope suggest this is the cheap enumeration path, but nothing states when to prefer it over jethr_list_employees or when to follow up with jethr_get_employee_overview. No exclusions or alternative routing are given.

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?

readOnlyHint already signals a safe read, and the description adds two things annotations cannot: the payload contains personal data (a privacy/visibility caution) and the result is paged with next_page carried into the page parameter. It omits any note on volume, permissions, or total-count behavior.

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 tight sentences: field manifest first, privacy caution and alternative second, paging mechanics last. The field list is not padding because no output schema exists, so each item 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, enumerating the returned fields is exactly the right compensation, and the personal-data warning plus paging note cover the main risks. Missing only secondary context such as expected volume or whether the listing is company-wide or scoped to the caller.

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 both parameters are already documented, including the next_page-to-page convention. The description restates the paging convention but says nothing about as_of_date (point-in-time resolution), so it adds essentially no meaning beyond the schema; 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 ('List') plus resource ('company's employees') and an explicit enumeration of the returned fields, including salary and contract data. It also names the lighter sibling jethr_list_employee_overviews, so an agent can distinguish this from both that tool and jethr_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?

Explicitly routes the agent to jethr_list_employee_overviews for a lighter payload, which is the main sibling ambiguity. It does not state when to prefer jethr_get_employee for a single record, so the guidance is clear 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?

readOnlyHint=true already establishes the safe-read profile, and the description adds pagination behavior plus the underlying endpoint. It does not describe what the returned policy fields look like, but with the safety trait covered by annotations this is solid added context.

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 with no waste; the content clarification is front-loaded and the paging note follows. Every clause 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?

For a simple one-param read tool with annotations and no output schema, the description covers what the list is and how to page through it. The only minor gap is not indicating the shape of a policy item, which is acceptable given the low complexity.

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 param already documents 1-based paging and the next_page mapping. The description restates that mapping, adding negligible value beyond the schema, so 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 (expense policies) and clarifies the content with a parenthetical: expense kinds and limits per employee. That distinguishes it from the sibling jethr_list_expenses (actual expense records) without naming it 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?

The paging instruction ('pass next_page as page') gives usage mechanics but there is no explicit when-to-use or when-not guidance versus jethr_list_expenses or the policy siblings. Usage is implied by the resource naming.

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, so the safety profile is covered and the description only needs to add context. It does add two useful facts: the endpoint path (GET /public-api/v1/expenses/) and that results are paged with a token-to-parameter mapping. It does not disclose default page size, sort order, or whether the list spans all employees or only the caller's scope.

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: purpose plus returned-field list first, paging behavior second, endpoint last. Every clause carries information an agent needs, and there is 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 parenthetical field list stands in for the return shape, and the pagination contract is spelled out, so an agent can call and iterate correctly. The remaining gap is scope — whether results are company-wide or scoped to the authenticated employee — which matters for a reimbursement 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 parameter's description already documents the 1-based default and the next_page handoff, so the baseline is 3. The description reinforces the loop semantics in the main body ('Paged: pass next_page as page'), which is valuable because the parameter name and the returned token name differ and agents commonly get this wrong.

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 ('List expense reimbursement requests') and enumerates the record fields (employee, amount, currency, kind, status, etc.), so the agent knows exactly what comes back. It is distinguishable from jethr_list_expense_policies and jethr_create_expense by resource and operation, though it never names a sibling to route against.

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 pagination instruction ('Paged: pass next_page as page') gives concrete operational guidance for iterating, which is real usage help. However, there is no statement of when to choose this over jethr_list_expense_policies or jethr_create_expense, and no prerequisites or filtering guidance — usage context is implied by the resource name 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, so safety is covered. The description usefully adds that results are paged and how to advance pages, plus the underlying endpoint path, but says nothing about result volume, ordering, or completeness of the kind set.

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 fragments with no filler; the purpose leads and pagination follows. The raw endpoint path is marginally useful for debugging and does not bloat the text.

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 trivial read-only list with one optional paging parameter, no output schema, and readOnlyHint already set, the description covers what an agent needs to invoke it and paginate. Only return-shape details are absent, and with no output schema 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?

With a single parameter at 100% schema description coverage, the schema already carries the semantics (1-based page, max 100000, use next_page from the previous reply). The description's "pass next_page as page" restates the schema rather than adding new meaning, so 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 fringe benefit kinds") with a clarifying gloss "(categories) available in payroll" that implicitly separates it from the sibling jethr_list_fringe_benefits. It stops short of explicitly stating "use this to get kind IDs, not the benefit assignments themselves," so the sibling distinction is inferred rather than 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?

The description hints at usage (categories available in payroll, paged) but never states when to call this versus jethr_list_fringe_benefits, nor that it is typically a prerequisite lookup for kind IDs. Usage must be inferred from the 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, so the safety profile is covered. The description adds genuinely non-redundant behavior: pagination mechanics ('pass next_page as page') and the shape of the returned records, which matters since there is no output schema.

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 purpose and returning-fields, then filters, then paging. Only the trailing endpoint path adds little for an agent; otherwise there is no 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?

With no output schema, the description usefully names the record fields and the paging token, which is the critical missing piece. It stops short of explaining what 'amount' or 'kind' resolve to, but that is a modest gap for a read-only list.

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 each parameter is already documented with ranges and formats, establishing a baseline of 3. The description only restates the filtering role of employee/year/month and adds no format or edge-case detail beyond the schema.

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?

Uses a specific verb+resource ('List fringe benefits assigned in payroll') and enumerates the returned fields (employee, payroll month, amount, kind), so an agent knows this returns assignments rather than definitions. It never explicitly names jethr_list_fringe_benefit_kinds to draw the distinction, but the word 'assigned' does the differentiation implicitly.

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 states the filters are optional ('optionally for one employee, year or month') and how to page, which implies a browse-then-narrow workflow. It gives no explicit when-to-use/when-not-to-use guidance or pointers to the sibling kind-listing tool, so the agent must infer applicability.

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?

readOnlyHint=true already covers the safety profile, so the description only needs to add context. It does: paged retrieval with 'pass next_page as page' from the previous reply, and the underlying GET endpoint, which signals a plain read with no side effects. It stops short of describing the envelope/next_page field itself, but that is minor.

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, zero filler, with the resource definition front-loaded ahead of filtering and pagination details. Every clause carries information an agent needs.

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 list tool with full schema coverage and no output schema, the description covers scope, filtering, and pagination adequately. Only the response envelope (items plus next_page) is left implicit, which is inferable from the pagination sentence.

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 both parameters are already documented, including the 'use next_page from the previous reply' phrasing the description repeats. The status examples (INCOMPLETE, COMPLETED) are drawn from the enum and add only slight orientation, not new semantics such as mutual exclusivity or default behavior.

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 ('List hiring processes') and disambiguates the vague term 'hirings' with the parenthetical '(drafts and onboarding in progress)'. The plural/collection form plus the status filter clearly separates it from the singular jethr_get_hiring 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?

'optionally by status (for example INCOMPLETE or COMPLETED)' tells the agent when to apply the filter, and the pagination sentence tells it how to iterate. It does not explicitly say when to prefer jethr_get_hiring over this list, but the collection-vs-single distinction is clear from the 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?

readOnlyHint=true already declares this is a safe read. The description adds genuinely useful context: it handles sensitive financial data and is paged, with a mechanical note on passing next_page as page. It does not describe what a page contains (page size, total counts, ordering), so it adds moderate value beyond 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, with the core purpose front-loaded ahead of the sensitivity and pagination notes. Slightly telegraphic ('Paged: pass next_page as page') but 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 three-param read-only list tool with full schema coverage and no output schema, the definition is adequate but omits two things an agent would want: the distinction from jethr_list_payslips and any indication of the response shape or page size. Complete enough to call, not complete enough to choose confidently.

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, including the 1-12/13-14 month semantics. The description adds only the pagination restatement ('pass next_page as page'), which duplicates the schema's page description. 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 ('List the company's monthly payrolls') and names the fields returned (year, month, status, totals). However, it never distinguishes itself from the sibling jethr_list_payslips, which is a real ambiguity for an agent choosing between 'payrolls' and 'payslips'.

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 use this versus jethr_list_payslips or the other list siblings, no prerequisites, no exclusions. The only usage hint is pagination mechanics, which is not a selection criterion.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description's main added content is the pagination mechanic and the raw endpoint path — the endpoint does confirm a GET read. It says nothing about result size, rate limits, or whether the list is complete vs filtered by company.

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 — purpose first, paging second — with no filler. The trailing raw path 'GET /public-api/v1/payslip-extra-deduction-kinds/' adds little for an agent that cannot choose transport, but it is cheap and does not bury the key 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?

A single optional parameter, an explicit readOnlyHint, and no output schema — the description covers purpose and paging, which is most of what's needed. The main residual gap is that, with no output schema, the agent gets no hint about what fields a 'kind' object contains.

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 page parameter already documents 'Page number, 1-based (default 1). Use next_page from the previous reply.' The description repeats that instruction verbatim without adding format or boundary detail (e.g., the 100000 max), so the schema carries the weight.

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: 'List the extra deduction kinds (categories) available on payslips,' with the parenthetical clarifying that kinds are a category catalog. This distinguishes it implicitly from jethr_list_payslip_extra_deductions (the actual deduction records), 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?

The only guidance is pagination: 'Paged: pass next_page as page.' There is no statement of when an agent should call this versus jethr_list_payslip_extra_deductions, nor that this is a reference/lookup list typically used to resolve a kind ID. Usage is implied by the resource name rather than explained.

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?

readOnlyHint=true already declares the safe-read nature. The description adds useful behavioral detail about pagination semantics and the underlying endpoint, but says nothing about auth, rate limits, or result ordering/totals — reasonable but not rich context beyond the annotation.

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 plus an endpoint, with the purpose front-loaded and the pagination rule stated immediately after the filter options. No 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?

For a read-only paged list with no output schema and fully documented params, the description covers what is returned, the optional filters, and pagination. It is nearly complete, missing only sibling-routing guidance and any ordering/count behavior.

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 parameter (page, year, employee, monthly_pay) is fully documented in the schema, including the tredicesima/quattordicesima nuance. The description only restates the filterable dimensions (employee, year, month), so 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 gives a specific verb+resource (list extra deductions applied to payslips) and even enumerates the returned fields (employee, payroll month, amount, kind), so an agent understands what it retrieves. It does not explicitly contrast with siblings like jethr_list_payslips or jethr_list_payslip_extra_deduction_kinds, so it falls 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?

It implies usage through "optionally for one employee, year or month" and gives pagination guidance ("pass next_page as page"), but never states when to choose this tool over the related payslip or deduction-kind listers, nor any 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, so the safety profile is covered; the description adds real context beyond that: it flags the data as sensitive payroll information and documents the paging contract ('pass next_page as page') plus the underlying endpoint. It stops short of describing what a payslip record contains or any auth/rate-limit constraints.

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 purpose, then sensitivity, then paging. Efficient overall, with only mild redundancy in the pagination sentence that echoes the schema's own page description.

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 filtered list with four fully documented optional parameters and no output schema, the description covers purpose, filters, sensitivity and paging adequately. The remaining gap is that it says nothing about what a payslip record contains or the shape of the paged response, which an agent may want before calling.

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 (page, year, employee, monthly_pay) are already documented in the schema. The description's pagination note is essentially a restatement of the page parameter's own description ('Use next_page from the previous reply'), adding no syntax or format detail the schema lacks. Baseline 3.

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 ('List employee payslips') plus the optional filter dimensions (employee, year, month). It is clear what the tool returns, though it never distinguishes itself from the close sibling jethr_list_payrolls, so an agent must 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?

The 'optionally for one employee, year or month' phrasing implies when the filters apply, and 'Sensitive payroll data' hints at a caution posture. But there is no explicit guidance on when to use this versus jethr_list_payrolls or the payslip deduction tools, and no stated prerequisites (e.g., needing an employee uuid from jethr_list_employees, which is only mentioned in the schema).

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?

readOnlyHint=true already covers the safety profile, so the description's remaining obligation is light. It does add the raw endpoint (GET /public-api/v1/terminations/) and pagination behavior, but says nothing about sort order, record volume, or whether all terminations or only current-period ones are returned.

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 purpose before the pagination note. The trailing bare endpoint is marginally useful for error diagnosis but is the weakest part of an otherwise lean definition.

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, so the description is the only place an agent could learn what a termination record contains (employee reference, effective date, type, reason). It never says, leaving the return shape unknown for a list tool whose whole job is returning records.

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 optional parameter is already documented as 'Page number, 1-based (default 1). Use next_page from the previous reply.' The description's 'Paged: pass next_page as page' largely restates the schema, so the baseline of 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 and resource ('List employee terminations') and disambiguates the domain with the parenthetical '(resignations and dismissals recorded in Jet HR)', which matters because the sibling set also contains jethr_list_hirings. It never names an alternative sibling explicitly, but the concept is 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?

Usage is only implied: an agent can infer this is the enumeration endpoint for terminations, and there are no exclusions or alternatives offered (e.g. when to use list_employees vs this tool to find leavers). The only procedural guidance is pagination mechanics, not when-to-use.

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, so the safety profile is covered; the description adds the pagination contract ('pass next_page as page') and the underlying endpoint path, which are real behavioral details. It does not describe the shape of the returned policy objects, but for a read-only list that is a modest gap rather than a blocker.

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 clauses, front-loaded with what the tool lists, then why it matters, then the paging mechanics. Nothing extraneous; even the endpoint path is compact and useful for debugging.

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 one-parameter, read-only list tool with no output schema, the description covers purpose, downstream use, and pagination well enough to call correctly. A brief note on what fields each policy returns would close the last gap, but the agent can discover that from the response.

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 100% schema description coverage and a single optional integer parameter, the schema already documents page, its 1-based default, and the next_page convention. The description's 'Paged: pass next_page as page' largely restates that, so it neither compensates for a gap nor adds new semantics — baseline 3 is right.

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 ('List the company's business-trip daily refund policies') and pins down the domain object precisely enough to separate it from siblings like jethr_list_absence_policies and jethr_list_expense_policies. The parenthetical explaining it supplies trip_name for trip absence requests gives an agent the reason it exists, not just a restatement of the title.

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 clear positive context: this is the lookup to call when you need a valid trip_name for a trip absence request, which implicitly routes agents away from guessing values. It stops short of naming alternatives or stating when not to use it, so it lands just below the top band.

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 only declare destructiveHint=true; the description adds real substance beyond that: a write to company HR records, employee-visible approval/rejection, notification side effects with a confirmation gate, and PATCH partial-update semantics ('Only the fields you pass change'). It omits permissions/auth requirements and whether status changes are reversible, which keeps it from 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?

Front-loaded with the core action, then the side-effect warnings, ending with partial-update semantics and the endpoint. Dense and mostly waste-free; the HTTP path is implementation detail that could be trimmed.

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 13-parameter mutation with no output schema, the description covers the riskiest aspects: write scope, employee visibility, notification gating, and partial-update behavior. Remaining gaps (return payload, applicability of kind-specific fields like puc or assisted_ssn) are minor since the schema labels those.

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, including the send_notification/confirm_notification dependency. The description mostly restates those rules in prose, adding only the grouping of 'dates, hours, note, or its status' — 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 ('Change') on a specific resource ('presence/absence request') and enumerates the mutable dimensions: dates, hours, note, status. The verb alone distinguishes it from the create/delete siblings, so an agent can route correctly 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?

Gives conditional guidance that matters at call time: 'give rejection_reason when rejecting' and 'send_notification=true ... needs confirm_notification=true'. It does not explicitly exclude any case or name a sibling alternative, so it stops short of a 5.

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