deputy

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

Annotations only supply destructiveHint=true, so the description usefully adds the downstream behavioral consequence that auto-scheduling will skip the employee during the window, plus the underlying API route. It does not state permission requirements, overlap handling, or how to undo the record, keeping it short of a 5.

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

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

Two tight sentences plus the endpoint reference; the core verb and the one-off/recurring distinction are 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?

For a 5-parameter write tool with a nested recurrence object and no output schema, the description covers the key decision (one-off vs recurring) and the scheduling impact. It omits return/ID behavior and validation constraints, but nothing critical to invoking it correctly is missing.

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

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

Schema coverage is 100%, and the description's recurrence example ('FREQ WEEKLY, INTERVAL 1, BYDAY MO') and 'Omit for a one-off block' largely restate what the nested schema properties already document. 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+resource: 'Record a time an employee cannot work', immediately scoped to one-off vs recurring blocks. It clearly distinguishes itself from the read-side sibling deputy_get_employee_unavailability and from shift/leave tools by naming the concrete effect on availability.

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: 'Auto-scheduling then skips them' tells the agent why the record matters, but there is no explicit when-to-use versus alternatives such as deputy_create_leave_request, which also blocks an employee's time. No exclusions or prerequisites are given.

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 annotation by explaining the downstream consequence: approved timesheets flow toward payroll export. It still does not say whether approval is reversible or requires specific supervisor permissions, but the payroll-flow context is genuinely useful behavior an agent cannot get from the annotations.

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

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

Two short sentences plus an endpoint: the purpose is front-loaded, the caveat follows immediately, and 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?

Adequate for a single-parameter mutation with a destructive annotation and a stated downstream effect. The only gap is error/response behavior (e.g., what happens if already approved), which is minor given there is no output schema.

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

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

