When I Work MCP by usefulapi

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

Annotations only supply destructiveHint=true and a title; the description adds meaningful behavior — default draft state unless published=true, the open-shift option, and the undo path. It does not explain what 'destructive' entails for a create operation or mention permissions, but it adds real context beyond the annotation.

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

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

Three tight sentences, front-loaded with the action and its scope, followed by lifecycle and undo detail. No wasted words.

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

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

Given 11 params, 100% schema coverage, and no output schema, the description covers the key lifecycle facts (draft/published, open/assigned, undo). It stops short of describing the return payload or auth needs, but the schema does most of the heavy lifting.

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 each parameter is already documented. The description's notes on user_id 0 (open shift) and published duplicate schema text rather than extending it, so 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 ('Create one shift on a schedule') and clarifies the two variants (assigned vs open). This is clearly distinguishable from siblings like update_shift, publish_shifts, and unpublish_shifts 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?

Implies usage context (draft vs published, open vs assigned), and 'Undo by editing it or unpublishing' gestures toward update_shift and unpublish_shifts as alternatives. However, it never states when an agent should prefer publish_shifts at creation time versus publishing later, nor any 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 only declare destructiveHint=true, so most behavioral burden falls on the description, which usefully discloses that the request "starts pending" rather than being auto-approved and points to the cancel mechanism. It adds real lifecycle context beyond the annotations, though it does not cover approval flow, notifications, or overlapping-request 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?

Three tight sentences, front-loaded with the action and default, then lifecycle, then the type-id source, then the raw endpoint. No filler; every clause carries information.

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

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

For a six-parameter creation tool with no output schema and annotations covering only destructiveness, the description supplies the missing lifecycle and prerequisite-routing context. It is essentially complete for correct invocation, with only edge-case behavior (overlaps, approval side effects) 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%, so the parameters are already documented, giving a baseline of 3. The description only restates the calling-user default and points to the sibling tool for type_id values, adding minimal meaning beyond the schema.

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

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

States a specific verb and resource ("Create a time-off request") plus the default target user, which cleanly separates it from wheniwork_get_time_off_request, wheniwork_list_time_off_requests, and wheniwork_update_time_off_request. An agent can identify the operation 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?

Names the prerequisite sibling (wheniwork_list_time_off_types for type ids) and the alternative path for undoing the action (wheniwork_update_time_off_request with status 1). It lacks an explicit "do not use when..." framing, but the routing context is strong and actionable.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds real context the annotations cannot: results are scoped to the token (no id argument), parent accounts return child accounts too, and the call is cheap. It stops short of mentioning rate limits or auth-failure behavior, 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 compact sentences, front-loaded with the action and payload, then the parent/child nuance, then the cheap-verification note and endpoint. No filler and every clause carries information.

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

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

There is no output schema, so the description carries the return-shape burden and does so by naming company name, plan, settings and child accounts. For a zero-parameter read tool with readOnlyHint set, nothing an agent needs to invoke it correctly is missing.

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

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

The tool takes zero parameters, which is the baseline-4 case. The description reinforces this by clarifying that scope comes implicitly from the token rather than any argument, so an agent has no ambiguity about what to pass.

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 ('Fetch the When I Work account (workplace) the token acts on') and enumerates the returned content (company name, plan, settings, child accounts for parent accounts). It is clearly distinguishable from siblings like wheniwork_get_user or wheniwork_list_users because it is scoped to the token's workplace, not a user-supplied id.

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

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

'A cheap way to confirm the credentials work' gives an explicit use case beyond simple retrieval, which is genuinely useful routing guidance. It does not name an alternative tool or state when not to use this one, so it falls short of the full when/when-not/alternatives bar.

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

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

The readOnlyHint annotation already establishes that this is a safe, non-mutating call, so the description's job here is lighter. It usefully discloses what comes back (breaks and publish state) plus the underlying endpoint (GET /2/shifts/{id}), but says nothing about auth requirements, rate limits, or behavior when the id does not resolve.

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 identification method and payload contents, with the endpoint appended as a compact reference. Nothing is padded or restated.

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, read-only lookup with a fully described schema, the description covers the missing output-schema gap by naming the notable return contents. An agent has everything needed to invoke it correctly without further documentation.

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 shift_id and include_repeating_shifts_to are already fully documented, including the repeating-series expansion and date formats. The description only echoes the id-based lookup and adds no meaning beyond the schema, 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 specific verb and resource with scope ('Fetch one shift by id') and adds what the payload contains ('including its breaks and publish state'), which cleanly separates it from the sibling wheniwork_list_shifts by cardinality. It never names a sibling explicitly, so an agent must infer the single-vs-list split, 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?

