Shiftbase MCP by usefulapi

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

Annotations already cover the write/destructive/non-idempotent/open-world profile, so the bar is lower, and the description earns credit by disclosing a side effect not in the annotations: the employee is notified only when notify is true. It also names the underlying endpoint (POST /rosters), which is useful operational 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 terse sentences, front-loaded with the 'WRITE:' signal and the core semantics, with the endpoint appended as a compact epilogue. 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 an 11-parameter mutation with no output schema, the description covers what the tool does, the notification side effect, and the endpoint, while annotations supply the safety and idempotency profile. It stops short of noting auth/permission requirements or what the response returns, which would round it out.

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

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

Schema description coverage is 100%, so the schema already documents all 11 parameters with formats, defaults, and cross-references (e.g. shiftbase_list_shift_types). The description only restates the key fields at a high level and adds no syntax or constraint detail beyond the schema, making the baseline 3 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 ('put one employee on the schedule'), the exact cardinality ('one employee... one date', 'a single, non-recurring shift'), and the resource (roster). It distinguishes itself from the sibling shiftbase_update_roster by explicitly scoping to creation of a non-recurring shift rather than modification.

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 'WRITE:' prefix and 'single, non-recurring shift' phrasing imply this is the creation path versus shiftbase_update_roster, but no alternative is named and no when-not condition is stated. An agent can infer intent but gets no explicit routing guidance.

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

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

Annotations already declare readOnlyHint=true, so the safe-read behavior is covered. The description adds useful return detail (per-day hours, reviewer) and the underlying endpoint, but does not elaborate on permissions, rate limits, or edge-case behavior beyond that.

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

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

Two compact sentences front-load the core purpose and then add the endpoint. Every piece of information earns its place with no 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 simple read-only lookup with one parameter, 100% schema coverage, and no output schema, the description is complete. It tells the agent what the call returns (per-day hours and reviewer), which 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%: the single absence_id parameter is already documented as 'Shiftbase absence (absentee) id.' The description does not add format or constraint details beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

States it returns one absence by id, with the per-day hours and reviewer, which is a specific resource and scope. It implicitly distinguishes itself from list_absences by being singular, though it does not name the sibling explicitly.

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

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

The 'by id' phrasing implies the tool is used when a single absence id is known, but there is no explicit when-to-use guidance or comparison to alternatives such as shiftbase_list_absences or shiftbase_get_expected_absence_hours. Usage is only weakly implied.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description goes further by naming the endpoint (GET /accounts) and listing the specific facts returned, which compensates for the absence of an output schema. It does not discuss rate limits or whether account data is cached, so it stops 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?

One sentence plus the endpoint. The resource is named first, the returned fields follow, and there is no filler. Every element earns its place.

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

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

With no parameters and no output schema, the description carries the informational burden, and enumerating the returned fields largely does that. A slightly fuller picture (e.g. whether this scopes subsequent calls, or the response shape) would complete it.

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

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

The tool takes zero parameters, so the baseline of 4 applies. There is nothing for the description to clarify beyond confirming the tool is unconditional.

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?

Identifies the exact resource ('the Shiftbase account this API key belongs to') and enumerates what it contains: company, country, time zone, working-day start/end, plan facts. This is unambiguous and distinct from every sibling, which all operate on users, rosters, absences or other sub-resources.

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 'this API key belongs to' implies the tool is for orienting the agent in its account context, but there is no explicit when-to-use statement, no prerequisite or alternative named. Usage is only implied, which is the definition of a 3.

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

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

With readOnlyHint already in annotations, the description adds valuable context beyond the safety profile: plan and permission requirements, the exact API endpoint, and the 62-day range limit. It does not cover pagination behavior or response format, but for a read-only reporting tool this is a solid level of disclosure.

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

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

Three compact sentences, front-loaded with the resource and scope, followed by prerequisites and endpoint. No filler; each sentence delivers a distinct piece of 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 seven-parameter, read-only reporting tool with no output schema, the description covers purpose, scope, permission requirements, and endpoint. The schema fully documents pagination and filtering parameters, so nothing essential is missing.

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

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

Schema description coverage is 100%, so all seven parameters are fully documented in the schema. The description restates the 62-day range and availability status types but adds no new syntax or format details beyond what the schema already provides. Baseline 3 is appropriate when 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?

The description states a specific verb and resource: retrieving employee availability from Shiftbase's availability report. It scopes the operation to a date range of at most 62 days and clarifies the available/unavailable, all-day/from-a-time variants. This distinguishes it from siblings like get_absence or get_timesheet without needing to name them.

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

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

