Workfeed MCP by usefulapi

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

Adds substantial context beyond the annotations: released:true publishes and cannot be undone through this connector, confirm:true is mandatory, employeeID:null creates an unassigned shift, and there is no automatic retry. These are important operational facts for a destructive, non-idempotent mutation that the annotations alone do not convey.

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

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

The description is four dense sentences with no filler. Safety-critical constraints and prerequisite conditions are front-loaded, and every sentence adds actionable information.

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

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

For a complex destructive create operation with no output schema and low schema coverage, the description covers prerequisites, irreversibility, retry behavior, and unassigned-shift behavior well. It is slightly incomplete regarding time format and comment/tag semantics, but overall gives an agent enough to act safely.

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 low (13%), and the description only clarifies three of eight parameters: confirm, released, and employeeID. It does not explain start/end formats, comment semantics, or tagIDs behavior, so meaningful gaps remain despite useful flag explanations.

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

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

States a specific verb and resource ('Create one shift') and scopes it to a single shift after exact staff, role, and times are approved. This clearly distinguishes it from sibling tools like workfeed_update_shift and the various read/list tools without ambiguity.

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

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

Provides a clear precondition: the user must approve the exact staff, role, and times before calling. It also gives handling guidance for uncertain outcomes ('inspect before retrying'), though it does not explicitly name workfeed_update_shift as the alternative for modifying an existing 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?

readOnlyHint=true already declares the safety profile, so the bar is lower, and the description does add useful disclosure that payroll identifiers are excluded from staff responses and leave notes are omitted. However, it never describes what an availability record actually contains or whether access is permission-scoped, leaving the data-shape opaque.

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

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

Two short front-loaded sentences with no filler; the scope statement comes first and the redaction caveats follow. It is efficient, though the second sentence is slightly cryptic out of context.

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-param read with readOnlyHint and no output schema, the description covers the minimum plus redaction notes. It stops short of conveying what fields an availability returns (dates/times/shift linkage), which matters since no output schema exists to fill that 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?

Only one parameter (id) exists and schema description coverage is 100%, with the schema itself explaining the opaque non-UUID ID format. The description adds nothing about the parameter, which is acceptable at full coverage but earns only the 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?

"Read one selected availability" names a specific verb (read), resource (availability), and singular scope, which implicitly distinguishes it from the sibling workfeed_list_availabilities. It does not explicitly name the sibling or state the ID-based lookup condition, but the purpose is unambiguous.

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

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

Usage is only implied by "one selected" - an agent can infer this fetch is for a known record rather than a search. It never states when to prefer this over workfeed_list_availabilities, nor that the id must come from a prior read (that only appears in the schema).

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's real contribution is the disclosure that a successful null means no data is stored, which prevents an agent from mistaking an empty day for a failure. It adds nothing about error cases, permissions, or the shape of a non-null record, which keeps it at a solid but not rich 4– level.

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 compact sentence with the core action front-loaded and no filler. The clause about null results is attached efficiently, though the phrasing "a successful null" is slightly compressed for what is a fairly important semantic detail.

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

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

With no output schema, the description is the only source for what a "daily record" contains, and it never enumerates or characterizes those fields. It does cover the null case, which is the highest-risk ambiguity, but an agent still cannot predict the returned structure before calling.

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 only 50%: departmentID is documented as an opaque Workfeed ID, but date has no description at all. The description does not compensate — it says nothing about the date format, whether it is a calendar day or a timestamp, or timezone handling, leaving the most ambiguous parameter unexplained.

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?

"Read one stored daily record" gives a specific verb (read) and scope (a single stored record), and the singular framing implicitly contrasts with workfeed_list_department_days. It never explicitly says the record is department-scoped, leaving the reader to infer that from the tool name and the required departmentID parameter.

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

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

There is no statement of when to call this versus workfeed_list_department_days or workfeed_get_department_stats, and no mention of prerequisites such as needing a valid departmentID from a preceding read. The only guidance is the null-result note, which describes an outcome rather than a usage 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 only declare readOnlyHint=true; the description adds substantive behavior: days are inclusive and interpreted in the company timezone, ranges are capped at 31 days, and laborPercentage is null (not 0%) when revenue is zero. The grossPay caveat for monthly-paid staff is a genuinely useful data-quality disclosure. It stops short of describing response shape or ordering.

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

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