Usage is only implied: an agent can infer this is the tool to call when it already has a shift id, versus wheniwork_list_shifts when it does not. There is no explicit when-to-use statement, no mention of the update/create siblings, and no note on when to pass include_repeating_shifts_to.

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 description's job is to add more, and it does: it discloses that the response is expanded with the request's message thread and associated user records, which the agent would not know from annotations or schema. It still omits any rate-limit, permission, or not-found 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 purpose and the expanded-return note. The trailing 'When I Work: GET /2/requests/{request_id}' mapping is mildly redundant for an agent but harmless and compact, keeping the whole thing tight.

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 with no output schema, the description covers what the agent most needs to know: that it fetches a single request and that the payload includes the message thread and users. Remaining gaps (error/empty behavior) are minor at this complexity level.

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 request_id is fully documented there, so the baseline is 3. The description's 'by id' adds no format, range, or source detail beyond what the schema already supplies.

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 (Fetch) and resource (one time-off request by id), and the singular 'one ... by id' clearly distinguishes it from the sibling wheniwork_list_time_off_requests. It also names the expanded content (message thread and users), so an agent knows what this returns versus the list variant.

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

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

Usage is only implied: 'by id' signals this is the retrieval-by-identifier path, distinct from the list tool, but there is no explicit when-to-use statement, no prerequisite (e.g. how to obtain a request_id), and no mention of the update/create siblings. Adequate but with clear gaps.

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 as a safe, non-mutating read, so the description's main added value is the field list (name, email, role, positions, schedules, wage). It does not mention permissions, whether wage data is sensitive/owner-restricted, or error behavior for unknown ids.

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 operation front-loaded and the returned fields immediately after; nothing is padded. The trailing API endpoint reference is informational rather than essential, keeping it just short of a 5.

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 readOnlyHint already declared, the main gap left by the absent output schema is what comes back — and the description enumerates the fields, closing that gap well. Only permission or error-path details are 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% with a single self-documenting parameter, so the schema carries the burden. The description adds only 'by id', which is already obvious from the parameter name and description — 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 (fetch one user by id) and enumerates the fields returned, so the agent knows exactly what it gets back. The word 'one' implicitly contrasts with the sibling wheniwork_list_users, though that sibling is never named.

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

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

Usage is implied by the required user_id — you call this when you already have a user id — but the description never states when to prefer it over wheniwork_list_users or wheniwork_list_eligible_users_for_shift, nor any exclusions.

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

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

readOnlyHint=true already declares the safety profile, so the description's main added value is the default date window and the underlying GET /2/annotations endpoint. It says nothing about pagination, result caps, or ordering, which for a range-query list tool would be genuinely useful extra context.

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

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

Two compact sentences: identity and scope first, default behavior second, API endpoint last. 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?

For a read-only 3-parameter list tool with no output schema, the description covers identity, contents, defaults, and endpoint. Only return-shape/pagination details are absent, which is a minor gap against annotations that already signal a safe read.

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

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

Schema coverage is 100%, so start_date, end_date, and no_time_off are fully documented in the schema itself. The description's range default largely restates the schema defaults and adds no format or filter semantics beyond them; 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 (schedule annotations), then enumerates what an annotation actually is — announcements, closed days, blackout dates — which is non-obvious domain vocabulary. No sibling covers annotations, so disambiguation is inherently satisfied.

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 default range ('today through one year out') tells the agent what happens if it omits arguments, but there is no explicit when-to-use/when-not guidance or reference to related tools such as wheniwork_list_time_off_requests for conflicting date information. Usage is only 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?

The readOnlyHint annotation already establishes this is a safe read. The description adds useful behavior beyond that by noting recurring patterns are included when they fall in the window and that the default range is now-to-two-weeks. It stops short of describing pagination, result limits, or ordering, so it is a modest addition over the annotation.

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

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

