Deputy MCP by usefulapi

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

Annotations only supply destructiveHint=true; the description usefully adds the downstream consequence ('Auto-scheduling then skips them') and the accepted recurrence format, which the annotations cannot convey. However it says nothing about permissions, whether an existing overlapping block is replaced, or reversibility, so it leaves gaps for a mutation tool.

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

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

Three tight sentences, front-loaded with the core action and effect, with the recurrence detail and API path trailing. The 'Deputy: POST /api/v1/supervise/unavail.' line is arguably extraneous for an agent but is short and non-disruptive.

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 5-parameter mutation with no output schema, the description covers what is recorded, the one-off/recurring split, and the scheduling side effect, which is enough to call it correctly. It is somewhat thin on failure modes and permissions, but the destructive annotation plus rich schema carry most of the load.

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_time, end_time, recurrence, and employee_id are already documented with format guidance. The description reinforces the recurrence syntax with a concrete 'FREQ WEEKLY, INTERVAL 1, BYDAY MO' example but adds little beyond the schema's own field descriptions. 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 ('Record a time an employee cannot work') and immediately distinguishes one-off from recurring with an RFC 5545 example. An agent can separate this write tool from the get-side sibling deputy_get_employee_unavailability without opening either 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 implies context by contrasting one-off vs recurring blocks and noting that auto-scheduling then skips the employee, but it never states when to prefer this over siblings like deputy_create_leave_request or deputy_update_shift, nor any prerequisites. Usage is inferable but not explicit.

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

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

Goes beyond the destructiveHint=true annotation by disclosing the downstream consequence: approved timesheets flow toward payroll export, which tells the agent approval has real side effects. The supervisor framing also hints at authorization context, though it does not state reversibility or error behavior.

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

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

Three short sentences, front-loaded with the action and its consequence, then the prerequisite, then the API endpoint. The endpoint reference is somewhat redundant but compact and does not bloat the definition.

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 what happens (approval), the consequence (payroll export), and the pre-check it should follow. Only reversibility/error handling is absent, which is 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?