Short and front-loaded with the computed output, with no filler. However the telegraphic style with missing spaces and concatenated tokens ('at most31days', 'revenue0 is not0%') makes it harder to parse than an extra clause of plain prose would.

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, so the description carries the burden of explaining return values; it names laborCost, revenue, and laborPercentage but not the per-day array structure, date keying, or any other returned fields. Combined with the 31-day cap and timezone note, it is adequate to call correctly but incomplete about what comes back.

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 only 33% — departmentID is documented in the schema, but from/to are bare strings. The description partially compensates by establishing that from/to are inclusive day boundaries in the company timezone with a 31-day span limit, yet it never states the accepted string format (ISO date, epoch, etc.), leaving a real gap for the two undocumented params.

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 concrete computed resource: per-day laborCost/revenue for a department, with a clear scope (from/to inclusive company-zone days, max 31). An agent can tell this is an aggregated stats tool rather than a raw record fetch. It does not, however, name the nearby siblings workfeed_get_department_day / workfeed_list_department_days to disambiguate.

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?

'Prefer laborCost here: shift grossPay is0 for monthly-paid staff' is guidance about which metric to trust, not when to call this tool versus the day/list siblings. There is no explicit when-to-use, when-not-to-use, or alternative routing, so usage must be inferred from the name.

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 return-value context beyond the annotations: payroll identifiers are excluded and leave notes are omitted, which tells an agent what it will not find in the response.

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

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

Two short sentences, front-loaded with the core action and followed by the data-omission caveat. No wasted words, though the second sentence could be slightly tighter.

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

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

There is no output schema, so the description must describe the return shape. It discloses exclusions but only vaguely characterizes what a 'staff response' contains, leaving the returned fields under-specified for a get tool without an output schema.

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

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

Schema description coverage is 100% and the single id parameter is fully documented ('Opaque Workfeed ID from a preceding read; not a UUID'). The description adds nothing further about the parameter, so the schema carries the full burden — baseline 3.

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

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

States a specific verb and resource ('Read one selected employee') and the 'one selected' qualifier implicitly distinguishes single-record retrieval from the sibling list_employees. It stops short of naming that sibling explicitly, so distinction is inferable 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?

Usage is only implied through 'one selected employee' — an agent can infer this is for fetching a single record versus listing, but there is no explicit when-to-use statement, no mention of list_employees as the alternative, and no prerequisite 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?

The description adds useful response-shaping context beyond the readOnlyHint annotation: staff responses exclude payroll identifiers and leave notes are omitted. This helps an agent understand what data will and will not be returned, though it does not cover authorization or not-found behavior.

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

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

The description is two short sentences with no wasted text. The core operation is front-loaded, followed by relevant response-filtering details.

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-record read tool with a fully documented one-parameter schema and readOnly annotation, the description is largely complete. It covers the main operation and response omissions, though it could explicitly point to workfeed_list_leaves for discovery.

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 id parameter is already well documented as an opaque Workfeed ID from a preceding read. The description adds no parameter-specific details, 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?

The description states a specific verb and resource: 'Read one selected leave.' It clearly implies retrieval of a single leave record and is distinguishable from list-oriented siblings like workfeed_list_leaves, though it does not explicitly name that sibling.

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

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

The phrase 'Read one selected leave' implies the tool is used when a specific leave is already known. However, it gives no explicit guidance on when to use this versus workfeed_list_leaves or how to obtain the required id, leaving usage context 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?

Annotations already establish readOnlyHint=true, so the safety profile is covered. The description adds useful operational context beyond annotations: the vendor response is unpaginated and bounded to 5000 rows and 2 MiB, which materially affects how an agent should handle the result.

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 short and front-loads the resource definition before the endpoint and response limits. Minor spacing/typo issues such as 'to5000rows and2MiB' slightly reduce readability but do not obscure the content.

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 zero-parameter read tool with annotations and no output schema, the description covers the resource, endpoint, and response-size constraints. It does not enumerate returned fields, but the purpose statement identifies the settings domain well enough for selection and 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?

There are zero input parameters, so the baseline is 4. The description correctly does not invent parameter semantics, and the schema has no parameter documentation burden to compensate for.

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 identifies the specific resource as pay-period and shift-break settings and maps it to GET /settings. That distinguishes it from all sibling shift, employee, department, availability, leave, and role tools, though it does not use an explicit English verb like 'retrieve'.

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 that the tool is used to retrieve scheduling settings, but it gives no explicit when-to-use guidance, prerequisites, or comparison to alternatives. For a zero-parameter settings getter the omission is less costly, but the dimension specifically asks for usage guidance and none is provided.

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

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

