RotaCloud MCP by usefulapi

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

Annotations already declare idempotentHint and destructiveHint, so the safety profile is partially covered. The description adds real value beyond that: it flags the operation as a WRITE, states the resulting state transition to booked leave, discloses the employee notification side effect, and gives the underlying endpoint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with the WRITE label first, then the effect, then the endpoint. No filler or redundancy; 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 two-parameter mutation with no output schema and existing annotations, the description covers operation type, effect, side effect, and endpoint. Adequate to call correctly; only minor gaps (e.g. permission/auth requirements, what an already-approved request yields) remain.

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 request_id and admin_message are already documented in the schema. The description adds no syntax, format, or constraint detail beyond what the schema provides, which is the expected baseline when the schema carries the load.

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 (approve a pending leave request) and names the resulting state change (becomes booked leave). This clearly distinguishes it from the sibling rotacloud_deny_leave_request and from rotacloud_create_leave_request.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The word 'pending' supplies a precondition that tells the agent when this tool applies, giving clear usage context. It stops short of explicitly naming the alternative (deny_leave_request) as the action for non-approval cases, so it is not a full when/when-not statement.

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 supply destructiveHint=true, so the description carries most of the behavioral burden and does add real value: it flags the operation as a WRITE, says the request is made 'as that user', and discloses the approval workflow and the User-header auth context. Missing details (irreversibility, conflict handling, response shape) are minor for a create operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single compact sentence, front-loaded with the 'WRITE:' marker and the core action, with no filler. Each clause (action, acting-as semantics, approval destination, endpoint/header) 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 7-parameter write tool with full schema coverage, no output schema, and only one annotation, the description covers the essentials: what it does, who it acts as, and where the request goes. It stops short of describing success/error outcomes or validation constraints that would fully round it out.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all seven parameters including the half-day am/pm enums. The description's 'sent as that user' and 'on behalf of an employee' reinforce the user_id semantics, but this is marginal over what the schema already states; baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('submit a leave request') with scope ('on behalf of an employee') and clarifies the workflow ('for a manager to approve'). It is clear what the tool does, though it does not explicitly name the sibling it complements (rotacloud_approve_leave_request) so differentiation is only implied.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use or when-not-to-use guidance. The 'on behalf of an employee' phrasing hints at a manager acting for staff, but nothing tells the agent how this differs from list/get/approve/deny variants, nor what prerequisites (a requestable leave type) apply.

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 supply destructiveHint=true, so the description carries the rest: it discloses that shifts are unpublished by default and become employee-visible only once published, plus the underlying POST /shifts endpoint. This is meaningful behavioral context an agent needs, though it omits permission/auth requirements.

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, front-loaded sentences with zero filler; the mutation type, key parameter rule, and default visibility are all stated efficiently.

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 write tool with no output schema, the description covers the essentials: create semantics, default unpublished state, open-shift handling. It stops short of explaining return values or auth needs, but the rich schema compensates.

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 8 parameters are already documented. The description's only parameter note ('leave user_id out for an open shift') essentially duplicates the schema's own 'omit for an open shift', adding little 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 ('create a shift on the rota') with a 'WRITE:' prefix that flags it as a mutation. It is clearly distinguishable from update_shift and list_shifts by verb, though it names no 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?

'Leave user_id out for an open shift' gives conditional usage for one parameter, and the publish note clarifies the default state. However, there is no explicit when-to-use vs. alternatives (e.g., update_shift vs. create_shift) or 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?