Only one parameter, and schema description coverage is 100%, so the schema fully documents timesheet_id. The description adds no format, source, or lookup guidance beyond the schema, so a 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 (Approve) plus resource (timesheet's times) and actor scope (as a supervisor). This clearly separates it from read/inspection siblings like deputy_get_timesheet, though it does not explicitly differentiate itself from deputy_update_timesheet.

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

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

Gives an explicit prerequisite ('check it first with deputy_get_timesheet') and names the sibling to use beforehand, which is strong when-to-use guidance. It stops short of stating when NOT to use it or naming a sibling that competes for the same intent.

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

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

Annotations only declare destructiveHint=true, so the description usefully adds the approval-workflow semantics (default status 0 waits for manager approval), the fact that leave is tracked in hours requiring exact start/end times, and the API route. It does not cover failure behavior or what happens to overlapping/duplicate leave, but it adds real context beyond the annotations.

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

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

Four short sentences, front-loaded with the action and the default behavior, then the exception, then unit/time guidance, then the id lookup and endpoint. No filler or repetition.

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 10-parameter mutation with no output schema, the description covers the critical gotchas: approval status semantics and the hours/exact-times requirement. It leaves the required comment field and any validation/failure behavior unexplained, so it is strong but not fully complete.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it explains the default/conditional semantics of status and tells the agent how to obtain a valid leave_rule_id via deputy_query_resource on LeaveRules. It does not clarify why comment is required or the approval_comment interaction.

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

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

Opens with a specific verb+resource ('Add a leave request for an employee') and immediately scopes the default behavior. It is clearly distinguishable from deputy_list_leave and the other create_* siblings, and it even names the underlying Deputy endpoint.

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 explicit conditional guidance for status ('pass status 1 only when your system is the source of truth and the leave is already approved') and routes the agent to deputy_query_resource on LeaveRules for the leave type id. It does not state when to prefer a sibling (e.g. deputy_list_leave) or any precondition on the required comment field, so it falls just short of fully explicit when/when-not coverage.

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

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

Annotations only supply destructiveHint=true, so the description carries most of the behavioral burden. It adds useful context beyond annotations: 'Visible to staff immediately' discloses the side effect timing and the confirm-read option has a stated default. However, it says nothing about authoring permissions, whether memos can be edited/deleted afterwards, or rate behavior.

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

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

It is a single packed sentence with the core action front-loaded, followed by a terse endpoint reference. The trailing 'Deputy: PUT /api/v1/...' adds little for an agent but does not bloat the text.

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

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

For a 5-parameter mutation tool with no output schema and thin annotations, the description covers the key behaviors (visibility timing, targeting, confirmation). It is reasonably complete, though it omits return information and permission requirements.

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

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

Schema description coverage is 100%, so all five parameters are already documented in the schema. The description mirrors the targeting concepts (specific locations or users, confirm read) but adds no syntax, format, or edge-case detail beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('Post a memo to a location's news feed') with clear scope, plus the targetable dimensions. No sibling tool competes with it, and an agent can distinguish it from the shift/leave/timesheet tools 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?

It explains the targeting options and the confirm-read flag, but gives no when-to-use guidance or alternatives context, nor any prerequisites (e.g., what permissions are needed to post a memo). Usage is only inferable from the parameter mention.

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?

Adds substantive behavior beyond the destructiveHint annotation: default DRAFT state, that publishing can notify the employee, and that success returns an empty 200 body. These side-effect disclosures are exactly what a create tool needs, though it never explains why destructiveHint is true (e.g. force_overwrite clobbering).

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: what it does, the default/notification behavior, and the empty-response workaround plus endpoint. No filler, front-loaded with the action.

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

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

There is no output schema, and the description compensates by explaining the empty 200 response and the follow-up call needed to obtain the id — the single most important gap for a create tool. Combined with the annotation and full schema coverage, 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 coverage is 100%, so all ten parameters are documented in the schema; the description only restates the publish/open semantics already present in the parameter descriptions. Baseline 3 is appropriate since the schema carries the parameter burden.

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

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

Specific verb (Add) plus resource (a shift to the roster) with scope details: assigned to an employee or left open. The name/create intent is unmistakable and clearly separable from deputy_update_shift and deputy_publish_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?

Explains the draft-vs-publish decision point and tells the agent to use deputy_list_shifts afterward to recover the new shift id, which is real workflow guidance. It does not explicitly contrast with siblings like deputy_update_shift or deputy_publish_shifts, so it stops 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?

readOnlyHint=true already covers the safety profile, so the bar is lower. The description adds real substance: it discloses the three parts of the return payload (field list, field types, joinable associations) despite there being no output schema, and names the underlying HTTP route. No auth or rate-limit caveats, but for a simple INFO call that is a minor omission.

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

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

Two clauses with zero redundancy: the capability statement comes first, the API route second as reference detail. Every word earns its place and the reader gets the essential concept in the first clause.

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-only metadata lookup with no output schema, the description supplies the return shape (fields, types, joins) and the sibling relationship, which is everything an agent needs to decide to call it and to interpret the result. Nothing material is missing.

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

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

Schema description coverage is 100% and the single enum parameter is richly documented in the schema, including the Deputy naming aliases (Company = location, Roster = shift, etc.), so the schema does the heavy lifting. The description only references the parameter indirectly via the '{Object}' path placeholder; 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 precise verb and resource (return a Resource API object's field list, field types, joinable associations) and explicitly ties itself to the sibling deputy_query_resource by naming what that tool can filter/sort/join on. The endpoint reference (GET /api/v1/resource/{Object}/INFO) pins down the exact operation, so the agent can distinguish this metadata tool from the query tool without opening either 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 'what deputy_query_resource can filter, sort and join on' clause tells the agent the downstream purpose, implying this is a discovery step before querying. It routes to the sibling by name, but it never states the explicit trigger ('call this before deputy_query_resource when you don't know the fields') or any when-not condition.

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 genuinely useful context beyond that: the response is filtered to the supervisor's visibility of the employee, which tells the agent that field presence and values can differ by caller privileges. It omits behavior for an unknown id, but the supervisor-scoping disclosure is real added value.

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, zero filler: the capability statement comes first and the raw endpoint mapping follows as a compact parenthetical. Every clause carries information an agent can use.

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

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

For a single-parameter read with no output schema, the description compensates reasonably by listing the categories of data returned, so an agent knows what it gets without a response schema. Missing only edge-case behavior (nonexistent id, permission-denied response), which is a minor gap for a read tool whose annotations already signal safety.

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

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

Schema description coverage is 100% with a single integer employee_id, so the schema carries the parameter burden and the description contributes nothing about the id (format, source, whether it must be a Deputy-internal id). Nothing here exceeds what the schema already states.

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

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

Specific verb (fetch) plus resource (one employee's details) with scope qualifier 'as a supervisor sees them,' and an enumeration of the returned facets (contact, locations, role, employment). The word 'one' cleanly separates it from the sibling deputy_list_employees and from deputy_get_employee_unavailability.

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 'one employee' versus the sibling list tool, and the supervisor-view framing hints at when this variant applies. However, no alternative is named explicitly and no precondition (e.g. needing a known employee_id) is stated, so the agent must infer the selection logic.

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 context beyond that: unavailability records may be self-marked OR marked by someone else, which tells the agent what population of records it will see, plus the concrete API 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?

One front-loaded sentence carrying the purpose and the usage trigger, followed by an endpoint reference. Nothing is padded, though the raw API path is marginally redundant for an agent that already has the tool interface.

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 this covers what to call and why. However, with no output schema, the description never indicates what the returned time records look like or whether results are paginated, leaving the agent guessing about the response shape.

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

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

Schema coverage is 100% and the single parameter (employee_id) is already documented in the schema. The description only restates it via the URL template, adding no format or constraint detail beyond the schema's minimum/maximum.

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 (times one employee marked unavailable to work), scoped to a single employee. It is immediately distinguishable from the sibling deputy_add_unavailability, which is the write counterpart.

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?

"check before rostering them" gives a concrete workflow trigger for calling the tool, which is better than generic guidance. It stops short of naming alternatives or stating when-not to use it (e.g., vs. deputy_list_shifts), so it does not reach the top band.

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

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

Annotations already declare readOnlyHint=true and the description corroborates the read-only GET endpoint, so no contradiction. It adds the useful Roster-resource mapping but says nothing about error behavior for a missing id, permissions, or response shape.

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

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

Two short sentences, front-loaded with the action and resource, with the API endpoint as supporting detail. 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 single-parameter read tool with no output schema, the description covers what is fetched and by what key. It could add a note on what the return contains or on not-found handling, but nothing essential to invoking it is missing.

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

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

Only one parameter and schema description coverage is 100%, so the schema already documents shift_id as the Roster id. The description's parenthetical '(Roster record)' adds the domain mapping but no new constraint or format detail, matching the baseline for fully covered schemas.

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 shift, mapped to the Deputy Roster record) with the lookup key (id). It implicitly separates itself from deputy_list_shifts by scope, but never names the sibling, so it falls short of the top mark.

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: fetch a single shift when you already have its id. There is no statement of when to prefer this over deputy_list_shifts or deputy_query_resource, and no exclusion 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 covers the safety profile, so the bar is lower, and the description adds real value by disclosing that the payload contains breaks and approval state — meaningful context given there is no output schema. It also cites the underlying endpoint, aiding traceability. No pagination or error behavior is mentioned, but that is not expected for a single-record read.

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

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

Two short sentences, front-loaded with the action and payload, followed by an endpoint reference. Nothing is redundant and nothing needs re-reading.

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

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

For a single-parameter read with annotations covering safety and no output schema, this is nearly sufficient: it says what is returned (breaks, approval state) and where it comes from. A brief note on how this differs from the list/update tools would close the remaining 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?

With one parameter at 100% schema description coverage, the schema already documents timesheet_id; the description adds no format, range, or sourcing guidance beyond the '{id}' placeholder in the endpoint string. This is the baseline 3 case where structured fields do 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 (fetch) and resource (one timesheet) with a scope qualifier ('one') that implicitly distinguishes it from deputy_list_timesheets. However, it never names the sibling tools it must be told apart from, so 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?

Usage is only implied: the agent is expected to infer that this is the right call when it has a specific timesheet_id and needs the detailed record. There is no explicit when-to-use, no exclusion of the list/update/approve siblings, and no stated 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?

readOnlyHint=true already tells the agent this is a safe read, so the description is not carrying the safety burden. It adds useful domain context that shifts and timesheets belong to an area, but does not disclose pagination behavior, default limits, or result shape beyond what the annotations and schema imply.

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

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

Short and front-loaded: the resource and its meaning come first, then scope and filtering. The trailing endpoint paths (GET/POST .../OperationalUnit) are the one expendable element for an agent-facing definition, but overall there is little waste.

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 no-required-parameter, non-destructive list tool with 100% schema coverage and no output schema, the description supplies everything an agent needs: what an area is, how it relates to shifts/timesheets, and that results can be scoped to one location. 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 four parameters (max, start, active, location_id) are already documented, including the cap and offset semantics. The description only loosely echoes the location filter ('Optionally only one location's areas') and adds no format or edge-case detail beyond the schema; baseline 3 is appropriate.

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

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

Uses a specific verb (List) on a specific resource and immediately disambiguates the Deputy term 'OperationalUnit' with the domain gloss 'the rosterable sections of a location, e.g. Kitchen, Front of house'. It also states the relationship to shifts/timesheets and the filtering capability, so an agent can distinguish it from siblings like deputy_list_locations or deputy_query_resource 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?

'Optionally only one location's areas' implies when the location_id filter applies, but there is no explicit when-to-use/when-not-to-use guidance relative to siblings such as deputy_list_locations or deputy_describe_resource. The mention of the underlying GET vs POST QUERY endpoints is implementation detail, not invocation guidance for 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 already declare readOnlyHint=true, so the safety profile is covered. The description adds genuinely useful context by enumerating the returned fields (Id, DisplayName, Company, Active, StartDate) and citing the underlying Deputy QUERY endpoint, though it says nothing about rate limits or pagination semantics beyond what the schema carries.

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

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

Three short front-loaded sentences with no filler; the API-endpoint note is arguably cosmetic but still earns its place as Deputy-specific context. Nothing else 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 shoulders the burden of explaining return values and does so with a concrete field list plus 'and more'. Combined with a fully documented schema and a readOnly annotation, this is nearly complete; only pagination expectations are left implicit.

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

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

Schema description coverage is 100%, and the schema documents caps, offset semantics and each filter precisely. The description's phrase 'by name, location or active status' maps loosely onto three parameters but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb (search/list) and resource (employees) plus the filterable dimensions (name, location, active status). An agent can distinguish it from the singular sibling deputy_get_employee without opening either 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 filter list implies when the tool is useful (bulk retrieval with filtering), but it never states when to prefer it over deputy_get_employee or deputy_query_resource, nor any prerequisites. Usage is inferred rather than guided.

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 only needs to add beyond that. It contributes pagination context (offset semantics, page-size cap) and the status-code table, but discloses nothing about permissions, result ordering, or caps on result volume.

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 purpose, followed by the filter/status reference and the endpoint. Every clause is dense but earns its place; 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?

Covers the searchable dimensions, status enumeration, time-unit semantics, and pagination handoff. No output schema exists, so return shape is unexplained, and the mismatch between the description's 'LeaveRule'/'Start'/'End' naming and the schema's parameters is a minor completeness 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 coverage is 100%, but the schema's status parameter only says '0-5, see description' — the actual code-to-meaning mapping exists solely in the description, so the description carries real semantic weight there. It also clarifies Start/End as unix and LeaveRule as the leave-type id, though it uses the name 'LeaveRule' which does not match the schema's employee_id/location_id/from/to names.

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 a specific verb+resource ('Search leave requests') and enumerates the four filter dimensions (employee, location, status, time window). An agent can distinguish it from deputy_create_leave_request without opening either 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 filter list implies when this tool is useful (querying existing leave), but there is no explicit when-to-use statement, no prerequisites, and no named alternative such as deputy_query_resource or deputy_create_leave_request. Usage is implied 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?

readOnlyHint=true already covers the safety profile, and the description adds value by disclosing the backing endpoint (GET /api/v1/resource/Company) and the Company/location naming convention. It does not describe return contents, so with annotations carrying the safety burden this is adequate but not rich.

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 no waste, front-loaded with the action and resource. Each sentence earns its place by adding terminology mapping and endpoint provenance.

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

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

For a zero-parameter read tool with readOnlyHint and no output schema, the description is close to complete: it identifies the resource, maps Deputy's odd naming, and explains the returned Id's role. It could optionally note whether the list is paginated or filtered, but nothing required 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 the baseline is 4 and there is nothing for the description to compensate for. The note about the Id field being consumed as location_id elsewhere usefully explains what downstream tools expect, though it is return semantics 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 install's locations) and immediately disambiguates the terminology mapping (Deputy calls a location a Company). It also discloses the underlying endpoint, which lets an agent distinguish it from siblings like deputy_list_areas or deputy_list_employees 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 implied rather than stated: the note that the returned Id is what other tools take as location_id signals this is a lookup to resolve location IDs before calling other tools. There is no explicit when-to-use/when-not or named alternative, so it lands at minimum-viable implied guidance.

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

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

Annotations declare readOnlyHint=true, and the description goes beyond that by disclosing the returned record shape (StartTime/EndTime unix, StartTimeLocalized, Employee as 0 or null when open, OperationalUnit, Published, Open, Cost, _DPMetaData) and the underlying API endpoint. No output schema exists, so this return-shape disclosure is genuinely load-bearing. It does not add permission or rate-limit detail, and the 'POST .../QUERY' endpoint note is an implementation detail rather than a behavioral trait, but the safety profile plus return structure is well covered.

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, zero waste. The search scope and filter axes are front-loaded in sentence one; the return-field inventory and API reference follow. Nothing is padding, especially since the field list substitutes for a missing output schema.

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

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

With 8 all-optional parameters and no output schema, the description does the heavy lifting on return values and filter axes, which is exactly what an agent needs to construct a query. It stops short of describing pagination/limit behavior (max cap, next_start chaining) beyond what the schema states, so it is strong but not fully complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description's filter enumeration (time window, employee, area, published/open) maps onto from/to, employee_id, area_id, published, and open, and '(0 or null when open)' clarifies the Employee value convention, but it adds no format or syntax detail beyond what the schema already states for each parameter.

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 ('Search the roster (scheduled shifts)') plus the four filter dimensions. An agent can distinguish it from deputy_get_shift (single shift), deputy_create_shift, and deputy_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?

Usage is implied by the filter-oriented phrasing, and the Deputy endpoint (Roster/QUERY) hints at a query operation, but there is no explicit when-to-use guidance and no named alternative such as 'use deputy_get_shift for a single shift by id'. Adequate but leaves routing to inference.

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

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

With readOnlyHint=true already covering the safety profile, the description adds real behavioral context: EndTime is null while a shift is in progress, IsInProgress/IsLeave/TimeApproved/PayRuleApproved semantics, and the underlying query endpoint. It stops short of noting pagination flow or rate limits, so it is solid rather than 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, front-loaded with the search scope, with the field enumeration efficiently packed into one parenthesis because there is no output schema. The trailing endpoint string is minor implementation detail, but the rest earns its space.

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?

Nine parameters, all schema-documented, and a read-only annotation; the field list in the description compensates for the absent output schema by telling the agent what each returned record contains. Nothing needed to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so the normalized baseline is 3. The description restates the filter axes already documented in the schema (from/to, employee_id, area_id, approval booleans) and adds no format or precedence detail beyond it.

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 ('Search timesheets') plus the exact filter axes (time window, employee, area, approval state), and the parenthetical '(actual worked time)' separates it from shift or leave data in the sibling set. An agent can distinguish this from deputy_get_timesheet and deputy_list_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?

The filter list implies when this tool applies (multi-record search over a window), but the description never states when NOT to use it or names the alternatives, e.g. deputy_get_timesheet for a single record or deputy_list_shifts for rostered rather than worked time. Usage must be inferred from the sibling set.

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 destructiveHint=true already declared, the description adds real value by disclosing the employee-facing side effects (visibility, SMS/email notification, confirmation-required mode) that annotations don't convey. It stops short of stating permission requirements or whether publishing can be undone.

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?

Effect and notification options are front-loaded in one dense sentence, with the scope limit following immediately. The trailing REST endpoint is extraneous for an agent but cheap and non-disruptive.

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

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

For a two-parameter tool with no output schema, the description covers what it does, its scope, and its notification behaviors adequately. Missing only edge-case behavior (invalid/already-published ids, reversibility) for full marks.

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 description's enumeration of notify_mode values is essentially a restatement of the schema's own description, so no new semantic depth is added. The note that only listed ids are published is a mild constraint clarification, but the baseline 3 applies.

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

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

States a specific verb (publish) and resource (draft shifts) plus the consequence (employees see them), which cleanly separates it from sibling mutations like deputy_create_shift and deputy_update_shift. The endpoint detail reinforces the operation.

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 implies the tool applies to draft shifts and scopes the effect with 'Only the listed shift ids are published', which is useful context. However, it never says when to prefer this over updating/creating shifts, nor whether publishing is reversible or what happens to already-published ids.

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 redundantly repeats 'Read-only.' It does add the underlying call (POST /api/v1/resource/{Object}/QUERY), which usefully reconciles a write-looking HTTP verb with read-only semantics. However, it says nothing about rate limits, result envelope, or pagination behavior, so it adds only a little beyond the annotation.

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

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

Front-loads the purpose and object examples, then the search syntax, then a routing hint. Dense but readable; the inline operator enumeration and the raw endpoint string are the only slightly expendable material, and the endpoint does carry some informational value.

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

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

For a 6-param, deeply nested, no-output-schema tool, the description covers what can be queried, how clauses are shaped, and how to discover unknown fields. The remaining gap is the response shape and pagination contract (next_start), which is only hinted at inside the schema rather than explained.

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 schema already documents max/start/sort/join/object/search, including the clause structure and operator enum. The description's clause-map example and operator list largely restate what the schema provides, so it does not meaningfully extend param semantics. Baseline 3 applies.

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

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

Opens with a specific verb and resource ('Run a Resource API search on any business object') and enumerates the object families covered (leave types, pay rules, shift templates, pay lines, availability, sales data). The 'any business object' scope implicitly carves it out from the narrow sibling list_* tools, so an agent can place it without opening the schema.

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

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

Gives clear workflow context by routing field/join discovery to deputy_describe_resource, which is the natural prerequisite for building a valid query. It stops short of naming when to prefer this generic query over the specific deputy_list_employees / deputy_list_shifts siblings, so there are no explicit exclusions.

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

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

Annotations only supply destructiveHint=true; the description adds real value by revealing that Deputy's update is the add call with the shift id, which explains why the full payload is required and implies omitted fields are overwritten. It still does not spell out consequences for unspecified fields or that publish can notify the employee (that fact lives 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?

Three short sentences, with the purpose and the payload requirement front-loaded. The trailing endpoint note ('Deputy: POST /api/v1/supervise/roster with intRosterId') is largely implementation detail that does not help tool selection, keeping it out of 5 territory.

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 tool with no output schema and only a destructiveHint annotation, the description covers purpose, required-field expectations and replace semantics, which is most of what an agent needs. It could still be explicit that unspecified fields are reset and note any permission requirements.

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

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

Schema description coverage is 100%, so the schema already documents all 11 parameters with formats, defaults and ranges. The description only restates the field categories (times, area, employee, break, comment) and adds no syntax or constraint detail beyond the schema, which is the expected baseline.

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

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

States a specific verb and resource ('Change an existing shift') and enumerates the mutable fields (times, area, employee, break, comment). The word 'existing' implicitly separates it from deputy_create_shift, but no sibling is named explicitly, so it stops short of full differentiation.

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

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

Gives actionable usage context: 'Send the full intended shift (same fields as create)' tells the agent this is a replace-style payload, not a partial patch. No explicit when-not-to-use or sibling routing (e.g., publish_shifts), 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?

The destructiveHint annotation already signals a mutating operation, so the bar is lower. The description adds a useful validity constraint (no future times) and the underlying endpoint, but does not say whether omitted optional fields are preserved or cleared, what permissions are required, or how errors surface.

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

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

Three compact sentences, front-loaded with the action and correctable fields. The trailing 'Deputy: POST /api/v1/supervise/timesheet/update' is marginally redundant with sibling conventions but is short and harmless.

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

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

For a destructive 6-parameter mutation with no output schema and no readOnly/safety annotations beyond destructiveHint, the description covers the action and one constraint but omits partial-vs-full update semantics, permission requirements, and result behavior. Adequate but with clear 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 all six parameters are already documented with types, ranges and formats (unix seconds or ISO 8601). The description's mention of meal break and comment mirrors the schema without adding format or default semantics, 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 ('Correct an existing timesheet') and enumerates the exact fields it can change (start/end time, area, meal break, supervisor comment), which cleanly separates it from siblings like deputy_approve_timesheet and deputy_update_shift. An agent can select it 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?

'Correct an existing timesheet' implies the usage context, and 'Times cannot be in the future' is a real invocation constraint. However, there is no explicit when/when-not guidance or pointer to alternatives (e.g. approve_timesheet, get_timesheet), so usage is only implied.

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

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

The readOnlyHint annotation already covers safety, so credit goes to what the description adds: the identity/scope of the lookup (token-derived), the returned field set, and the cost signal ('cheap'). With no output schema, disclosing the return contents is genuinely useful information the agent cannot get elsewhere.

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

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

Two short sentences plus an API endpoint citation, with the purpose front-loaded before the when-to-use rationale. Nothing is padded and every clause carries information.

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

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

For a zero-parameter tool with no output schema, the description supplies the returned field list and the reason to call it, which covers the practical gaps. The only shortfall is the absence of any error/auth-failure behavior guidance, which is minor given the simplicity.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly implies no input is needed since the token is the implicit subject, and nothing is left ambiguous about what to supply.

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 the Deputy user the token belongs to') and enumerates what comes back (name, employee id, company, permissions). This clearly separates it from siblings like deputy_get_employee, which take an employee identifier rather than resolving the token owner.

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

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

'A cheap way to confirm DEPUTY_INSTALL and the token are right' gives an explicit use context, so the agent knows when this diagnostic identity check is warranted. It does not name an alternative or state exclusions, which keeps it 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.