readOnlyHint=true already covers the safety profile, so the description's real contribution is disclosing output redaction: payroll identifiers are excluded from staff responses and leave notes are omitted. That is non-obvious behavior an agent cannot get from annotations or schema, though it does not say whether the redaction is caller-role dependent.

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, no filler, with the core action front-loaded and the caveat about omitted fields following immediately. Every clause carries information.

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

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

There is no output schema, so the description carries some burden for return shape; it mentions only what is excluded, not what a shift record contains. For a simple single-record read with a fully documented ID this is adequate but leaves the returned payload opaque.

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 id parameter is fully documented in the schema (opaque Workfeed ID from a preceding read, not a UUID), so the description correctly defers. It adds nothing about the parameter, which is acceptable at one parameter but not above baseline.

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

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

"Read one selected shift" gives a specific verb (read) and resource (shift) and the word "one" implicitly separates it from the list_* siblings. It does not explicitly name workfeed_list_shifts as the alternative, so the differentiation is inferred rather than stated.

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

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

The singular "one selected shift" implies you should already have an ID and want a single record rather than a collection, but there is no explicit when-to-use/when-not guidance and no sibling tool is named. The agent must infer that workfeed_list_shifts is the alternative for enumeration.

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?

Beyond the readOnlyHint annotation, the description discloses real behavioral traits: the containment rule start>=from AND end<to, the hard 93-day window, and the exclusive upper boundary with the workaround of extending by a second. These are exactly the kind of gotchas that prevent wrong calls. It still says nothing about volume, pagination, or result 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?

Only three sentences and the key constraint leads, but the prose is telegraphic: 'max93days here' and 'allow an extra second beyond the last desired end' read like notes to self rather than specification. No sentence is wasted, but several are compressed to the point of ambiguity.

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

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

With no output schema and 25% schema coverage across 4 parameters, the description should do more: it never says what an availability record contains, what the default `type` behavior is, or whether results are paginated. The interval semantics are well covered, so it is adequate rather than 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 25% (only employeeID is documented), so the description carries most of the burden for `from`/`to` — and it does, defining the interval boundaries and the 93-day cap precisely. However the `type` enum (WORK/NO_WORK) is never mentioned in the description, leaving a filtering parameter unexplained in both places.

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 opens with 'Read contained records', which states the operation class but never names the resource being read — the agent must fall back on the tool name/title to learn these are availability records. It does distinguish the semantics from leave overlap, which is a useful differentiator against workfeed_list_leaves/workfeed_get_leave.

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: 'This differs from leave overlap' signals that this tool is not for leave queries, but no sibling is named and no positive condition ('use this when you want WORK/NO_WORK blocks per employee') is given. An agent can infer the intent from the interval semantics but gets no explicit routing guidance among the 16 siblings.

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, so the description carries the rest and does well: nulls appear for unstored days, the range is capped at 93 days, and days are interpreted in the company timezone with an exclusive `to`. It does not mention auth requirements or error behavior when the cap is exceeded.

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

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

Front-loads what is returned before the range constraints, with no filler. The semicolon-joined fragment style and shorthand like 'max93days' are dense but readable; a little more structure would help.

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

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

With no output schema, the description does enough: it names the returned fields, warns that array entries may be null, and constrains the range. The per-day object shape and the failure mode when the 93-day cap is exceeded are the remaining gaps.

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

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

Schema coverage is 33%, so the description must compensate, and it does for `from`/`to`: inclusive start, exclusive end, company-zone days, and the 93-day max. `departmentID` is left to the schema's own description, which is acceptable since that field is documented there.

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 (read) and the exact resource contents (stored daily notes, manual revenue, extra labor, targets) over a day range. It clearly distinguishes itself from the calculated-totals sibling get_department_stats, though it does not mention the single-day sibling workfeed_get_department_day.

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

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

Explicitly routes calculated labor totals to get_department_stats, giving a clear when-not-to-use-this signal. It does not say when to prefer the single-day get_department_day, but the range semantics make the split largely implicit.

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

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

Annotations already cover the safety profile (readOnlyHint=true), and the description adds genuinely useful behavioral context: the vendor response is unpaginated but bounded to 5000 rows / 2 MiB here. That tells the agent to expect a possibly large, capped payload and that no paging cursor exists, which annotations do not convey.

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

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

Very short and front-loaded, with the resource described before the endpoint and limits. The limit clause is cramped ('bounded to5000rows and2MiB here'), slightly impairing readability, but 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?