Beyond the destructiveHint/idempotentHint annotations, it discloses the two-phase preview-then-confirm behavior, per-shift guard re-checks with skip (not error) semantics, post-delete verification reads, and the 1-100 batch bound. This is exactly the extra context annotations cannot carry.

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 WRITE/destructive warning and the confirm workflow, then guard details. Dense but nearly every clause carries operational meaning; the trailing 'DELETE /shifts/{id}' endpoint is the only line with marginal value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive batch tool with no output schema, it covers safety, sequencing, guards, and verification well. It stops short of describing what the preview response contains, which is the one thing an agent must relay to the user before confirming.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3; the description earns above that by clarifying that guards cause a silent skip rather than a failure and that confirm gates actual deletion. It does not add format detail for the numeric guard threshold beyond what the schema already states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource ('deletes shifts from the rota') and immediately states the consequence ('assigned employees lose the shift'). The reference to rotacloud_find_shifts clearly separates this destructive tool from the sibling listing/finding 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?

Gives an explicit workflow: select ids with rotacloud_find_shifts, call without confirm to preview, show the preview to the user, then re-call with confirm: true. The when-not (omit confirm = nothing deleted) is stated outright, leaving no inference needed.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the write/irreversibility profile is covered. The description adds genuinely new behavioral context beyond annotations: the employee is notified, and the target must be a pending request. It stops short of stating permission requirements or error behavior for already-resolved requests.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with an operation-type prefix ('WRITE:'), the effect, the side effect, and the endpoint. Every clause earns its place with zero padding.

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 mutation with no output schema and full annotation coverage, the description is nearly complete: it conveys intent, precondition, and the notification side effect. Minor gaps remain around failure modes (e.g., denying an already-approved request) and auth requirements.

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% ('Leave request id.', 'Reason shown to the employee.'), so the schema fully documents both parameters. The description adds only the path shape /leave_requests/{id}/deny, which duplicates the request_id semantics. 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 ('deny a pending leave request') and even names the underlying endpoint. The verb 'deny' inherently contrasts with the sibling rotacloud_approve_leave_request, but the description never names that sibling explicitly, so differentiation is implicit 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?

The word 'pending' implies a precondition (only pending requests can be denied), which is useful usage context. However there is no explicit when-to-use vs alternatives guidance and no naming of rotacloud_approve_leave_request as the counterpart action.

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 carry readOnlyHint, so the description does the heavy lifting: deleted shifts never match, elapsed duration excludes breaks, the shorter_than_minutes boundary is exclusive (exactly 180 does not match), and pagination completes via a complete flag or next_offset that becomes stale after mutations. These are non-obvious behaviors an agent would otherwise get wrong.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One dense paragraph, but it is front-loaded with purpose, then the bulk-change use case, then pagination and return shape. Every sentence carries operational content; the only cost is that the paging and return-value guidance runs together without visual separation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, and the description fully compensates: it names the return fields (shift_ids plus per-shift summary with UTC times, elapsed_minutes, user, location, role, published), the complete flag, and next_offset. Combined with the deletion caveat, an agent has everything needed to call and page this 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?

Schema coverage is 100%, so baseline is 3, and the description adds the critical definition that elapsed_minutes is end minus start with the break not subtracted, which the schema never states, plus a boundary example and the note that max_results aligns with delete_shifts' 100-id cap. Most remaining parameters (roles, users, locations, published) are left entirely to 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 with the exact filter axes (open/assigned, published, location, role, elapsed duration) and a time range, which pins down scope precisely. It implies a distinction from the other shift-listing siblings by noting it 'reads page after page', but never names rotacloud_list_shifts or rotacloud_get_shift as the non-paginated alternatives, so differentiation is inferred 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?

Gives a clear when-to-use rule: this is the way to select shifts for a bulk change such as rotacloud_delete_shifts, plus a concrete worked example (open shifts under 3 hours = open: true, shorter_than_minutes: 180). It also tells the agent to restart from offset 0 after a delete because positions shift. It doesn't say when a different listing tool should be used instead.

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 the response is per-date availability windows; it says nothing about pagination limits or rate limits, though those are partly handled by the 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?