It provides clear prerequisites: Basic plan and 'View reports' permission, and specifies the underlying endpoint (POST /reports/availability) and that it is read-only. It does not explicitly state when to choose this over alternatives such as get_absence or get_roster, but the context is sufficient to infer usage.

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

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

Annotations already declare readOnlyHint=true, and the description confirms it with 'Changes nothing.' More valuably, it discloses the computation basis (schedule vs contract, per the absence policy) and a hard 366-day limit that the agent could not otherwise know. It stops short of describing error behavior when the period is exceeded.

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: the computed quantity, its basis, its limit and its safety profile are all front-loaded 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 output schema, the description usefully specifies the return shape ('per day and in total'), the source of the computation and the period cap, which is enough for correct invocation. It omits what happens at the 366-day boundary and whether the day-by-day output can be empty for non-working days.

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 meaning beyond the schema: the 366-day cap constrains how start_date/end_date may be paired, and 'from the schedule or the contract' explains why absence_type_id matters. It still does not map individual parameters to 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 computed resource: the expected hours an absence would cost, per day and in total. It is clearly distinguishable in kind from sibling readers like shiftbase_get_absence (recorded absence) and shiftbase_list_absences, though it never names a sibling or says which to prefer.

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 the use case (previewing the hour cost of an absence before requesting one) and discloses the 366-day period constraint, but gives no explicit when-to-use or when-not-to-use guidance relative to get_absence, list_absences or request_absence.

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 goes further by enumerating the response payload (employee, shift type, team, creator/changer) and citing the exact REST path. It still omits failure behavior such as what happens with a stale or malformed occurrence_id.

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

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

Two sentences with zero filler, front-loading the resource and selector before the endpoint. 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?

With no output schema, the description usefully summarizes the returned entity and its annotations cover the safety profile, leaving little for an agent to guess. Only edge-case behavior (unknown occurrence_id, recurring-shift semantics) is 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 coverage is 100% and the schema already documents the occurrence_id format including the '<roster id>:<yyyy-mm-dd>' recurring-shift variant. The description adds no format or constraint detail beyond restating the parameter name, 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 (get), resource (a single scheduled shift) and the exact selector (occurrence_id), and even names the fields returned plus the underlying endpoint. An agent can distinguish this from shiftbase_list_rosters or shiftbase_get_timesheet immediately.

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

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

The singular framing ('One scheduled shift by its occurrence_id') implies this is the detail lookup once you have an id, but the description never states when to prefer it over shiftbase_list_rosters or what to do if the id is unknown. Where the id comes from is only noted in the schema, not the description.

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

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

The readOnlyHint annotation already establishes the safe-read profile, so the bar is lower. The description adds genuinely useful payload context beyond the annotations: the response includes the timesheet's clocked breaks, which matters because there is no output schema.

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

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

Two short sentences, zero filler, with the resource scope front-loaded before the endpoint restatement. Every clause earns its place.

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

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

For a trivial one-parameter read tool with annotations covering safety, the description is largely sufficient, and it partly compensates for the absent output schema by naming the included breaks. It stops short of describing the timesheet's other returned fields or error behavior on a bad id.

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

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

With a single parameter at 100% schema description coverage, the schema already documents timesheet_id fully. The description adds no format, range, or sourcing detail beyond it, so baseline 3 applies.

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

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

States a specific verb+resource: fetching a single timesheet by id, and notes it includes clocked breaks. The singular 'One timesheet by id' implicitly separates it from the sibling shiftbase_list_timesheets, though it never names that sibling explicitly.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no named alternative. The id-based framing hints that a lookup follows a listing call, but the agent must infer that entirely.

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 added value is disclosing the return payload ('with teams and departments'), which is useful given there is no output schema. It does not cover auth needs, error behavior, or whether both lookup keys can be combined.

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?

Very compact and front-loaded, leading with the resource and lookup keys. The trailing 'GET /users/{identifier}' is largely redundant restatement of the endpoint, 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 simple single-read tool with full schema coverage, a readOnly annotation, and no output schema, the description is nearly sufficient, even naming the nested data returned. Minor gap: no statement of what happens on a missing/ambiguous identifier or whether one of the two optional params is required.

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 parameters are fully documented in the schema, establishing the baseline of 3. The description's 'user id or email address' merely echoes the schema and does not clarify the mutual-exclusivity/precedence between the two optional keys.

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

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

