when-i-work

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

The destructiveHint=true annotation only tells the agent this mutates state; the description adds the genuinely useful defaults (draft vs. published, open vs. assigned) and the undo route. It does not disclose permission requirements or what happens on validation failure, but it exceeds the annotation's information.

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 primary action, then the variant, then the default state, then remediation. 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 an 11-parameter create tool with no output schema, the description covers creation mode, default state, and undo, but says nothing about the returned object or how to obtain the new shift's id for follow-up edits. Adequate but with a real 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 the baseline is 3. The description restates the user_id 0 = open-shift convention and the published default, which the schema already documents, adding little new parameter meaning.

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 immediately disambiguates the two creation modes: assigned to a user vs. open (user_id 0). It is clearly distinct from update_shift / publish_shifts in intent, though it never names those siblings explicitly.

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

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

Gives actionable context: the record is a draft unless published is true, and the reversal path is 'editing it or unpublishing' — which points the agent at when to use update_shift / unpublish_shifts. It stops short of an explicit 'use this instead of X when Y' statement.

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

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

Annotations only give destructiveHint=true; the description adds crucial lifecycle context that the annotation cannot convey: the request starts pending, and cancellation is done via a separate update call with status 1. This is genuinely helpful behavioral detail. It doesn't cover permissions or idempotency, 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 short sentences, front-loaded with the action, then state, then prerequisites and alternative. No filler; every clause has a concrete purpose (routing, lifecycle, endpoint).

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

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

For a mutation tool with no output schema and full schema coverage, the description covers what an agent needs: the call's effect, initial state, cancel path, and type_id source. It omits raw HTTP/return details, but that's acceptable given the endpoint reference 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 coverage is 100%, so all six parameters are already documented in the schema, including defaults and formats. The description adds the type_id sourcing hint (via list_time_off_types), but otherwise restates rather than extends the schema. Baseline 3 applies since the schema does the heavy lifting.

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

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

States a specific verb+resource ('Create a time-off request') and adds scope ('for a user, default the calling user'). It distinguishes itself from sibling get/list/update tools by naming the exact creation action.

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 to alternatives: use wheniwork_list_time_off_types to get type ids and wheniwork_update_time_off_request to cancel. States the initial state (pending) and the cancel condition (status 1), leaving no ambiguity about lifecycle.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds real value beyond that: it clarifies token scoping ('the token acts on'), describes the returned payload including parent/child account behavior, and notes the call is cheap — all useful for an agent deciding whether to invoke it.

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

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

A single tight sentence with the core purpose front-loaded, followed by the return contents and a usage note. The trailing 'When I Work: GET /2/account' mapping is compact and informative rather than wasteful.

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

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

With no output schema and no parameters, the description carries the full burden and discharges it: it explains what is returned, how parent accounts behave, and why an agent might call it. Nothing needed 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, so per the baseline a 4 applies; there is nothing for the description to compensate for. The schema coverage is 100% but empty, and the description correctly implies no inputs are needed.

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 (the When I Work account/workplace), and enumerates what it returns: company name, plan, settings, and child accounts for a parent account. This is clearly distinguishable from the sibling tools, which all operate on shifts, users, time-off, or lists.

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 a concrete use case ('A cheap way to confirm the credentials work') and implicitly scopes the call to the token's account. It does not name alternatives or when-not to use it, but the context is clear enough to guide selection.

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), and the description adds real behavioral value by disclosing what the response contains (breaks and publish state) and the REST mapping. It stops short of noting auth requirements or error behavior, so it is 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?

Two short sentences, front-loaded with the core action and benefit, with the endpoint mapping trailing. No filler words and nothing redundant.

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

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

For a single-resource read tool with 100% schema coverage and annotations carrying the safety profile, this is nearly complete; calling out breaks and publish state partially compensates for the absent output schema. Only missing pieces are auth/error expectations, which are minor here.

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

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

Schema description coverage is 100% – both shift_id and include_repeating_shifts_to are already well documented, including date-time formats. The description adds no parameter-level meaning beyond the schema, so the baseline 3 applies.

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

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