A single front-loaded sentence plus the endpoint verb. Nothing is wasted, though the 'GET /availability' fragment adds little for an agent that already has the tool name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only range query with a fully documented schema and no output schema, the description is minimally adequate. It omits what 'availability' actually means (shift availability windows vs. conflicts) and any pagination guidance an agent might need when scanning long ranges.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all five parameters (start, end, users, limit, offset) are already documented with formats and semantics. The description adds no parameter-level meaning beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a concrete verb and resource: employee availability per date within a range, returning available/unavailable times. It is clearer than most siblings like list_attendance, though it does not explicitly differentiate itself from adjacent leave/days-off 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?

There is no when-to-use guidance and no mention of alternatives. The agent must infer that this is the tool for checking who can work, versus rotacloud_list_days_off or rotacloud_list_attendance.

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 useful context that the response includes a per-day breakdown and the underlying endpoint, but says nothing about error behavior for missing ids or auth requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short, front-loaded sentences with no filler; the return-content detail comes first. The trailing raw endpoint path is mildly redundant with the tool name but still 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?

For a single-resource getter with no output schema, the description tells the agent what comes back (per-day breakdown), which is the main thing the schema cannot convey. Missing only error/not-found behavior to be fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% with a single documented request_id parameter, so the schema carries the semantics. The description only restates 'by id' without adding format or constraint detail, matching the baseline 3 for a well-documented 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 (get) and resource (one leave request) scoped to a single id, which cleanly separates it from rotacloud_list_leave_requests. It also adds the return shape ('per-day breakdown') beyond the title, but never names the sibling it is contrasted with.

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?

'By id' implies you need a known request_id, so usage is inferable, but there is no explicit when-to-use versus rotacloud_list_leave_requests or rotacloud_get_availability, and no prerequisites or exclusions.

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

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

readOnlyHint=true already establishes the safety profile, so the bar is lower, but the description does add real context: it flags sensitive content ('Contains pay data') and lists exactly which payroll components are returned. It says nothing about pagination behavior, permission requirements, or whether pay data is visible to the calling user, which would matter for a financial-data read.

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 fragments, front-loaded with the resource and scope, then the payload contents, then the endpoint. Nothing is wasted and nothing is 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?

No output schema exists, so the description shoulders the burden of describing the return value — and it does, enumerating pay settings, attendance, leave, overtime, and totals at per-employee granularity. Combined with fully documented pagination params and a readOnly annotation, an agent has everything needed to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% — limit, offset, and pay_period_id all carry clear descriptions, including the cross-reference to rotacloud_list_pay_periods for the id. The description adds no parameter semantics beyond what the schema already documents, 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+resource — retrieving payroll for one pay period, broken down per employee — and enumerates the visible content (pay settings, attendance, leave, overtime, totals). It is clearly distinguishable from rotacloud_list_pay_periods, though it never names a sibling or states the exclusion 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?