States a specific verb and resource ('One employee') plus the lookup keys (user id or email) and the extra data returned (teams and departments). This clearly contrasts with the plural list_users sibling via 'One employee', though it never names that sibling explicitly.

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

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

The singular-resource framing implies you use it when you know an id or email, but there is no explicit when-to-use or when-not guidance and no mention of list_users as the alternative for discovery. Usage is inferable rather than stated.

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

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

Annotations only declare readOnlyHint=true, so the description usefully adds the plan-level prerequisite (Basic plan) and the hard 366-day date-range constraint, neither of which appears in structured fields. It also summarises the status vocabulary returned. It stops short of describing pagination/return shape, but 100% schema coverage on limit/offset covers that.

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

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

Front-loads the core action and scope, then appends the two operational facts (plan requirement, endpoint) as short sentences. The mid-sentence list of returned fields is slightly dense but every element is informative; 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?

With no output schema, the description compensates by enumerating the returned fields (employee, type, dates, hours/days, status, reviewer) and by stating the plan and range limits. Coverage is solid for a 9-parameter list tool, though pagination behaviour is left entirely to the schema.

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

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

Schema description coverage is 100% and every parameter is documented inline, so the schema carries the semantics. The description reinforces the date-range constraint but adds no format or syntax detail beyond what min_date/max_date already declare.

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 (absences), and parenthetically defines the scope of what counts as an absence: leave, sick leave, other time off. This differentiates it cleanly from shiftbase_get_absence (singular fetch) and shiftbase_list_absence_types.

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 real preconditions – the Basic plan requirement and the 366-day maximum range – which help an agent know whether the call will succeed. However, it never states when to prefer this over shiftbase_get_absence or how it relates to list_absence_types beyond the enum hint in the schema; usage is implied rather than spelled out.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds value beyond that by enumerating the payload fields an agent will receive, including the hours-vs-days unit and the leave-cost flag, which an agent needs to interpret results correctly.

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

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

One front-loaded sentence plus the raw endpoint reference; the parenthetical examples and field list each carry information. The 'GET /absentee_options' tail is marginally useful metadata rather than 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 compensates by describing the returned fields and their meaning, and pagination is handled in the schema. Adequate for a simple read-only list tool, though an explicit cue about when to fetch types would make it complete.

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

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

Schema description coverage is 100% and both limit/offset are fully documented there, including how to chain next_offset. The description adds nothing about pagination, so baseline 3 applies.

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

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

Specific verb+resource ('List absence types') with examples (Holiday, Sick, Unpaid leave) and the concrete fields returned (name, unit, costs leave hours, colour). It also clarifies the relationship to absences via absence_type_id, which cleanly separates it from sibling shiftbase_list_absences.

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

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

Usage is only implied: the note that these ids are 'the absence_type_id for absences' hints that this tool precedes absence creation/requests, but there is no explicit when-to-use or when-not-to-use statement, and no sibling is named as an alternative.

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, and the description adds genuinely new context: this is a live snapshot rather than a historical query, it names the backing endpoint GET /timesheets/clock, and it lists the fields returned. It does not mention pagination behavior, though that is in the schema.

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

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

A single sentence plus endpoint reference, with the identifying scope ('right now') front-loaded and every clause carrying information about the return payload.

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

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

There is no output schema, so the description usefully enumerates the returned fields, and annotations cover the read-only safety profile; the only omission is any mention of result-set size or paging, which the schema does handle.

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 limit and offset are already fully documented with defaults and paging semantics. The description adds no parameter meaning beyond the schema, which is the baseline-3 case.

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

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

States a precise resource ('clocked-in employees') and a precise temporal scope ('right now'), and enumerates the returned attributes. An agent can distinguish it from shiftbase_list_timesheets or shiftbase_get_timesheet without inspecting schemas.

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 'right now' implicitly defines the moment-in-time use case, but the description never states when to prefer this over shiftbase_list_timesheets or shiftbase_get_timesheet, nor any exclusions or prerequisites.

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

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

The readOnlyHint annotation already establishes this is a safe read. The description adds useful content context beyond the annotation by noting that results include address and timesheet/clocking settings, and it cites the backing endpoint. It does not discuss pagination behavior or auth requirements, though the schema covers pagination.

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 clauses: the resource definition comes first, then the endpoint shorthand. No filler, nothing repeated from the schema, and the most useful disambiguating detail 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 simple, annotation-covered read-only list tool with fully documented parameters and no output schema, the description covers what the resource is and what it contains. Only the when-to-use routing against sibling list tools is absent, which is minor for 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 coverage is 100%, so limit and offset are fully documented in the schema with defaults and paging semantics. The description adds no parameter-level detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('List departments') and disambiguates what a department is ('sites/branches that own teams, shifts and schedules'), which helps separate it from siblings like shiftbase_list_locations and shiftbase_list_teams. It also names the endpoint. It stops short of explicitly differentiating itself from those siblings 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?