The description states a specific verb and resource ('Fetch one shift by id') and even names the underlying endpoint (GET /2/shifts/{id}). The word 'one' plus the id requirement cleanly separates it from wheniwork_list_shifts without needing the sibling's schema.

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

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

Usage is implied by 'by id' – an agent can infer this is the single-record lookup versus list_shifts – but there is no explicit when-to-use/when-not guidance or mention of the alternative tools. Minimum viable.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds non-obvious return context — that the response embeds the message thread and associated users — which is genuinely useful for an agent deciding whether one call suffices.

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

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

One compact sentence plus a short endpoint reference; the key behavior (fetch one by id, includes thread and users) is front-loaded with zero filler.

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

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

With one fully documented parameter, no output schema, and readOnlyHint covering safety, the description is nearly sufficient on its own; the mention of the embedded message thread and users compensates for the missing 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 description coverage is 100% and the single request_id parameter is fully documented there, so the baseline is 3. The description only restates that lookup is by id and adds no format or constraint detail beyond the schema.

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

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

States a specific verb (Fetch) and resource (one time-off request) with the retrieval key (by id), which cleanly separates it from the sibling wheniwork_list_time_off_requests. It also names the upstream endpoint, leaving no ambiguity about what the tool does.

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 'one ... by id' phrasing implies this is the single-record lookup versus the list tool, but no explicit when-to-use or when-not-to-use guidance is given. Usage must be inferred from the singular/plural naming and the required id.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds real value by enumerating the returned fields and naming the underlying endpoint (GET /2/users/{id}), which compensates for the absent output schema. It does not mention error behavior for a missing id, keeping 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?

Two tight clauses, zero filler, with the core action front-loaded and the endpoint reference last. 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 one-parameter read tool with no output schema, listing the returned fields plus the API endpoint gives the agent enough to invoke and interpret the call. Only the not-found/error behavior is left unaddressed.

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

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

Schema description coverage is 100% for the single user_id parameter, so the schema already documents it fully. The description's 'by id' adds no syntax, format, or constraint detail beyond what the schema provides, matching the baseline 3.

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

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

States a specific verb and resource ('Fetch one user by id') and enumerates the returned fields (name, email, role, positions, schedules, wage), which cleanly separates it from the sibling list_users. 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?

The 'by id' phrasing implies you already have a user_id, which implicitly excludes the list/eligible-users siblings, but the description never explicitly names when to use this versus wheniwork_list_users or wheniwork_list_eligible_users_for_shift. Usage is inferable but not 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?

readOnlyHint=true already signals a safe read, and the description adds genuine context on top: the default window (start of today through one year out) and the semantic meaning of the annotation types, including that blackout days block time off. It does not cover pagination, max result size, or auth requirements, 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?

Two tight sentences plus an endpoint reference; the resource definition and its default window are both front-loaded with 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 read-only list tool with no output schema, the description tells the agent what entities come back, their meaning, and the default range, so it is nearly self-sufficient. It omits pagination/volume expectations and any auth or rate-limit note, which are the only remaining gaps.

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

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

Schema description coverage is 100%, so the schema already documents date formats and the no_time_off flag; baseline is 3. The description's 'today through one year out' reinforces the default range for start_date/end_date and its mention of time-off blocking loosely maps to no_time_off, but adds no format or syntax detail beyond the schema.

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

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

States a specific verb (List) and resource (schedule annotations), then unpacks what that resource contains: announcements, business-closed days, and blackout dates. No sibling tool covers this resource, so an agent can route to it unambiguously 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?

The description supplies a useful behavioral default ('today through one year out') but never states when to reach for this tool versus siblings like list_time_off_requests or get_shift, nor any exclusion. Usage is only implied by the resource being listed.

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

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

readOnlyHint=true already establishes the safe-read profile, so the description is free to add the non-obvious traits: availability events represent can/cannot-work declarations and may include recurring patterns materialized into the window. It doesn't cover pagination or result size limits, but it meaningfully exceeds the annotation baseline.

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

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