No when-to-use guidance, no prerequisites, no mention of alternatives such as rotacloud_list_pay_periods (the source of pay_period_id) or the leave/attendance tools that overlap with its content. The only routing hint lives in the schema parameter description, not the tool description.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered structurally. The description adds nothing behavioral beyond restating the HTTP route — no note on whether a missing id errors, what fields the shift carries, or any access scoping.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two telegraphic fragments with zero padding, and the essential scope ('one shift') is front-loaded. It is efficient, though the endpoint restatement adds little and the style is clipped rather than polished.

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 tool with full schema coverage and a readOnlyHint, little else is strictly required, and there is no output schema to explain. However, with no output schema the description could usefully indicate what a shift record contains or how missing ids behave.

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 shift_id parameter is fully documented in the schema. The description's 'by id' merely echoes the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('One shift by id') and the underlying endpoint, which separates it from rotacloud_list_shifts, create_shift and update_shift. It does not name the siblings explicitly, but the singular/plural distinction is clear.

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 alternatives such as rotacloud_list_shifts or rotacloud_get_user. The 'by id' phrasing implies the precondition of already knowing a shift id, but nothing states when-not-to-use or what to do without an id.

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, but the description adds essentially nothing beyond the annotation: no return shape, no error behavior for a missing/deleted user, no permission requirements.

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 resource scope before the endpoint notation. Nothing is wasted, though the telegraphic style omits context a slightly longer sentence could carry.

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 one-parameter read tool this is nearly sufficient, but with no output schema the description could at least indicate the shape of the returned user record. It leaves the return contract entirely 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 user_id parameter is fully documented in the schema with type and bounds. The description's 'by id' merely echoes this, adding no format or constraint detail beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Get' a user/employee) and constrains it to a single record via 'by id', which implicitly separates it from rotacloud_list_users. It never names the sibling, so an agent must infer the distinction rather than being told.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no mention of the list_users alternative, and no note about prerequisites or what happens for an unknown id. 'One employee by id' only hints at the single-record use case.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds value by disclosing the concrete payload fields and the underlying endpoint (GET /accounts), but it says nothing about whether one or many accounts can return, auth scope, or rate limiting. With annotations covering the safety profile, this sits at a solid baseline.

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 resource and its return fields. The trailing 'GET /accounts.' is mildly redundant but cheap and useful for API mapping, so it is close to optimal without being 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-value burden and does list the key fields. The '(s)' hedge partially signals cardinality, though it could be crisper about whether multiple accounts are possible; overall adequate for a two-parameter, 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 description coverage is 100%, and both limit and offset are already fully documented in the schema (including the next_offset pattern and capping behavior). The description adds nothing about pagination, 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 names the specific resource (the RotaCloud account(s) tied to the API key) and even enumerates the returned fields (name, plan, time zone, employee count), which is far more concrete than a generic 'list accounts'. It does not explicitly distinguish itself from siblings, but 'accounts' is naturally distinct from users/shifts/leave, so an agent can route correctly.

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 stated when-to-use, no prerequisites, and no mention of alternatives. The field list implies this is a discovery/metadata call, but the agent must infer that. Usage is only weakly implied.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description adds what the response contains (clock-in/out, breaks, late minutes, hours, approval state) and the underlying endpoint, but says nothing about pagination behavior, sorting, or empty-result handling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the resource and returned fields. The trailing 'GET /attendance' is marginal value for an agent but adds almost no length.

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 9 parameters, no output schema, and full schema coverage, the description usefully compensates for the missing output schema by enumerating the returned record fields and the required time-range scope. It stops short of describing ordering or how totals/next_offset behave across pages.

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%: the schema already explains the timestamp/ISO formats for start/end, limit capping, next_offset usage, and the filter semantics for users/roles/locations/approved/include_deleted. The description adds no parameter-level detail 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?

States a specific verb (list) and resource (time & attendance records) and enumerates the returned fields (clock-in/out, breaks, minutes late, hours, approval state), which is more than a name restatement. It does not explicitly differentiate itself from the close sibling rotacloud_list_clocked_in, leaving the agent to infer the range-vs-current-state distinction.

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 time-range scope is stated, implying usage for historical/period attendance queries. However, there is no explicit when-to-use guidance, no exclusion of alternatives (e.g. list_clocked_in), and no prerequisites such as permission needs.

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 non-mutating read, so the bar is lower. The description adds the returned field set and the underlying endpoint (GET /users_clocked_in), but says nothing about pagination behavior, volume, or auth beyond what the schema and annotations imply.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence plus the endpoint reference; every clause earns its place and nothing is padded.

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 read-only list with no output schema, the description effectively substitutes for the return-value contract by naming the fields returned. Pagination is covered by the schema, so the definition is essentially complete; only usage routing to siblings is absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and both limit and offset are fully documented in the schema, including the next_offset chaining hint. The description adds nothing parameter-specific, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific real-time query ('who is clocked in right now') and enumerates the returned fields (user, location, role, clock-in time, minutes late, break state), which distinguishes it from rotacloud_list_users and rotacloud_list_attendance without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance and no reference to alternatives such as rotacloud_list_attendance, which covers similar ground. The temporal phrase 'right now' is the only contextual hint.

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 as a safe read, so the bar is lower; the description adds the underlying endpoint (GET /day_notes) and clarifies what a 'day note' is. It says nothing about pagination behavior or result size, though the limit/offset schema fields partly cover that.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single compact sentence that front-loads the resource and its definition, followed by the endpoint as a trailing detail. Nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only list tool with full schema coverage and no output schema, the description supplies the domain meaning of 'day notes' and the location filter, which is enough to call it correctly. Only minor gaps (pagination/return shape expectations) remain.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all five parameters (start, end, limit, offset, location) are already documented in the schema. The description only echoes the location filter ('optionally for one location') without adding format or default semantics beyond what the schema provides, making the baseline 3 correct.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a clear verb+resource ('List day notes') and, crucially, defines the domain term by example ('notices pinned to rota dates, e.g. events or deliveries'). This makes the resource distinguishable from siblings like list_days_off or list_shifts, though it does not explicitly name a sibling to contrast with.

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 location' implies the filtering context, and the resource is distinct enough from siblings that misuse is unlikely. However, there is no explicit when-to-use/when-not statement or named alternative, so guidance remains implicit.

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

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