Three tight sentences, each earning its place: what the resource is, the default scope, and the backing endpoint. The scope semantics are front-loaded before any implementation detail.

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 correctly carries the burden of explaining what comes back (availability events including recurring patterns), and it discloses the default window so an agent can invoke it with zero arguments. It omits return shape detail and pagination, which keeps it just short of 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 every parameter is already documented in the schema (including the managers-only constraint on include_all and the default caller for user_id). The description only restates the default window, adding essentially no semantics 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 and resource ('List availability events') and then defines what an availability event actually is — when people said they can or cannot work, including recurring patterns in the window. That framing cleanly separates it from siblings like list_shifts or list_time_off_requests without needing 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?

It conveys the default scope ('defaults to the caller, from now to two weeks out'), which implicitly tells the agent the tool works out-of-the-box with no arguments. However, it gives no explicit when-to-use versus alternatives such as list_eligible_users_for_shift, and no guidance on when to widen the window or use include_all.

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, and the description reinforces it by disclosing the underlying GET endpoint. The mode mutual-exclusivity (shift_id vs. hypothetical parameters) is useful behavioral context, but nothing is said about pagination, result ordering, or the effect of include_objects on the response.

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 dense sentence: purpose first, mode branching second, endpoint last. No filler, and the most decision-relevant information (which identifier to supply) 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 read-only lookup with a fully documented 7-parameter schema and no output schema, the description covers mode selection and required parameters adequately. It leaves the return payload and pagination unspecified, but those gaps are minor given the annotations and schema.

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

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

Schema description coverage is 100%, so the schema already documents every parameter's meaning and its 'required without shift_id' condition. The description restates the conditional requirement grouping but adds no new syntax or format detail beyond what the schema provides; baseline 3 applies.

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

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

States a specific verb and resource ('find who could take an open shift') and immediately distinguishes the two operating modes: an existing shift via shift_id vs. a hypothetical one via start/end/position_id/location_id. The added HTTP endpoint (GET /2/shifts/eligible) removes any ambiguity about what the tool 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?

Clearly states the two invocation paths and the required parameter set for the hypothetical branch ('start, end, position_id and location_id all required'), which tells an agent when each mode applies. It does not explicitly route against siblings such as wheniwork_list_availability or wheniwork_list_users, but those do not overlap meaningfully with eligibility lookup.

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

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

readOnlyHint=true already declares this is a safe read, and the description is consistent with that. It adds genuinely useful context by explaining that a location's id is the location_id every shift belongs to, but says nothing about return size, pagination, or 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?

Three short sentences, front-loaded with the action and immediately followed by the terminology clarification an agent needs. Every sentence earns its place with no filler.

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

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

For a simple one-parameter read tool with an existing readOnlyHint annotation and no output schema, the definition covers what the tool is and what its ids mean. Only pagination/return-shape detail is absent, which is minor at this complexity.

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

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

Schema description coverage is 100%, so the single optional parameter (only_unconfirmed) is already fully documented in the schema, establishing a baseline of 3. The description does not reference the filter, adding no parameter-level meaning beyond the schema.

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

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

The description gives a specific verb (List) and resource (schedules/locations) and resolves a real terminology trap by stating the API calls a schedule a 'location'. It does not explicitly differentiate itself from siblings such as wheniwork_list_shifts or wheniwork_list_positions, so it stops short of a 5.

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

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

Usage is implied by 'List the schedules in the account', which tells the agent this is the account-wide enumeration call. There is no explicit when-to-use versus when-not-to-use guidance, and no mention of alternatives like wheniwork_list_shifts for shift data.

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 declares this is a safe read, lowering the bar. The description adds only account scope and the underlying endpoint (GET /2/positions); it says nothing about pagination, result ordering, or typical volume, so it adds limited behavioral value beyond the annotation.

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

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

Two short, front-loaded sentences with no filler; the purpose comes first and the endpoint reference is secondary. The endpoint mapping is marginally useful but borders on not earning its place for an agent deciding how to call the 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 low-complexity read tool with annotations and a fully documented single parameter, the definition is adequate. However, with no output schema present, the description could reasonably indicate what a returned position contains, and it omits any pagination note.

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 parameter (show_deleted) and schema coverage is 100%, so the schema fully documents it. The description adds nothing about the parameter (e.g., default behavior for deleted positions), so the baseline of 3 applies.

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

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