For a zero-parameter read with no output schema, the description covers what is returned (names and IDs), the source endpoint, and the response size cap. Duplicate IDs, ordering, and total count are unstated, but nothing essential to invoking the tool 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?

Zero parameters, so the baseline of 4 applies; there is nothing for the description to compensate for. The note that results are bounded rather than paginated is a small bonus relevant to consuming the call.

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

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

States the resource and what it returns ('Department names and IDs') plus the vendor endpoint GET /departments, which makes it clearly a list operation. It is distinguishable from siblings like workfeed_get_department_stats/day that return aggregates rather than the roster itself, though the verb is implied by the title rather than the description.

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?

No when-to-use or when-not guidance, and no reference to alternatives such as workfeed_get_department_day or workfeed_get_department_stats. The agent must infer from the name alone that this is the source of department IDs used by other calls.

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

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

Annotations already cover read-only safety, and the description adds genuinely useful context beyond them: which sensitive fields are withheld, the underlying endpoint, and critically that the vendor response is unpaginated and is capped at 5000 rows / 2MiB here. It does not say whether exceeding the cap truncates silently or errors, which is the one remaining ambiguity for an agent planning a full sync.

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

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

Three short sentences, each carrying distinct information (field scope, endpoint, size bounds), front-loaded with the most decision-relevant detail. Minor deduction for cramped formatting such as 'to5000rows and2MiB', which slows parsing.

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 carries the burden of describing what comes back, and it does so at the field-category level plus hard size limits, which is the operationally important part. It could be more complete by naming representative returned fields (name, email, phone, role) rather than only what is excluded.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly implies a full unfiltered listing rather than suggesting any filter options exist.

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 name and title make the verb+resource obvious, and the description adds the key scope qualifier: it returns scheduling/contact fields only, not full employee records. It stops short of naming the sibling it complements (workfeed_get_employee for a single full record), so differentiation is implied 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?

No explicit when-to-use or when-not-to-use statement, and no alternative is named. The field-scope sentence implicitly tells an agent when this listing is sufficient versus when it needs full records, but the agent has to infer that itself.

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 readOnlyHint=true, and the description adds real behavioral detail beyond that: a 93-day ceiling on the query window, the fact that free-text leave notes are omitted from results, and that includeDeleted defaults to true upstream. These are exactly the kind of constraints an agent cannot recover from annotations or schema. Return shape and pagination are still unstated.

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 very short and the purpose clause leads, so nothing is blatantly wasted. But the telegram style ('Max93days here', 'includeDeleted defaults true upstream') compresses several distinct facts into unpunctuated fragments, making it slower to parse than a slightly longer, structured sentence would be.

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 wisely notes that free-text notes are omitted from results, and it flags the range cap and includeDeleted default. Still missing for a 5-parameter filtered list tool: the accepted date format for required from/to, and any indication of result ordering or size limits.

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 0% for the top-level fields, so the description has to carry the load; it does explain overlap behavior for from/to, the includeDeleted default, and that employeeIDs/typeIDs act as filters. But the critical date format for from/to is never given, and the phrase 'repeated employeeIDs/typeIDs filters' is ambiguous (OR vs AND across repeated values) against a schema that already declares them as arrays.

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 with scope: read leave overlapping a from/to range, explicitly including leave that starts before 'from'. That overlap semantics distinguishes it from workfeed_get_leave (single record) implicitly, but the description never names that sibling or says it returns a collection.

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?

Useful implied guidance comes from 'Read any leave overlapping from/to, including leave beginning before the range', which tells the agent this is a range query rather than a point lookup. However, there is no explicit 'use this instead of get_leave when...' or any exclusion, so the agent must infer the routing from sibling names.

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 useful operational behavior beyond annotations: the vendor response is unpaginated and bounded to 5,000 rows and 2 MiB. It does not explain what happens when those bounds are exceeded, which keeps it from 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?

The description is three short, front-loaded fragments with essentially no wasted content. 'GET /roles' is mildly redundant with the tool name, and the spacing typo '5000rows and2MiB' slightly hurts readability, but the structure is efficient.

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-only list with no output schema, the description states what is returned ('Roles and their department IDs') and important response-size behavior. It could additionally clarify truncation/error semantics at the row/MiB cap, but otherwise it is complete enough to call 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?

The tool takes zero parameters, so the parameter-semantics baseline is 4. The description correctly adds no parameter detail because there is none to add.

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?