There is no statement of when to use this tool versus alternatives such as shiftbase_list_locations or shiftbase_list_teams, and no prerequisite or context guidance. Usage must be inferred entirely from the tool name and resource description.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the bar is low. The description does add one useful behavioral fact beyond the annotation — that only active locations are returned — plus the underlying endpoint, but it says nothing about result ordering or volume beyond what the schema's limit/offset notes cover.

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

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

A single tight sentence with the scope constraint front-loaded and no filler. The trailing 'GET /locations' is mild redundancy for an MCP tool but costs little.

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

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

For a simple read-only list endpoint with annotations covering safety and a schema that documents pagination fully, the description supplies what an agent needs to select and call it. Only minor gaps remain, such as result ordering or default page size, which the schema partially covers.

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

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

With 2 optional parameters and 100% schema description coverage, the schema fully carries the semantics (limit range/default, offset chaining via next_offset), so the baseline is 3; the description adds no parameter detail but the endpoint path modestly reinforces what is being paged, landing slightly above 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 active locations') and the parenthetical 'addresses that group departments' defines the domain object, letting an agent distinguish it from siblings like shiftbase_list_departments and shiftbase_list_teams 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?

Usage is only implied: reading locations is the obvious action, and the word 'active' hints that inactive locations are excluded. There is no explicit when-to-use, when-not-to-use, or pointer to an alternative tool.

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

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

Annotations only declare readOnlyHint=true; the description adds real behavioral context beyond that — the Basic plan requirement and the hard 62-day window with a default. It stops short of describing return shape or pagination behavior, but the added constraints are meaningful.

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 what the tool returns, followed by the constraints and endpoint. No filler or 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 6 optional parameters, no output schema, and no enums, the description covers purpose, plan gating, and the date-window rule well. The only gap is that nothing hints at the paginated response (total/next_offset), which the schema mentions only incidentally.

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 contributes a constraint the schema lacks: the at-most-62-day span for min_date/max_date and the today default. It adds genuine semantic value on top of an already well-documented schema.

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

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