Specific verb + resource ('List the positions... in the account') with parenthetical examples that disambiguate the otherwise vague term 'positions' as job roles. It is clearly distinct from neighboring resources like locations, users, and shifts, though it does not explicitly contrast itself with any sibling by name.

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: a read-only listing tool with no stated when-to-use, prerequisites, or named alternatives. For a simple resource listing this is largely self-evident, but there is no guidance on when it is preferred over, say, list_locations or list_users.

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 lowered. The description adds modest value by characterizing the returned payload and noting that open shifts and drafts are optional inclusions, but the permission requirements for those flags (supervisor/manager) live only in the schema, and nothing is said about pagination or how the limit interacts with the result set.

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

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

The scope statement and optional-inclusion clause are front-loaded, and the example questions earn their place by clarifying intent. The trailing 'When I Work: GET /2/shifts' endpoint reference is mildly extraneous for an agent that cannot call the REST API directly.

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

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

For a 13-parameter tool with no required fields and no output schema, the description covers purpose and payload but omits default behavior when start/end are omitted, how limit/pagination behaves, and how the many boolean flags combine. Adequate, but an agent still has meaningful gaps to infer.

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% across all 13 parameters, with formats, bounds, and permission notes already documented per-field. The description adds no parameter-level meaning beyond what the schema provides, so the baseline 3 applies.

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

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

The description gives a specific verb and resource ('List scheduled shifts in a time window') and enumerates the payload contents — who, when, where, position — which clearly separates it from the singular wheniwork_get_shift and from wheniwork_list_shift_swaps. An agent can identify the tool's role 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?

It supplies concrete usage questions ('who is on on Friday?', 'what open shifts are left?') that map cleanly onto the tool's intended calls, giving strong context for when to reach for it. It stops short of naming alternatives or exclusions (e.g., use get_shift for a single shift, list_shift_swaps for swap requests), so it is clear context rather than explicit 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, so the safe-read profile is covered. The description adds the return-content hint ('with the shifts and users involved') and the API endpoint, but does not describe default listing behavior when unfiltered, pagination semantics, or rate limits, so it adds some but not rich behavioral context.

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

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

Front-loaded with the resource, then a compact enumeration of code meanings and the one cross-parameter constraint, ending with the endpoint. No filler sentences; every clause carries information.

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

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

For a 9-parameter, no-required-parameter list tool with no output schema, the description covers the enum decoding and the start/end pairing rule that the schema states but does not explain. It leaves the unfiltered/default behavior and paging defaults unstated, which is a minor but real gap against no 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%, so the baseline would be 3, but the description meaningfully exceeds the schema by decoding numeric enum values the schema only labels generically ('One or more statuses' / 'One or more types'): status 0-5 and type 1/2/3. It also restates the start/end pairing rule. That decoding is genuine added value.

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 ('shift requests: swaps, drops and alerts') plus the scope of what is returned ('with the shifts and users involved'). This clearly distinguishes it from the sibling wheniwork_list_shifts and wheniwork_list_time_off_requests, and it even names the backing endpoint (GET /2/swaps).

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 resource: you call this to enumerate swap/drop/alert requests. The only explicit guidance is the constraint that 'start and end must be given together'. It never states when to prefer this over a sibling or what happens if no filters are supplied, so guidance is only implicit.

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

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

readOnlyHint=true already establishes the safe-read profile, and the description adds value beyond it: it discloses that each request is returned together with its requesting user, and decodes the status lifecycle (0 pending through 4 denied), which is nowhere in the annotations. It still says nothing about pagination volume or the effect of include_deleted_users, so it is not exhaustive.

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 terse fragments: purpose/scope first, then the status legend, then the upstream API route. Nothing is padded and the most decision-relevant content 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 12-parameter, optional-only listing tool with no output schema, the description covers the primary scope (date range) and the returned payload composition. The filter parameters (type, user_id, location_id, since_id/max_id, include_deleted_users) are documented in the schema, so their absence from the description is tolerable, though default date behavior is 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 coverage is 100%, so the baseline is 3 and the schema already documents all 12 parameters in detail. The description goes one step further by supplying the status code legend (0 pending, 1 canceled, 2 accepted, 3 expired, 4 denied), which the schema's bare integer range 0-4 does not convey.

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

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

States a specific verb+resource (list time-off requests) plus scope (date range) and payload composition (requesting users), which distinguishes it from the singular get_time_off_request and the create_time_off_request siblings. It never names a sibling explicitly, so it stops short of full differentiation.

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

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

The date-range framing implies when this bulk listing is appropriate versus the single-record get_time_off_request, but there is no explicit statement of when to use it, no exclusions, and no named alternative. Usage is left 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?