Names the resource ('Roles') and returned field ('their department IDs'), and gives the underlying endpoint. It is distinguishable from siblings like workfeed_list_departments by resource, though it relies on the name/title for the explicit 'list' verb rather than stating scope in the description.

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

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

There is no explicit when-to-use guidance, no alternatives, and no exclusions. Usage is strongly implied by the tool name and the 'GET /roles' endpoint, which is adequate for a zero-parameter read-only list but leaves nothing 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 well beyond the readOnlyHint annotation by disclosing that the underlying vendor response is unpaginated and that results are capped at 5000 rows / 2MiB here — a truncation risk the agent must know about. It also clarifies that duration days are inclusive and interpreted in company timezone, which affects how returned values should be 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?

Four short, front-loaded clauses with no filler: scope, semantics, endpoint, and result limits. Slightly hurt by compressed formatting ('to5000rows and2MiB') that reads as a token artifact rather than deliberate style.

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

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

With no output schema, the description does the necessary work: it names what is returned (supplement definitions), how durations are counted, and the size bound on the result set. It does not enumerate returned fields, but for a simple zero-param read the agent has enough to call it and interpret truncation.

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 no parameters, so the schema carries nothing to elaborate on; baseline is 4. The description correctly spends no words on inputs and instead uses the space for return-value 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+resource ('Read supplement definitions') and adds a scope boundary by excluding flex-hour supplements, which is a related-but-distinct concept an agent could confuse it with. It does not name a sibling tool to route to, 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?

'not flex-hour supplements' is an explicit exclusion that tells the agent when this tool is the wrong choice. There is no positive when-to-use condition or named alternative, but for a zero-parameter list endpoint the exclusion carries most of the routing value.

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

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

With readOnlyHint already declaring the safety profile, the description adds real operational context: half-open interval semantics (non-overlap), a hard 93-day per-request window, and the absence of a pagination parameter. It still says nothing about result size limits or ordering, which matters given unlimited-return 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?

Four compact clauses, front-loaded with the range semantics; no filler. Minor defects (missing space in 'Maximum93days', the awkward passives 'must agree' and 'is invented') cost a point against the highest mark.

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 calling contract (window, role/department consistency, no pagination param) but leaves important gaps for a 6-parameter read tool with no output schema: what a returned shift contains, ordering, and whether result volume is bounded.

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?

At 50% schema coverage the description usefully pins down the two undocumented required params (startFrom/startTo as a half-open start-time range) and the role/department agreement constraint. However 'released' and 'employeeID' filtering go entirely unexplained in both description and 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 ('Read shifts') plus the exact range boundary semantics used to select them. It is clearly distinguishable from the single-record sibling workfeed_get_shift, though it never names that sibling or the list_* alternatives explicitly.

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

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

The range predicate implies the use case (query shifts inside a window) and the 93-day cap tells the agent when a single call is not viable, but there is no explicit 'use X instead when...' routing to siblings such as workfeed_list_availabilities or workfeed_get_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?

Goes well beyond the annotations: it discloses the pre-read of current state, optimistic concurrency via stale expectedUpdateTime rejection, the invariant that the original UTC calendar day is never changed, vendor-side company-date rules, the published-shift restriction, and the absence of automatic write retries. These are operational traits an agent cannot infer from readOnlyHint=false / destructiveHint=true / idempotentHint=false, and they directly shape safe retry and error-handling 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?

Front-loaded with the action and the confirm gate, and every clause carries real information (no filler). The semicolon-chained telegraphic style packs several distinct constraints into one sentence, which is efficient but slightly reduces scanability.

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 high-complexity mutation with 10 parameters and no output schema, the description covers safety and invariants well but leaves the agent guessing on partial-update semantics (omitted vs null fields) and on the meaning of several parameters. It also gives no notion of what a successful response or a rejected stale-update response looks like.

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 only 20%, and the description compensates for only part of the gap: it explains confirm=true and the role of expectedUpdateTime as a staleness guard. It says nothing about start/end format, the meaning of released, or whether an omitted field is left unchanged versus cleared — significant omissions for a 10-parameter mutation 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 ('Update one shift') and narrows scope to a single shift after user review, which distinguishes it from the sibling create/list/get tools. The 'confirm:true required' clause immediately signals this is a gated mutation rather than a read.

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 clear activation condition ('after user review; confirm:true required') and several when-not constraints ('Published shifts cannot be unpublished', 'No deletes', 'inspect uncertain outcomes'). It does not explicitly name a sibling alternative, but the sibling set contains no other update tool, so the routing ambiguity is low.

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