States a specific verb (list) plus resource (open/unassigned shifts) and adds the business meaning — shifts employees can pick up. This clearly distinguishes it from the many list_* siblings (rosters, absences, timesheets, 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?

Provides concrete operating context: 62-day maximum date range, default of today when no dates are given, and a plan prerequisite. It does not explicitly name a sibling as the alternative or state when not to use this tool, so it falls short of a 5.

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

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

readOnlyHint=true already tells the agent this is a safe read, and the description adds the 62-day window limit and the underlying endpoint (GET /rosters). It does not spell out pagination behavior in prose, but the schema's limit/offset descriptions carry that load, so the incremental value is real if 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?

Two sentences: the first front-loads the core purpose and the 62-day constraint, the second carries the field list and the sibling hand-off. Nothing is repeated 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?

With no output schema present, the description compensates by enumerating the returned fields (date, times, break, employee, team, shift type, department, published state, hours, cost) and by flagging occurrence_id as the key for follow-up calls. Combined with annotations and a fully described input schema, an agent has what it needs to call and chain this tool correctly.

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

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

Schema description coverage is 100%, so every parameter (limit, offset, user_id, min_date, max_date, department_id) is already documented with its filter meaning. The description's only added parameter-level meaning is restating the ≤62-day relationship between min_date and max_date, which the schema already expresses, 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 and even defines the domain term ("rosters = shifts assigned to employees"), which implicitly separates it from unassigned siblings like shiftbase_list_open_shifts or shiftbase_list_timesheets. It also enumerates the returned fields, so an agent knows exactly what this call yields 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?

It states the hard operating condition (date range of at most 62 days) and explicitly routes follow-up work by saying each occurrence_id is what shiftbase_get_roster and shiftbase_update_roster consume. It does not, however, state when to prefer this over adjacent list tools such as list_timesheets or list_open_shifts, so an explicit exclusion is missing.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower; the description adds substantive context by enumerating the template fields returned and the REST endpoint. It doesn't disclose pagination or the default treatment of deleted records, but those gaps are partly covered by the schema.

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

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

One dense sentence plus the endpoint, with the core purpose and the field enumeration front-loaded before the optional filters. No sentence is filler; the parenthetical efficiently defines the domain term 'shift type'.

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 appropriately describes what a shift type contains and what the ids are for, which is what an agent needs to chain into create_roster. Paging behavior is delegated to the fully-described schema, leaving only minor gaps about default exclusions of deleted types.

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

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

Schema coverage is 100%, so all four parameters including limit/offset paging semantics and include_deleted are already documented in the schema. The description's 'optionally for one department' merely restates department_id's optionality without adding format or behavioral detail, so the baseline 3 applies.

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

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

States a specific verb+resource ('List shift types') and then defines the resource itself — templates holding name, short name, default start/end time and break — which disambiguates it from sibling list tools like list_departments or list_rosters. It also names the downstream consumer (shift_id for shiftbase_create_roster) and the backing endpoint GET /shifts.

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

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

The description gives clear usage context by tying the returned ids to shiftbase_create_roster and noting the optional department scoping, so an agent knows when this lookup is the right step. It stops short of explicitly stating when-not to use it or naming an alternative sibling, which keeps it out of 5 territory.

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 by structured data. The description adds only the underlying endpoint ('GET /teams'), which is minor context and no behavioral trait such as pagination semantics — though those are already documented in the schema for limit/offset.

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

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

A single front-loaded sentence plus an endpoint tag, with zero filler. The parenthetical definition is the highest-value content and appears immediately after the verb.

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

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

For a simple read-only list tool with three optional, fully documented parameters and no output schema, the definition covers what an agent needs to call it. It would be complete at 5 with one line on how to obtain a department_id or what a returned team contains.

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

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

Schema description coverage is 100%, with limit, offset, and department_id each fully documented including defaults and the next_offset chaining pattern. The description's 'optionally for one department' merely restates department_id semantics, 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 teams') and defines the domain term precisely — teams are the rows of the schedule within a department — which is genuinely clarifying for an ambiguous noun. It does not, however, distinguish itself from nearby siblings like shiftbase_list_departments or shiftbase_list_rosters, whose names could plausibly overlap.

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

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

'optionally for one department' implies that department_id narrows results and that omitting it returns all teams, which is useful implied usage. There is no explicit when-to-use guidance or routing to alternatives (e.g., list_departments first to obtain a department_id), so it stays at 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?

readOnlyHint=true already tells the agent this is a safe read, so the description only needs to add context. It adds the 62-day range limit, but that is also repeated in the max_date schema description, and it says nothing about permissions, scoping to the caller's own timesheets, or result volume beyond what the schema's limit/offset already 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?

A single front-loaded sentence with a content enumeration and the key constraint, followed by a short PATH note. Nothing is padded, though the trailing 'GET /timesheets' adds little an agent can act on.

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

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

With no output schema, the description usefully inventories the timesheet fields an agent can expect, and pagination is covered by the schema's limit/offset descriptions. It is nearly complete for a list tool; only explicit sibling routing and scoping notes 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 description coverage is 100%, so every parameter (limit, offset, status, user_id, department_id, min_date, max_date) is already documented in the schema. The description adds only the enumeration of returned fields and restates the 62-day constraint, which is the expected baseline when 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 and resource ('List timesheets') and enumerates the returned content (clock in/out, breaks, total, status, wage, surcharges), so an agent knows exactly what it gets back. The scope constraint (date range max 62 days) is also stated. It does not explicitly distinguish itself from the singular shiftbase_get_timesheet or shiftbase_list_clocked_in, 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?

The 62-day maximum date range is a real usage rule, but there is no explicit when-to-use guidance, no named alternative, and no statement of when to prefer shiftbase_get_timesheet or shiftbase_list_clocked_in over this tool. Usage is only implied by the date-range and status/user/department filters.

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 valuable behavioral context by explicitly stating that 'Identity, bank and birth data are never returned,' which is not in the schema or annotations.

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

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