Three tight sentences, front-loaded with purpose and scope before defaults, plus the underlying endpoint for traceability. No filler or redundancy.

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, four-optional-parameter list tool with no output schema, the description covers purpose, default scoping, and the recurring-pattern nuance. Return shape and pagination behavior are unspecified, but the annotations and schema carry most of the remaining burden.

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

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

Schema description coverage is 100%, so start/end, user_id and include_all are already documented in detail, including date formats and the manager restriction. The description restates the caller/two-week defaults but adds no format or scoping detail the schema lacks — baseline 3.

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

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

States a specific verb and resource ('List availability events') and then defines the resource in domain terms — 'when people said they can or cannot work' — which disambiguates it from shift and time-off listing tools. It stops short of naming a sibling explicitly, so an agent must still infer the boundary versus wheniwork_list_time_off_requests.

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

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

Gives concrete usage context: defaults to the caller and a now-to-two-weeks window, and the include_all parameter is flagged manager-only. There is no explicit when-not guidance or named alternative tool, so it's clear context without exclusions.

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

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

readOnlyHint=true already establishes this is a safe read, and the description adds the underlying endpoint (GET /2/shifts/eligible) and the dual-mode behavior. It does not disclose anything about result ordering, pagination, or how eligibility is computed, which would be useful for an agent interpreting the output.

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

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

Two compact sentences with zero filler; the core action is front-loaded and the mode branches follow immediately. The API reference is tacked on and costs 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 read-only lookup with no output schema, annotations covering safety, and full schema coverage, the description supplies the one thing structured fields omit: the choose-a-mode logic with conditional requirements. Only richer behavioral detail (ordering, cap on results) 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 the baseline is 3, but the description supplies a conditional-requiredness rule that the schema does not express (the schema lists zero required parameters). Stating that start, end, position_id and location_id are all required without shift_id prevents a malformed call.

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 ('Find who could take an open shift') and immediately clarifies the two modes: an existing shift via shift_id or a hypothetical one via start/end/position_id/location_id. This distinguishes it from siblings like list_shifts and list_availability, which serve different questions.

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

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

The description clearly explains the two invocation modes and what each requires ('either an existing shift (shift_id) or a hypothetical one'). It gives clear context for choosing a mode but does not explicitly contrast against alternative sibling tools such as list_availability.

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

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

The readOnlyHint annotation already establishes this is a safe, non-mutating read, so the description's burden is lighter. It adds the underlying endpoint (GET /2/locations) and terminology context, but says nothing about pagination, result size, or filtering behavior beyond the optional flag.

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, no filler, with the core purpose front-loaded and the terminology clarification placed immediately after. Every sentence carries information an agent needs.

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

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

For a single-optional-param read tool with annotations covering safety, the definition is nearly sufficient; the terminology mapping is the key missing piece from the schema and it is supplied. It stops short of describing what a returned schedule record contains, though with no output schema that is a minor omission.

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

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

There is only one optional parameter and schema description coverage is 100%, so the schema fully documents only_unconfirmed. The description adds no additional parameter meaning, which is the expected baseline when the schema does 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 ('List the schedules in the account') and then resolves a genuine naming ambiguity by explaining that the API calls a schedule a 'location' and that its id is the location_id every shift belongs to. That mapping is exactly what lets an agent distinguish this tool from siblings like wheniwork_list_shifts.

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

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

Usage is implied rather than stated: the note that location_id is 'the location_id every shift belongs to' hints this tool is the way to resolve that id before shift operations, but there is no explicit 'use this when / use X instead' guidance and no mention of alternatives such as wheniwork_list_shifts.

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

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

Annotations declare readOnlyHint=true, so the safety profile is already covered. The description adds domain context by defining what a 'position' is and naming the backing endpoint (GET /2/positions), but says nothing about pagination, result ordering, 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 sentences, zero waste, with the core purpose front-loaded and the endpoint reference trailing as supplementary 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?

For a simple read-only listing tool with one fully documented optional parameter and no output schema, the description covers what the tool returns conceptually and what the filter does at a high level. Minor gaps around pagination and result ordering keep it from a 5.

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 optional parameter with 100% schema description coverage, so the schema already explains 'show_deleted'. The description adds no parameter detail, which is acceptable given the schema does the work, but it is not additive.

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 (positions), and even glosses the resource as 'job roles such as Cashier or Dishwasher', which disambiguates it from sibling resources like locations, users, or shifts. It does not explicitly name a sibling, but the resource is distinctive enough that an agent can route correctly.

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

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