readOnlyHint=true already tells the agent this is a safe read. Beyond that the description only restates the resource and appends the raw endpoint path (GET /days_off), adding no rate-limit, pagination-behavior, or result-shape context that the annotations don't already cover.

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 the resource statement front-loaded and no filler. Terse to the point of being under-specified, but nothing is redundant 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?

Five parameters and no output schema, yet the description covers only the date-range scope. It does establish result granularity ('per date in a range'), but says nothing about what a day-off record contains or how pagination should be driven, which the schema only partially compensates for.

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 start/end/limit/offset/users are already fully documented in the schema. The description's phrase 'per date in a range' loosely maps to start/end but adds no format, default, or filtering semantics beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a concrete resource (employees' scheduled days off) scoped to a date range, which an agent can distinguish from generic schedule tools. However it does not differentiate from close siblings such as rotacloud_list_leave or rotacloud_list_day_notes, leaving the agent to infer the boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no when-to-use guidance and names no alternative. With siblings like rotacloud_list_leave, rotacloud_list_leave_requests, and rotacloud_list_day_notes, an agent gets no help choosing between them.

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, and the embedded 'GET /holiday_allowances/{year}' reinforces that this is a non-mutating read. The description usefully details what each row contains, but says nothing about pagination limits or throttling behavior beyond what the schema already spells out.

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: returned fields first, endpoint second. Every clause carries information and nothing is padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description does the work by naming the returned attributes, which is enough for an agent to know what it gets back. The remaining gap is pagination semantics on the return side, which the schema documents for input only.

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 year/limit/offset semantics are fully documented in the schema. The description only restates that the data is scoped to a leave year, adding no new parameter meaning. 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 a clearly distinct resource (holiday allowances per employee per leave year), and it enumerates the returned fields (default/custom allowance, unit, carried over). No sibling tool covers holiday allowances, so the agent can disambiguate 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?

The description states what the tool returns but gives no guidance on when to choose it over near-neighbours such as list_leave_types or list_leave, nor any prerequisite context. Usage has to be inferred purely 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?

readOnlyHint=true already establishes a safe read, so the description's job is to add behavior beyond that. It does: the default exclusion of pending/denied/expired requests is disclosed, telling the agent that a plain call silently drops those records. It does not discuss pagination behavior, but limit/offset semantics are covered in the 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?

Two dense sentences plus the endpoint path. Return fields come first, filtering options second, defaults third - front-loaded with zero filler and no repetition of schema content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-parameter, zero-required read tool with no output schema, the description covers what is returned, how to narrow it, and the default-filtering trap. Pagination guidance is only in the schema, and no output shape is described, but the field list gives an adequate sketch of 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?

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the shared default semantics behind the four include_* booleans (excluded unless asked for), which the schema only states per-flag as 'Include X' without saying what the default is.

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 booked leave) and enumerates the returned fields (type, user, dates, hours, status), which is more than the title offers. It also implicitly routes away from rotacloud_list_leave_requests by noting that pending/denied/expired requests are excluded by default, but 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?