The readOnlyHint annotation already establishes this is a safe read. The description adds useful output context (each type and whether it allows paid time) and the underlying endpoint, but discloses nothing about result shape, ordering, or volume, so it goes only slightly 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?

Two short sentences plus an endpoint reference, with the core purpose front-loaded. The 'When I Work: GET /2/requesttypes' tail is mildly extraneous for an agent but short and harmless.

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

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

For a parameterless read with no output schema, the description covers what is returned (type names and paid status) and why it matters (the id feeds a new request). It is nearly complete; only the exact field name/shape of the id 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline for a parameterless tool is 4. The mention of type_id actually clarifies downstream use rather than input 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?

States a specific verb and resource ('List the time-off types') and even characterizes the returned items (Personal, Sick, Holiday) plus the paid-time flag. It is clearly distinguishable from sibling list tools by resource, though it never names a sibling to sharpen the contrast.

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 via 'Their ids are the type_id for a new request,' which hints this is a prerequisite lookup before wheniwork_create_time_off_request, but it never says when to call this versus that sibling or states any prerequisites explicitly.

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 this as a safe read, so the description's added value is in the payload: it names the returned fields (hours, clock-in/out, length, approval state) and the underlying endpoint GET /2/times. It does not disclose pagination, default time window, or response size, which are the remaining behavioral unknowns.

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 plus an endpoint reference, with the resource definition front-loaded and the practical tip immediately after. No filler, no restatement of the title.

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 correctly compensates by enumerating the fields returned, and annotations cover the safety profile. It is close to complete for a filter-only list tool, missing only window defaults and whether filters are ANDed together.

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

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

Schema description coverage is 100%, so all five parameters are already documented, and the description's only_open note ('who is clocked in right now') essentially restates the schema's own gloss ('Only times with no end yet (people currently clocked in)'). Baseline 3 is appropriate since the schema does the heavy lifting and the description adds no format, combination, or default 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?

States a specific verb and resource (list clocked time entries / timesheets) and enumerates what those entries contain: actual hours worked, clock-in/out times, length, approval state. This cleanly separates it from the shift- and time-off-oriented siblings without requiring the schema to be opened.

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 usage guidance is 'Use only_open to see who is clocked in right now,' which is a parameter tip rather than tool-selection advice. There is no statement of when to prefer this over list_shifts or when-not to call it (e.g. coverage window requirements, whether zero required params means an unbounded query).

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 description's added value is the role-code legend (1 admin, 2 manager, 3 employee, 5 supervisor) and the underlying endpoint GET /2/users. It omits pagination behavior and result size limits, which matters for an account-wide list.

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

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

Three short sentences, front-loaded with the core action and scope. The role-code legend is dense but useful; the trailing 'When I Work: GET /2/users' is largely redundant given the tool name and annotations.

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 and full schema coverage, the description covers scope, filters and role-code interpretation adequately. Only pagination/return-size expectations are absent, which is a minor gap.

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

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

Schema description coverage is 100%, so all six parameters (search, location_id, only_deleted, only_pending, show_deleted, show_pending) are already documented in the schema. The description only restates the schedule and search filters without adding format or default details, 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 ('List the employees, supervisors, managers and admins in the account') plus the scoping options (schedules, name/email search). An agent can distinguish it from write tools like wheniwork_create_shift, but it never contrasts itself with the read siblings get_user or list_eligible_users_for_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?

The phrase 'optionally limited to some schedules or searched by name/email' implies when the filters are useful, but there is no explicit when-to-use guidance and no exclusions. It does not tell the agent when to prefer this over wheniwork_get_user for a single lookup.

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 adds real value: it clarifies that publishing itself sends no notifications, and that the action is reversible via unpublish. Those are non-obvious behavioral traits an agent could not infer from 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?

Three short sentences, each doing distinct work (effect, behavioral caveat, undo path), with the core purpose front-loaded and no filler.

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

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

For a one-parameter mutation with no output schema, the description covers effect, notification behavior, and reversibility. It omits permission/auth requirements and any batching or rate considerations, but nothing essential to 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% and the single 'ids' parameter is already documented in the schema ('The shift ids to publish.'). The description adds no format, ordering, or batch-limit detail beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb ('Publish'), the resource ('draft shifts'), and the observable effect ('so employees can see them'), which cleanly separates it from wheniwork_unpublish_shifts and the create/update shift 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?