There is no guidance on when to use this tool versus alternatives, or any stated prerequisites. 'In the account' implies account-scope listing, but nothing tells the agent when positions are the right resource to fetch versus another list 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?

readOnlyHint=true already tells the agent this is a safe read. The description adds that open shifts and draft/unpublished shifts are opt-in inclusions, but the actual permission requirements for those flags live in the schema descriptions rather than here. Useful 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?

Two tight sentences: what is returned first, optional scope second, with the API endpoint as a trailing aside. No filler and the core capability 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 wide read-only list tool with no output schema and 13 fully documented params, the description covers purpose, scope, and intent mapping adequately. It omits pagination/limit behavior and time-window defaulting, which an agent calling with 13 optional params would benefit from knowing.

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 one of the 13 parameters is already documented with format, bounds, and permission notes. The description only gestures at 'open shifts and unpublished drafts' without adding syntax or default behavior 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 scheduled shifts) plus the returned fields (who works when, where, position) and the optional scope expansions (open shifts, unpublished drafts). This cleanly separates it from the singular sibling 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 concrete trigger questions ('who is on on Friday?', 'what open shifts are left?') that map user intent to this tool. It does not explicitly name when to prefer a sibling like wheniwork_get_shift or wheniwork_list_shift_swaps instead, 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?

readOnlyHint=true already tells the agent this is a safe read, so the description's burden is lighter. It usefully discloses the start/end pairing constraint and the upstream endpoint (GET /2/swaps), but says nothing about result ordering, pagination behavior beyond what the schema notes, or the shape of the returned records beyond 'shifts and users involved'.

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

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

Front-loaded with the core purpose, then the code tables and the start/end constraint in tight sentences. Dense but every sentence carries information; the only mild cost is that the enumeration lists read as a run-on rather than structured.

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, zero-required list tool with no output schema, the description covers what is listed, the filter vocabularies, and the one cross-parameter constraint. What remains thin — default time window behavior and pagination/result-shape detail — is either in the schema or minor for a read-only listing 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 the baseline is 3, but the description adds real meaning the schema lacks: it decodes the integer status values (0 pending through 5 expired) and type values (1 swap, 2 drop, 3 alert), which the schema only labels generically as 'One or more statuses/types'. It also reinforces the start/end coupling constraint.

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

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

States a specific verb and resource (list shift requests) and immediately narrows scope to the three record kinds — swaps, drops, alerts — plus the related shifts and users. This clearly separates it from siblings like wheniwork_list_shifts and wheniwork_list_time_off_requests without the agent needing to open 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?

Usage is only implied: an agent can infer that this is the tool for swap/drop/alert records, and the status/type enumerations hint at filtering. There is no explicit when-to-use versus wheniwork_list_shifts or wheniwork_get_shift, and no stated prerequisites (e.g. required permissions or whether a window is mandatory in practice).

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

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

The readOnlyHint annotation already establishes that this is a safe read, and the description adds valuable domain context that structured fields lack: the status code mapping (0 pending, 1 canceled, 2 accepted, 3 expired, 4 denied) and the underlying API endpoint. It does not describe pagination or return-shape behavior, but the schema covers 'page' and 'more'.

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

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

Two tight sentences, front-loaded with the primary purpose, then the enum-like semantics and endpoint reference. Every clause carries information; no 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 12-parameter, no-required read tool with full schema coverage and a readOnly annotation, the definition covers purpose, status semantics, and the API mapping. It could mention that omitting filters returns all requests and note pagination behavior, but the schema handles the individual parameters.

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 supplies the status-code semantics that the schema omits (status is a bare integer 0-4 with no enum). That meaningfully compensates for a real enum gap in the input 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 names a specific verb and resource ('List time-off requests in a date range, with the requesting users'), making the plural/list nature clear versus the singular sibling wheniwork_get_time_off_request. It stops short of explicitly naming that sibling, so differentiation is inferred rather than stated.

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

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