Gives clear usage context: filter by date range or leave year, by users, by leave types, and notes the default exclusion of pending/denied/expired requests with the implication that include_* flags opt in. It stops short of naming an alternative tool (e.g. rotacloud_list_leave_requests) for pending requests, so no explicit when-not 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?

readOnlyHint=true already tells the agent this is a safe read. The description adds that it returns the employee's message and half-day detail and names the backing endpoint (GET /leave_requests), but says nothing about pagination behavior or default ordering beyond what the schema's limit/offset already imply.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One tight sentence plus an endpoint reference; the scope qualifier is front-loaded and every clause carries information. Slightly terse in that '(and past ones)' is ambiguous about whether it means filtered history or closed requests.

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 helpfully enumerates the returned fields (user, leave type, dates, half days, message), which is what an agent needs to decide whether this tool answers its question. A note on ordering or default pagination 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 description coverage is 100%, and the limit/offset/include_deleted descriptions are already detailed. The description adds no parameter guidance, so the baseline of 3 applies – the schema carries the full burden.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource (list leave requests) and narrows the scope to those awaiting a decision plus past ones, then enumerates the returned fields. It does not explicitly differentiate itself from close siblings like rotacloud_list_leave or rotacloud_get_leave_request, but the scope qualifier makes the intent readable.

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 phrase 'awaiting a decision (and past ones)' implies the retrieval context (pending approvals plus history), which is useful, but there is no explicit when-to-use versus rotacloud_get_leave_request for a single request or rotacloud_list_leave. Usage is implied rather than directed.

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 this is a safe, non-mutating read, so the description carries a lower burden. It adds useful detail about what each record contains and cites the underlying endpoint, but says nothing about listing completeness, ordering, or pagination behavior beyond what the schema already documents.

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 zero filler; the resource and its returned fields are front-loaded and the endpoint reference is a useful trailing anchor. Every element earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description sensibly compensates by naming the fields returned (id, short name, requestability). Combined with the fully documented pagination parameters, an agent has enough to call and interpret this correctly, though ordering and total-count behavior are left unstated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the two pagination parameters are fully documented in the schema, including limit caps and offset chaining. 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?

States a specific verb and resource ('List leave types') and goes further by enumerating representative values (Holiday, Sickness, Unpaid) and naming the returned fields (id, short name, requestability). This is clearly distinguishable from siblings such as rotacloud_list_leave or rotacloud_list_leave_requests, which deal with actual leave entries rather than the type catalogue.

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: it is apparent this feeds valid leave-type IDs into tools like rotacloud_create_leave_request, but the description never states when to call it or how it differs from rotacloud_list_leave / rotacloud_list_leave_requests. No exclusions or prerequisites 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?

Annotations already declare readOnlyHint=true, so the safe read nature is covered. The description adds the endpoint (GET /locations) and the shape of the payload (address, time zone, managers), which is modest extra value; it says nothing about pagination behavior or rate limits beyond what the schema params already state.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with zero filler; the resource and its payload fields come first, endpoint second. 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 read-only list tool with fully documented params and an annotation covering the safety profile, the description is close to complete, even naming the returned fields in lieu of an output schema. Only pagination/return-size behavior is left to the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all four parameters (ids, limit, offset, include_deleted) are already documented with paging semantics in the schema. The description adds no parameter-level information, 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 (locations), and disambiguates the term by glossing it as 'sites/branches' and naming the returned fields (address, time zone, managers). It does not explicitly differentiate from siblings, but no sibling covers locations, so the resource noun is sufficient to distinguish it.

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 verb/resource: call this to enumerate locations. There is no explicit when-to-use, no exclusions, and no pointer to alternatives (e.g. get_user for managers), leaving context to inference.

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 usefully adds that results are overlap-filtered and enumerates returned fields (id, name, start/end, locked), but says nothing about ordering, pagination behavior, or empty-result handling beyond what the schema already implies.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence carries the scope and payload, with the endpoint appended tersely. No filler; 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?