Only one parameter (timesheet_id) and schema coverage is 100%, with an inline description; the description adds no format, range, or sourcing detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (approve), a specific resource (one timesheet's times), and the actor role (as a supervisor), which cleanly separates it from the sibling deputy_update_timesheet and the read-only deputy_get_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/verification step ('check it first with deputy_get_timesheet') and a reason for it, but does not state when approval should be withheld or which alternative to use if the timesheet is wrong.

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 only annotation is destructiveHint=true, which carries little semantic weight, so this description does real work: it discloses the default approval workflow (status 0), the narrow condition for auto-approval (status 1), and that Deputy records leave in hours requiring exact start/end times. It does not cover permissions, whether the request can be edited afterward, or what the response returns, but it adds meaningful behavior 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?

Four tight sentences, front-loaded with the action, then the approval-status rule, then the time-granularity caveat, then the lookup route. No filler and no restatement of schema fields.

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 8-required-parameter creation tool with no output schema, the description covers the two things the schema cannot: the default/override approval behavior and how to obtain the leave-rule id. Missing only edge-case guidance (e.g. overlapping leave, location mismatch) that an agent might want before writing.

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 goes slightly beyond the schema by clarifying the default semantics of status (schema only says '0 awaiting approval (default)') and by explaining the hours/start-end precision requirement, and it supplies the discovery method for the otherwise opaque leave_rule_id.

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 ('Add a leave request for an employee') and even names the underlying endpoint (POST /api/v1/resource/Leave). It routes the agent to deputy_query_resource for leave-rule ids, but does not explicitly contrast itself with the other write siblings such as deputy_add_unavailability, so it stops short of full sibling 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 a concrete conditional for the status parameter: default 0 (awaiting manager approval), pass 1 only when the caller's system is the source of truth and leave is already approved. It also tells the agent where to find leave_rule_id (deputy_query_resource on LeaveRules). No explicit when-not-to-use case or alternative create path is stated, so it is clear context without exclusions.

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

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

Adds genuinely useful behavior beyond annotations: staff see it immediately and can be forced to confirm read. However, destructiveHint=true is set while this is an additive create operation, and the description neither explains nor reconciles that; it also omits auth/permission requirements and what happens on a failed post.

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 densely packed sentence plus the endpoint reference; nothing is repeated and the core action leads. The trailing "Deputy: PUT /api/v1/..." is marginal but cheap and useful for API-aware agents.

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 create tool with no output schema, the description covers purpose, side effects (immediate visibility), and the confirm flow, with the schema handling parameter detail. Only the destructiveHint mismatch and absence of failure/permission behavior keep it from being fully complete.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters, including the user-ids-not-employee-ids distinction. The description only restates the targeting and confirm options at a high level, adding no syntax or format 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?

Specific verb + resource ("Post a memo to a location's news feed") with scope and optional behaviors (read confirmation, multi-location/user targeting) stated up front. It also names the underlying Deputy endpoint, making it unmistakably distinct from the shift/timesheet/leave 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?

Implies usage context (news feed post, visible to staff immediately) but never states when to choose this over an alternative or any prerequisites such as permissions. No sibling tool covers memos, so the gap is narrow, but the description gives no explicit when-to-use 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 only carry destructiveHint=true and a title, so the description does the heavy lifting. It discloses the draft-by-default lifecycle, that publishing can notify the employee, and critically that Deputy returns an empty 200 with no id, directing the agent to deputy_list_shifts. This is exactly the behavior an agent cannot infer from structured fields.

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 lifecycle and side effect, then the surprising response behavior. No wasted words and the most decision-relevant facts come first.

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 fully by explaining the empty 200 response and the follow-up call to obtain the id. Combined with the draft/publish and notification details, an agent has everything needed to invoke this 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 each parameter is already documented, and the description largely restates what the schema says (open vs. employee_id, publish default). Baseline 3 is appropriate since the schema carries 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 ('Add a shift to the roster') with the scope that it may be filled or open. It distinguishes itself implicitly from deputy_update_shift through 'Add', but does not explicitly name that sibling the way it names deputy_list_shifts.

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

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

Gives clear operational context: created as a DRAFT unless publish is true, and directs the agent to deputy_list_shifts to retrieve the new id. It does not state explicit when-not conditions (e.g., when to use update_shift instead), 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 establishes it is a safe read, and the description adds real behavioral context by naming the underlying passthrough (GET /api/v1/resource/{Object}/INFO) and describing the shape of what is returned (fields, types, joinable associations). It stops short of discussing permissions, error behavior for unknown objects, or caching.

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 covering purpose, return content and downstream use, followed by a terse endpoint reference. No filler, and the payoff ('what deputy_query_resource can filter, sort and join on') is placed prominently.

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 a single-param tool and no output schema, the description carries the burden of describing the return and does so (field list, field types, joinable associations). It could be slightly more complete on failure modes for invalid object names, but nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100% and the enum documents all 52 object names plus the Deputy naming aliases, so the schema carries this dimension. The description only supplies the {Object} placeholder correspondence, which is marginal additional value; 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 (return) and resource (a Resource API object's field list, types and joinable associations), naming exactly what artifact comes back. It explicitly ties itself to the sibling deputy_query_resource as the consumer of that metadata, so an agent can separate it from query/list tools 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 clearly implied: this is the introspection step that tells you 'what deputy_query_resource can filter, sort and join on', so the natural workflow is describe-then-query. It does not spell out an explicit when-not or preconditions (e.g. whether the object must exist or be permitted), which keeps it just short of a 5.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds real value beyond that by noting the result is 'as a supervisor sees them', signaling that visibility/fields are permission-scoped, and by citing the backing endpoint GET /api/v1/supervise/employee/{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?

A single sentence that front-loads the action and resource, then the returned facets, then the API reference. No filler and nothing repeated from the schema.

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

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

With no output schema, the description usefully names the categories of data returned (contact, locations, role, employment) and the permission-scoped view. It lacks error/not-found and permission-failure behavior, but for a read-only single-resource lookup it is nearly complete.

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

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

Schema coverage is 100% and the single parameter has its own description in the schema, so the description need not re-explain employee_id; baseline 3 applies. It adds no format or constraint detail (e.g. id provenance) beyond the schema.

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

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

States a specific verb and resource ('Fetch one employee's details') and enumerates the returned facets (contact, locations, role, employment). The word 'one' plus the singular focus clearly distinguishes it from the sibling deputy_list_employees.

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 singular 'one employee' framing, so an agent can infer this is for a known employee_id rather than browsing. However, it never states when to prefer this over deputy_list_employees or what prerequisites (such as supervisor scope) are needed to call 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?

The description is consistent with readOnlyHint=true and confirms this is a read of existing unavailability entries, so no contradiction. Beyond that it adds little behavioral context — no mention of pagination, date-range scoping, or whether output is grouped, presumably because the annotations already carry the safety profile.

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 purpose and usage, plus a compact API reference for implementers. Nothing is redundant and no sentence is wasted.

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

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

For a simple one-param read tool with an annotation covering the safety profile, purpose plus the pre-rostering usage cue is enough to call it correctly. The only mild gap is that with no output schema there is no hint about the shape or volume of returned unavailability entries.

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

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

There is a single parameter and schema description coverage is 100%, so the schema already documents employee_id adequately. The description adds no syntax or format detail beyond what the schema provides, which is the expected baseline for a fully covered single-param tool.

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 times one employee ... unavailable to work') and names the scope precisely: one employee's unavailability records. This clearly distinguishes it from the sibling deputy_add_unavailability (which writes) and from shift/timesheet tools.

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

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

Gives an explicit usage cue — 'check before rostering them' — which tells the agent when this tool is relevant. It stops short of naming an alternative or stating exclusions, so it is clear context rather than a full when/when-not decision rule.

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 the underlying REST endpoint (GET /api/v1/resource/Roster/{id}), which is modestly useful context, but says nothing about error behavior (e.g., not-found) or the shape of the returned record.

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

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

Two short sentences, zero filler, and the identity of the resource is front-loaded before the endpoint detail. 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 one-param getter this is close to adequate, but with no output schema the description could have said what a shift record contains or what happens on a missing id. The endpoint reference partially compensates, leaving a clear 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% with a single documented integer parameter, so the schema fully carries parameter meaning. The description only restates "by id" and adds no format, range, or lookup semantics beyond the schema.

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

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

States a specific verb ("Fetch") and resource ("one shift (Roster record) by id"), which distinguishes it from the list/create/update shift siblings by implying single-record retrieval. It stops short of explicitly naming those alternatives, so it isn't a textbook 5.

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

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

There is no when-to-use guidance, no mention of prerequisites (e.g., needing a valid shift_id), and no contrast with deputy_list_shifts or deputy_query_resource. "By id" weakly implies the use case but nothing is 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 tells the agent this is a safe read, lowering the burden. The description adds useful context about what the payload contains (breaks, approval state) and maps to the underlying endpoint GET /api/v1/supervise/timesheet/{id}/details, but says nothing about failure behavior for an invalid id or any rate limits.

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 with zero filler; the core action leads and the endpoint reference trails as supporting detail. Nothing is wasted and nothing important is buried.

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

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

With no output schema, the description partially compensates by naming what the response contains (breaks, approval state). However, it does not cover error cases such as an unknown timesheet_id, which matters for a single-resource fetch with a required 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?

There is exactly one parameter with 100% schema description coverage, so the schema fully documents timesheet_id. The description adds no syntax, format, or validity detail beyond it, 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?

The description states a specific verb and resource ('Fetch one timesheet's full details') and scopes the payload by naming 'breaks and approval state.' The word 'one' implicitly separates it from deputy_list_timesheets, though no sibling is named explicitly, so differentiation is inferred rather than stated.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as deputy_list_timesheets or deputy_get_shift. The agent must infer from the name that this is the single-record retrieval 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, so the description carries most of the burden and does add value: it explains the domain model (areas own shifts and timesheets) and discloses that filtering switches the backend behavior from GET /OperationalUnit to POST .../QUERY. It stops short of describing pagination behavior or result shape, but the added context is substantive for a read-only 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?

Front-loaded with the purpose and definition, followed by the relation and filter note in two tight sentences. The trailing endpoint/verb string is developer-facing detail that is less useful to an agent but does not bloat the description.

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

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

No output schema exists, but the description covers identity, domain relations, and the filter behavior for a 4-optional-param read tool whose schema is fully documented. Only the return shape and pagination contract 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%, so max, start, active, and location_id are already fully documented with ranges and semantics. The description only gestures at the location filter and adds no syntax or format detail beyond the schema; baseline 3 is correct.

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

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

States a specific verb and resource, then disambiguates with the underlying Deputy entity name (OperationalUnits) and a concrete definition ('the rosterable sections of a location, e.g. Kitchen, Front of house'). The relation to shifts and timesheets further separates it from siblings like deputy_list_locations.

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 the filter use case, but there is no explicit when-to-use guidance or named alternative (e.g. call deputy_list_locations first to obtain a location_id). 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?

readOnlyHint=true already tells the agent this is a safe read. The description adds the returned field set, which is genuinely useful context, but says nothing about pagination behavior, result ordering, or empty-result semantics beyond what the schema already declares for start/max.

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 capability and filter axes. The trailing internal API endpoint note (POST /api/v1/resource/Employee/QUERY) is implementation detail that does not help an agent select or call the tool, slightly diluting an otherwise tight description.

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 returned fields (Id, DisplayName, Company, Active, StartDate, Role). Combined with readOnly annotations and a fully documented parameter schema, an agent has what it needs, though ordering and total-count behavior remain unstated.

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

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

Schema description coverage is 100%, so every parameter including pagination semantics is already documented in the schema. The description merely restates the filter axes (name, location, active status) without adding format or edge-case detail, so baseline 3 applies.

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

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

States a specific verb and resource ('Search employees') plus the filter dimensions, and the plural framing distinguishes it from the single-record deputy_get_employee. It never explicitly names the sibling it is not, so it falls short of full sibling differentiation.

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

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

The filter dimensions (name, location, active status) imply when a caller would reach for this tool, but there is no explicit when-to-use guidance and no routing to deputy_get_employee for a single record. 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?

readOnlyHint=true already tells the agent this is a safe read, so the description need not re-declare safety. It adds the underlying endpoint (POST /api/v1/resource/Leave/QUERY) and status semantics, but says nothing about rate limits, default page behavior, or result shape beyond what the schema covers.

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

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

Front-loaded with the core action and filter set, then the enum mapping, then the endpoint. Dense and free of filler, though the trailing LeaveRule/Start-End clause is dead weight that could be dropped.

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

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

For a read-only filtered list with no output schema, the description plus a 100%-covered schema gives the agent everything needed to construct a query: filters, status values, time-window types and pagination. The only real omission is what the response looks like, which is minor for a list endpoint.

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

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

Schema coverage is 100% and the schema explicitly defers the status enum to the description ('0-5, see description'), so the status code mapping is genuinely additive. However, 'Start/End are unix' conflicts with the schema, where `start` is a 0-based pagination offset, and 'LeaveRule is the leave type id' references a parameter that does not exist in the schema — stale/misleading text that offsets the gain.

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 leave requests') plus the four filter dimensions, and the read-only nature distinguishes it from the sibling deputy_create_leave_request. An agent can tell it apart from the create/approve tools 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 the tool is useful (scoping leave by employee/location/status/window), but there is no explicit when-to-use guidance, no statement of what it does not cover, and no named alternative for other leave operations. Usage is inferable but not stated.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds the underlying call (GET /api/v1/resource/Company) and the Company alias, but says nothing about pagination, permissions, or whether the list can be empty/scoped — modest added value against a low annotation bar.

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

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

Two tight sentences, front-loaded with the verb and resource, followed by the disambiguation and endpoint. No filler or repetition 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?

For a no-parameter read-only list tool with no output schema, the definition covers identity, vocabulary aliasing, downstream Id usage, and the raw endpoint. The only gap is the shape of the returned location records, which the agent must discover by calling 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?

There are zero input parameters, so the baseline is 4. The note about the returned Id mapping to location_id used by sibling tools is useful output-side context but not a parameter concern.

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 (workplaces)') and immediately disambiguates the domain vocabulary most agents would trip on: Deputy calls a location a Company. This lets an agent distinguish it from deputy_list_areas and deputy_list_employees 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?

Provides clear context for when this tool matters: its Id 'is what other tools take as location_id', effectively telling the agent to call this first when a location_id is needed elsewhere. It stops short of naming explicit alternatives or exclusions, so it is a 4 rather than a 5.

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

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

Annotations declare only readOnlyHint=true, so the description carries the rest and does so well: it enumerates the returned record fields (StartTime/EndTime, StartTimeLocalized, OperationalUnit, Published, Open, Cost, _DPMetaData with names) and clarifies that Employee is 0 or null for open shifts. It also discloses the underlying Deputy call. It stops short of describing result ordering or pagination behavior beyond the schema's start/max.

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: the first front-loads purpose and filters, the second enumerates the record shape, with the Deputy endpoint tacked on as a reference. No filler or restatement of the tool name.

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

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

No output schema exists, and the description compensates by listing the returned fields and the open-shift sentinel values, which is exactly what the agent needs to interpret results. With no required params and a clear read-only annotation, the remaining gaps (ordering, total counts, pagination loop details) are minor.

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

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

Schema description coverage is 100%, so every parameter is already documented with types, ranges and Deputy-specific semantics (next_start paging, 1-500 cap). The description only adds the Employee=0/null tie-in to the open flag, which is marginal beyond what the schema provides. Baseline 3 applies.

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

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

States a specific verb (Search) and resource (the roster / scheduled shifts) plus the filter dimensions it accepts: time window, employee, area, and published/open state. This cleanly separates it from deputy_get_shift (single shift) and deputy_list_timesheets without the agent needing to open a schema.

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

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

Usage is only implied through the enumerated filters; there is no explicit when-to-use or when-not-to-use guidance, and no sibling is named as an alternative (e.g. get_shift for a single shift, publish_shifts for state changes). Adequate for an agent that reads schemas, but no routing help.

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 substantive behavior the agent could not otherwise know, notably that EndTime is null while a timesheet is in progress and that TotalTime is in hours, plus the deputy approval semantics (TimeApproved vs PayRuleApproved). It omits operational details like rate limits and does not explain the paging contract, which the schema only partly covers.

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 purpose and filters are front-loaded in the first sentence, and the field enumeration plus API endpoint follow without filler. The list of record fields is long but earns its place given there is no output schema, though it is dense enough to be slightly harder to scan.

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 enumerates the returned fields and flags the in-progress/nulled EndTime case. Pagination behavior (passing next_start, the 500 cap) is left to the schema only, and no sorting or default-window behavior is stated, so it is solid 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 all nine parameters are already documented, and the description's mention of time window, employee, area and approval state merely restates those filters. It adds no syntax, format, or interaction guidance beyond the schema, so the baseline 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 a specific verb ('Search'), a precise resource ('timesheets (actual worked time)'), and the filter dimensions (time window, employee, area, approval state). It is clearly distinguishable from the sibling deputy_get_timesheet (singular fetch) and deputy_list_shifts by naming the exact records returned.

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 vocabulary ('by time window, employee, area and approval state') gives clear context for when this listing tool applies. However, it never names an alternative such as deputy_get_timesheet for a single record, nor any condition under which this tool should not be used, 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?

With destructiveHint=true already signaling mutation, the description adds that publishing makes shifts visible and that only listed ids are affected. The notification mode mapping duplicates the schema exactly, so the extra behavioral value is limited to the visibility effect and scoping.

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

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

The description is front-loaded with the core action and effect, then provides the notification mapping and scoping constraint. It is appropriately sized, though the trailing API endpoint is slightly extraneous for an agent-facing tool.

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

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

Covers the essential mutation behavior, the scope of affected shifts, and notification choices. Missing permissions or failure conditions, but with destructiveHint covering risk and no output schema needed, it is largely complete for correct invocation.

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 both parameters are already documented. The description restates the notify_mode mapping verbatim and clarifies that only the listed shift_ids are published, adding minor scoping meaning but no syntax or format beyond the schema.

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

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

States a specific verb (publish) and resource (draft shifts) plus the effect (employees see them). Distinguishes from sibling tools like create_shift, update_shift, and list_shifts without needing their 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 context 'Publish draft shifts so employees see them' implies when to use it, and 'Only the listed shift ids are published' gives a scoping constraint. However, it never explicitly names when not to use it or compares it to alternatives like update_shift.

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 repeats "Read-only", but it adds context beyond the annotation by disclosing the underlying POST /api/v1/resource/{Object}/QUERY endpoint and the fact that despite POST it is a read. It does not discuss return shape or rate limits, but the annotation already covers the safety profile.

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?

Purpose and object examples are front-loaded, followed by the search format, operators, and the describe_resource pointer. Dense but each element is load-bearing; the trailing endpoint reference is slightly redundant but justified by the unusual POST-for-read pattern.

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 complex nested-parameter query tool with no output schema, the description covers purpose, search construction, operators, and the field-discovery path adequately. It omits any description of the returned result shape and how expanded joins surface, which is a minor gap for a query tool.

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

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

Schema coverage is 100% (baseline 3), but the description adds real meaning: a concrete clause-map example ({"s1":{"field":"Employee","data":12,"type":"eq"}}), the operator set, and the guidance that field/join names come from deputy_describe_resource. This goes beyond the schema's enum list by showing how clauses are actually composed.

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 ("Run a Resource API search on any business object") and enumerates concrete objects (leave types, pay rules, public holidays, etc.). It distinguishes itself from the describe sibling by naming deputy_describe_resource for field discovery, so an agent can tell query from describe without opening a schema.

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

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

Gives clear workflow context: use deputy_describe_resource to learn an object's fields and joins before querying, which is explicit 'when to use the other tool' guidance. It does not, however, state when to prefer this generic query over the purpose-built list_* siblings (e.g. deputy_list_employees), leaving that ambiguity.

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 flag destructiveHint=true; the description adds the crucial full-replacement semantics (you must resend the entire shift, so omitted fields are effectively reset) and that update maps onto the add call. It does not cover auth requirements or any confirmation/precondition 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 tight, front-loaded sentences with no filler; the replacement rule comes first and the implementation detail (POST /api/v1/supervise/roster with intRosterId) trails it. The endpoint detail is arguably extra but is short and useful for a Deputy-specific tool.

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

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

For a destructive mutation with destructiveHint already declared, 100% parameter documentation and no output schema, the description supplies the one thing an agent most needs: that this is a full-payload replacement, not a partial patch.

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 still adds meaning by grouping the mutable fields and emphasizing that the whole payload must be supplied, which changes how the 11 parameters are meant to be used rather than merely restating 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?

Specific verb+resource ('Change an existing shift's') with an enumeration of what may change (times, area, employee, break, comment). It also implicitly separates itself from deputy_create_shift by noting the update uses the same field set as create plus the shift id.

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

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

Gives a concrete invocation rule: 'Send the full intended shift (same fields as create)' and clarifies the underlying call is the add endpoint plus shift id. It does not state explicit when-not conditions or name sibling alternatives such as deputy_create_shift or deputy_publish_shifts for publishing-only changes.

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

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

destructiveHint=true already declares this is a mutating operation, and the description is consistent with that. It usefully adds the future-time restriction, but does not disclose overwrite semantics even though start_time, end_time, and area_id are all required, nor any permission requirements.

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 with the action and editable fields front-loaded, followed by a trailing endpoint reference. Nothing is padded, though the raw 'Deputy: POST /api/...' fragment adds little for an agent that already has the tool.

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

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

For a destructive mutation with no output schema and annotations limited to destructiveHint, the description covers what is edited and one validity rule but omits permission/auth needs and whether unlisted fields are cleared. Adequate, not complete.

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

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

Schema description coverage is 100%, so every parameter including timestamp formats and the mealbreak range is already documented in the schema. The description's field list (start/end, area, meal break, 'supervisor comment') merely restates 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 ('correct') and resource ('an existing timesheet') and enumerates the editable fields, which cleanly separates it from create/approve/get timesheet siblings. It stops short of naming any sibling explicitly, so it is clear but not sibling-routing.

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

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

The only constraint offered is 'Times cannot be in the future,' which is a validity rule rather than usage guidance. There is no statement of when to prefer this over deputy_update_shift, deputy_approve_timesheet, or a create path.

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 value beyond the readOnlyHint annotation by disclosing the exact return payload and noting the call is cheap, implying no rate/cost concern. It does not discuss error behavior on an invalid token, which keeps it out of 5 territory.

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 clauses, front-loaded with the primary purpose, then the usage rationale, then the endpoint reference. Every sentence earns its place with no filler.

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

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

With no input parameters and no output schema, the description carries the burden of describing the return content and it does so explicitly, plus it names the underlying endpoint. Nothing an agent needs to call it correctly is missing.

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

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

The tool takes zero parameters, so the description cannot add parameter meaning and the baseline for a parameterless tool applies. No gaps or ambiguity introduced.

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?

Precise verb+resource ('Return the Deputy user the token belongs to') and it enumerates the returned fields (name, employee id, company, permissions). This clearly distinguishes it from siblings like deputy_get_employee, which targets a specific employee rather than the token's 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?

Explicitly frames the use case: 'A cheap way to confirm DEPUTY_INSTALL and the token are right.' That tells an agent when to reach for it, though it does not name an alternative tool or state when not to use it, so it stops short of a 5.

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