Hubity

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

Goes well past the annotations by disclosing the per-week independent evaluation rule (role, reports-to line, no self-approval unless workspace allows), that refused weeks are reported alongside approvals and never block them, and that approved weeks lock. The idempotentHint=true annotation is consistent with this locking behavior rather than contradicted by it.

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

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

Three compact sentences, front-loaded with the action and its identity constraint, then the failure semantics. The trailing quoted phrase is a mildly unconventional addition but earns its place as an intent trigger.

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 annotations and an output schema already present, the description supplies exactly the remaining gaps: who may approve, how per-week validation works, partial-failure behavior, and the locking side effect. An agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so both parameters (submissionIds and userId) are already fully documented in the schema, including the source of submissionId and the 25-item cap. The description only restates that approval is by submissionId, adding no syntax or format detail beyond the schema, so the baseline of 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 (approves), resource (filed timesheets), the keying parameter (submissionId), and the acting identity (signed-in approver). It is clearly separable from sibling verbs like return_timesheet, recall_timesheet, and submit_timesheet 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?

Usage context is clear: it names the actor constraint (signed-in approver; other IDs refused) and gives a natural-language trigger example ('approve my team's timesheets for last week'). It stops short of explicitly routing to alternatives such as return_timesheet or recall_timesheet when approval is the wrong action.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true; the description adds real context beyond them by stating no time is logged and that the call is refused when no timer is running. That precondition/error behavior is exactly the kind of detail annotations cannot carry, though permissions or post-cancel state are not addressed.

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: what it does, then the analogy and the refusal condition. The distinguishing fact (no time logged) is front-loaded and nothing is padded.

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

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

An output schema exists, so return values need not be described, and the one optional parameter is fully covered by the schema. The description supplies the missing behavioral piece (no time logged, refusal when idle), leaving nothing an agent needs to invoke it correctly.

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

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

Schema description coverage is 100% and the single userId parameter is already fully documented as optional and only relevant to workspace connections. The phrase 'the signed-in person's running timer' reinforces the same default scoping, but adds no syntax or format detail beyond the schema — 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?

Specific verb ('Discards') plus resource ('the signed-in person's running timer') with an explicit scoping clause ('without logging any time') that separates it from stop_timer at a glance. The agent can distinguish this from start_timer/stop_timer/list_running_timer 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?

Frames the tool as 'the undo for starting one by mistake', giving a clear condition for choosing it, and the 'without logging any time' clause implicitly steers away from stop_timer. It stops short of naming stop_timer as the alternative, so the routing is inferred rather than spelled out.

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

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

Annotations cover the safety profile (readOnlyHint false, idempotentHint true, destructiveHint false), and the description adds materially: idempotency is explained concretely (re-calling returns alreadyConverted: true), the side effect of auto-creating a missing client, draft-only behavior ('nothing is sent'), and Trash proposals being invisible. This is exactly the extra context annotations cannot carry.

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?

Dense but well front-loaded: the conversion contract comes first, edge cases (legacy, alreadyConverted, Trash) follow, and the example phrasings land last. Slightly long, but nearly every sentence carries distinct behavioral information.

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

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

With an output schema present, return values need not be detailed, and the description still notes the returned invoice ID/number. Preconditions, side effects, idempotency and edge cases are all covered for a 3-param mutation 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%, so proposalId, dueDate and netDays are already documented in the schema. The description explains downstream effects like depositDue but does not add format or precedence detail beyond what the schema states, so the baseline 3 applies.

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

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

States a specific verb+resource ('converts an accepted proposal into a draft invoice in one step') and the transformation logic (priced rows become invoice lines, deposit becomes payment schedule). An agent can distinguish this from create_month_invoice_drafts and preview_month_billing 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?

Gives clear preconditions (proposal must be status 'accepted' and linked to a client; legacy quotes follow a variant path) and example utterances that map intent to tool. It stops short of explicitly naming what to use instead when the proposal is not accepted or when bulk/monthly invoicing is wanted.

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 annotations already declaring idempotentHint and destructiveHint, the description still adds substantial behavioral context the annotations cannot convey: nothing is sent, drafts are attributed to the assistant, re-runs update rather than duplicate, and human-edited/sign-off/sent drafts are never overwritten but flagged. It also discloses the partial-failure model (scope skipped on plan_changed or not_confirmed).

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?

Single front-loaded paragraph that leads with the core action and the draft-only guarantee before moving to idempotency, guardrails, and result shape. It is dense and clause-heavy, but nearly every clause carries distinct load-bearing information; only the expectPlan restatement is somewhat redundant with 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?

For a 9-parameter, nested-object mutation with partial-failure behavior, the description covers safety (nothing sent), idempotency, non-overwrite guarantees, plan-hash validation, and per-scope outcome vocabulary. With an output schema present it need not detail raw return fields, and it leaves no operational question unanswered.

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 in the schema, and the expectPlan skip semantics the description restates are also present in the schema's own parameter description. The description adds little per-parameter meaning beyond that, so the baseline 3 is appropriate.

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

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

The first clause names a specific verb (writes), resource (the month's invoices), and crucial qualifier (as DRAFTS), plus the granularity (one per project, per client for client-level expenses). It is immediately distinguishable from the sibling preview_month_billing, which it explicitly ties itself to.

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

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

It establishes the operating context clearly: run after a billing preview, expectPlan must carry the previewed planHash, and re-running is the supported way to reconcile. It does not, however, name preview_month_billing as the prerequisite tool or state when the agent should fall back to a plain create/update 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false), it discloses non-obvious behaviors: a same-name task on the project is returned instead of duplicating (and reopened if closed), ambiguous project names return candidates and create nothing, and the result carries the undo call. The dedupe/reopen behavior is consistent with idempotentHint=false since the repeated call does mutate state.

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 sentences, front-loaded with the core add-scope statement, each carrying distinct information (project resolution, ownership, dedupe/undo, example utterance). Slightly padded by the natural-language example sentence and a small overlap with the output schema, keeping it off a 5.

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

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

For a 10-parameter mutation tool with an output schema and annotations, the description covers the operation, ownership defaults, project resolution ambiguity, duplicate/reopen semantics, and a pointer to the inverse operation. Nothing needed to call it correctly is missing, and return-value detail is appropriately left to the 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%, so the baseline is 3; the description goes further by explaining that project accepts a code (e.g. "RISE") or name, that assignee takes "me" or a roster name, and the exact assigneeRef form used by undo. It adds genuine meaning over the schema's short one-liners.

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 a specific verb+resource ('Adds a task') and immediately scopes it: on a project by projectId/code/name, or on no project, owned by the signed-in person unless an assignee is named. This is enough to distinguish it from create_tasks_from_meeting, update_task, and delete_task 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?

It gives clear context for when the tool applies (signed-in person's own task, project resolution by code or name, dedupe/reopen behavior) and states the mutual exclusion of assignee vs assigneeRef. It stops short of explicitly naming alternative tools or a when-not condition, so it earns a 4 rather than 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?

Beyond the idempotentHint and destructiveHint annotations, the description adds concrete semantics: already-existing tasks are listed and not recreated (explaining the idempotency in practice), the exact-name-match assignee rule, the fallback to unassigned with a reason, and the pointer to a removal call. This is rich behavioral context not derivable from annotations alone.

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 transformation, followed by the matching/idempotency rules and a closing example. Information-dense with no filler sentences, and the example succinctly anchors the intended usage.

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 batch creation tool with an output schema (which already covers return values), the description supplies the conditions, idempotency behavior, assignee logic, and reversal path an agent needs to invoke it correctly. Nothing essential is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, including the userId signed-in caveat. The description reinforces the acted-for-signed-in-person model but adds no syntax or format detail 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?

The description names a specific verb and resource ('Turns a meeting's action items into tasks on the meeting's project') and states the scope condition (a meeting the signed-in person organized or attended). This clearly distinguishes it from the single-item sibling create_task.

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

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

It states when the tool applies (meeting the signed-in person organized/attended) and points to the call that reverses the action ('The result names the call that removes the new tasks'). However, it never explicitly contrasts with the create_task sibling or states when-not to use this batch variant.

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 destructive=true and non-idempotent, but the description adds the crucial nuance that this is a soft delete to Trash and is restorable, plus the two refusal conditions and that a reason is returned. Those are behavioral traits the annotations cannot convey.

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

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

Three short sentences, zero filler; the destructive-but-recoverable nature is front-loaded, followed by refusal conditions, then an example. Every sentence earns its place.

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

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

For a destructive single-item tool with an output schema present, the description covers scope, reversibility, and refusal behavior — everything an agent needs before invoking it. Return values are legitimately left to the 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%, so expenseId and the optional userId are already fully documented in the schema. The description reinforces the "own expenses" scoping that explains userId's role but adds no new format, syntax, or ID-provenance detail beyond the schema.

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

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

Specific verb+resource: it moves one of the signed-in user's own expenses to Trash, and it immediately distinguishes itself from the sibling restore_expense by stating the item is recoverable. The scope qualifier ("own expenses") separates it from any admin-style deletion.

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?

States clear preconditions and failure modes: only the caller's own expenses, refused if already on an invoice or synced from accounting, with the reason returned. It gives a recognizable use case ("remove the parking I logged twice") but never names an alternative tool or explains when a sibling like delete_time_entry/restore_expense would be the better pick.

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 destructive=true and idempotent=true; the description adds substantial context beyond that: deletion is reversible via Trash, refusals are reported per-task with reasons, and restoration is restricted to the creator or a workspace admin. That is exactly the behavioral depth an agent needs before a destructive batch call.

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

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

Three sentences, front-loaded with the action and its rule, and every sentence carries information. The final sentence is somewhat convoluted ('says who can restore the rest'), costing a little readability but not enough to waste 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?

With an output schema present, return structure needn't be spelled out, yet the description still explains the meaningful parts of the result (refusal reasons, restore-call naming, restore authorization). For a destructive batch tool this is 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% for both parameters, so the schema already documents taskIds limits and the userId signed-in caveat. The description's permission rules loosely imply the userId context but add no syntax or format detail beyond the schema, so the baseline of 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 (moves to Trash), resource (one or more tasks), and the governing rule (board's delete policy), so an agent knows exactly what the operation does and that it is a soft delete rather than a permanent purge. This cleanly separates it from sibling restore_task, which the description implicitly references.

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 conditions for use: the caller must be the task's creator or at the workspace's task-delete floor, and it explains what happens to refused tasks. It stops short of explicitly routing the agent to restore_task as the alternative for undoing, though it gestures at it by describing the restore call.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds critical nuance: the delete is a soft move to Trash and is restorable, and it enumerates exactly which entry states will be refused. That is meaningful behavior beyond the flags.

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, with the core action and recoverability front-loaded before edge cases. The trailing quoted utterance is slightly informal but functions as a compact usage cue.

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 annotations carrying the safety profile and an output schema covering returns, the description supplies the remaining essentials: soft-delete semantics, refusal conditions, and idempotent behavior. 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?

Schema coverage is 100%, so the baseline is 3. The description reinforces scope for userId ('signed-in person's own') and encodes the refusal of foreign IDs, aligning with the schema note — a modest value-add over the already-rich schema text.

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 ('Moves one of the signed-in person's own time entries to Trash'), plus the ownership scope. It is clearly distinguishable from restore_time_entry and list_time_entries, and notes the refusal conditions up front.

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

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

Gives concrete when-it-fails conditions (entry filed for approval, approved, or invoiced is refused) and idempotency behavior (already in Trash succeeds and changes nothing). It does not explicitly name sibling alternatives (e.g., restore_time_entry), but the quoted example utterance grounds the intended use case.

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 (readOnly, idempotent, non-destructive). The description goes well beyond them by disclosing the exact weighting formula (100/90/50/25 by age band), what is included (all unbilled billable time regardless of approval, sent/accepted proposals) and explicitly what is excluded (hours a retainer fee covers, proposals as sales opportunities). This is genuine behavioral disclosure an agent cannot get 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?

Front-loaded with the core method and weighting table, then examples of the questions it answers. Slightly repetitive – the unbilled-time scope is stated twice ('adds the value of all unbilled billable time... approved or not' and again later) – but every block 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 no-arg, read-only forecasting tool with an output schema, the description is complete: it explains the calculation, inclusions/exclusions, units, and the question space. An agent can invoke it correctly and interpret the results without further information.

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 parameters, which sets a baseline of 4. The description nonetheless explains the currency units and the valuation basis for the figures returned, which is the only 'parameter-like' semantics available for a no-arg 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+resource (forecast cash flow) and goes further by naming the exact methodology and the question space it answers ('what cash can we expect?'). Siblings like get_project_profitability or list_invoices are clearly different operations, so no sibling differentiation is needed.

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 closing sentence maps user intents directly onto this tool ('what cash can we expect?', 'forecast our receivables'), giving strong context for when to reach for it. It stops short of naming when NOT to use it or which sibling handles outstanding-invoice listing, 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?

With readOnly/idempotent already declared by annotations, the description still adds substantial behavior: output sorted by margin descending, truncation to 50 highest plus 50 lowest past 100 projects, companyTotals covering every project, and date attribution rules (invoices by issue date, time by work date). None of this is recoverable from annotations or schema.

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

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

Front-loads the definition and result shape, then pagination, then date scoping, then example queries. Dense and mostly waste-free; the trailing question list is slightly redundant but serves retrieval matching.

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?

An output schema exists, yet the description still covers the sorting, the truncation contract, the totals scope, and the default time range — everything an agent needs to interpret results and choose parameters correctly. No material gap remains.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns more by explaining what from/to actually mean semantically (invoices attributed by issue date, time by work date) and by noting projectId reads any single project even when the list is truncated. It doesn't restate the date formats, which is appropriate given the schema already does.

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 (per-project profitability) and pins the exact margin definition used: revenue billed in company currency against cost of time logged. That precision separates it cleanly from siblings like get_utilization_report and list_projects.

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 says lifetime is the default and that from/to switch to a period, and lists concrete question shapes ('which projects are profitable', 'margins last quarter') that route an agent here. It stops short of naming a sibling tool or stating when to prefer a different report instead.

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 readOnly, idempotent, non-destructive, and closed-world. The description adds real behavioral context beyond that: it reads already-logged time rather than forecasts, mirrors 'the same capacity rules as the app' (work pattern less holidays and approved leave), and notes the historical-only scope. It does not discuss permissions or performance, but that is a modest gap given the rich annotation coverage.

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 core scope and contents are front-loaded in the first sentence, with the historical-vs-forward distinction next and example questions last. It is slightly long and the three sample questions are somewhat redundant with the enumerated return fields, but every sentence is relevant and nothing is padding.

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

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

For a two-parameter read-only report with a full output schema and comprehensive annotations, the description supplies the scope, the capacity-rule semantics, and usage triggers. Since the output schema exists, return-value detail is not required, and what remains absent (auth requirements, pagination) is minor for this tool class.

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

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

Schema description coverage is 100% and both date parameters already document format and defaults (today, first day of current month). The description adds only the loose notion that the range may be 'past or current,' so it does not meaningfully extend parameter meaning beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Returns utilization for the company over a past or current date range') and enumerates exactly what the report contains: available hours, logged client hours, utilization rate, and a company-wide figure. The explicit contrast with booking/forecasting data separates it from the forward-looking siblings like forecast_cash_flow.

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

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

The description clearly frames when to use it ('reads time already logged, so it says who was over or under capacity in the range, not who is booked ahead') and supplies representative trigger questions ('how utilized was the team last month?', 'who is over capacity?'). It stops short of naming a specific alternative sibling tool to use instead, so it falls shy of 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 readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds genuinely useful semantics about returned content: value as estimated worth in the deal's currency, probability as the effective weighted-pipeline figure, and onHold as paused pursuit.

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 verb and resource, then scope and examples. The mid-sentence glosses of value/probability/onHold are output-field definitions rather than parameter guidance, which is slightly off-placement, but they are informative and reasonably tight.

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?

An output schema exists, so return values need not be explained, yet the description still glosses key fields and fully covers the id-vs-filter modes and domain boundaries. Complete for an agent to call correctly, with only mild redundancy.

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 id, limit, stage, and owner_id, including the stage enum and the 'other arguments ignored' behavior. The description restates the stage/owner filtering without adding format or syntax 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+resource (lists sales opportunities/deals) and explicitly scopes the domain in both directions: 'opportunities, not priced proposals and not expected cash.' This cleanly separates it from siblings like list_proposals and forecast_cash_flow.

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

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

Gives concrete when-to-use triggers ('what deals are in progress?', 'what is in the sales pipeline?') and rules out the adjacent concepts it is not for, plus explains what stage open returns. Nothing is left to inference about when to pick this 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 already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the mode-switch behavior (single read by id returning line items), but says nothing about pagination limits beyond 50, ordering for the id path, or the shape of the response — little beyond what the annotation and schema pair already conveys.

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 dual mode are front-loaded in the first sentence, with the illustrative questions trailing as supporting context. It is one tight pair of sentences with no filler, though the example-question sentence is somewhat redundant with the already-explicit scope statement.

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 an output schema present (return fields need not be explained) and annotations covering the read-only safety profile, the description supplies everything else an agent needs: scope, the id-based single-read mode, supported filters, and representative question phrasings for selection.

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, limit, status and clientId parameters each carry their own semantics in the schema, including the enum meanings and the id override rule. The description contributes no additional parameter detail such as id formats or clientId sources, so the baseline 3 applies.

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

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

States a specific verb and resource ('Lists company invoices'), and additionally spells out the dual behavior: a filtered list with status/amount/due-date fields, or a single invoice with line items by id. This clearly separates it from siblings like list_deals, list_projects, or forecast_cash_flow without needing the schema.

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

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

The four example questions ('what invoices are outstanding?', 'what is overdue?', 'what does this client owe us?', 'which invoice has been unpaid longest?') give concrete selection context for the agent. It stops short of naming an alternative tool or stating when not to use it (e.g. versus get_project_profitability or forecast_cash_flow), 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?

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so safety is covered; the description still adds non-obvious behavior: result ordering flips depending on whether from is supplied, and supplying id causes the other arguments to be ignored. It does not mention pagination or result-size behavior, but for a read-only list tool this is solid added context.

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

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

Two dense sentences followed by example questions; the primary mode and its override are front-loaded. The example-question sentence is somewhat redundant with the preceding prose but does help matching, so it mostly earns its place.

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

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

With an output schema present, return-shape detail is unnecessary, and the description covers both invocation modes, ordering, and representative queries. Only minor gaps remain (pagination/default page size are left to the schema, and nothing about empty results).

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 in the schema, and the description largely restates them (id reads one, from/to form a window). It adds only the ordering consequence of from plus the 'from = today lists upcoming' interpretation, so baseline 3 is appropriate.

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

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

States a specific verb (lists) plus resource (company meetings with summaries and attendees) and explicitly covers the second mode: reading one meeting's minutes by id. The default ordering (most recent first) and the from/to alternative (soonest first) are named, so an agent knows exactly what this tool returns without consulting the schema.

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

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

It gives explicit routing conditions: pass id to read a single meeting, pass from (optionally to) to list a window and get upcoming meetings, otherwise get recent ones. It also illustrates intent with sample questions. It stops short of naming an alternative tool, but none of the siblings overlap this domain, so the gap is minor.

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 (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds the non-obvious default window ('default: the last 30'), the fact it returns expense ids consumed by delete_expense, and the totals that come back — genuinely additive behavioral context.

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

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

Front-loads the verb and scope, then the returns and use case. The long mid-sentence field enumeration is somewhat heavy, but every clause carries information 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?

For a read-only list tool with an output schema, rich annotations, and 100% schema coverage, the description supplies purpose, default window, returned-id linkage and use case. 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?

Schema description coverage is 100%, so the schema already documents to/from/userId/projectId. The description only reinforces the date-span semantics ('default: the last 30'), adding marginal value over 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 ('Reads the costs') and resource ('the signed-in person recorded on their projects') with the exact scope ('over a span of days'). It also enumerates the returned fields, letting an agent distinguish it from siblings like log_expense, delete_expense and log_mileage without opening the schema.

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

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

Gives a default span (last 30 days) and anchors the use case with 'Handles "what expenses have I claimed this month?"'. It also ties to the delete tool by noting it 'returns the expense ids the delete tool takes', but names no explicit when-not-to-use or a reading alternative.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description adds genuinely useful behavioral detail beyond that: the granular balance breakdown (allowance/used/pending/booked ahead/remaining), the inclusion of notice and approval rules, and that request ids are returned. It does not discuss pagination or result size 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 sentences, front-loaded with the core action and scope, then a user-intent mapping. The middle enumeration of balance fields is dense and slightly list-like, but every element corresponds to a distinct piece of returned data rather than filler.

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

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

For a read-only list tool with an output schema present, the description needn't explain return formatting, and it still supplies scope, data groups, and intent examples. An agent has everything required to select and invoke it correctly.

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

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

Schema coverage is 100% and the single userId parameter is fully documented in the schema itself, including when it is unnecessary and that other IDs are refused. The description adds nothing about the parameter, 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 (reads) and a precisely scoped resource (the signed-in person's OWN time off), then enumerates the three data groups returned: balances per leave type, workspace leave types with notice/approval rules, and upcoming/pending requests with ids. The 'own'/'signed-in person' framing clearly distinguishes it from siblings like list_pto_requests and list_time_entries.

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 closing sentence maps real user intents ("how much vacation do I have left?", "what time off have I booked?") to this tool, which gives an agent clear usage context. It stops short of naming exclusions or pointing to alternatives such as list_pto_requests or request_time_off, so it is clear context rather than explicit routing.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds real behavioral detail beyond that: the id mode 'reads one project in full' and overrides other arguments, and search prioritizes exact code matches and returns an exact match alone. It doesn't discuss result caps or pagination, but those are schema-level concerns.

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 paragraph, front-loaded with the primary list behavior before the id and search modes, with no filler sentences. The trailing example questions are useful for retrieval rather than padding, though the sentence is dense with three modes packed together.

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?

An output schema exists, so return values need no explanation, and annotations already carry the safety profile. Combined with a fully documented schema, the description covers all three invocation modes and their selecting conditions, leaving nothing an agent needs in order to call it correctly.

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

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

Schema description coverage is 100%, so the parameters (including the exact-code-first search behavior and defaults) are already fully documented in the schema. The description restates the search example 'RISE' and the id-mode override but adds no syntax or format detail the schema lacks, which is the expected baseline when structured data does the heavy lifting.

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

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

States a specific verb and resource ('Lists company projects') and enumerates the tool's three distinct modes: filtered list, full read by id, and search by code/name. An agent can separate it from siblings like list_tasks, list_deals, and get_project_profitability 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 example questions ('what projects are we working on?', 'which projects are at risk?', 'what are we doing for this client?') give concrete retrieval contexts that map cleanly onto the status and clientId filters. It stops short of naming alternatives or stating when-not-to-use (e.g. pointing to get_project_profitability for margin analysis), so no explicit exclusions.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is low. The description adds real behavioral context beyond that: results are 'most recent first', legacy quotes are read-only, and the id mode returns one proposal in full while ignoring other arguments. It stops short of mentioning pagination beyond the schema's limit.

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

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

Front-loads the core purpose and returned fields, then layers filters, edge cases, and scope exclusions. Every sentence carries information, but the parenthetical asides make it denser and longer than strictly necessary for a list 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?

An output schema exists so return values needn't be explained; the description nonetheless covers ordering, the workshop/legacy distinction, filter semantics, and scope boundaries. For a read-only listing tool this is fully sufficient 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?

Schema coverage is 100%, so baseline is 3. The description still adds meaning beyond the schema: it clarifies that 'accepted' proposals are the ones that become invoices, that older quotes lack a clientId and are excluded from client filtering, and that id-mode takes precedence over other args.

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 ('Lists company proposals') and enumerates the returned fields, plus a distinct lookup mode by id. It actively distinguishes itself from siblings by scoping to 'priced offers only: not unpriced sales opportunities and not expected cash', which separates it from list_deals and forecast_cash_flow.

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 usage context via example questions ('what proposals are out?', 'what has been accepted?') and states filter conditions. It implies when to use the id-mode versus list mode. However, it never names the alternative sibling tools to route to for the excluded categories, so routing is left partly 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 declare readOnly/idempotent/non-destructive, so the bar is context-adding; the description discloses that results are permission-scoped by role (own / reports' / everyone's) and that listing is ordered 'earliest start first'. It doesn't spell out pagination behavior beyond the schema's limit field, but the role-visibility rule is substantive value.

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

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

Front-loaded with the core behavior, then the parameter-driven variants, then example questions. Every sentence carries information, though the prose is dense and slightly run-on.

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

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

With an output schema present and annotations covering safety, the description need not explain return values; it fully covers scope, ordering, per-role visibility, and mode-switching, leaving nothing an agent needs before 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?

Schema coverage is 100%, so baseline is 3; the description goes further by explaining the temporal overlap semantics of from/to ('leave that overlaps those days') and the meaning of the status combination, adding interpretation beyond the field-level text.

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 ('Lists time off and leave requests') and also covers the single-record read mode ('or reads one by its id'). No sibling tool covers PTO data, so the agent can place it immediately among the invoice/project/task listers.

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 conditional guidance: 'With from and to it lists leave that overlaps those days... with status approved that shows who is out', and illustrates with example questions. It doesn't name an alternative tool, but no sibling overlaps, so exclusions are unnecessary.

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 (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds the important conditional behavior — it returns data only "if one is running" — which is the key behavioral nuance an agent needs, though it says nothing about the shape of the no-timer response or any rate/permission constraints.

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 purpose is front-loaded and the usage phrasings follow. 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?

An output schema exists, so return values need no explanation here, and the annotations carry the safety profile. For a single-optional-parameter read tool, the description plus structured fields leave nothing an agent needs 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 userId parameter is fully documented in the schema, including that it is unnecessary when signed in and that other IDs are refused. The description's "signed-in person's" wording reinforces but does not extend that meaning, so the baseline of 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 ("Reads the signed-in person's running timer") and enumerates the returned content: start time, project, task, activity, and elapsed duration. It is immediately distinguishable from siblings like list_time_entries (historical) and start_timer/stop_timer (mutations).

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

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

Gives concrete usage triggers in natural language ("what am I timing?", "is my timer still on?"), which clearly signals the when-to-use context. It does not name alternatives such as list_time_entries for completed entries or mention the no-timer-running case beyond the conditional phrasing, so it falls short of full when/when-not routing.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuine behavioral context beyond them: name filters are applied server-side, so the returned total is exact without paging through everyone.

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 primary list behavior before the single-record mode, and every sentence carries content. The example-question run is slightly verbose but earns its place by doubling as usage guidance.

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?

An output schema exists, so return values need no explanation. Between the description's mode coverage, filter semantics, count exactness, and the fully documented schema, an agent has everything needed to call 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 coverage is 100%, so baseline is 3, but the description adds value by clarifying the two usage modes, noting that when `id` is supplied the person comes back 'in full (phone, start date)' and that the other arguments are then ignored. This is real semantic layering on top of 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 plus its two modes: listing active team members with titles/departments/reporting and the matching total, or reading one person in full by id. No sibling tool overlaps with staff, so an agent can route correctly without opening the schema.

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

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

Maps concrete user questions ('who is on the team?', 'who reports to whom?', 'find someone by name') directly to this tool, which is strong intent routing. It stops short of naming when NOT to use it or any alternative tool, but no sibling competes for these queries.

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, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered without the description. The description adds the useful dual-mode detail that a single id returns one task in full rather than a list, but says nothing about return shape, ordering, or pagination beyond what the schema provides.

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

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

Two sentences, no filler, with the primary listing behavior and filters front-loaded before the example questions. Dense but appropriately sized for a five-parameter tool with dual behavior.

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 an output schema present, the description need not explain return values, and the annotations carry the safety story. It covers both the list and single-task modes plus the filter dimensions, leaving only minor gaps such as default/sorting behavior, which the schema's limit description partially addresses.

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 explains id, limit, status, priority and project_id, including the enum values and the "other arguments are then ignored" behavior for id. The description only restates the filterable dimensions (status, priority, project) at a high level, adding essentially nothing beyond the schema — the baseline 3 applies.

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

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

The description names a specific verb and resource ("Lists company tasks") and additionally discloses a second mode — reading one task in full by id — that an agent might not infer from the name alone. The task resource is clearly distinct from the sibling list_* tools (list_projects, list_staff, etc.), so no sibling is easily confused with it, but the description never explicitly contrasts itself with an alternative.

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

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

It supplies concrete usage context by mapping example questions ("what is pending?", "what is urgent?", "what is assigned to this project?") onto the status, priority and project filters, which helps an agent recognize the right invocation. It stops short of stating when to avoid this tool or which sibling to prefer for other task-related needs.

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 readOnly/idempotent annotations, the description discloses the default range (this week Mon–Sun in the user's time zone), the approval-status per week, required hours and time-off annotation so gaps read correctly, and that returned entry ids feed the edit/delete tools. That is substantial added context; only rate limits or pagination behavior are absent.

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?

Dense but front-loaded: the core action and default range lead, then return contents, then use cases. Every clause adds information, though the single long sentence chain could be split for easier scanning.

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 filtered read with four optional params, an output schema, and full annotation coverage, the description covers defaults, scope restrictions, cross-tool linkage (entry ids for edit/delete), and interpretation of time-off days. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is already 100%, and the description still adds the meaningful default (current week, Monday to Sunday, local time zone) that the schema does not express, plus reiterates the self-only semantics of userId. It does not elaborate on projectId filtering syntax, but that is well covered in 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?

"Reads the signed-in person's own timesheet for a span of days" names a specific verb, resource, and scope (self-only), which separates it cleanly from list_my_expenses, list_timesheet_approvals, and list_time_suggestions. The scope constraint also signals no user-filtering, which is the key differentiator from broader listing 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?

The closing sentence gives concrete trigger intents ("what have I logged this week?", "am I missing any days?") and notes it exists so nothing is logged twice. It does not explicitly name alternative tools or exclusion conditions, so it stops 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 readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds real context beyond that: row contents, the scope of people returned, and which weeks are included by default. It does not discuss pagination or ordering beyond 'newest first,' but with an output schema present that is minor.

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

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

Front-loaded with the core purpose, then scope, then the default behavior. Three dense sentences that each carry information, though the middle sentence about approver coverage is long and slightly packed.

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 an output schema handling return shape and annotations covering the read-only/idempotent profile, the description supplies exactly the missing pieces: what a row means, who is in scope, and what the default status filter does.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning on top: it clarifies that 'submitted' means still waiting and is the default, and that the tools always act as the signed-in approver rather than an arbitrary userId, mirroring the schema's own note.

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: 'Lists the filed timesheets the signed-in approver may decide, newest first.' It also enumerates what each row contains (person, period, total hours, project breakdown, own-week flag), which clearly separates it from list_time_entries and approve_timesheets.

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?

Answers the natural question 'what timesheets are waiting on me?' and explains the default filter (status submitted = still waiting) plus who is covered (company-wide approver sees everyone, otherwise reports plus unplaced people). No explicit sibling exclusions such as 'use list_time_entries for your own logged time,' 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.

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

Annotations already declare readOnly/idempotent/non-destructive, so the description's job is to add nuance, and it does: calendar events become draft entries with workspace rounding-grid minutes and a project guessed from the title, and on a full holiday or leave day no drafts are produced. It also states nothing is saved, which is the key reassurance beyond annotations; it does not discuss cost or latency, but little more is needed for a read-only aggregation.

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 is front-loaded in the first clause, but the middle is one long comma-chained enumeration of six data sources that is hard to parse in a single pass. Every element is substantive, yet the structure could be tightened into shorter sentences or a list without losing meaning.

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?

Although an output schema exists and return shape need not be explained, the description still covers the aggregation contents, the draft-entry heuristics (rounding grid, guessed project), the holiday suppression rule, and the no-write guarantee. For a read-only suggestion tool with two optional parameters, nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and both parameters are already documented, including the 'today in the person's time zone' default and the userId refusal rule for signed-in sessions. The description's 'for one day (default today)' largely restates the date parameter rather than adding new semantics, so the baseline 3 applies.

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

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

The description states a specific action (gather candidate time-entry material for one day) and enumerates exactly what is gathered: calendar events as drafts, assigned tasks, usual projects/activities, favorites, activity codes, and existing logged time. Combined with 'Nothing is saved' and 'to turn into time entries after they confirm', an agent can clearly separate this from list_time_entries or log_time_entry without opening a schema.

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

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

It gives explicit invocation triggers ('Handles "break down my day" or "fill in my timesheet for today"') and a default scope (today when no date is given). It does not name when NOT to use it or point to specific alternatives such as log_time_entry, 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?

Beyond the annotations (which only declare this is a non-idempotent write), the description discloses substantial behavior: closed accounting months and likely duplicates are refused with a reason, receipts are added later rather than here, and the result carries the undo call. These are exactly the traits an agent needs before invoking a mutation tool.

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

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

Core purpose is front-loaded and the single dense paragraph has little wasted text; the receipt-deferral, example phrasing, and undo-call notes each carry information. It is slightly packed for a single block, which keeps it just shy of a 5.

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

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

With an output schema present, return-value explanation is unnecessary, and the description covers the remaining gaps: side effects (refused closed months/duplicates), receipt workflow, undo capability, and project resolution. An agent has everything needed to call 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 the schema already documents all 12 parameters thoroughly (project resolution, currency, defaults, allowDuplicate). The description reinforces project-by-id/code/name and workspace-currency behavior but adds little that the schema does not already state, so the baseline 3 applies.

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

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

The description names a specific verb and resource ('Records one cost the signed-in person paid on a job') with concrete examples (parking, materials, client lunch). It implicitly distinguishes this from siblings like log_mileage and log_time_entry by framing it as a single job cost. It even captures the exact project-resolution mechanism and a natural-language invocation example.

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 context is clear ('against a project they work on', handles 'log $42 parking on RISE, billable') and it states that this behaves like the project Expenses tab. However, it never explicitly names alternatives (e.g., log_mileage for mileage) or states when not to use it, so the routing guidance is contextual rather than 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?

Annotations only declare the generic write profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false); the description goes further by disclosing the pricing model, that the computed arithmetic is stored on the claim, the default reimbursable=true, and that the result returns the call that undoes the entry. It stops short of warning that repeated calls create duplicate claims despite idempotentHint=false.

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, then layered with pricing, default, example, and return-value note — each clause earns its place. It is dense but not padded; only the reimbursable restatement is mildly redundant with 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?

For an 8-parameter mutation with an output schema, the description covers the essentials: rate sourcing, currency limitation, project resolution by code/name/id, and the undo handle. Minor gaps remain around duplicate-submission behavior and what happens when no published rate exists for the currency.

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

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

Schema coverage is 100%, so the schema already documents every parameter including the distance unit-to-currency mapping and the projectId/project choice. The description's only marginal addition is reinforcing the reimbursable default ('owed back to the person unless they say otherwise'), which the schema already states. 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 ('Records one trip ... as a mileage claim on a project') plus the scoping rules that define the operation (rate by workspace currency and trip year, USD/CAD only). The mileage framing and currency constraint separate it cleanly from the sibling log_expense without needing to open either schema.

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

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

Usage context is implied through the worked example ('Handles "I drove 34 miles to the RISE site today"'), which shows the intended natural-language trigger. However, it never explicitly says when to choose this over log_expense, nor what conditions make it the wrong tool (e.g., non-mileage costs, non-USD/CAD workspaces).

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 the basic safety profile (readOnly=false, destructive=false, idempotent=false), yet the description adds real behavioral depth: requestKey replay semantics (a repeat returns the first entry marked replayed instead of double-logging), the ownership constraint (entry is always the connected person's, other userIds refused), timezone-based defaulting of the work date, the result pointing to its undo call, and the specific refusal mode for holiday/leave days. These are exactly the traits an agent cannot infer 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?

Front-loaded with the core action and an example, then the two safety-relevant behaviors (replay and time-off confirmation) at the end. Dense but nearly every clause carries information; the final sentence is long but earns its length by describing the refusal outcome.

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?

A 12-parameter write tool whose return values are covered by an output schema, so the description only needs to carry behavioral risk. It does: idempotency, ownership, date defaulting, ambiguity handling, and the time-off gate that blocks the write. Nothing an agent needs to call it safely is missing.

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

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

Schema description coverage is 100%, so the schema already documents every parameter thoroughly, including project code-first matching, hours-vs-minutes exclusivity, and the confirmTimeOffDay contract. The description restates the project-by-code-or-name and hours/minutes semantics without adding format or precedence 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 and resource (logs time worked) plus the three things it can be attached to (project, task, activity code) and the units accepted. This clearly separates it from update_time_entry, delete_time_entry, and start_timer/stop_timer siblings, which handle different lifecycle stages.

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

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

The description gives concrete invocation context ("log 2 hours on RISE for the site survey") and an explicit conditional rule for confirmTimeOffDay: do not log holiday/leave days without it. It does not, however, name alternatives such as update_time_entry for corrections or start_timer for live tracking, so routing between siblings is left 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 (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial behavior beyond them: exactly which items go on the draft, which items get flagged (unapproved time, missing rate, contract cap, open month), the per-scope create/update/no-op outcome, and the planHash fingerprint that drafting later checks. That is real operational context an agent cannot get from the 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?

The core purpose is front-loaded in the first sentence and most sentences carry distinct information. It is still a very dense single block with mild redundancy ('Each scope...' used twice, restating the read-only guarantee at both the start and end), which costs a point but does not obscure the message.

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, paginated preview tool with a full output schema, the description covers what is included, what is excluded, what each result carries (lines, totals, flags, planHash, deep link, plain-language summary), and confirms no side effects. 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?

Schema description coverage is 100%, so the schema already documents month/from/to, limit, cursor and the three scope filters in full. The description adds conceptual meaning to 'the period' (WIP definition) but no syntax, format or constraint detail beyond what the schema states, so the baseline 3 applies.

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

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

The opening clause names a specific verb and resource ('Previews what billing a month would draft') and immediately scopes it as non-writing ('without writing anything' / 'Nothing is created or sent'). That framing cleanly separates it from the write-path siblings like create_month_invoice_drafts, so an agent can route 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?

It gives concrete invocation contexts ('bill everything for October', 'what is our WIP?') and clearly states what is and is not counted (approved/rated/unbilled time plus expenses, contract progress and retainer fees; other time excluded). It never explicitly names the alternative tool to call when you do want to actually draft, so the when-not side is implied rather than spelled out.

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

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

Annotations mark this as a non-read-only, idempotent, non-destructive mutation. The description adds genuinely useful behavior beyond that: the state gate (pending approval only), the error behavior (refusal with reason for approved/rejected periods), and the downstream effect (entries become editable again). What it does not cover is authorization requirements or what a successful recall returns, but the state gating already exceeds the 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 sentences, with the operation and its undo framing front-loaded, followed by the precondition and failure mode. No filler, and the argument's origin is appended last where it belongs.

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?

An output schema exists, so return values need no explanation, and the description covers the operation, the state gate, and the failure path. The remaining gap is authorization/permission context for the userId-less case and what the caller should do after a refusal, which keeps it from a 5.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's only parameter detail, submissionId's provenance ('a filing result or a timesheet read gave'), duplicates the schema's own wording rather than extending it, and userId is left entirely to 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?

The description gives a specific verb and effect ('pulls a filed timesheet back... the undo for filing it') plus the resource scope (a timesheet still awaiting approval). It distinguishes itself from submit_timesheet, return_timesheet, and approve_timesheets by naming the inverse operation explicitly, so an agent can route without opening the schema.

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

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

It clearly states the operating precondition ('while it still waits for approval') and the failure condition ('an approved or rejected period is refused with the reason'), which is strong when-to-use guidance. It does not name sibling alternatives such as return_timesheet, so it falls just short of the explicit alternatives coverage a 5 requires.

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 the safety profile (readOnly=false, destructive=false, idempotent=false); the description goes well beyond that by describing the full domain outcome — advance-notice types refuse earlier starts and return the earliest valid date, no-approval types are granted immediately, otherwise approvers are notified. It also discloses day-counting semantics against the working week and holidays, and that requestKey files at most one request.

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 required fields are front-loaded, followed by workspace-rule behavior and identity constraints, with the natural-language examples placed last where they aid slot-filling. It is dense but nearly every clause carries operational meaning; the closing example sentence is the only part that could be trimmed.

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

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

For a 7-parameter mutation tool, the description covers identity constraints, date-range scoping, day counting, approval-flow outcomes, and per-request deduplication. With an output schema present, return values need not be explained, so nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters and the baseline is 3. The description reiterates key semantics (days, requestKey dedup, userId refusal) and slightly enriches 'days' by tying it to the working week and holidays, but adds little syntax or meaning the schema does not already carry.

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

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

The description names a specific verb and resource ('Asks for time off for the signed-in person'), scopes it with the exact fields (startDate to endDate inclusive, one of the workspace's leave types), and makes clear it acts on behalf of the signed-in user rather than an arbitrary one. An agent can distinguish this from list_my_time_off, withdraw_time_off, or restore_time_off 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?

It gives clear triggering context, including example utterances ('take Friday off', 'request vacation the week of the 24th') and the rule that userId is unnecessary when signed in because other IDs are refused. It does not explicitly route the agent away from sibling tools such as withdraw_time_off or list_pto_requests, so exclusions are left 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 declare non-readonly, idempotent, non-destructive. The description adds real behavioral value beyond them: the failed-restore condition ('only an expense they deleted themselves comes back') and the ownership constraint, which the agent needs to predict outcomes.

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

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

Two sentences, front-loaded with the action, no filler. Every clause carries information (scope, undo semantics, constraint).

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?

An output schema exists, so return values need not be explained. Combined with the annotations covering the safety profile, the description supplies everything needed: scope, ownership constraint, and failure behavior.

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

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

Schema coverage is 100%, so both parameters are already fully documented in the schema. The description only alludes to ownership scope and adds no expenseId syntax or userId detail, so the 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 (restore) and resource (expense), plus the precise scope: one of the signed-in person's own expenses from Trash. It distinguishes itself from siblings like delete_expense and restore_task without needing the schema.

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

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

Explicitly frames the tool as the inverse of deletion ('the undo for deleting it'), which tells the agent when to use it. It doesn't name a concrete alternative tool, but the usage context is clear.

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 idempotency and non-destructiveness, but the description adds genuine behavioral context: the role requirement (creator or admin) and the failure mode where a task is refused because its line code is reused. It does not describe return values, though an output schema exists to carry 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?

A single tight sentence that front-loads the action and follows with the authorization rule and the failure case. Every clause carries information; nothing is padding.

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

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

With annotations, full schema coverage, and an output schema present, the description supplies everything an agent still needs: the write semantics, the role requirement, and the conflict-refusal behavior.

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

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

Schema description coverage is 100%, so both userId and taskIds are fully documented in the schema. The description only echoes the batch nature ('one or more trashed tasks') without adding format or constraint detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('brings one or more trashed tasks back') and frames the tool as 'the undo for deleting them', which cleanly distinguishes it from the sibling delete_task. An agent can identify its role without opening the schema.

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

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

Gives clear usage context ('the undo for deleting them') and an authorization precondition ('as the task's creator or an admin'), plus a refusal condition for line-code conflicts. It stops short of explicitly naming delete_task as the counterpart, so routing is implied rather than spelled out.

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

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

Annotations already declare readOnly=false, destructive=false, idempotent=true and closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: the undo/trash semantics, the two refusal conditions, and the ownership restriction (own entries only). It stops short of describing state transitions such as whether the restored entry keeps its original 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 front-loaded sentence defining the operation, followed by the refusal conditions. No filler, no restatement of the title, 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?

An output schema exists, so return values need not be explained, and annotations cover the safety profile. Combined with the ownership restriction and refusal conditions, an agent has everything needed to decide whether to call this tool and predict the outcome.

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

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

Schema description coverage is 100%, so both userId and entryId are already documented in the schema, and the description adds little parameter-level detail. The 'signed-in person's own' phrasing does reinforce why userId is usually unnecessary, but this is already in the schema text, so the 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+resource ('Brings ... time entries back from Trash') and immediately tags it as 'the undo for deleting one', which pins the inverse relationship to delete_time_entry without naming it awkwardly. It also scopes the operation to the signed-in person's own entries, so an agent can distinguish it from list/delete 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?

The description gives explicit refusal conditions: a live entry already holding the same hours, or a day inside a week already filed. These are concrete when-not-to-use signals an agent can check before calling, which is unusually strong for a restore 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 this is not read-only, not destructive, and not idempotent; the description supplies the meaningful behavioral detail behind that profile — eligibility windows, who cancelled, and the re-file fallback. It could add slightly more on whether a repeated restore errors out, which is relevant given idempotentHint=false.

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

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

Two sentences, zero filler, with the core action and undo relationship front-loaded before the eligibility caveats.

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?

An output schema exists so return values need no explanation, and the description covers eligibility, destination after restore, and failure path. 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?

Schema description coverage is 100%, so requestId and userId are already fully documented, including the signed-in-user semantics. The description adds no parameter-level syntax or format detail, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb (restore) and resource (a time-off request), and explicitly frames itself as 'the undo for withdrawing it', which cleanly separates it from the sibling withdraw_time_off.

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

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

Gives concrete when-it-works conditions: pending requests go back to approvers, person-cancelled approved leave only within a few minutes, and manager/HR-cancelled requests must be refiled. The agent knows both the eligible cases and the fallback.

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 real consequences beyond the annotations: entries revert to draft, the owner is notified with the comment, and the action is validated against the same rules as approving (so it can fail). It does not address repeat calls or what happens after the owner re-files, and the annotations already cover the safety profile (non-read-only, non-destructive).

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

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

Front-loads the action and actor in the first clause, then consequences, then the validation gate, then a worked example. Every sentence carries distinct information and none is filler.

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

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

For a 3-parameter mutation with an output schema, the description supplies everything an agent needs: who the caller is, what the tool changes, who is notified, and the precondition that approval rules are re-checked. Return values are covered by the output schema, so nothing material is missing.

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

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

Schema description coverage is 100% and each field is documented in the schema itself (userId scope, comment purpose, submissionId origin). The description's only added value is the natural-language example mapping a sentence to the arguments; 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 and resource ('sends one filed timesheet back to its owner') plus the actor ('as the signed-in approver'), which separates it cleanly from approve_timesheets and recall_timesheet. An agent can tell what this does without opening the schema.

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

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

Gives clear situational context: this is the approver-initiated rejection path with a required fix comment, gated by the same approval rules as approving, and the example 'send Alice's week back: Tuesday is on the wrong project' pins the trigger. It stops short of explicitly naming when to prefer this over approve_timesheets or recall_timesheet, so it is context-rich but not fully routing.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds a real behavioral constraint beyond them: only non-sensitive, company-visible documents are returned, which tells the agent results may be silently filtered by visibility. It does not discuss pagination or result truncation, but limit is schema-documented.

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

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

Three tight sentences, front-loaded with what the tool does, then the return content, then the scope caveat. Every sentence carries distinct information and nothing is 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?

An output schema exists, so return values need not be detailed; the description still summarises them briefly. For a read-only, closed-world search with fully documented parameters, there is no gap an agent would need to call 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 coverage is 100%, so the baseline is 3. The description goes beyond it by explaining the interaction semantics that matter: an id fetch returns full content under `document`, and that mode supersedes the other arguments. That is genuine routing value the schema only partially conveys.

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

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

The description names a specific verb and resource (search the knowledge base) and immediately states the second mode (read one document in full by id). It also declares the return shape (title, category, content snippet) and the access scope, so the agent knows exactly what this tool does without opening the schema.

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

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

It clearly states the two invocation modes and the condition that selects the second one (pass a document id), which is the key routing decision. It does not name any alternative tool or a when-not-to-use case, but no sibling overlaps with knowledge retrieval, so the missing exclusion is low-risk.

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 the generic write profile (readOnlyHint=false, idempotentHint=false). The description adds the non-obvious behavior an agent must know: single concurrent timer, refusal-with-incumbent on conflict, a 24-hour cap, and that nothing is logged until the timer is stopped.

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?

Six short sentences, each carrying distinct information (scope, identifier forms, concurrency rule, duration limit, logging behavior, example utterance), with the core action front-loaded. 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 an output schema present, return values need not be explained, and the description covers the stateful constraints (concurrency, 24h cap, no logging until stop) that an agent needs before invoking a non-idempotent write with no required parameters.

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

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

Schema description coverage is 100%, so projectId/project dual-mode, exact-code-first matching, ambiguity handling and the optional description are already documented in the schema; the description largely restates them plus the 'RISE' example. Baseline 3 applies since the schema does the heavy lifting.

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

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

Specific verb ('Starts') plus resource ('a timer') plus actor ('the signed-in person') and the target scope (project/task/activity). It is clearly distinguishable from stop_timer, cancel_timer and list_running_timer siblings 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?

It gives real invocation conditions: one timer at a time, the call is refused while another runs, and the running timer is returned. It also supplies an utterance example ('start a timer on RISE for the site survey'), which tells the agent what kind of phrasing this tool serves. It stops short of explicitly routing to stop_timer/cancel_timer as the follow-up tools.

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 past the annotations: it discloses that the entry lands on the day the timer started, that time is snapped to the workspace rounding grid, that rating/billable behave as if typed in the app, that the optional description replaces the timer's text, and that refusal leaves the timer running with the reason returned. It even states the result carries the logged entry and the call that removes it.

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

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

Front-loaded purpose followed by three information-dense sentences covering parameter effect, failure behavior, and result contents, with no filler or repetition of the schema. Every sentence earns its place.

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

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

For a non-idempotent mutation on the signed-in user's timer, the description covers the write effect, the billing/rounding consequences, the failure mode, and a pointer to the undo call; the output schema is present so return shape needn't be spelled out further.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: 'An optional description replaces the timer's' tells the agent that omitting the parameter preserves the existing description, which the schema does not convey. The userId parameter is only explained in the schema, not the description.

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 ('Stops the signed-in person's running timer and logs the time as one entry') and pins the scope to the signed-in user's own timer, which separates it from start_timer, cancel_timer and list_running_timer. The logging/billing behavior is described concretely rather than left to inference.

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

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

Gives clear operating context: what happens on success, and that when the entry is refused the timer keeps running and the reason is returned, so the agent knows the failure path is non-lossy. It stops short of explicit routing to alternatives (e.g. cancel_timer for discarding a timer without logging), so there is no when-not-to-use statement.

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

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

Annotations only supply the generic hint set (readOnlyHint=false, destructiveHint=false, idempotentHint=false); the description goes well beyond them by disclosing that entries lock, approvers are notified, exempt roles are auto-approved, and that refusals occur for empty or already-filed periods. Those consequences are exactly what an agent needs before invoking a non-idempotent mutation.

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

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

Front-loaded with purpose, then behavior, refusals, and return value in a tight three-sentence block with no filler. The closing sentence about the result is partly redundant given an output schema exists, which is the only wasted clause.

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

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

With annotations, a fully documented schema, and an output schema in place, the description covers the remaining unknowns an agent needs: locking, notification, auto-approval, refusal conditions, and which period modes are valid. Nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: the week is defined as Monday-to-Sunday, weekOf defaults to this week, and periodStart/periodEnd are framed as an exact alternative period. The only gap is that userId's signed-in-vs-connection distinction is left entirely to 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 ('Files the signed-in person's timesheet for approval') and pins down scope: the signed-in person's own sheet, not someone else's. An agent can distinguish this from approve_timesheets (approver action), return_timesheet, and recall_timesheet 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 concrete selection conditions: use weekOf (defaulting to this week) or an exact periodStart/periodEnd pair, and it states when the call is refused (no entries, already filed) plus the exempt-role auto-approval case. It gestures at the recall counterpart ('the call that recalls it') but never names recall_timesheet, so the alternative is implied rather than 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?

Annotations only say the call is a non-read, destructive, idempotent, closed-world write. The description adds real substance beyond that: partial-update semantics ('Only the fields given change'), visibility behavior ('A task the person cannot see reads as not found'), workspace reassignment/reprioritization floors, a contract lock on locked lines, and that the response carries prior values usable as an undo. This is exactly the behavioral context annotations cannot express.

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 its field list, then rules, then examples; each sentence is doing work. Slightly long and the closing example sentence is more motivating than strictly necessary, but nothing is egregiously wasteful.

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

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

With an output schema present, return shape need not be spelled out, yet the description still notes that prior values are returned as the undo call. Given the tool's complexity (9 params, mutation, destructive hint), it covers visibility, locks, partial updates, reassignment rules, and undo — the agent has everything needed to call it correctly.

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

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

Schema description coverage is 100% across 9 parameters, so the schema already documents every field, including the assignee/assigneeRef mutual-exclusion and the assigneeRefs set semantics. The description reinforces 'only the fields given change' and the undo-ref form, but adds little syntax or meaning the schema does not already carry; 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 and resource ('Changes one task') and enumerates the mutable fields (status, due date, priority, title, assignee), so an agent immediately knows the scope. It scopes to a single task, implicitly separating it from list_tasks/create_task/delete_task, but never names a sibling or states its boundary against them explicitly.

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

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

Gives concrete usage triggers via natural-language examples ('mark the drainage memo done', 'push the survey task to Friday'), which tells the agent when this tool applies. However, it offers no exclusions or alternatives (e.g. when to prefer update_time_entry or delete_task), so the routing guidance is context without contrast.

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 annotations (destructiveHint=true, idempotentHint=true), it discloses genuine behavioral traits: patch semantics ('Only the fields given change'), the status-based refusal rule, the reopen path, and that the result echoes prior values so the edit can be undone. This is unusually rich disclosure for a mutation tool.

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

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

Dense but front-loaded, leading with what changes and the partial-update rule before the edge cases. The trailing example ('make Tuesday's RISE entry 3 hours') is slightly extraneous but useful for routing and does not bloat the text.

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

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

An output schema exists so return structure need not be described, and the description nonetheless covers the refusal/undo behavior that matters for a mutation. Nothing an agent needs to call this correctly is missing.

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

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

With 100% schema coverage the baseline is 3, but the description adds real meaning: project may be given by projectId, code or name, and it clarifies the field set that can be edited. It reinforces rather than merely repeats 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 (changes/updates) on a specific resource (the signed-in person's own time entry) and enumerates the mutable fields, so an agent can tell it apart from delete_time_entry, restore_time_entry, and log_time_entry without opening a sibling 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 conditions for failure: entries filed for approval, approved or invoiced are refused with a reason, and recalling the filed week reopens it. It stops short of naming the sibling tool (recall_timesheet) that performs the reopen, leaving that inference to the agent, so it is strong but not fully explicit about alternatives.

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 (destructiveHint=true, idempotentHint=false): it discloses exactly what is destroyed in each case, the refusal conditions with a returned reason, and that prior state is retained with a restoring call returned. That is the reversibility and failure-mode context an agent needs for a destructive mutation.

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 with the primary action and scope front-loaded, then effects, then refusal/reversal semantics. The closing intent phrase is short and aids matching for colloquial requests; nothing is padded.

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

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

For a destructive, non-idempotent mutation with an output schema present, the description covers scope, success cases, refusal cases and reversibility, so nothing needed to call it correctly is missing. Return-value detail is appropriately delegated to the 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%, so both parameters are already documented (userId scoping, requestId format). The description's 'signed-in person's own' reinforces the userId constraint but adds no syntax or format detail beyond the schema; baseline 3 applies.

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

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

States a specific verb (withdraws) and a precisely scoped resource (one of the signed-in person's own time-off requests), which separates it from request_time_off, list_my_time_off and restore_time_off without needing the schemas. The description also enumerates the two concrete effects (leaves the approvers' queue / cancels unstarted approved leave).

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