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 is covered. The description adds genuinely useful behavioral content beyond that: the report is produced in both cash and accrual views and covers both hours/earnings and invoice issuance/payment status, which tells the agent what the call will and won't include.

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 with no filler, and the breakdown dimensions are listed compactly. The colon-fragment style is dense but readable; nothing needs to be cut.

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 one required parameter, an output schema to describe the return shape, and annotations covering the safety profile, the description only needs to convey scope — which it does (dimensions, both accounting bases). The lack of explicit routing guidance against sibling aggregation tools is the only real 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?

There is a single parameter and schema description coverage is 100%, with the schema already giving the calendar-year meaning, the 2000-2100 range and an example. The description adds no additional semantics for 'year' beyond what the schema supplies, so the baseline 3 applies.

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

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

The description names the resource (one calendar year) and enumerates exactly what it reports: hours and earnings broken down by quarter, month, client and project, plus invoice status. That is specific enough to distinguish it from aggregate siblings like project_totals, 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 by the title 'Year summary for taxes' and the annual scope of the description; there is no statement of when to choose this over project_totals or list_entries, and no exclusions or prerequisites. An agent can infer the tax/annual-reporting context but must guess the boundary against sibling aggregation tools.

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

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

Annotations already state readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the safety profile is partly covered. The description adds genuinely new behavioral context: related time entries and invoices are retained, which tells the agent this is a reversible-looking soft-hide rather than a cascade delete.

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 visibility effect is front-loaded and the data-retention caveat follows immediately. 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?

With an output schema present and annotations covering safety, the description only needs to convey scope and side effects, which it does. The one gap is that it never says whether the archive can be undone, and no unarchive_client sibling exists to fall back on.

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

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

Schema description coverage is 100% and the single 'client' parameter is documented there as an id or exact client name. The description adds no extra parameter meaning, so the baseline of 3 applies.

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

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

The description gives a concrete verb ('Hide') and resource ('a client'), plus the effect on visibility ('from the lists'). It implicitly distinguishes archiving from deletion by stating data is preserved, though it never names a sibling such as delete_entry or archive_project.

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 right call when a client should be removed from view without losing data. There is no explicit when-to-use, no when-not-to-use, and no mention of how this differs from update_client or whether it can be reversed.

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 idempotentHint=true and destructiveHint=false, and the description reinforces this by stating that time and invoices are kept, telling the agent what is NOT lost. It still does not state that the action is reversible via unarchive_project, but the retention detail is genuine value beyond the annotations.

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

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

Two short sentences with no filler; the core effect (hiding from lists) is front-loaded and the retention guarantee follows immediately.

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

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

With an output schema present and annotations covering safety and idempotency, the description only needs to convey the semantic effect, which it does. Mentioning reversibility (unarchive_project) would fully close the loop.

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

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

Only one parameter, and schema description coverage is 100% — the schema already documents that it accepts a project id or a "Client / Project" string. The description adds nothing about parameter format, 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 (hide/archive) and resource (project), and clarifies the non-destructive nature by noting time and invoices are kept. It does not name the sibling unarchive_project, which would make the archive/reverse pairing explicit, but the operation is unambiguous.

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

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

Usage is implied: use this to hide a project from lists while retaining its data, which implicitly contrasts with deletion. There is no explicit when-to-use statement, no mention of the unarchive_project counterpart, and no prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the write/repeat-safety profile is covered structurally. The only behavioral claim in the description (names unique per account) largely restates the 'name' schema field description, adding little beyond structured data, and it doesn't explain what happens on a duplicate (error vs upsert) or what the response returns.

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

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

Two short sentences, front-loaded with the core action and no filler. It is appropriately sized, though the second sentence's uniqueness note is redundant with the schema.

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

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

With annotations covering the write/safety profile and an output schema present, the description needn't explain return values. However, for a creation tool it omits useful context such as the duplicate-name failure mode, whether 'color' is optional at creation, and any prerequisite permissions, leaving it only minimally adequate.

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 'name' (uniqueness, max 80) and 'color' (hex format) semantics are already fully documented in the schema. The description adds no parameter detail beyond that, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource ('Add a client'), which clearly distinguishes it from read-oriented siblings like get_client and list_clients. It does not, however, differentiate itself from the other creation/mutation siblings such as create_project or create_invoice, so sibling routing is only implied.

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 guidance on when to use this tool versus create_project, update_client, or the other client-management siblings. The uniqueness note reads as a constraint rather than a usage condition, so the agent gets no explicit context or exclusions.

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

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