With no output schema, the description compensates by listing the returned fields, and the schema already covers pagination parameters. It is nearly complete; only ordering and pagination semantics in the response are left implicit.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so start, end, limit, and offset are already documented with formats and constraints. The description adds no parameter detail beyond the generic 'date range', so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (List) and resource (pay periods) and adds scope — 'overlapping a date range' — plus the returned fields. It is clear what the tool does, though it never names or distinguishes itself from the nearby rotacloud_get_payroll 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?

The overlap-based date range implies when this list is appropriate, but there is no explicit when-to-use guidance and no routing away from rotacloud_get_payroll or the other list_* tools. Usage is only inferable.

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

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

readOnlyHint=true already declares the safe-read profile, so the description doesn't need to restate it. It adds the endpoint (GET /roles) and the shape of the returned records, which is mild extra context, but says nothing about pagination behavior or how deleted roles appear even though include_deleted exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two compact sentences, zero filler, with the core purpose and returned fields front-loaded before the endpoint. Nothing is repeated from the title or schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple filtered list tool with no output schema and annotations covering safety, the description is largely sufficient: purpose, returned fields, and endpoint are covered, and pagination is handled by the schema. It could be marginally improved by clarifying include_deleted behavior, but no critical gap remains.

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 (ids, limit, offset, include_deleted) are already fully documented in the schema, including pagination semantics and the next_offset convention. The description adds no parameter-level meaning beyond that; 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 ('job roles (positions)'), and the parenthetical disambiguates roles-as-positions from any permission/account role concept among the many list_* siblings. It also names the key fields returned (colour, default break, pay rate), so an agent knows exactly what it retrieves.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no when-to-use or when-not-to-use guidance and does not mention alternatives or prerequisites. Nothing tells the agent when to reach for this rather than rotacloud_list_users or rotacloud_get_user, beyond the obvious 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?

With readOnlyHint=true already declaring the safe-read profile, the description adds real value beyond annotations: it enumerates the response fields (break, location, role, notes, published and acknowledged state) and clarifies the open-shift semantics (null assigned user). It also names the underlying endpoint (GET /shifts). Pagination behavior is left to the schema fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the core action and scope, then the filter capabilities. Every clause carries information: the field list doubles as response documentation and there is no redundant padding.

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 usefully enumerates the returned fields, and the read-only nature is covered by annotations. For a 10-parameter list tool with full schema coverage the essentials are present; only pagination/capping behavior is left entirely to the schema rather than the description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all ten parameters including start/end formats, limit, offset, and filter arrays. The description restates the filter set (users, locations, roles, open, published) and Unix-seconds times but adds no syntax or constraints beyond the schema; baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("List rota shifts") plus the time-range scope, so an agent can immediately tell it is a read/list tool. It does not explicitly name the sibling it differs from (rotacloud_get_shift for a single shift, rotacloud_list_attendance for attendance), so differentiation is inferable 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?

"Filter by users, locations, roles, open or published" implies the narrowing use case, giving implied usage guidance. However there is no explicit when-to-use vs alternatives guidance (e.g. use this to enumerate vs get_shift for one shift) and no exclusions or prerequisites, leaving the agent to infer the context.

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, so the bar is lower. The description adds the GET endpoint and the shape of returned records, but says nothing about pagination behavior, default filtering of deleted requests, or result ordering beyond what the schema already documents.

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 action and followed by the returned content. Every clause carries information and nothing is padded.

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 usefully names the returned fields (status, shifts, users). Combined with 100% parameter coverage and a readOnly annotation, an agent has enough to call this correctly, though it lacks guidance on result volume or pagination expectations.

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%: limit, offset, and include_deleted are each explained in the schema itself (including the next_offset chaining hint). The description names no parameters, so it adds nothing here; 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 shift swap requests') and enumerates what the payload carries (status, shifts, users involved), so an agent knows exactly what it retrieves. No other sibling targets swap requests, so no differentiation is required. It stops just short of a 5 because it doesn't contrast itself with adjacent list tools such as rotacloud_list_shifts.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no when-to-use context, no prerequisites, and no alternatives – it never says when to reach for this over rotacloud_get_shift or rotacloud_list_shifts. Only the resource name implies usage.

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 useful context by listing the returned fields and the underlying GET /users endpoint, but says nothing about pagination constraints, auth, or rate limits beyond what the schema already states.

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 the endpoint token; the return fields come first and the usage hint second. Nothing is wasted and the reader is front-loaded with the important 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?

