docket

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

Annotations declare destructiveHint=true, readOnlyHint=false, idempotentHint=false. The description confirms and adds detail: the stopwatch is removed, duration is rounded up to the next 15 minutes, and ticket defaults to the stopwatch's ticket. This goes beyond annotations by describing exactly what gets destroyed and how defaults are computed.

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; every clause carries information. Minor deduction for the elliptical phrase 'the ticket to the one on the stopwatch', which is slightly awkward though understandable.

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

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

Covers the essential behavior for a 6-parameter mutation tool whose schema already documents all parameters well. It doesn't describe the return value (the created time entry), but no output schema exists and that omission is minor for this operation.

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 adds meaningful extra semantics: the duration is rounded up to the next 15 minutes based on the stopwatch suggestion, and the ticket defaults to the one on the stopwatch. These behavioral rules are not fully captured in the schema's plain 'default' notes.

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: books a stopwatch as a time entry and removes the stopwatch. This clearly distinguishes it from siblings like log_time (creates a time entry but doesn't consume a stopwatch) and discard_stopwatch (removes without booking).

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

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

Implies usage context by describing what happens (converts stopwatch into time entry and removes it), which lets an agent infer it's for finalizing a stopwatch. However, it never names alternatives such as log_time or discard_stopwatch, nor states when not to use it.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=true, so the safety profile is covered. The description adds genuine value beyond that by disclosing the side effect — followers are notified — and the concrete state change to the done column, which the annotations do not convey.

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

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

A single sentence that front-loads the action, then parenthetically explains the effect and the notification side effect. No filler and nothing an agent must read past to get the core 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?

For a one-parameter mutation with no output schema, the description covers the action, the resulting state, and the side effect, while annotations cover idempotency and non-destructiveness. Only the behavior on an already-closed ticket and any permission requirements are left unstated.

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

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

Only one parameter and the schema describes it fully (100% coverage), including where to obtain the ID ('From search_tickets or my_tickets'). The description adds nothing about the parameter 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?

Names a specific verb and resource and, unusually, defines what 'close' actually means mechanically (moving the ticket to the board's done column). The only gap is that it doesn't explicitly contrast with reopen_ticket, the obvious inverse sibling, though the semantics are unambiguous.

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

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

Usage is implied by the verb and the 'close button in docket' analogy, but there is no explicit statement of when to reach for this versus reopen_ticket or a status-changing alternative, and no prerequisites (e.g., permissions, whether already-closed tickets are affected).

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 a non-destructive write operation. The description adds valuable behavioral context beyond annotations: comments are plain text with blank lines separating paragraphs, and ticket followers are notified. These side-effect details are not present in the structured data and help the agent understand the consequences of the 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?

The description is two sentences, front-loaded with the action, and every sentence adds value—formatting constraints and notification behavior. There is no filler or redundancy.

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

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

For a simple 2-parameter tool with full schema coverage and annotations covering safety, the description is nearly complete: it covers purpose, formatting, and side effects. It could optionally mention return behavior (e.g., what the API returns), but given no output schema, this is a minor gap.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful formatting semantics for the 'text' parameter (plain text, blank lines for paragraphs) that the schema merely labels as 'The comment'. It doesn't add info about 'ticket_id', but the schema already documents its source.

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 uses a specific verb ('Adds a comment') and resource ('to a ticket'), making the action unambiguous. It does not explicitly differentiate itself from siblings like create_ticket or get_ticket, but the purpose is clear enough that an agent can select it without confusion.

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

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

Usage is implied by the description—an agent knows this is for adding comments. However, there is no explicit guidance on when to use this versus alternatives (e.g., create_ticket, get_ticket) or any exclusions. It falls into the 'implied usage' tier.

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 the mutation profile (readOnly=false, destructive=false, idempotent=false, openWorld=false), so the bar is lower. The description still adds genuinely useful behavior: default assignee is the current user, and the ticket lands in the project's backlog rather than an active state, which an agent would not know from the 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?

Two short sentences with the core action and prerequisites front-loaded; no wasted preamble. The trailing clause 'as a ticket made in docket does' is slightly odd phrasing but conveys the backlog placement.

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

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

There is no output schema, so the description should say what comes back from a create — presumably a ticket identifier or the created ticket object — and it does not. Aside from that missing return-value guidance, coverage of preconditions and defaults is adequate for a 7-parameter create 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 description coverage is 86%, so parameters are largely self-documenting. The description restates the optional fields (description, start/end date, priority) without adding format or constraint detail, and only marginally clarifies assign_to_me ('assigned to the user unless asked otherwise'). 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 ('Creates a ticket') and adds scoping detail: the project must be one the user can open, and the ticket is assigned to the user by default. It does not name or differentiate against siblings like comment_on_ticket or my_tickets, but the create semantics are unambiguous.

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

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

Implies when to use it via the precondition 'in a project the user can open' and the default-assignment rule, but never states when not to use it or which sibling to prefer (e.g. comment_on_ticket for discussion, search_tickets to find existing ones first). Usage is inferable rather than stated.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds two things beyond that: the ownership/authorization constraint ('the user's own') and an explicit irreversibility warning, which is useful reinforcement for an agent deciding whether to proceed. It stops short of describing what happens when the entry doesn't exist or is already deleted.

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 scope constraint front-loaded and the irreversibility warning second. Nothing could be cut without losing signal.

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

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

For a one-parameter destructive tool with full schema coverage and annotations covering the safety profile, this is essentially complete. Minor residual gap: no note on error behaviour for missing/already-deleted entries, though with no output schema this is low-stakes.

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

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

Schema coverage is 100% and the single parameter already carries the high-value note 'From list_time_entries', which is the key sourcing hint. The description adds no further meaning about the identifier (format, source, or reuse), 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 ('Deletes ... time entries') and adds an ownership scope ('the user's own'), which rules out deleting teammates' entries. It doesn't name the neighbouring update_time_entry or list_time_entries, so sibling differentiation is only implied by the scope phrase.

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

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

Usage is implied rather than stated: the ownership qualifier tells the agent it can only target its own entries, and 'can't be undone' signals this is a last-resort action versus update_time_entry. There is no explicit when-to-use/when-not or named 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 destructiveHint=true and idempotentHint=false, so safety and repeat-call behavior are covered structurally. The description reinforces this with 'this can't be undone' and clarifies the side effect that no time entry is created, but adds no other behavioral context such as whether a discarded stopwatch can be recovered or what state remains.

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

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

Two short sentences, front-loaded with the action and immediately followed by the irreversible consequence. No wasted words.

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

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

For a single-parameter deletion with full annotation coverage and no output schema, the description gives the agent everything needed to call it correctly. Only marginal gaps remain around recovery or post-deletion state.

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?

Single parameter with 100% schema description coverage ('From list_stopwatches'), so the schema already tells the agent where to obtain the ID. The description adds nothing further about parameter meaning; 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 (deletes) and resource (user's stopwatch) and adds a distinguishing qualifier, 'without booking its time', which separates it from book_stopwatch. It never names that sibling explicitly, so differentiation is implied rather than stated.

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

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

The phrase 'without booking its time' hints that the alternative is book_stopwatch, but the description never says when to choose discard versus booking or versus delete_time_entry. Usage is implied, not guided.

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

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

Annotations already cover readOnly, idempotent, closed-world and non-destructive, so the bar is lower. The description still adds real context beyond them: the figures are net amounts, access is restricted to admins, and the scope is a full year — all of which affect interpretation of the result.

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

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

One front-loaded sentence that names the source dashboard first and then lists contents; nothing is padded. The nested parenthetical about confirmed quotations without sent order confirmations is dense but earns its place as a precise definition.

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

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

With no output schema, the description must convey return contents and does so by enumerating every metric group. Combined with the admin restriction and the net-amount convention, an agent has enough to call it correctly, though the shape of the response (single object vs. per-month series) remains implicit.

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

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

There is a single optional parameter with 100% schema description coverage ('Default: this year'), so the schema already carries its meaning. The description's 'for a year' adds nothing on formatting, timezone or how partial-year data is handled, so the high-coverage 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?

The description enumerates the exact metric groups the tool returns (open/paid/overdue invoices, pipeline, order confirmations, revenue per month, quotations by status), which is far more specific than the title's generic 'financial summary'. The enumeration itself separates it from single-resource siblings like list_invoices or revenue_forecast.

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?

'Admins only, as in docket' is an access constraint rather than usage guidance. It never says when to use this dashboard rollup versus list_invoices, list_quotations or revenue_forecast, so the agent must infer that this is the aggregate overview and the others are detail lists.

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 and openWorldHint=false, so the safety profile is covered. The description adds meaningful behavior beyond that: it discloses that the response includes the connection's allowed capabilities, which is the key non-obvious trait for an identity tool. It does not state whether the result is cached or free to call repeatedly.

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 that spends every word on the return contents. No preamble, no redundancy, nothing to trim.

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

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

There is no output schema, so the description carries the burden of describing the return value — and it does so field by field (identity, role, default service, workspace, date, time zone, permissions). An agent knows what it will get and needs no parameters to call it.

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

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

The tool takes zero parameters, so there is nothing for the schema to document and no semantic gap to close; baseline 4 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 (returns) and enumerates exactly what is returned: connected user with name/role/default service, workspace, date, time zone, and permitted capabilities. This is unambiguous and distinguishable from every sibling (tickets, time entries, invoices), though it does not explicitly contrast with any of them.

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

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

Usage is only implied — an agent can infer this is a session-start identity/permission check, but the description never says when to call it (e.g., before other tools, to resolve the current user, or to check permissions) or when it is unnecessary. No alternatives are named, which is acceptable since no sibling serves the same purpose.

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 non-destructive behavior, so the description's job is smaller. It still adds real value by disclosing a permission-dependent output ('budget itself only when the user may see it in docket'), which an agent can't infer 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?

Two compact sentences, front-loaded with the resource and its return fields, with the conditional visibility caveat placed last. No filler or repetition of the title.

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

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

The return field list compensates for the absence of an output schema, but nothing covers identifier format or behavior on an invalid/unknown project_id. For a simple one-param read tool this is adequate but not complete.

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

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

Schema description coverage is 0% and the single parameter project_id is undocumented — the description doesn't say whether it is a numeric ID, slug, or key. It adds no meaning beyond the schema, so an agent must guess the identifier format.

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 resource and enumerates what is returned (customer, status, deadline, tickets, progress, budget usage), which makes the tool's purpose unambiguous. It doesn't distinguish itself from search_projects or project_budgets, so a sibling comparison is missing.

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

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

Usage is only implied: 'Details of one project' suggests fetching a single known project, but there is no statement of when to choose this over search_projects (discovery) or project_budgets (budget data). No prerequisites or alternatives are named.

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

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

The annotations already establish this as a safe, idempotent read operation. The description adds useful behavioral context by specifying what is returned, including latest comments ordered newest first, which helps an agent understand the response without an output schema.

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

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

The description is a single front-loaded sentence that efficiently lists the key returned fields. It is appropriately sized, though the parenthetical slightly interrupts the field list.

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?

Because there is no output schema, the enumeration of returned fields is valuable and mostly sufficient for a simple read tool. However, it leaves gaps around ticket_id semantics, comment count defaults, and error behavior for missing tickets.

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

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

Schema description coverage is only 50%, and the description does not compensate for the undocumented ticket_id parameter or explain ticket identifier format. It only indirectly references comments via 'latest comments (newest first)' and omits the count/default behavior documented in the schema.

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

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

The description clearly states this retrieves details for one ticket and enumerates the returned fields, so the resource and scope are unambiguous. It does not explicitly contrast with sibling tools like search_tickets or my_tickets, which keeps it from a 5.

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

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

There is no explicit guidance on when to use this tool versus search_tickets, my_tickets, or get_project. The single-ticket scope implies intended use, but alternatives and exclusions are absent.

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 behavior, so the bar is lower, and the description adds genuinely new context: an authorization requirement plus the exact overdue computation (invoice date + customer/workspace payment term). It does not describe pagination or ordering, but the safety and permission profile is well covered.

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

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

A single sentence with the core scope front-loaded and the permission caveat last. The nested em-dash parenthetical explaining overdue is dense and breaks the reading flow, but every clause carries information.

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

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

For a 3-parameter read tool with rich annotations and no output schema, the description covers permissions, status semantics, and returned amounts. Ordering and page-size behavior are only in the schema, which is acceptable given the 100% schema coverage.

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 goes further by defining 'overdue' semantically (past due date derived from payment term) and clarifying that customer filtering narrows rather than requires. That adds meaning the enum alone does not convey.

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 concrete resource (invoices) narrowed by status and optionally by customer, and names the returned fields (net and gross amounts). It is specific enough to separate from list_quotations or financial_summary, though it never uses an explicit verb and relies on the title for the 'list' framing.

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?

Includes a hard eligibility constraint ('PMs and admins only') and a default-status implication, which tells the agent when it can call it at all. It never says when to prefer financial_summary, revenue_forecast, or list_quotations over this tool, so the alternatives 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 readOnly, idempotent, non-destructive and closed-world, so safety is fully covered. The description adds one genuinely useful piece of non-annotation context — 'PMs and admins only' (an authorization requirement) — but says nothing about ordering or how the totals are scoped.

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

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

A single compact sentence that front-loads the resource and status filter, with no filler. It is fragmentary rather than elegantly constructed, but nothing is wasted.

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

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

For a three-parameter read-only list with an output-less schema, the description covers what it returns (net/gross amounts plus totals) and who may call it. Only ordering/pagination behavior is left implicit, which is minor.

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

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

Schema coverage is 100%, so all three parameters including the status enum are already documented in the schema. The description's paraphrase of awaiting_confirmation echoes the schema text rather than adding new meaning.

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 ('Quotations by status') and even names what the rows contain (net and gross amounts and totals). It does not explicitly differentiate itself from the closest sibling, list_invoices, though 'quotations' is naturally distinct.

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 ('the ones sent to a customer and not confirmed yet') implies the primary use case, but there is no explicit when-to-use/when-not guidance and no named alternative such as list_invoices or search_customers for narrowing.

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 the safety profile is covered. The description contributes domain semantics (what a service actually is, with concrete examples) and the default-fallback behavior when a booking omits one, which is genuinely useful context not present in the annotations.

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

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

Two very short sentences with zero waste, and the resource definition is front-loaded ahead of the default-service footnote. The first sentence is a noun-phrase fragment rather than a full clause, which slightly softens the opening.

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

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

For a zero-parameter, read-only enumeration with annotations covering safety and no output schema to explain, the description says what the resource is and when a value matters. Only the enumeration/return shape is left implicit, which is a minor gap at this complexity level.

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

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

The tool takes zero parameters, so per the baseline this is a 4. The description correctly spends no words on parameter documentation that would be redundant.

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 defines the resource precisely ("kinds of work, e.g. Design, Development") and ties it to its domain function (services time can be booked with), which distinguishes it from the many ticket/time-entry siblings. It stops short of an explicit verb like "list", leaving the enumeration action implicit in the name alone.

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

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

There is no explicit when-to-use or when-not, and no named alternative. However, "Booking without one uses the user's default service" implicitly tells the agent the tool matters when a specific service must be chosen rather than defaulted, which is more than nothing but still requires 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 and closed-world, so the safety profile is covered. The description adds genuine value by scoping results to 'the user's' stopwatches and by explaining that the suggested booking minutes are rounded up to the next 15 — a non-obvious behavioral detail absent 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?

A single front-loaded sentence that enumerates exactly what comes back, including the rounding rule. No preamble or redundant restatement of the title.

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

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

For a zero-param read tool with full annotation coverage and no output schema, the description adequately explains what is returned. Minor gaps remain: no mention of ordering, pagination, or behavior when no stopwatches exist.

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

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

Zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description instead spends its words on the return payload, which is the relevant semantics for a parameterless lister.

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

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

States the resource clearly ('the user's stopwatches') and enumerates the fields returned, so an agent knows this is a read of the caller's own stopwatch list. It doesn't explicitly name the action siblings (start/pause/resume/discard) it contrasts with, so it stops short of 5.

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

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

Usage is implied: use this to see current stopwatches. There is no explicit when-to-use, when-not, or named alternative (e.g., 'use before book_stopwatch to pick a stopwatch'), leaving routing to inference.

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

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

Annotations already establish that this is a safe, read-only, idempotent list operation. The description adds meaningful context beyond that: default date range, aggregation behavior (totals per day and project), admin-only scoping via user_id, and permission-gated revenue visibility. It does not mention pagination or result limits, keeping it below a 5.

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

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

Three compact sentences with no obvious filler. The default date range is front-loaded and the admin and revenue caveats follow logically. Slightly clearer wording around 'in docket' would improve it marginally.

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

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

With no output schema, the description appropriately explains the key return characteristics: time entries with totals per day and per project, plus conditional revenue visibility. It does not detail entry-level fields or ordering, but for a simple list tool this covers the essential 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 the schema already documents from, to, user_id, and project_id in detail. The description reinforces the default date range and admin-only behavior for user_id, but adds little beyond the schema and does not mention project_id at all.

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

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

The description states a specific verb and resource ('time entries in a date range') and adds useful scope details like default week and per-day/per-project totals. It does not explicitly distinguish itself from potential siblings such as my_week, so it stops short of a 5.

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

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

It implies the primary use case (viewing one's own entries for a date range) and notes the admin escalation path for other users' or everyone's entries. However, it does not name alternatives like my_week or explain when not to use this tool, leaving usage guidance only partially 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 already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description adds real context that the project is derived from the ticket (there is no project parameter), but it never warns that a non-idempotent re-call creates a duplicate entry — a meaningful omission for a mutation tool.

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

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

Three tight sentences with the purpose front-loaded and no filler. The trailing 'steps of 15' sentence mildly duplicates the schema's multipleOf constraint rather than adding to it.

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

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

For a 5-parameter mutation tool with annotations present and no output schema, the description covers the non-obvious derivation rules (project from ticket, service default) and the duration granularity. Missing only the duplicate-entry risk and any hint of the created entry's shape.

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

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

Schema coverage is 80%, so the schema already documents ticket_id, service_id, date, and the duration constraints (minimum 15, multipleOf 15). The description mostly restates that coverage — service default and duration steps both appear in the schema — with the only genuinely new detail being that project is inherited from the ticket. Baseline 3 fits.

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 ('Books time for the user on a ticket'), which is clearly distinguishable from update_time_entry or delete_time_entry. It doesn't explicitly contrast against the closest sibling book_stopwatch, so it stops short of a 5.

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

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

Usage is only implied — an agent can infer this is for creating a manual time entry, but nothing states when to prefer it over book_stopwatch, start_stopwatch, or update_time_entry, and no prerequisites or exclusions are given.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), and the description adds genuinely new behavioral detail: aggregation into one entry per thing/event with counts, newest-first ordering, and the unread default. It doesn't mention whether archived items are reachable, which is the one remaining gap.

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 dense sentence that front-loads what the tool returns and then the default filter. The 'docket's inbox' framing is slightly decorative but costs little.

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

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

With no output schema, the description does the necessary work of explaining entry granularity (one per thing and event, with counts) and sort order. Archived-notification behavior is the only thing an agent might still wonder about.

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

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

Schema coverage is 100%, so both parameters are already documented. The description only reinforces the include_read default ('unread only unless asked otherwise') and adds nothing about the limit cap or ordering interaction.

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

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

States a concrete resource and enumerates its contents (comments, mentions, assignments, closed/reopened tickets, document status changes), which clearly separates it from siblings like my_tickets or get_ticket. It never explicitly names an alternative, so it stops just short of a 5.

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

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

'Unread only unless asked otherwise' implies the default usage context, but the description never says when to reach for this versus my_tickets, get_ticket, or my_week. Usage is inferable rather than stated.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds real context beyond that: the definition of each bucket (OVERDUE = ended before today, UNPLANNED = no dates) and the fact that results are grouped rather than a flat list. It omits ordering within a group and whether counts/totals are returned.

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

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

It is a single front-loaded sentence that opens with the user-facing question and then supplies the bucket taxonomy, with no filler. The dense em-dash-and-parenthetical list is information-rich but slightly harder to scan than a short bulleted structure would be.

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

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

For a two-parameter, zero-required, read-only list tool with no output schema, the description supplies scope, bucket semantics, and defaults, which is nearly everything needed to invoke it correctly. The remaining gap is what each ticket entry contains and how results are ordered or paginated across groups.

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 a 3 is the floor, but the description goes beyond the enum list by explaining what each bucket actually means (e.g. THIS_WEEK = lies in this week, OVERDUE = ended before today) and restating the default of OVERDUE + THIS_WEEK. It does not clarify the per-group nature of `limit`, though the schema already covers that.

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 resource (open tickets assigned to the user) and a specific grouping model (the Workload page's six buckets), so an agent knows exactly what comes back. It does not explicitly contrast with the closest siblings (search_tickets, my_week), so it stops short of full sibling differentiation.

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

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

"What's on the user's plate" plus "assigned to them" implies the usage context, and the stated default (overdue + this week) tells the agent what happens if it passes nothing. However, there is no explicit when-to-use-this-versus-my_week or search_tickets guidance and no exclusions (e.g. closed tickets), so guidance is only implied.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior, so the description's job is lighter. It adds useful context beyond annotations: the default week, that it compares against working hours, and that it surfaces gaps and possibly forgotten bookings, though it does not describe the output shape.

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

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

The description is a single front-loaded sentence that leads with the core measure and then enumerates the derived insights. It is dense but earns its length given the composite report, though the em-dash list could be structured more scannably.

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

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

With no output schema, the description must convey what comes back, and it does so qualitatively by category (daily booked vs working hours, past gaps, unbooked due tickets, commented-on tickets without time). It stops short of describing result structure, which is a modest gap for a report 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?

The single parameter is fully documented in the schema (format YYYY-MM-DD, any day in the week, default today), giving a baseline of 3. The description only restates the default as 'this week' and adds no syntax or interpretation guidance 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?

The description specifies a concrete resource (the user's week) and a concrete measure (booked time vs working hours, day by day), plus the derived insights it returns. It clearly distinguishes itself from time-entry listing tools by being an aggregate report, though it never names a sibling to contrast with.

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

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

Usage is implied by the returned content (gaps, forgotten bookings, commented tickets), but there is no explicit when-to-use statement or comparison to alternatives like team_capacity or financial_summary. An agent can infer the right context but is not guided.

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

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

Annotations already declare this is a non-destructive, idempotent mutation, so the safety profile is covered. The description adds one genuinely useful behavioral fact beyond them — 'the time so far stays on it' tells the agent accumulated elapsed time is preserved. It does not state behavior when the stopwatch is already paused, whether the caller can pause another user's stopwatch, or any error conditions.

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 short sentence, front-loaded with the action, with the only non-obvious fact (time retained) appended. No filler, no restating of the title.

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

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

For a one-parameter, non-destructive, idempotent mutation with a fully documented schema and no output schema, this is nearly sufficient. The remaining gap is edge-case behavior (already paused, ownership scope), which the idempotentHint partly covers.

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

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

Single required parameter with 100% schema coverage; the schema description 'From list_stopwatches' even routes the agent to the correct discovery tool. The description adds no parameter-level meaning, which is acceptable at this coverage level but is baseline, not value-add.

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

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

Specific verb (pauses) plus resource (stopwatch) with the added scope 'one of the user's stopwatches.' It is clearly distinguishable from start_stopwatch/resume_stopwatch/discard_stopwatch by the verb, though it never names those siblings 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?

Usage is implied — you pause a stopwatch that is currently running — but there is no explicit when-to-use, when-not-to-use, or pointer to resume_stopwatch/start_stopwatch as the inverse operation. The agent must infer the routing from sibling names alone.

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 the tool as read-only, idempotent, and non-destructive, so the description does not need to repeat safety details. It adds useful behavioral context: budget amounts are visible only to users with docket visibility, and monthly budgets count the current month.

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

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

The description is front-loaded with the core purpose and then adds visibility and monthly-budget caveats. It is appropriately sized with little waste, though the phrasing could be slightly tighter.

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

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

For a read-only analytical tool with no output schema and complete parameter documentation, the description gives enough context about what is returned: budget usage percentages, over-budget flags, visibility rules, and monthly handling. It could more explicitly describe the response shape, but the key concepts are covered.

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 parameters are already well documented. The description adds meaning to the over-budget threshold (more than 100% used) and clarifies that customer filtering can cover all customers by default, but it does not elaborate on include_finished 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?

The description clearly states this is a budget overview of projects, including budget usage and over-budget status. It is specific enough to distinguish from generic project search, though it does not explicitly name sibling tools like financial_summary or search_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?

Usage is implied: fetch budget overviews, optionally for one customer, and optionally filter to over-budget projects. However, it does not state when to use this instead of related tools such as financial_summary or search_projects.

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 (not destructive, idempotent), and the description adds genuine context beyond them: the resulting state (backlog), the UI analogue (docket's reopen button), and the side effect of notifying followers. It does not say what happens when the ticket is not closed or what errors/permissions apply, so it stops short of a 5.

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

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

A single sentence, front-loaded with the verb and precondition, and every clause earns its place by adding state outcome, behavioural analogy, or side effect.

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

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

For a one-parameter state-transition tool with annotations and full schema coverage, this is nearly sufficient: outcome state and notification side effect are disclosed. The only gap is behaviour on invalid input (ticket not closed, unknown id), which the description doesn't cover and no output schema explains.

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

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

Schema coverage is 100% and the single parameter carries its own provenance hint ('From search_tickets'), so the schema does the work. The description adds nothing about the identifier format. Baseline 3 applies.

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

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

Specific verb+resource ('Reopens a closed ticket') with the resulting state named (back to the board's backlog), which distinguishes it cleanly from close_ticket and reschedule_ticket. An agent knows exactly what state transition occurs.

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 precondition 'closed ticket' is implied by the description, which is useful, but there is no explicit when-to-use guidance or mention of alternatives (close_ticket, update_ticket-style siblings don't exist, but reschedule_ticket is adjacent). Usage is inferable rather than stated.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true; the description adds the non-obvious mechanics that make it partially destructive — pass only the fields that change, and an empty string clears a date. It does not mention permissions, validation of start vs end date, or side effects on related time entries, but the added context beyond the annotations is substantive.

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 what changes, followed by the operational rule for optional fields. Every clause carries information an agent needs; nothing is redundant with the title.

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

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

For a four-parameter mutation with no output schema and strong annotation coverage, the description covers the essentials: what is mutable, that updates are partial, and how to clear values. It leaves unaddressed the interaction with ticket status (closed/reopened tickets) and whether date ordering is validated, which are minor but real gaps for a destructive operation.

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 75% and already documents the YYYY-MM-DD format and ticket_id source; the description adds the crucial partial-update semantic (only pass what changes) and the empty-string clearing convention, which is not obvious from the schema alone. The priority enum values are left to the schema, which is acceptable since they are self-describing.

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) plus the exact mutable resources (start date, end/due date, priority) and gives a concrete example ('moves it to next week'). This is clearly distinguishable from sibling mutations like close_ticket, reopen_ticket, or update_time_entry.

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 implies the intended use case (shifting a ticket to a later date), but there is no explicit statement of when to use this versus close_ticket/reopen_ticket, nor any prerequisite such as whether closed tickets can be rescheduled. Usage is inferable rather than stated.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false, and non-read-only, so the safety and repeat-call profile is covered. The description adds ownership scoping ('of the user') but nothing about what state changes occur or error behavior for non-paused stopwatches.

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 short sentence with the key state qualifier front-loaded and no filler. It is not verbose, though one clause about alternatives would have improved routing without bloat.

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

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

For a one-parameter state-transition tool with annotations covering safety and idempotency, the description is essentially sufficient. The only meaningful gap is failure behavior when the stopwatch is not paused.

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

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

Schema description coverage is 100%, and the schema already tells the agent the stopwatch_id comes from list_stopwatches. The description adds no further parameter meaning, 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 verb (resumes) and resource (stopwatch), and adds the state constraint 'paused', which helps distinguish it from start_stopwatch and pause_stopwatch. It stops short of naming those siblings explicitly, so differentiation is implied rather than guaranteed.

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?

'Paused stopwatch of the user' implies the prerequisite state and ownership scope, giving some usage context. However, it does not say what to do if the stopwatch is running, nor does it point to start_stopwatch/pause_stopwatch as alternatives, leaving routing to inference.

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

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

The description adds meaningful context beyond the read-only annotations: it states that access is admin-only and that amounts are net. It also describes the returned forecast components in detail, which is valuable because there is no output schema.

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

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

The description is front-loaded with the core purpose and every clause adds relevant detail about the forecast contents or access. It is slightly long and runs as a single sentence, but there is little wasted wording.

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 read-only annotations, full schema descriptions, and no output schema, the description does the important work of explaining what the forecast returns and that access is restricted to admins. It is sufficient for an agent to understand the tool, with only minor room for additional guidance about related tools.

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

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

The input schema already has 100% description coverage for both parameters, including that year defaults to the current year and customer_id comes from search_customers. The description reinforces that the customer filter is optional and that the forecast is yearly, but it does not add much beyond the schema's own semantics.

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

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

The description clearly identifies a yearly accounting revenue forecast and enumerates the specific data returned: monthly expected revenue, paid amounts, confirmed quotations, invoices, external costs, and underlying documents. It is more specific than the name alone, though it does not explicitly differentiate this tool from siblings such as financial_summary.

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

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

It implies usage by describing the forecast scope and says results can optionally be limited to one customer, and it states an admin-only prerequisite. However, it gives no explicit guidance on when to choose this over financial_summary or other financial tools, and no exclusions are mentioned.

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 and openWorldHint=false, so safety and repeatability are covered. The description adds the useful disclosure that results are ids meant to be fed into other tools, but says nothing about match behavior (partial vs exact), result ordering, or what happens when nothing matches.

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

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

Two short sentences with zero filler; the core action is front-loaded and the return-value note follows. Nothing repeats the name or title wastefully.

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 search with full schema coverage and no output schema, the description covers the essentials and even hints at the return shape via the downstream ids. Minor gaps remain around no-result behavior and pagination beyond the limit default, but nothing blocks a correct call.

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 the query ('Part of the company name') and limit ('Default 25') are fully documented in the schema. The description restates the company-name filter but adds no extra semantics such as case sensitivity or substring anchoring, so it earns the baseline rather than more.

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 ('Finds customers') and the matching criterion ('by company name'), which distinguishes it from search_projects and search_tickets by resource type. It also names the downstream consumers of the returned ids, which further sharpens its role.

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

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

Usage is only implied: an agent can infer this is the way to resolve a customer to an id before calling project_budgets, list_invoices or list_quotations. There is no explicit statement of when to prefer this over another lookup route, and no exclusions or prerequisites.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior, and the description adds useful context beyond that: results are permission-scoped to accessible projects, omitting the query defaults to active projects, and the output is ids intended for other tools. It does not describe pagination behavior or the full result shape, but the added behavioral context is solid.

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

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

Three short sentences, front-loaded with the core action and followed by the key default behavior and return-value note. Every sentence contributes useful information without repetition.

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

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

For a read-only search tool with four well-documented optional parameters, full schema coverage, and safety annotations, the description provides everything needed: search scope, default listing behavior, and output usage. No output schema exists, but the description's note about returning ids is sufficient for correct invocation.

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

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

Schema coverage is 100%, so the schema already explains each parameter. The description adds meaning by clarifying what happens when 'query' is omitted (active projects are listed), which complements the schema's 'status' and 'include_archived' defaults and helps the agent interpret optional parameters.

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

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

The description states a specific verb and resource (“Finds projects”) and clarifies the searchable fields (name, number, customer) plus the access scope (“the user can access”). It also distinguishes this from detail-fetch siblings by explaining that it returns ids for use with other 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?

It gives clear usage context: use with a query to search by name/number/customer, or omit the query to list active projects. It does not explicitly name alternatives such as get_project for a known id or search_customers/search_tickets, so it falls short of the top score.

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

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

Annotations already establish read-only, idempotent, closed-world behavior, so the description needn't repeat that. It does add useful non-annotation context: results are restricted to accessible projects and the output is ids intended for downstream tools. It stops short of describing ordering, pagination behavior, or empty-result handling.

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

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

Two compact sentences, front-loaded with the core purpose and followed by the return-value note. Slight imprecision in the example phrasing keeps it from being maximally 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?

With no output schema, the description correctly tells the agent it receives ids for other tools, which is the most important missing piece. It still leaves gaps around result ordering, default OPEN filtering, and how many results to expect when limit is omitted.

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%, with descriptions and defaults for query, status, project_id, assigned_to_me, and limit, so the schema carries the parameter burden. The description mentions no parameters at all, so it adds nothing beyond the baseline.

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

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

States a clear verb+resource ('Finds tickets') and scopes it to projects the user can access, with two concrete example use cases. It doesn't name the close sibling my_tickets, which handles the 'own open tickets' case, so the boundary is only loosely drawn.

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

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

Usage is implied through examples ('the ticket to book time on, or the user's own open tickets'), which suggests search-before-mutate flows. However, it never says when to prefer this over my_tickets or get_ticket, nor what to do when no results are returned.

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

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

Annotations declare non-readonly and non-idempotent; the description earns extra credit by explaining the concrete consequence — multiple stopwatches can run simultaneously, so calling it again creates another timer rather than replacing one. It adds no permission, side-effect, or error info beyond that.

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

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

Two short sentences, front-loaded with the parallel-run behavior, then the optional ticket hint. Every clause carries information an agent would otherwise have to infer.

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

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

For a simple two-optional-param creation tool with no output schema, the description covers the parallel-running semantics and the deferred ticket workflow, which are the non-obvious behaviors. 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 both params are documented, but the description adds real meaning: ticket_id is genuinely optional and can be attached later at booking, which the schema only hints at with '(optional)'. The title default behavior is left 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 ('Starts a new stopwatch for the user') and adds a distinguishing scope note: it runs in parallel with existing stopwatches rather than replacing them. It doesn't explicitly name siblings like resume_stopwatch or book_stopwatch, so it stops short of full differentiation.

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

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

Gives clear context for when to use it (starting a fresh stopwatch alongside others) and clarifies that the ticket link is optional and deferrable to booking. It doesn't name an alternative tool or state a when-not condition, so the exclusion guidance is absent.

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 (readOnly/idempotent/non-destructive), the description discloses what is computed per person and, importantly, that budget figures only appear 'for users who see budgets' — a permission-dependent output shape an agent must anticipate. It also warns the result is an estimate because docket has no capacity planning, which sets expectations about accuracy.

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 question an agent asks, and the long second sentence is dense rather than padded. The em-dash chain makes it slightly harder to scan but every clause carries information about the return shape.

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

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

With no output schema, the description carries the return-value burden and does so: per-person target hours left, open tickets due by week end, and remaining budgets/free hours. It also flags the estimation caveat and the permission gating. An agent has enough to decide and interpret 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 coverage is 100%, and the description largely restates the schema: 'default: this week' vs. the schema's 'default today', and expertise matched against 'service and its category' vs. the schema's 'service or service category title'. It adds marginal clarification but no new semantics, so baseline 3 applies.

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

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

The opening clause 'Who still has room in a week' names a specific resource and scope (people with remaining capacity) and is instantly distinguishable from siblings like my_week or project_budgets. It never explicitly names an alternative, so it stops short of a 5.

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

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

It gives clear use context: default is the current week, and the optional expertise filter narrows to people with matching service/category. There are no exclusions or named alternatives ('use X instead when...'), so the guidance is contextual rather than prescriptive.

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 idempotentHint=true and destructiveHint=true; the description's 'it keeps running if it was' adds real value about state behavior when the clock is reset. However, for a tool flagged destructive it never says the previous elapsed minutes are overwritten/lost, nor whether title changes can clash, which is exactly the context the annotation 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?

A single tightly packed sentence that front-loads the rename operation and enumerates the remaining capabilities without filler. The parenthetical is slightly clunky but earns its place by explaining runtime state.

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 4-parameter mutation with no output schema, the description covers the three mutated fields and one behavioral nuance. It leaves out whether multiple fields can be set in one call, what happens on an invalid/nonexistent stopwatch_id, and what confirming response a caller gets.

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 75% and the schema already documents minutes ('Sets the clock') and the ID sources, so baseline 3 applies. The description adds partial meaning (renames, corrected minutes, attach ticket) but the 'or' phrasing is ambiguous about whether fields must be updated one at a time or can be combined, and stopwatch_id is never discussed.

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 specific verbs (renames, sets its clock, attaches a ticket) against a specific resource (the user's stopwatch), and the three named fields let an agent recognize it apart from start/pause/resume/discard siblings. It never names an alternative outright, but the CRUD-update role is unmistakable.

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

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

Usage is implied by the listed operations (rename, correct the clock, attach a ticket), so an agent can infer when to reach for it. There is no explicit 'use this instead of X' guidance, e.g. no pointer telling the agent to use pause_stopwatch/resume_stopwatch for timing control or update_time_entry for logged entries.

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, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely non-redundant context: the patch semantics ('Only the fields given change') and the ownership restriction, plus the cascade that the project follows the ticket when moving entries.

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 dense sentence with the resource and mutable fields front-loaded and the patch-semantics caveat placed at the end where it modifies the whole clause. No filler.

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

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

For a mutating tool with no output schema but strong annotations, the description covers scope, the patch model, and the ticket-to-project side effect. It stops short of stating error conditions or what the response contains, which is a minor gap given the annotation coverage.

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

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

Schema coverage is only 33%, so the description has to compensate, and it does: it names date, duration, description, ticket and service, and clarifies that changing ticket_id relocates the entry (and thereby its project). Only time_entry_id is left to the schema's own 'From list_time_entries' hint.

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 ('Changes') plus resource ('one of the user's own time entries') and an enumeration of the mutable fields. It distinguishes itself from create-style siblings like log_time by the word 'changes' and by the ownership scoping, though it never names an alternative 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?

Usage is only implied: the ownership constraint ('user's own') and the list of mutable fields tell the agent this is a partial update, but there is no explicit when-to-use versus log_time / delete_time_entry / update_stopwatch guidance.

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