The description gives a scope ('in a date range') but no when-to-use guidance, exclusions, or routing to alternatives such as wheniwork_get_time_off_request for a single request or wheniwork_list_time_off_types. The agent must infer the selection criteria.

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

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

readOnlyHint=true already covers safety, and the description adds genuinely useful behavior: this is a catalog read whose returned ids feed a subsequent create call. It does not mention pagination or ordering, but no output schema exists, so the return-content description carries real weight.

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

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

Two tight sentences plus the endpoint reference. The scoping fact (what is listed) comes first, and the downstream use case follows immediately, 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?

With no parameters and no output schema, the description supplies the essential return shape (type names and whether paid) and the reason to call it. Missing only minor detail such as ordering or pagination, which is a small gap for a simple catalog tool.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline for a parameterless tool is 4.

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

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

States a specific verb (List) and resource (time-off types), and goes further by naming what each entry contains (e.g. Personal, Sick, Holiday, paid flag). This distinguishes it cleanly from siblings like wheniwork_list_time_off_requests, which list requests rather than the type catalog.

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?

Explains the downstream purpose explicitly: 'Their ids are the type_id for a new request,' which tells the agent to call this before wheniwork_create_time_off_request. It does not state exclusions or when not to use it, so it falls short of a full 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?

readOnlyHint=true already establishes this is a safe read, and the description usefully adds the shape of the returned data (hours, approval state). However, it says nothing about pagination, result limits, or default time-window behavior — meaningful gaps for a timesheet list endpoint.

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

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

Two compact sentences plus the upstream endpoint reference; the returned-data summary is front-loaded and every clause carries information. 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?

With no output schema, the description does well to summarize the returned fields, and the annotations cover the safety profile. It falls short only on pagination/limit and default-window behavior that an agent would need for a list endpoint.

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 only_open are already documented in the schema. The description only echoes only_open's meaning and adds no syntax, format, or interaction detail beyond that baseline.

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

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

States a specific verb and resource ('List clocked time entries') and immediately enumerates what the resource contains — hours worked, clock-in/out, length, approval state. This is clearly distinguishable from sibling listing tools such as wheniwork_list_shifts (scheduled) and wheniwork_list_users.

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 'Use only_open to see who is clocked in right now' line gives an in-tool usage cue, but it is effectively a restatement of the parameter rather than guidance on when to choose this tool over an alternative. No when-not conditions or sibling routing 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, so the safe-read profile is covered. The description adds the underlying endpoint (GET /2/users) and the role-code legend (1 admin, 2 manager, 3 employee, 5 supervisor), which is genuinely useful disclosure, but says nothing about pagination, result limits, or sort order.

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 tightly packed sentences plus a short endpoint note, with the resource and its filters front-loaded. Nothing is redundant, though the API-endpoint tail is marginally lower value than the rest.

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 fully documented parameters, this is close to complete: it names the entity, the filterable dimensions, and the role-code vocabulary needed to interpret results. Missing pagination/sorting behavior is the only notable 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 are already documented with meaning (search, location_id, only_deleted, only_pending, show_deleted, show_pending), which sets the baseline at 3. The description restates the schedule-limit and search behavior but adds no format or interaction detail beyond the schema; the role codes clarify returned values rather than parameter semantics.

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

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

States a specific verb and resource ('List the employees, supervisors, managers and admins in the account') plus the optional narrowing dimensions (schedules, name/email search). It implicitly separates itself from single-user reads like wheniwork_get_user, but never names a sibling such as wheniwork_list_eligible_users_for_shift, so the differentiation is left to inference.

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

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