With 100% schema coverage (including pagination via limit/offset/next_offset) and readOnlyHint covering safety, the description supplies the missing framing: what fields come back and why to call it. No output schema exists, but the field enumeration largely compensates, leaving only minor gaps like deleted-user 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%, so ids, limit, offset, locations, and include_deleted are already fully documented in the schema. The description adds no parameter-level meaning beyond that, which is the baseline 3 case.

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 (employees/users), and enumerates the returned fields, so the agent knows exactly what this tool yields. It does not explicitly distinguish itself from the sibling rotacloud_get_user (single-user lookup), so it falls short of the top band.

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?

"Use it to map user ids in shifts, leave and attendance to names" gives a concrete context for when to reach for this tool. There is no explicit when-not guidance or named alternative (e.g. get_user for a single id), so it is clear but not complete routing guidance.

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

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

Annotations declare idempotentHint=true and destructiveHint=true, so the safety profile is already covered. The description adds real behavioral context beyond that: publishing triggers employee visibility and notifications, which is a side effect an agent should know before invoking.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One short sentence front-loading the WRITE marker and the effect, followed by the endpoint. No wasted 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 one-parameter tool with full schema coverage, no output schema, and annotations covering idempotency/destructiveness, this is nearly complete. It could mention the 500-shift batch limit or whether publishing is reversible, but those are minor gaps.

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 there is a single, well-documented parameter (shift_ids). The description adds no extra detail about the parameter, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (publish) and resource (shifts), plus the concrete effect: assigned employees see them and get notified. This clearly separates it from rotacloud_create_shift, rotacloud_update_shift, and rotacloud_list_shifts.

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 conveys when this operation matters (making shifts visible/notifying employees), which implies usage context. It does not, however, name alternatives or state preconditions, such as whether the shifts must already exist or be approved.

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 idempotentHint=true and destructiveHint=true, so the bar is lower. The description adds genuinely useful context beyond them: the merge/partial-update semantics ('Only the fields you pass change') and the underlying operation (POST /shifts/{id}), which tells the agent the request shape. It does not spell out what a destructive overwrite actually damages or any auth/permission requirement, so it falls short of 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 short sentences with zero filler. The operation type is front-loaded, the field list and partial-update rule follow, and the endpoint is appended last — every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 9-parameter mutation with no output schema, the description covers the field scope, partial-update behavior, and the HTTP route, and the annotations carry the safety profile. It stops short of noting permission requirements or what the response returns, but nothing essential for correct invocation 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 the schema already documents every parameter including format strings for start_time/end_time and the null-opens-a-shift semantics for user_id. The description's field list merely mirrors the schema properties and adds no format or constraint 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?

States a specific verb+resource ('change a shift's times, assignee, location, role, break, notes or published state') and even leads with 'WRITE:', which immediately distinguishes it from read siblings like rotacloud_get_shift and rotacloud_list_shifts. An agent can tell this is the update-shift mutation 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?

The 'Only the fields you pass change' phrasing implicitly conveys patch-style usage, but there is no explicit when-to-use guidance or exclusions. Notably, the sibling rotacloud_publish_shifts exists while this tool can also flip published state, and the description never routes the agent between them — a real ambiguity it leaves unresolved.

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