Papershift MCP by usefulapi

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

Annotations already flag this as destructive, non-read-only, and idempotent, so the safety profile is covered. The description adds genuinely new behavior: the employee is typically notified, existing assignments are overwritten rather than erroring, and the response contains the shift's assigned and applied users. It does not explain what exactly the destructive action destroys or what permissions are needed, so not 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?

Three tight sentences plus an endpoint, with the operation mode and core action front-loaded. No filler; each clause carries distinct information (mode, effect, side effect, return 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?

With no output schema, the description usefully states what comes back (assigned and applied users) and discloses the notification side effect and idempotent re-assignment. It is nearly complete for a 3-parameter write tool; only permission requirements and failure conditions are absent.

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

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

Schema description coverage is 100%, so user_id and shift_id are already documented, establishing a baseline of 3. The description's note about application=true only restates the schema's own wording ("record as an application instead of assigning directly"), adding little new semantics.

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

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

Opens with a mode tag ("WRITE:") then a specific verb+resource: "put an employee on a shift," plus the alternate application mode. This is clearly distinguishable from read-side siblings like papershift_list_shift_assignments or papershift_get_shift.

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 situational context: use it to assign, and pass application=true to record an application instead of a direct assignment. It also states that re-assigning an already-assigned user is allowed, removing a common ambiguity. It stops short of naming an explicit alternative or exclusion (e.g., when to prefer list_shift_assignments for verification).

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, destructiveHint=true and idempotentHint=true, and the description is consistent with all of them ('WRITE'). It adds genuine business context beyond the annotations by explaining what confirmation means downstream (final for payroll and balances), though it never says whether a confirmation can be reversed.

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 fragments, front-loaded with the write semantics and the downstream effect; nothing is padded. The trailing endpoint reference is minimal and supports transparency without dominating.

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, no-output-schema tool with rich annotations, the description covers action, effect, and id sourcing adequately. It omits failure behavior and reversibility, which is a small remaining gap given destructiveHint is already set.

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% for the single parameter, so the baseline is 3; the description earns an extra point by telling the agent where to source a valid time_tracking_id, which the schema's format description does not cover.

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 ('confirm/approve'), the exact resource ('a worked-time entry'), and the business consequence ('counts as final for payroll and balances'). The lead token 'WRITE:' immediately distinguishes it from read siblings like papershift_get_time_tracking and papershift_list_time_trackings.

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 papershift_list_time_trackings to obtain a valid id, which is the key prerequisite for calling this. It does not state when-not to use it (e.g., versus papershift_create_time_tracking or after an entry is already confirmed), so it stops short of full when/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?

Annotations already flag destructive/non-idempotent/openWorld, and the description adds real value on top: approval behavior varies by absence type and account rules, the employee may be notified, and paid hours/vacation days are computed server-side rather than supplied. It stops short of stating what the destructive hint concretely implies or how the employee is notified.

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?

Four short sentences, front-loaded with the WRITE marker and the resource, then prerequisites, then behavioral caveats. 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?

For a mutation tool with no output schema, the description never says what comes back — whether the created absence id is returned or whether the caller must re-query via papershift_get_absence. Safety profile is covered by annotations and prerequisites are covered, so the remaining gap is the response contract.

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 six parameters are documented in the schema itself. The description adds only indirect semantics (server computes paid hours, implying no hours argument) and says nothing about full_day or time_zone formatting beyond what the schema already provides.

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

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

Opens with an explicit verb+resource pair ("WRITE: record an absence ... for an employee") and enumerates the domain (vacation, sick leave). It also names the sibling tools needed to resolve ids, so an agent can tell this apart from read-side siblings like papershift_list_absences or papershift_review_absence.

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

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

Gives concrete preconditions: fetch absence_type_id from papershift_list_absence_types and user_id from papershift_list_users. It doesn't explicitly state when NOT to use this (e.g., versus review_absence for approval decisions), but the usage context is clear enough to act on.

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, destructiveHint=true, idempotentHint=false, openWorldHint=true; the description adds the meaningful behavioral detail annotations cannot: the default resolution of the visible flag (account setting) and the fact that assignments are a separate call. It does not address the non-idempotent/destructive profile (e.g. duplicate shifts if retried), which would be the remaining valuable addition.

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 with the operation class and the core action front-loaded, then the conditional parameter rule, then the follow-up call. No sentence is filler; even "POST /shifts" is a one-token endpoint anchor.

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?

Adequate for an 8-parameter mutation tool: required inputs, the conditional flag, and the next-step workflow are covered, and time formats are handled by the schema. With no output schema, one gap remains — the description never says what comes back (presumably a shift id) that the subsequent assign call needs.

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, but the description adds semantics the schema lacks: the default behavior of visible and the intent behind setting it. It also frames number_of_employees as a planning headcount rather than an assignment, which prevents a misread of the required 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?

Opens with an explicit operation class ("WRITE"), a specific verb+resource ("plan a new shift"), and states the scope (location, working area, headcount). It also names the sibling used for the follow-up step, so the agent can distinguish it from papershift_assign_user_to_shift and the list/get siblings 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 concrete guidance for the one ambiguous parameter ("Set visible to true only if employees should see it right away") and routes the agent to papershift_assign_user_to_shift for staffing. It stops short of stating prerequisites (e.g. that location_id/working_area_id must exist, or how to obtain them), so usage is clear but not fully bounded.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is partly covered. The description still adds real value by stating the consequence — 'It changes the employee's recorded hours and balance' — which tells the agent this is a balance-affecting mutation, not an isolated record. It does not mention required permissions or what happens on duplicate submission (implied only by the non-idempotent hint).

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 compact sentences with the write marker and core action front-loaded, followed by consequence and id sources. There is no filler and every sentence carries distinct 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 six-parameter write tool with a fully documented schema and no output schema, the description covers action, impact, and id provenance well. The remaining gap is the result of the call — whether it returns the created working session or only a status — which matters for a non-idempotent mutation an agent may want to verify afterward.

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 six parameters (including manual_pause as 'Break length in minutes' and ISO 8601 formats) are already documented. The description restates the same fields (start, end, break minutes, location, working area) without adding format, range or default guidance 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?

Starts with an explicit 'WRITE:' verb marker and a specific resource: a worked-time entry for an employee with start, end and break minutes, in a location and working area. The phrase 'after the fact' distinguishes retroactive entry from live clocking, so an agent can separate it from the other create_* siblings without opening a 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 clear context for when to use it (retroactive entry) and tells the agent exactly how to source the three foreign-key ids from papershift_list_locations, papershift_list_working_areas and papershift_list_users. It stops short of naming alternatives or exclusions, e.g. when to prefer papershift_confirm_time_tracking to approve a pending session 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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the returned field set (status, confirmation, hours, vacation days) and the underlying endpoint, but says nothing about not-found behavior, permissions, or rate limits, so it is modestly additive.

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 and id constraint before the field list; nothing is padded. The trailing 'GET /absences?id=.' with a dangling value is slightly rough but 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?

With no output schema, the description usefully fills the return-value gap by naming the fields returned, and the single required parameter is fully covered by the schema. For a simple id-based getter, an agent has enough 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% with a single required 'absence_id' already documented as 'Papershift absence id' with bounds. The description's 'by id' merely restates 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?

The description names a specific verb+resource ('One absence by id') and enumerates the payload fields (status, confirmation, hours, vacation days), which clearly separates it from the bulk list_absences sibling. It stops short of explicitly naming that sibling as the alternative, so it is clear but not maximally differentiated.

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 'One absence by id' implies this is the single-record fetch to use when an id is already known, as opposed to list_absences, but no when-to-use/when-not guidance or alternative is stated explicitly. Usage is inferable rather than instructed.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered elsewhere. The description contributes by disclosing the returned fields (id and name) and the connection-check purpose, plus the underlying endpoint, but adds little beyond 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?

Three short sentences with zero filler: the resource and return shape come first, then the usage hint, then the endpoint. Every sentence earns its place and the tool's identity is front-loaded.

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-parameter, read-only lookup with no output schema, the description does enough by stating the returned fields and the connection-check purpose. It is essentially complete, with only the absence of an explicit action verb as 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?

The tool takes no parameters, which is the baseline-4 case; there is nothing to document and no ambiguity to introduce. The description correctly implies the account is derived from the API key rather than supplied as input.

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 resource ('the Papershift account this API key belongs to') and even the returned fields (id, name), which clearly separates it from siblings like get_user or get_location. The verb is only implied rather than stated, but the resource and scope are 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?

'A quick way to check the connection' supplies one concrete use case, so the agent understands a likely intent. However, there is no explicit when-not guidance and no naming of alternatives among the many sibling get_* tools, leaving routing mostly 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, destructiveHint=false, and openWorldHint=true, and the description adds only the HTTP endpoint path. It does not mention what happens if the id does not exist, whether the call requires account scoping, or anything about the response shape, so it adds little beyond structured data.

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 and cardinality, with no filler. The trailing 'GET /locations?id=.' is a slightly awkward truncation but 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 tool with full schema coverage, annotations, and no output schema, this is minimally sufficient to call correctly. It stops short of describing error behavior or how ids are discovered, which an agent would still need in practice.

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% with 'location_id' documented as the Papershift location id, and the description corroborates that a single id is the input. No added syntax, sourcing guidance (where to obtain ids), or format detail 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 the resource (location) and that it returns exactly one by id, which is enough to distinguish it from the sibling papershift_list_locations. The verb is only implied by the name and the 'GET /locations' fragment rather than spelled out, keeping it short of a 5.

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

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

There is no explicit statement of when to use this tool versus papershift_list_locations, and no prerequisite or failure conditions are given (e.g. what happens for an unknown id). The singular 'One location by id' is the only implied routing signal.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered elsewhere. The description's only additional content is the raw endpoint "GET /shifts?id=", which adds nothing about not-found behavior, permissions, or 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 short fragments, front-loaded with the resource before the endpoint detail, with no filler. The trailing "GET /shifts?id=." is largely redundant with the tool name, but it costs little.

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 full schema coverage and annotations, the minimum is present. Still missing is any hint of what a returned shift contains or what happens when the id does not exist, which is the only burden a terse definition like this leaves.

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 parameter is documented as "Papershift shift id." The description's "by id" merely echoes that, so the baseline 3 for fully-covered schemas 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?

"One shift by id" identifies the resource (shift) and cardinality (single), which implicitly separates it from papershift_list_shifts. But it is a telegraphic noun phrase with no explicit verb, and it never names the list sibling it must be chosen over.

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 versus papershift_list_shifts or the other get_* siblings, and no preconditions such as needing a valid id. The agent must infer that a single known id selects this 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=true and destructiveHint=false, so safety is covered. The description adds genuinely useful behavioral context not in the schema: the response bundles breaks, tags and a computed break total, and the underlying endpoint (GET /working_sessions?id=) is disclosed. It stops short of describing response shape or missing-id 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?

Two short sentences, front-loaded with the resource and then the returned payload. The trailing 'GET /working_sessions?id=.' is slightly awkward with the dangling '=' but gives a cheap endpoint mapping.

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 one parameter, no output schema, and a read-only tool, the description covers the essentials: what is fetched, by what key, and which fields come back. Only the absence of not-found/error behavior keeps it from being 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 coverage is 100% and the single id parameter is fully documented in the schema, so the baseline is 3. The description confirms the id refers to the working session (via the endpoint query string) but adds no format or edge-case detail beyond that.

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: retrieves a single worked-time entry by id, listing the included sub-resources (breaks, tags, break total). This distinguishes it from the sibling papershift_list_time_trackings by scope (one vs. many), though it doesn't name 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 'by id' phrasing implies this is the lookup path when you already have a time tracking id, and the sibling list tool covers browsing. But the description never states when to use this over papershift_list_time_trackings or mentions 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context about what payload comes back (contact data, status, locations, working areas, tags, profile fields) and hints at the underlying GET endpoint, but says nothing about error behavior for missing ids or account 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 short sentences, front-loaded with the key identification and the returned fields. The trailing 'GET /users?id=.' fragment is a slightly noisy artifact but does not impede comprehension.

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 with no output schema, the description compensates by listing the categories of data returned, which is exactly what an agent needs to decide whether to call it. 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?

Only one parameter exists and the schema already documents it at 100% coverage ('Papershift user id.'), so the description adds essentially nothing beyond confirming the lookup is keyed on the id. Baseline 3 is appropriate when the schema does all the work.

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 employee by id') and enumerates the profile facets returned (contact data, status, locations, working areas, tags, profile fields), which clearly separates it from list-oriented siblings like papershift_list_users. It stops short of naming the list counterpart explicitly, but a single 'by id' lookup is unmistakable.

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 'by id' implies this is the single-record lookup versus the list endpoint, but there is no explicit statement of when to prefer it over papershift_list_users or what happens if the id is unknown. Usage is inferable rather than 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?

Annotations already cover the read-only, non-destructive safety profile, so the description's added value is real: it names the returned fields (type title, times, hours, vacation days, confirmation flag), states the 25-per-page page size, and prints the underlying GET /absences endpoint. It omits empty-result and pagination-continuation behavior, which is the only 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?

Three compact sentences with no filler: purpose and scope first, then return contents, then pagination and endpoint. Every clause carries information the 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 paginated list with no output schema, the description supplies the return shape and page size, which is what an agent needs to decide relevance and how to page. Only edge-case behavior (no matches, date-range validation) is 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 all five parameters (including date format and next_page chaining) are already documented in the schema. The description only restates that user_id/location_id are optional filters and the range is inclusive between two days, adding little syntax or semantics beyond the structured fields.

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 absences") plus the defining scope ("fall between two dates"), and parenthesizes concrete record types (vacation, sick leave) to disambiguate the resource. An agent can immediately tell this is a ranged collection read, distinct from papershift_get_absence or papershift_create_absence.

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: a required two-date range, with optional narrowing by employee or location, which tells the agent exactly what a valid call looks like. It does not explicitly exclude alternatives (e.g. "use papershift_get_absence for a single record"), so it stops short of 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 already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds the return shape (id, title, rules) and the endpoint, which is useful context beyond the annotations; pagination semantics live in the schema rather than here.

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 verb and resource, then the returned fields, then the downstream use. 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 simple read-only, two-parameter list tool with no output schema, the description covers scope, returned fields, and the follow-up action. Pagination is fully documented in the schema, so nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% — location_id and page are both documented in the schema, including the 25-per-page and next_page convention. The description only restates that the listing is scoped to a location, adding no format or constraint detail 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?

States a specific verb+resource with scope: 'List the absence types of a location', and enumerates examples and returned fields (id, title, rules). It is clearly distinct from papershift_list_absences and papershift_list_vacation_entitlements by resource, though it doesn't explicitly name a sibling to differentiate 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?

'Use the ids to create absences' points the agent to the downstream workflow with papershift_create_absence, which is real routing guidance. It gives no when-not-to-use condition or prerequisite (e.g., permissions), 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.

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds the real behavioral detail that results come back paginated at 25 per page. It does not disclose auth requirements, ordering, what happens if the range spans more than 25 records beyond pagination, or the shape of each availability record.

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 fragments, front-loaded with the data meaning, then page size, then endpoint. The trailing 'GET /availabilities.' is marginally useful for debugging but borders on filler; otherwise 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 simple read-only list tool with full schema coverage and no output schema, most needs are met, but the description never indicates what fields an availability entry contains (start/end time, type, note), which an agent must know to use the result. Missing that, the definition is adequate rather than complete.

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

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

Schema description coverage is 100%, so page numbering, yyyy-mm-dd formatting, and user_id are already documented in the schema; the baseline of 3 applies. The description's only added detail is the 25-record page size, which the schema also states, so it contributes little beyond the structured data.

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?

Names the specific resource (an employee's marked-available times) and the scope (between two dates, per employee), which separates it from siblings like papershift_list_absences or papershift_list_shifts. The verb is only implied by the name/title rather than stated, and no sibling is explicitly contrasted.

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 versus the other list tools, nor any prerequisites (e.g. whether user_id must be a Papershift user from papershift_list_users). The usage is only inferable from the phrase 'between two dates', which implies a required bounded range.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds pagination behavior (25 per page) and the underlying endpoint, but says nothing about what happens on missing users, empty days within a range, or result ordering.

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?

Four short fragments, front-loaded with what is returned before the usage hint and pagination note. The trailing 'GET /evaluations.' is cheap but largely decorative for an agent.

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 right thing by listing the fields returned per day and giving the page size. Date-range defaults are left to the schema, which covers them, so nothing essential is missing for a read-only list call.

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 four parameters (user_id, range_start, range_end, page) are already documented with formats and defaults. The description only echoes the page size and date scoping, adding no syntax or semantic detail 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?

States a specific resource (an employee's daily evaluations) and enumerates the returned fields (target, planned, actual hours, vacation, compensation per day), which distinguishes it from payroll- or time-tracking-oriented siblings. It does not name any sibling explicitly, so differentiation relies on the field list.

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 for overtime and balance questions' gives a use case, but there is no guidance on when to prefer e.g. papershift_list_target_hours or papershift_list_payrolls, and no exclusions or prerequisites (user_id required, date range required) are surfaced in the prose.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful context by enumerating the returned fields and the underlying endpoint (GET /locations), but is silent on pagination, ordering, or whether results can be truncated for large accounts.

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, no filler. The what-is-returned statement comes first, followed by the dependency cue, which is the right ordering for an agent planning a call sequence.

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 parameters and no output schema, the description carries the return shape burden and does so by listing id, name and status. The only gap is pagination/result-size behavior, which matters for a list endpoint on an open-world API.

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?

The tool takes zero parameters, so the baseline is 4; the description correctly implies no filtering input is needed. Nothing further is required of it on this dimension.

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 clarifies the domain term with "sites/companies inside the account," plus names the returned fields (id, name, status). This cleanly distinguishes it from the singular sibling papershift_get_location.

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?

"Most other tools need a location id from here" is an explicit prerequisite/ordering cue that tells an agent to call this first. It doesn't explicitly say to use papershift_get_location when a single id is already known, so it falls just short of full alternative routing.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds value beyond that by flagging the data as sensitive pay data and stating the page size and underlying endpoint (GET /payrolls). It does not state what permissions are required to read pay data, which is the one meaningful omission.

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?

Four short fragments, front-loaded with the resource and its fields, then sensitivity, pagination, and endpoint. It is telegraphic rather than full sentences, but every element 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?

With no output schema, the description partially compensates by enumerating the returned fields and the page size. Combined with clean annotations it gives an agent enough to call correctly; only permission scope for sensitive pay data is missing.

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

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

Schema coverage is 100%: both page and user_id carry their own descriptions, including the default and the next_page chaining hint. The description only echoes the 25-per-page figure already in the schema, so it adds little beyond what the structured fields provide — 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?

The description names the resource (payroll entries) and enumerates the fields per period (paid hours, salary, bonus, time-account start/end), which makes the result set concrete. It does not explicitly differentiate itself from sibling list tools such as papershift_list_evaluations or papershift_list_time_trackings, but the resource is distinct enough to route on.

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 over alternatives, no prerequisites (e.g. payroll module enabled, permission to see pay data), and no guidance on paging through results beyond the raw '25 per page' fact. The agent must infer usage from the resource name alone.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the useful behavioral detail that the result merges two populations (assignees and applicants), but says nothing about ordering, pagination, or what an empty result means.

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 front-loaded sentence gives the payload content first, followed by the endpoint as a compact hint. Nothing is padded, though the raw REST path is mild noise for an agent that already has the schema.

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

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

With one simple parameter, rich annotations, and no output schema, the description does the important remaining work by describing what the response contains (assignees and applicants with id and name). It stops short of explaining the shape of the returned collection or how to tell assignees from applicants.

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 a single required parameter with 100% schema description coverage, so the schema already carries the semantics ('Papershift shift id.', positive integer). The description only echoes it via the endpoint pattern '?shift_id=', adding no format hints or edge-case guidance beyond that.

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 result set: users assigned to a shift plus users who applied, including which fields come back (user id and name). It is clearly a read of assignments for one shift, distinct in intent from papershift_assign_user_to_shift, though it never names that sibling explicitly.

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

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

Usage is only implied: the required shift_id and the embedded 'GET /assignments?shift_id=' suggest 'call this when you have a shift id and want its participants.' There is no explicit when-to-use, no mention of papershift_list_shifts or papershift_get_shift as alternatives for adjacent 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?

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), but the description adds real context: the fields returned (start, end, headcount, note, visibility), the 25-per-page page size, and the underlying GET /shifts endpoint. It stops short of noting auth requirements, rate limits, or whether pagination totals are exposed.

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?

Four short clauses, front-loaded with the core action and scope, then return fields, then sibling routing, then pagination. Every sentence carries information an agent would otherwise have to infer.

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 no output schema, the description enumerates the returned fields and the page size, and it correctly delegates assignment data to a sibling tool. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so location_id, range_start/range_end, working_area_id, tag_ids, and page are all documented in the schema itself, including date format and next_page chaining. The description only restates the filtering axes already in the schema and adds no format 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?

States a specific verb and resource with scope: "List planned shifts of a location between two dates, optionally for one working area or tags." It also names the sibling that owns a related resource (papershift_list_shift_assignments), so an agent can distinguish it from that tool and from papershift_get_shift without opening a schema.

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

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

Explicitly routes assignment lookups to papershift_list_shift_assignments, which is a clear alternative with a stated condition. However, it gives no negative guidance (e.g., use get_shift for a single known shift id, or limits on range span), so the routing is partial rather than complete.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is clear. The description adds useful semantic context about what tags represent and notes the underlying 'GET /filters' endpoint, but it does not disclose return format, pagination, auth needs, or other behavioral details beyond the annotations.

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

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

The description is a single, front-loaded sentence with no wasted words. The trailing endpoint notation ('GET /filters') is slightly technical but harmless. It is appropriately sized for a simple list tool.

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 listing tool with one required parameter, full schema coverage, and annotations covering safety, the description is largely complete. It explains what is listed and scopes it to a location. Minor gaps like return format are acceptable because no output schema exists and the task is straightforward.

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 is already documented as 'Papershift location id.' The description's phrase 'of a location' aligns with the schema but adds no syntax, format, or additional meaning beyond what the schema provides. 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?

The description states a specific verb and resource (list tags) and scopes it to a location. It also clarifies what tags are by naming the entities they label (shifts, time trackings, employees), which helps distinguish it from other list tools. However, it does not explicitly contrast itself with any sibling tool.

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: an agent can infer it should call this tool when it needs tags for a specific location. There is no explicit guidance on when to use this versus alternatives, no prerequisites, and no exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds pagination behavior ('25 per page') and the underlying endpoint, but says nothing about ordering of returned entries or how the date range interacts with the 'over time' rhythm data.

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

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

Three tightly packed fragments with the resource definition front-loaded and zero filler. The trailing 'GET /target_hours' is the only element that 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 four-parameter read-only list tool with full schema coverage and annotations, the definition covers what the resource is, its periodicity, and its page size. With no output schema, it could say a bit more about the shape of the returned entries (e.g. effective date ranges, next_page), but nothing essential for a correct call is missing.

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

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

Schema coverage is 100%, so page, user_id, start_date and end_date are all documented in the schema itself; the baseline of 3 applies. The description's '25 per page' and 'over time' only restate what the page and date parameters already say.

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?

It names a specific resource (contractual target hours) and enumerates what the record contains (weekly/monthly rhythm, hours per weekday, over time), so an agent knows exactly what data comes back. It doesn't explicitly contrast with related siblings like papershift_list_vacation_entitlements or papershift_list_availabilities, which would have pushed it to 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?

There is no when-to-use guidance: nothing says this is the tool for reading (not editing) contractual hours, nothing about when to prefer it over vacation entitlements or availabilities, and no mention that user_id is required to scope the call. The only hint is the scoping phrase 'An employee's', which the agent must infer.

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

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

Annotations already cover the read-only, non-destructive, open-world profile, and the description adds real behavior: page size of 25, the underlying GET /working_sessions endpoint, and the fields returned. It does not mention limits on date-range span, ordering, or pagination termination, which keeps it 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?

Three compact sentences, front-loaded with the core action and filters, then return fields, then pagination and endpoint. Every sentence carries information an agent would otherwise have to infer.

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 (start, end, break, location, employee, confirmation status). Nothing is said about ordering or auth requirements, but for a simple read-only list tool the coverage is nearly sufficient.

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

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

Schema description coverage is 100%, so all four parameters are already documented including the yyyy-mm-dd pattern and the next_page handoff for paging. The description restates range and employee scoping plus the 25-per-page rule without adding format or constraint detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('List worked-time entries (clock-ins)') and scopes the query by date range and optional employee. It is clearly the collection-level counterpart to papershift_get_time_tracking, though it never names that sibling to make the split 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?

Implies usage via the filter description (start date required, end date and employee optional), so an agent can infer when it fits. But it gives no explicit guidance on when to prefer this over papershift_get_time_tracking for a single entry, or over papershift_list_evaluations for aggregated hours.

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

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

The annotations already declare this as a read-only, non-destructive, open-world operation. The description adds useful context beyond annotations by listing returned fields and stating the 25-per-page limit and GET endpoint, though it does not discuss any auth or 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?

The description is compact and front-loaded, covering the main action, return fields, filters, pagination, and endpoint in a few tight sentences. 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?

For a list tool with annotations covering safety and a fully described parameter schema, the description supplies the essential missing return-field and pagination context. It falls just short of 5 because it does not clarify how this tool relates to papershift_get_user for single-record lookups.

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 parameter semantics are already fully documented in the input schema. The description mentions filtering and pagination, but adds little detail beyond what the schema provides for page, location_id, working_area_id, and tag_ids.

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

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

The description uses a specific verb and resource ('List employees (users)') and names the returned fields, so the operation is clear. It does not explicitly distinguish itself from the sibling papershift_get_user, which is the main remaining ambiguity.

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 that results can be filtered by location, working area, or tag, which implies typical usage. However, it gives no explicit guidance on when to use this tool versus papershift_get_user or other list endpoints, and no exclusions are provided.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds pagination (25 per page) and the underlying GET endpoint, which is useful operational context, but says nothing about permissions needed to read another employee's entitlements or how expiry/carry-over values are computed.

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 resource and returned fields, compact at three sentences. The trailing 'GET /vacation_entitlements' is marginal value for an agent and page size is duplicated from the schema, but nothing is padded or confusing.

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 helpfully enumerates the returned fields (planned days, spent days, expiry, carry-over) and page size, which compensates for that gap. With 100% schema coverage on the four parameters and annotations covering safety, the only remaining gap is permission/scope behavior for reading another user's data.

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, user_id, start_date and end_date are already fully documented in the schema. The description only adds 'for the given period', which vaguely frames the date filters without adding syntax or semantics beyond the schema's yyyy-mm-dd pattern definitions. 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?

Names the resource (vacation entitlements) and enumerates the concrete fields returned (planned days, spent days, expiry, carry-over) scoped to a period. The verb 'list' is only implied from the name/title, but the 'how many vacation days does X have left' framing makes the operation unambiguous and separates it from siblings like list_target_hours or list_absences.

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?

Provides an explicit usage context: answering 'how many vacation days does X have left'. This makes the intended scenario concrete. However, it names no alternatives or exclusions (e.g., when to use list_absences instead for actual absences), so the agent must infer boundaries.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description only adds that the result is a plain list with optional location filtering and that ids are reusable — nothing on pagination, result shape, or volume, so it adds modest value over the annotations.

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

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

Two short sentences plus the endpoint path — scope and filter first, downstream use second, zero filler.

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

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

For a one-optional-parameter read tool with annotations and no output schema, the description covers purpose, scope, and downstream id usage. Only the returned field set is unstated, which matters little without an output 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 coverage is 100% and the single location_id parameter is already documented as 'Only the working areas of this location.' The description's 'optionally for one location' merely restates 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 ('List working areas') and adds a clarifying gloss — departments/stations shifts are planned in — plus the optional location scoping. An agent can distinguish it from papershift_list_locations by that gloss, though 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?

'Use the ids for shifts and time trackings' gives a concrete downstream-use cue, and 'optionally for one location' explains the filter context. There is no explicit when-not or named alternative, but the usage context is clear for a simple lookup 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?

Goes past the annotations by disclosing the downstream consequence of 'confirm' (counts against vacation days and the plan), the 'reset' state transition back to pending, and the external notification side effect, which corroborates openWorldHint. It does not mention permission requirements or whether a rejected request releases any reserved balance, so it stops short of full behavioral disclosure.

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 marker and tightly packed with no filler; every clause about the three actions earns its place. The trailing raw endpoint string ("PUT /absences/{confirm|reject|reset}") is low-value implementation detail for an agent.

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 annotations already covering safety hints, the description supplies the missing decision semantics, side effects, and id-discovery path. Residual gaps are minor: no permission prerequisites and no indication of what the response confirms.

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 explaining what each enum value actually does to the record, whereas the schema only says "The decision." It also tells the agent where to obtain absence_id, adding meaning the integer-typed field does not carry.

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?

Starts with an explicit "WRITE" marker and a specific verb+resource ("decide on an absence request"), then enumerates three distinct actions. An agent can immediately separate this state-transition tool from papershift_create_absence or papershift_list_absences without opening a 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 clear operative context for each action mode and explicitly routes id discovery to papershift_list_absences. It never states the inverse – e.g. that new absences must be created via papershift_create_absence rather than this tool – so one exclusion gap remains.

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