The description implies usage through 'optionally limited to some schedules or searched by name/email', giving the agent a sense of when the filters apply. However, it offers no explicit when-to-use vs when-not guidance and never points to an alternative tool, so the routing burden stays with the agent.

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; the description adds genuinely new behavior — that publishing changes employee visibility, that no notifications are sent, and that the change is reversible via unpublish. That reversibility context is exactly what the destructive annotation alone cannot convey.

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 effect and immediately followed by the notification caveat and undo route. No filler or restatement of 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 one-parameter mutation with no output schema, the definition covers effect, side-effect (no notifications), and reversal, which is most of what an agent needs. The batch size ceiling (1000 ids) is left to the schema and could have been surfaced.

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 already documented at 100% schema coverage ('The shift ids to publish'), and the description adds no format, ordering, or batching guidance beyond it. Baseline 3 applies when the schema carries the 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 ('Publish draft shifts') plus the resulting state change ('so employees can see them'), which separates it cleanly from wheniwork_create_shift 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?

Makes the precondition clear (shifts must be in draft) and names the inverse operation wheniwork_unpublish_shifts as the undo path. It does not spell out when an agent should choose this over scheduling via create_shift, so it falls short of a full 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 destructiveHint=true, so the safety profile is known. The description adds real context beyond that: what destruction means here (shifts revert to draft, become hidden from employees) and that it is reversible via wheniwork_publish_shifts, which is valuable for a destructive-flagged op.

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: effect first, undo route second, endpoint third. Front-loaded and every sentence earns its place.

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

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

For a single-parameter mutation with no output schema, the description covers the effect, reversibility, and the underlying API operation. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% with a single, well-described 'ids' array (including min/max items), so the schema carries the parameter burden. The description adds nothing about id format, batch limits, or partial-failure behavior, 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 ('Return published shifts to draft') plus the observable effect ('hiding them from employees'). It also explicitly names the inverse tool, so an agent can distinguish it from wheniwork_publish_shifts 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?

Clearly conveys the context of use (reverting published shifts to draft) and names the counterpart tool as the undo path. It stops short of explicit when-not-to-use guidance or prerequisites, but the routing signal is present.

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, but the description discloses the key destructive mechanism: this never sends a breaks array, and omitted breaks are removed by the API, so the agent should re-check breaks afterward. That is exactly the non-obvious mutation consequence an agent needs, and it is consistent with the destructive 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 sentences, front-loaded action first, then prerequisites and the destructive caveat, then the endpoint reference. No filler; each sentence carries distinct, actionable 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 12-param destructive mutation with no output schema, the description covers the prerequisite (fetch first), the destructive side effect (breaks removal), the required fields, and the underlying endpoint. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the schema already documents all 12 parameters and even notes the required-even-if-unchanged semantics. The description adds workflow meaning by tying the required trio (start_time, end_time, location_id) to the fetch-first pattern the agent must follow.

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 shift) and enumerates the concrete operations — reassign, move, change position or notes. An agent can distinguish this from get_shift, create_shift, and publish_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?

Explicitly instructs the agent to fetch the shift first (get_shift) and pass back the required fields, which is real when-and-how guidance. It stops short of naming sibling alternatives like create_shift or publish_shifts for competing outcomes, so it is clear context rather than full 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 only supply destructiveHint=true; the description adds real behavioral context on top: mutation is reversible by setting status back, the paired start/end constraint is disclosed, and the status codes are decoded. It does not mention permission/authorization requirements or what happens to fields not supplied.

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: action, status semantics, constraint, then API endpoint. The critical mutation-and-status information is front-loaded and no sentence is 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 mutation tool with no output schema and thin annotations, the description covers reversibility, field coupling, status codes, and the endpoint well enough to call it correctly. Missing only auth/permission expectations and behavior for partial updates, which are minor given the schema's clarity.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning the schema lacks: the status field is only described as 'New status' in the schema, whereas the description decodes all five values (0 pending, 1 canceled, 2 accepted/approved, 3 expired, 4 denied). The start_time/end_time pairing is also restated usefully.

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 precise verb+resource (change a time-off request) and enumerates the specific mutable fields (status, dates, hours). The sibling set contains create/get/list time-off variants, and the word 'change' plus the status-mutation framing clearly separates this from wheniwork_create_time_off_request and wheniwork_get_time_off_request.

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

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

The title and description together establish the use case well: approving, denying, canceling, or editing an existing request. It gives the conditional constraint ('start_time and end_time must be given together') but never names an alternative tool or states when-not to use it (e.g., use create_time_off_request for new requests).

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