Two compact sentences plus the endpoint; information is front-loaded with the returned fields and use case, 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 list tool with no output schema, the description summarizes the key returned fields and explicitly excludes sensitive data, but does not detail pagination or response structure (handled by schema's limit/offset descriptions).

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

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

Schema description coverage is 100%, so the schema already documents all five parameters (limit, active, offset, department_id, include_hidden). The description adds no parameter-specific meaning beyond what is in 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 the specific verb 'List' and resource 'employees (users)', and enumerates returned fields (teams, departments, contact details, etc.), clearly distinguishing it from the singular shiftbase_get_user and other list_* siblings.

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 clear use case—'map user ids in schedules, timesheets and absences to names'—but does not name alternatives (e.g., get_user) or state when not to use it.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and idempotentHint=false, so the safety profile is partially covered; the description adds real value on top by disclosing the default Pending status, the approve-absence permission gate for Approved, the required Basic plan, and the side effect that hours are derived from Shiftbase's expected-hours calculation. It adds no contradiction with the annotations.

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

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

Four compact sentences with the operation class and resource front-loaded, no filler, and the endpoint last. Dense but each sentence carries distinct information (status semantics, permission, hours source, plan requirement).

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

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

For a 7-parameter write tool with no output schema, the description covers the mutation semantics, permission/plan prerequisites, side effects, and the reference sibling for absence types. It does not describe what is returned (e.g., the created absence id) or what destructiveHint implies for existing bookings, which is a minor residual 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 schema already documents all 7 parameters including the status enum, date patterns, and the absence_type_id cross-reference. The description mostly restates the status semantics the schema already states, adding only the behavioral note about how per-day hours are computed, 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?

Starts with an explicit operation class (WRITE) plus a specific verb and resource: 'add an absence (leave/time-off request) for an employee', and closes with the concrete endpoint POST /absentees. This clearly separates it from read siblings like shiftbase_get_absence / shiftbase_list_absences and from shiftbase_review_absence.

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

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

It explains the two operating modes (default Pending vs Approved booking directly) and the permission required for the Approved path, plus a plan prerequisite (Basic plan). It does not explicitly state when to prefer this over shiftbase_review_absence or shiftbase_update_* flows, so it falls short of full when/when-not 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=false, destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds valuable non-obvious context: the call is a read-modify-write that sends the absence back unchanged except for status, plus the required permission and the underlying PUT endpoint. It does not explain the notify_employee side effect or failure modes.

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 sentences with the WRITE prefix and the core verb front-loaded; the permission caveat and endpoint come after. No sentence is filler and it is far shorter than the schema it accompanies.

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 full annotation coverage, a 100%-documented schema and no output schema, the description supplies the missing pieces an agent needs: write semantics, permission requirement, and the mutate-one-field behavior. It is essentially complete, missing only any note on the notify_employee default or error behavior.

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

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

Schema description coverage is 100% and all three parameters are documented in-schema, so the baseline is 3. The description adds one useful nuance — that 'decision' changes only the status field and the rest of the record is sent back unchanged — but contributes nothing about notify_employee or id range.

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 leads with a specific verb pair and resource ('approve or decline an absence request') and adds a WRITE marker, making it trivially distinguishable from siblings like shiftbase_get_absence or shiftbase_request_absence. 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?

It states the permission prerequisite ('needs the approve-absence permission') and implies the correct context (an existing absence awaiting a decision), which is enough to select the tool. It never names an alternative tool or an explicit when-not condition, so it falls short of full routing guidance.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=false. The description adds valuable behavior: it reads the shift first (a read-modify-write pattern), and clarifies how the scope parameter changes which occurrences are affected. It does not detail authentication needs, rate limits, or error conditions, but with annotations covering the safety profile, this is good transparency.

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

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

The description is front-loaded with 'WRITE: change a scheduled shift', followed by a concise enumeration of what can change, then the scope semantics, and finally the endpoint. Every sentence adds value with no 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 mutation tool with 13 parameters, 100% schema coverage, and no output schema, the description covers the essential behavioral aspects (read-modify-write, scope meaning). It does not mention possible side effects (e.g., notifications controlled by 'notify' parameter) or what happens on failure, but the schema and annotations fill many 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 baseline is 3. The description adds meaning for the scope parameter by defining the three enum values in plain language and explaining applicability to recurring vs non-recurring shifts. It also lists the categories of changeable fields, which helps map parameters to intent, though individual parameters are already well-described in 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 (change) and resource (scheduled shift), then enumerates the exact fields that can be modified (date, time, employee, team, shift type, break, note), and even names the HTTP endpoint. This clearly distinguishes it from siblings like shiftbase_create_roster and shiftbase_get_roster.

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 explains how to use the scope parameter to target recurring vs non-recurring shifts, which is a key usage decision. It also notes that it reads the shift first and sends it back, implying prerequisites. However, it does not explicitly state when to use this tool versus alternatives like create_roster or list_rosters, though the purpose makes that fairly clear.

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