Annotations already declare readOnly=false, idempotent=false, destructive=false, so the safety profile is covered; the description adds genuinely useful behavior beyond that: totals are server-computed from logged entries, the number auto-defaults to the next INV-<year>-NNN, and the record is permanent. It stops short of saying whether the invoice can later be edited or must be deleted/reissued.

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

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

Four sentences, front-loaded with the core action, followed by derived behavior, defaults, and the safety caveat. No sentence is redundant and the most important warning comes last for emphasis.

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, non-idempotent tool with full annotation coverage, a 100%-covered schema and an output schema that handles return values, the description supplies everything an agent needs: what it creates, how totals are derived, numbering defaults, and the confirmation requirement.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: totals are derived server-side (no amount inputs exist), lines map one-per-project, and the number parameter's default behavior is spelled out. It does not explain the effect of include_detail or compact_notes beyond what the schema already says.

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 plus the exact source of the data ('an invoice for a client from billable time between two dates'), and it states the derived structure ('one line per project'). An agent can distinguish this from list_invoices, get_invoice, next_invoice_number and mark_invoice_paid without opening any schema.

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

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

It gives clear conditions for use (billable time within a date range, for a specific client) and a strong precondition ('confirm the client, period and dates with the user first'). It does not, however, name alternatives or exclusions — e.g. that next_invoice_number can preview the number or that entries should be reviewed first.

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-read-only, non-idempotent, non-destructive write, so the safety profile is covered. The description adds only that the project is attached to a client and that the rate is in dollars, but says nothing about duplicate-name behavior, required client existence, or failure modes beyond what annotations and schema imply.

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

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

A single front-loaded sentence with no filler; the key scoping fact ('under a client') comes first. It is efficient, though quite terse for a creation tool.

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

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

An output schema exists, so return values need not be explained, and annotations cover the mutation profile. However, for a 4-parameter creation tool with sibling alternatives, the description omits any prerequisite or duplicate-handling context, leaving it only minimally complete.

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

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

Schema description coverage is 100%, so all four parameters (name, client, billable, hourly_rate) are already documented with defaults and bounds. The description echoes 'hourly rate in dollars' and 'billable' but adds no format or constraint detail beyond the schema, matching the baseline for fully covered schemas.

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

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

The description names a specific verb ('Add') and resource ('a project') and scopes it to a parent ('under a client'), which separates it from siblings like update_project, archive_project, and create_client. It is clear what the tool creates, though it does not explicitly call out how it differs from the other project-mutating siblings beyond the verb.

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

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

There is no statement of when to use this versus update_project or create_client, and no prerequisites such as whether the referenced client must already exist. The agent is left to infer usage entirely from the name and schema.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false. The description adds value beyond those flags by emphasizing permanence ('Permanently') and requiring user confirmation before invocation, which is not captured by the annotations.

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

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

Two short sentences with no filler. The destructive action is front-loaded, and the safety instruction follows immediately, making the description efficient and easy to act on.

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

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

Given the rich annotations, full schema coverage, and existence of an output schema, the description covers what is needed to call the tool safely. It could mention whether deleting an entry affects related totals or invoices, but the core destructive context is present.

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

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

Schema description coverage is 100%, and the single id parameter is fully documented in the schema as coming from list_entries. The description adds no additional parameter meaning, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: 'Permanently delete one time entry.' It distinguishes this tool from the sibling delete_invoice by scoping to a single time entry, so an agent can identify the correct deletion tool without inspecting schemas.

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

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

It gives a clear prerequisite for a destructive operation: 'Confirm with the user before calling this.' It does not name alternatives like update_entry, but no sibling offers an archive or soft-delete for entries, so the lack of explicit alternatives is minor.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds genuinely new behavioral context: the deletion is permanent/irreversible and the associated time entries are NOT cascaded away. It also mandates user confirmation. It stops short of stating permission requirements or exactly what else references the invoice.

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, no filler, with the destructive/permanent nature and cascade behavior front-loaded ahead of the confirmation instruction. Every sentence earns its place.

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

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