It tells the agent the input state this applies to (draft shifts) and names the reverse operation (wheniwork_unpublish_shifts) for undoing it. It stops short of an explicit 'do not use this if...' condition or permission prerequisites, but the routing context is clear.

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

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

destructiveHint=true already flags the mutation; the description adds real substance by explaining the resulting state (published → draft) and the employee-visible effect of hiding shifts, plus the reversal tool. It still omits whether notifications go out or whether unpublished shifts block scheduling, so it is not fully transparent.

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 plus an endpoint reference, with the outcome and the undo path front-loaded. Every clause carries information; nothing is 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 single-parameter state-change tool with no output schema, the definition covers the effect, the visibility change, and the inverse operation. Remaining gaps (side effects like notifications, partial-failure behavior on batches up to 1000 ids) are minor but not negligible.

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 ('ids') and schema description coverage is 100%, so the schema already documents the input fully. The description adds no cardinality, batching, or limit guidance beyond what the schema states, which is the expected baseline.

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

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

States a specific verb and resource ('Return published shifts to draft') plus the user-visible consequence ('hiding them from employees'). It is immediately distinguishable from its sibling wheniwork_publish_shifts, which it explicitly names as the inverse.

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?

Names the alternative and the recovery path ('Undo with wheniwork_publish_shifts'), giving clear context for when to reach for it. It stops short of explicit when-not conditions (e.g. don't unpublish shifts already worked or locked), so it is clear but not exhaustive.

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

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

Goes well beyond the single destructiveHint annotation by disclosing two non-obvious API behaviors: required-on-every-update fields (start_time/end_time/location_id) and that omitted breaks are deleted by the API, with a warning to re-check breaks afterwards. This is exactly the kind of hazard an agent cannot infer from annotations or 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?

Four sentences, each carrying distinct operational payload: capability, required-field echo, breaks caveat, API endpoint. Front-loaded with the verb and no filler, though the mandatory-field and breaks sentences could be marginally tighter.

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

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

For a destructive mutation tool with no output schema and an invisible breaks array, the description supplies every non-obvious fact needed to call it correctly: required echo fields, the silent-break-deletion hazard, and the named endpoint. An agent has all it needs to avoid data loss.

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

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

Schema coverage is 100% so the schema already documents all 12 params; baseline would be 3. The description adds genuine value beyond the schema by explaining the server-side requirement that start_time/end_time/location_id must be echoed back, and by flagging the implicit breaks-array behavior that has no corresponding schema property.

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

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

States a specific verb (change/update) and enumerates the actual mutable aspects — reassign, move, change position or notes — and anchors to the concrete API operation PUT /2/shifts/{id}. Clearly distinguishable from sibling wheniwork_create_shift and wheniwork_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 a concrete procedural instruction: fetch the shift first and pass back start_time, end_time and location_id. However, it never names sibling alternatives (e.g. create vs update vs publish_shifts) or states when-not to use this tool, so routing guidance is implicit rather than explicit.

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

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

Annotations provide only destructiveHint=true, and the description usefully softens/clarifies that by noting the operation is reversible (set the status back). It also supplies the status code semantics that no structured field carries. It does not discuss permissions, side effects on related shifts, or notification 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?

A single dense sentence carries the mutable fields, the status table is inline, and the two constraints plus the API endpoint follow without padding. Front-loaded with the core action; 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?

No output schema exists, but this is a mutation tool where the important caller knowledge — mutable fields, status values, pairing constraint, reversibility, and endpoint — is all present. It stops short of noting permission requirements or the effect of overwriting existing approved time off.

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

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

Schema coverage is 100%, so baseline is 3, but the description meaningfully exceeds the schema by decoding the status integer (0 pending, 1 canceled, 2 accepted/approved, 3 expired, 4 denied) — the schema only says 'New status.' with a 0-4 range. It also reinforces the start_time/end_time pairing rule.

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

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

States a specific verb (Change) and resource (a time-off request), then enumerates exactly what is mutable: status, dates, and hours. It is clearly distinguishable from siblings like wheniwork_create_time_off_request, wheniwork_get_time_off_request, and wheniwork_update_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 concrete operative context — the full status code mapping, the requirement that start_time and end_time be supplied together, and the fact that the change is reversible. It does not, however, explicitly route the agent away from sibling tools such as the read-only get_time_off_request.

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