For a one-parameter destructive tool with an output schema and full annotation coverage, the description supplies exactly the additional facts an agent needs: irreversibility, non-cascading of time entries, and a confirmation requirement.

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

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

Schema description coverage is 100% and the single parameter is fully documented in the schema with a format example (INV-2026-004), so the description adds no parameter meaning beyond it. Baseline 3 is correct when the schema does all the lifting.

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

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

States a specific verb+resource ('Permanently delete an invoice record') and immediately clarifies scope by saying the time entries stay, which separates it from the sibling delete_entry that removes time data. An agent can distinguish it from delete_entry without opening either schema.

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

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

Gives an explicit precondition for invocation ('Confirm with the user before calling this'), which is the key usage constraint for a destructive tool. It does not name an alternative action (e.g., marking paid or voiding) that would avoid deletion, so it falls short of full when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructiveHint and openWorldHint=false, so the safety profile is fully covered structurally. The description adds only that the payload is invoice-printed legal name and address, which overlaps the existing output schema and adds little behavioral context such as permission needs or lookup behavior for a non-matching name.

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

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

A single tight clause with zero filler, and the identifying scope (one client's billing details) is front-loaded. It is a sentence fragment with no verb, which slightly weakens readability but not substance.

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

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

For a one-parameter read tool with full schema coverage, complete annotations and an output schema carrying the return shape, the description covers what is needed: entity, scope and field contents. The only real gap is routing guidance versus list_clients and get_invoice.

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% — the single 'client' parameter is documented as 'Client id or exact client name'. The description adds no resolution rules or hints about ambiguous/partial names, 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?

Names a specific verb (get) and resource (one client) and narrows scope to billing details — full legal name and address as printed on invoices — which distinguishes it from the generic client-data siblings. It does not explicitly call out its relationship to list_clients or update_client, so a 5 is not warranted.

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

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

Usage is only implied by the stated scope: an agent can infer it should fetch details for a single known client rather than enumerate clients. There is no explicit when-to-use, no when-not, and no alternative named (list_clients, get_invoice), so this stays at the minimum-viable level.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely new behavior: the invoice is a frozen snapshot 'as issued' rather than a recomputation, and logos are deliberately omitted from 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?

Three economical sentences, front-loaded with what the resource is and what it contains, then the one optional flag, then a deliberate omission. 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?

An output schema exists so return values need no explanation, and the description covers content and the detail flag. Minor gap: no mention of error behavior for an unknown/nonexistent invoice id.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning by describing the output shape in each parameter state: default returns lines per project and totals, while include_detail expands to a per-entry breakdown.

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 implicitly (retrieving the frozen invoice) and enumerates its content (seller, client, lines per project, totals). This clearly separates it from list_invoices, create_invoice, and mark_invoice_paid in the sibling set.

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 one already-issued invoice by id. There is no explicit when-to-use vs. list_invoices (to find an id) or create_invoice, and no note about whether drafts or unpaid invoices can be retrieved.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the null-when-idle contract, which is genuinely useful behavioral context, but it discloses nothing further (no cost, no scope, no freshness). The null case is also arguably part of the return contract covered by the 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?

A single front-loaded sentence with no filler. The most decision-relevant fact (what is returned) leads, and the edge case (null) closes 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 zero-parameter, read-only singleton lookup with a declared output schema, the description covers everything an agent needs: what it fetches, what it includes, and what happens when there is nothing to fetch.

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 to document and the schema/description cannot conflict. Baseline of 4 applies; the description neither needs to nor attempts to explain inputs.

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 ('the timer that is running now') and its payload ('elapsed minutes'), so an agent knows exactly what this returns. It does not explicitly contrast itself with siblings like start_timer or stop_timer, but the verb/resource combination is unambiguous enough that confusion is unlikely.

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 read used to check whether a timer is active before starting/stopping one. There is no explicit when-to-use statement, no mention of alternatives, and no prerequisites or side conditions called out.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed world, so the safety profile is covered. The description adds genuine behavioral context beyond that: the result is filtered to active clients and embeds each client's active projects, which tells the agent the shape and filtering of the payload.

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 fragment with zero filler, and the scoping information (active-only, nested projects) is front-loaded. It is arguably too terse rather than bloated, but it wastes no 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?

An output schema exists, so return values need no prose explanation, and with zero parameters the description's only remaining duty is to convey scope — which it does via the active-only filter and nested projects. The one gap is routing guidance against sibling list/get 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 tool takes zero parameters, so there is no parameter semantics to explain and the baseline is 4. Nothing in the description contradicts or confuses the empty 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 fragment names the resource (clients) and adds meaningful scope: only active clients, and each includes its active projects. That is more specific than the title alone. However, it never differentiates itself from siblings like get_client or list_projects, so an agent gets no help choosing among 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?

There is no explicit when-to-use statement, no exclusions, and no named alternative. The agent must infer from 'active clients' that this is the bulk-listing entry point rather than the single-client lookup get_client.

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, closed-world. The description goes beyond them by disclosing result ordering (newest first) and that aggregated totals per project and per day are included, which sets expectations an agent can't get from the hints 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?

Three short sentences, front-loaded with scope and return shape before the usage hint. No filler and nothing repeated from the name or 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?

With an output schema handling return values and annotations handling safety, the description covers all the behavioral context an agent needs to call this correctly. Only minor gaps remain, such as any practical limit on the date span or how an unknown project string is treated.

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%: from/to inclusivity and the project id-or-name format are already documented in the schema. The description only echoes 'inclusive' and the optional project limit, adding no syntax or matching detail, so the baseline 3 is appropriate.

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

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

States a specific verb (list) and resource (time entries) plus the exact scope and return shape: date-bounded, inclusive, newest-first, with per-project and per-day totals, optionally filtered to one project. That combination of ordering/aggregation semantics cleanly separates it from siblings like project_totals, annual_report, and get_running_timer.

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

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

Gives concrete trigger scenarios ('what did I log last week', checking a day before adding time), which maps the tool to real intents. It stops short of naming alternatives or exclusions (e.g., when to prefer project_totals or merge_entries instead), so it is clear context without routing.

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

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

Annotations already cover readOnly, idempotent, and non-destructive, so the safety profile is free. The description adds a genuinely non-obvious behavioral trait: results are silently capped at 200. It stops short of saying whether that is a truncation or an error, or how to page past it.

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

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

Two short sentences, no filler, with the result-cap constraint front-loaded before the filter summary. 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?

With an output schema present, return values need no explanation, and all six optional parameters are documented. The only real gap is what happens when the 200-item cap is hit and how sort interacts with it.

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

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

Schema description coverage is 100% and each parameter's enums and patterns are documented in the schema, so the baseline is 3. The description restates the filter axes but adds no syntax or format detail beyond the schema.

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

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

The description names the resource (invoice history) and states the key behaviors: a 200-item cap and the four filter axes. An agent can tell this is a filtered list rather than a fetch, though it never names get_invoice as the single-invoice alternative.

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

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

Usage is implied by the filter list — use it when you want invoices matching text, client, paid status, or a date range — but there is no explicit when-to-use versus get_invoice, and no exclusions or prerequisites 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 and closed-world, so the safety profile is covered. The description adds value beyond that by disclosing the default filter (active only) and the opt-in for archived projects, which is the key behavioral trait of this 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 short sentences, each carrying distinct information (scope/return fields, identifier convention, archived toggle), with the primary scope statement front-loaded. Nothing is redundant.

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 tool is simple, has an output schema so return structure needn't be explained, and annotations cover the safety profile. The description completes the picture with default filtering, the archived override, and the identifier convention used by sibling 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?

Schema description coverage is 100% and there is only one parameter, so baseline is 3. The description goes beyond the schema by documenting the label format ("Client / Project") used to identify projects elsewhere, which the schema does not carry.

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

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

The first sentence states a specific verb and resource plus the returned fields (client, hourly rate), so an agent knows exactly what comes back. It does not explicitly distinguish itself from siblings that also enumerate projects-adjacent data (list_clients, get_client), 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 real operational guidance: reference projects by "label" ("Client / Project") or id, and set include_archived to widen scope. It lacks explicit when-not-to-use steering (e.g., versus get_client or project_totals), but the context it provides is clear and actionable.

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, idempotentHint=false, and destructiveHint=false, so the write/safe profile is covered. The description adds the non-obvious consequence — "it never merges with an existing one" — which tells the agent that duplicate days produce duplicate entries, something idempotentHint alone does 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?

Four short sentences, front-loaded with the action, then the input choice, then the key non-merge behavior, then the pre-check. The opening field enumeration slightly restates the schema but is compact and orienting rather than wasteful.

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

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

An output schema exists, so return values need not be explained, and annotations cover the safety profile. Combined with the no-merge warning and the list_entries pre-check, the definition is sufficient for correct invocation; only the differing behavior for already-logged days is 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?

Schema description coverage is 100%, so the schema already documents project, date, minutes, duration, and note. "Give minutes or a duration text" restates the mutual exclusivity already stated in the schema ("use this or minutes"), adding no format or precedence guidance, 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?

Specific verb + resource ("Add one time entry") with the fields it carries, which implicitly separates it from bulk/day-level siblings like log_time_on_days and set_day_totals. It does not explicitly name those siblings, so differentiation is left to inference.

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

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

Gives a concrete when-to-use condition and a named alternative: "Check list_entries first if the day may already be logged." It stops short of stating what to do instead when a day is already logged (update_entry vs set_day_totals), so the routing is clear but not exhaustive.

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

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

Adds real behavioral detail beyond the annotations: days already holding time for this project are skipped and reported, with the skip controlled by skip_existing (default true). The annotations already declare write/non-destructive/non-idempotent, so this extra context on skip semantics is the meaningful addition; it stops short of covering partial-failure or overwrite behavior.

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

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

Two tight sentences with zero waste, front-loading the core action (add the same entry on up to 31 dates) before the conditional skip rule.

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

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

An output schema exists, so return values need not be described, and the annotations cover the safety profile. The description covers the key edge case (existing time), though it leaves open what happens to a skipped day's data and whether minutes/duration are mutually exclusive.

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

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

Schema description coverage is 100%, so the schema fully documents all six parameters, making 3 the correct baseline. The description only loosely echoes project/minutes/note and mentions skip_existing, adding no format or syntax detail beyond the schema.

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

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

States a specific verb and resource: adds the same time entry across up to 31 dates, with the fields (project, minutes, note) called out. It is clearly a batch variant of the sibling log_time, but it does not name log_time or otherwise explicitly distinguish itself from that sibling, so a 4 rather than 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?

The batch nature (multiple dates, same entry) implies when to use it versus a single-day logger, but there is no explicit when-to-use statement, no prerequisites, and no named alternative such as log_time or set_day_totals.

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 safety profile (readOnly=false, destructive=false, idempotent=true), so the bar is lower. The description adds useful context beyond them: that the call is reversible via null ('mark it unpaid again') and why the date matters (cash-basis tax treatment). It does not discuss permissions or audit behavior, but for a two-parameter setter that is minor.

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

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

A single sentence that front-loads the primary action and appends the inverse case. No filler, no repetition of the title, nothing that could be cut without losing 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?

An output schema exists, so return values need no explanation, and the annotations carry the idempotency and safety profile. Both modes of the operation and the date format are covered, so an agent has everything needed to invoke this correctly.

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

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

Schema coverage is 100% — both 'invoice' and 'paid_date' are documented in the schema, including the YYYY-MM-DD format and null option. The description's 'pass null to mark it unpaid again' largely restates the schema's 'null for unpaid', so it adds rationale rather than new parameter semantics. Baseline 3 is correct.

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

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

States a specific verb (record the paid date) on a specific resource (an invoice), and covers both directions of the operation — set paid or null to unmark. An agent can distinguish it from get_invoice, list_invoices, and create_invoice without opening any schema.

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

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

Gives clear context for when to use it (recording a payment date, which matters for cash-basis taxes) and explicitly describes the inverse case via null. It names no sibling alternatives, but no sibling competes for this action, so the absence is not a real gap.

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 flag destructiveHint=true, and the description meaningfully expands on this by stating exactly what is destroyed ('The others are removed') and how data is preserved (minutes added, notes joined, first entry kept). It stops short of noting non-idempotency or permissions, but adds real value beyond the annotations.

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

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

Two tight sentences, no filler, and the key data-preservation behavior is front-loaded before the destructive consequence. Every clause earns its place.

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

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

With an output schema present, return values need not be described, and the constraints, kept-entry rule, and destructive outcome are all covered. Only the absence of alternative-tool routing and non-idempotency detail keeps it slightly short of complete.

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

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

Schema coverage is 100% and the single parameter is fully documented, including the 2-20 range and the 'first one is kept' rule. The description largely restates the schema's own constraint ('same project, same day'), so it does not add notable meaning beyond the structured field.

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 verb (fold/merge) and resource (entries) plus the actual effect: minutes added, notes joined, first kept, others removed. This clearly distinguishes it from sibling delete_entry or update_entry, 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?

The parenthetical constraint 'same project, same day' implies the scenario (collapsing duplicate entries) but there is no explicit when-to-use guidance or comparison against update_entry/delete_entry for cleaning up entries. 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 readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds only the nuance that the number is 'suggested' rather than guaranteed, and says nothing about whether the value is reserved or how it is derived. Adequate, but adds little beyond the annotations.

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

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

One tight sentence that front-loads the return value and immediately illustrates the format. There is no filler or redundant restatement of the tool name.

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

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

An output schema exists, so return values need not be explained, and the single required parameter is fully documented. For a trivial read-only lookup this is nearly complete; the only missing nuance is whether the returned number is reserved or merely advisory.

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

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

Schema description coverage is 100% and the single 'year' parameter is fully documented in the schema, including its 2000-2100 range and an example. The description's 'INV-2026-004' example reinforces the year-to-number relationship but adds no syntax or semantics beyond what the schema already supplies. 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 exactly what is returned (the suggested next invoice number) scoped to a year, with a concrete format example ('INV-2026-004'). It is a noun phrase rather than a verb+resource, but it is unambiguous and distinguishable from invoice siblings like create_invoice, list_invoices, and get_invoice.

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

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

The description gives no when-to-use guidance, no prerequisites, and names no alternatives. The usage (call it before creating an invoice) must be inferred entirely from the name and context. 'Suggested' hints the value is advisory, but nothing states when it should be consulted or whether it reserves the number.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds genuinely non-structured context: the output unit is whole minutes and the parsing convention is 'the way UseHourly reads it', which tells the agent the app-specific format is authoritative. It does not say what happens on invalid input, keeping it from a 5.

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

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

One sentence, front-loaded with the concrete format examples, with zero filler. 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?

An output schema exists, so return values needn't be explained, and the description supplies the unit and parsing convention. The only material gap is error behaviour for malformed input, which is minor for a pure read-only conversion utility.

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

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

Schema coverage is 100% for the single 'text' parameter, so the baseline is 3. The description earns an extra point by enumerating formats ('1h30', '1:30', '2.5') that the schema only partially shows (schema example is just '1h30'), clarifying the accepted grammar.

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

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

States a precise verb (turn/convert), the input form (duration text), the output unit (whole minutes), and names three concrete example formats. No sibling tool in the list does anything comparable, so it is trivially distinguishable.

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 naming of input formats, but there is no explicit 'use this when...' or indication of what to do with unparseable input, nor any comparison to alternatives (none exist, but that isn't stated). Adequate but leaves routing to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds the scoping dimension (all-time vs. range) but doesn't clarify pagination, grouping, or how projects with zero hours appear.

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 resource and aggregation before the range qualifier. Nothing redundant, though the trailing parenthetical adds 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 an output schema present, return values need no explanation, and the tool is a simple two-param read. Still, the required-range versus 'all time' ambiguity and the absence of any alternative-tool routing leave gaps for an agent deciding how 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?

Schema coverage is 100% with explicit format and inclusivity notes on both params, so the schema carries the semantics. The description's 'all time and within a date range' actively implies the range may be optional, which conflicts with 'from' and 'to' both being required.

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 aggregation (logged hours) and the grouping dimension (per project), so an agent can tell it apart from raw listing tools like list_entries. The only blur is the 'all time and within a date range' phrasing, which is ambiguous given both range params are required.

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 never says when to use this instead of the many sibling reporting tools (annual_report, list_entries) or whether a date range is mandatory. Usage is only loosely implied by the mention of 'this month'.

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

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

Annotations only say it is a non-read-only, idempotent, non-destructive write. The description goes well beyond that: create-or-update semantics for positive minutes, deletion semantics for 0, explicit refusal to merge multi-entry days, partial-failure reporting, and the note being applied to every written day. That is exactly the extra side-effect detail annotations cannot convey.

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

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

Three sentences, no filler, front-loaded with the scope ('up to 31 days') and then the write/clear rule and the skip rule. Every clause carries actionable information.

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

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

An output schema exists, so return formatting need not be explained, and the description already covers the mutation semantics, skip behavior, and reporting of skipped days. Nothing material is missing 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 baseline is 3, but the description adds real meaning: the meaning of minutes=0 (clears the day) versus >0 (create/update), which is only implied by the schema's minimum of 0, and the fact that note is broadcast to every day written.

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 (set), resource (one project's total minutes), and bound (up to 31 days) in the first clause. The behavior 'more than 0 creates or updates that day's single entry, 0 clears it' distinguishes it from additive siblings like log_time and log_time_on_days without needing to open their schemas.

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

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

Gives clear context for when a day is written versus skipped: days holding several entries or a running timer are skipped and reported rather than merged. It does not name an explicit alternative tool for those skipped cases (e.g. update_entry, merge_entries), so the when-not path is described but not routed.

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

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

Annotations already declare readOnly=false, idempotent=false, destructive=false, so safety is covered. The description adds real behavioral value beyond that: it discloses the side effect that any already-running timer is stopped first, which is essential for an agent to predict state changes.

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, purpose front-loaded, with the constraint sentence adding genuinely new information. 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?

With an output schema present, return values need not be explained, and annotations carry the safety profile. The description covers purpose and the key state-changing constraint, leaving only minor gaps like permission requirements.

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

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

Schema description coverage is 100%, so all three parameters (date, note, project) are already documented in the schema. The description adds no additional parameter detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('Start a timer on a project') with the scope of the operation clear. It does not name any sibling (e.g., stop_timer, log_time) explicitly, but the 'only one runs at a time' clause implicitly separates it from the other time-tracking 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?

Usage is implied by the purpose statement but there is no explicit when-to-use guidance or named alternative. An agent must infer that it should call this instead of stop_timer/log_time when it wants a live timer running.

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 safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false). The description adds genuinely new behavioral context beyond that: elapsed time is rounded up to the next minute with a minimum of 1, which materially affects the recorded 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?

Two short sentences, front-loaded with the action and followed by the one behavioral caveat. Nothing is padded and every clause earns its place.

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

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

With an output schema present, return values need not be explained, and the rounding rule is the key behavioral detail an agent needs. The only gap is the error/edge-case behavior when no timer is running, which is 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate. Per the baseline for zero-parameter tools, a 4 is appropriate.

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

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

States a specific verb and resource ('Stop the running timer'), which is unambiguous against siblings like start_timer and get_running_timer. It does not explicitly name or contrast with any sibling, so it falls 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?

The usage is implied by the verb: you call this to stop a timer that is currently running. There is no explicit guidance on prerequisites (e.g., what happens if no timer is running) or routing to alternatives such as get_running_timer to check state first.

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, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds genuine value by disclosing a side effect beyond the parameter: the associated client may also be unarchived, which the agent could not learn from the schema or 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 with no wasted words, and the dual scope (project + client) is packed into the parenthetical rather than padded out.

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

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

An output schema exists, so return values need no explanation, and the single simple parameter is fully documented. The main gap is the absence of any explicit rejection/failure behavior when the target is not archived, but overall it is complete for a simple restore 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?

Only one parameter with 100% schema description coverage that already documents both the id and the 'Client / Project' format. The description adds no format or resolution detail beyond that, so the baseline 3 applies.

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

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

States a specific verb ('bring back' = restore) and resource (archived project), and the parenthetical scope clarifies that an archived client is also restored. It implicitly contrasts with the sibling archive_project but never names it, so the agent must infer the inverse relationship.

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 'archived project' implies the precondition that the project must currently be archived, but there is no explicit when-to-use or when-not-to-use guidance and no alternative tool is named. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the mutation safety profile is covered. The description adds genuine context beyond that: partial-update semantics and the fact that the logo is preserved, which an agent could not infer from the annotations.

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

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

Two tight sentences with the core action front-loaded and no filler; every clause (field scope, partial update, logo retention) 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?

An output schema exists, so return values need not be described, and annotations cover the safety profile. What remains is minor: no statement of error behavior for a nonexistent client, and the 'logo is kept' note references a field that has no corresponding parameter.

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 four parameters (including the required 'client' identifier and the 'empty string clears it' semantics for address/legal_name) are already documented. The description restates the editable fields but adds no format or identifier syntax beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Rename a client', 'change the legal name and address') and names the exact fields that can be edited, which cleanly separates it from create_client, archive_client, and get_client without opening any schema.

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

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

The description implies usage through its partial-update framing ('Only the fields you pass change'), which tells the agent this is for edits rather than creation. However, it names no alternative tools and gives no when-not guidance (e.g. use archive_client to retire a client), so usage is only implied.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds a genuine behavioral trait not present in annotations: partial-update semantics where omitted fields are preserved. It stops short of describing failure behavior for invalid ids or field conflicts.

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

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

Two short sentences, zero waste, with the action front-loaded and the patch-semantics caveat immediately after. Nothing superfluous and nothing buried.

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

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

An output schema exists and annotations cover the safety and idempotency profile, so the description needn't explain return values. It is nearly complete for a partial-update tool, missing only notes on validation failures or the minutes/duration exclusivity that would help prevent a malformed 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 each of the six parameters is already documented, including the id source ('from list_entries'), date format, note max length, and the minutes/duration exclusivity. The description only re-lists a subset of fields, adding no syntax or constraint detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('Change') and resource ('an entry') and enumerates the mutable fields (project, date, minutes, note), so the agent knows exactly what the tool operates on. It does not, however, distinguish itself from nearby siblings like merge_entries, delete_entry, or log_time.

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 clause 'Only the fields you pass change' implies patch-style editing of an existing entry, which is useful invocation guidance. But it never says when to prefer this over merge_entries, delete_entry, or log_time, so usage is only implied rather than directed.

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, idempotentHint=true, and destructiveHint=false, so safety is partly covered. The description adds the key behavioral fact beyond annotations: patch semantics ('Only the fields you pass change'), which reassures the agent that unspecified fields survive. It does not mention permission requirements or validation failures.

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 operation list is front-loaded and the patch-semantics clarification is placed second where it matters most for invocation. Every clause earns its place.

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

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

An output schema exists, so return values need no explanation, and annotations carry the safety profile. The description covers the mutation set and partial-update behavior, but leaves open side effects an agent might want, such as whether changing client or rate affects existing time entries.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds partial-update semantics that the schema alone does not convey — all five properties are optional except 'project', and the description confirms that omitting a field leaves it untouched. It adds no detail on the 'Client / Project' identifier format, which the schema already handles.

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-resource pair and enumerates the exact mutations supported: rename, move to another client, change rate, change billable flag. An agent can immediately distinguish this from create_project, archive_project, and update_client without opening any schema.

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

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

Usage is implied by the enumeration of editable fields — an agent knows this is for modifying an existing project — but there is no explicit when-to-use versus alternatives guidance, no note on when to prefer archive_project instead, and no prerequisites stated. Adequate but with clear gaps.

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 beyond that: it says the call reports what the token may do (read vs write), turning it into an authorization probe, and implies it is safe to use as a connectivity check.

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 covering both what is returned and when to call it, with zero filler.

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

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

For a parameterless, side-effect-free identity check with full annotation coverage and an output schema, the description need only state purpose and when to invoke. Nothing an agent needs is missing.

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

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

The tool takes no parameters, so there is nothing for the description to disambiguate; the baseline of 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+resource: it returns the signed-in account (name, email, business details) and the token's read/write scope. No sibling tool overlaps with an identity/permission check, so the agent can place it immediately.

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

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

"Call this first to confirm the connection" gives a clear trigger for when to use it, which is strong guidance for a zero-arg diagnostic tool. It does not name a when-not or alternative, but no plausible alternative exists among the siblings.

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