UseHourly

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?

Adds behavior annotations cannot express: totals are computed server-side, entries already invoiced are silently excluded so hours are not double-billed, numbering auto-assigns INV-<year>-NNN, and the record is permanent. The dedupe rule in particular is non-obvious and changes how an agent should construct 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?

Four sentences, front-loaded with what is billed, then the computation/ dedupe rule, then the numbering default, then the confirmation warning. No filler and no repetition of schema text.

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

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

An output schema exists so return values need no explanation, and annotations declare the write profile; the description covers the non-obvious generation logic well. It leaves open the failure case (no billable entries in the range) and whether the invoice is issued as draft or final, which matter for a permanent record.

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

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

Schema description coverage is 100%, so the schema already documents all nine parameters and the description correctly does not restate them at length. It adds only that `number` defaults to next free INV-<year>-NNN (already in the schema) and says nothing about compact_notes, include_detail, or due_date behavior. 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 and, crucially, the data source: an invoice built from billable time between two dates, with one line per project. That distinguishes it from get_invoice, list_invoices, and next_invoice_number without needing the 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 a concrete pre-flight instruction ('confirm the client, period and dates with the user first'), which is exactly the guidance needed before a non-idempotent write. It does not point at alternatives (e.g. next_invoice_number or list_entries to preview billables) or state what to do if no unbilled time exists, so it stops short of explicit when/when-not routing.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the mutation profile is covered structurally. The description adds genuine value with the currency-resolution rule, but it omits any warning that repeated calls create duplicate projects (non-idempotent) or that a client must pre-exist.

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 verb and parent relationship. The nested parenthetical about currency is slightly dense 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?

Because an output schema exists, return values need no explanation, and all four parameters are documented. What is missing is failure behavior for a non-idempotent create: duplicate names, unknown client ids, or validation limits are left unaddressed.

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 every parameter is documented in-schema, including the same currency fallback rule the description repeats. The description therefore adds no meaning beyond the structured fields, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Add a project') plus its parent relationship ('under a client') and the key attributes set at creation. It is clearly distinguishable from create_client and create_invoice, though it never names those siblings to reinforce the distinction.

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

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

No guidance on when to use this versus update_project or archive_project, and no stated prerequisites (e.g. the client must already exist via create_client). The agent must infer the workflow from the sibling list 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 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, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real semantic context beyond that: what the payload contains and the non-obvious null semantics for invoice_schedule (null = freelancer chooses cadence), which an agent cannot infer from the 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?

One compact sentence with zero filler; the resource is front-loaded and the clarifying parenthetical about invoice_schedule is the only elaboration, and it earns its place by removing ambiguity.

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

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

For a trivial single-record read with an output schema, annotations, and fully documented parameters, the description is essentially complete. The one gap is behavior on a missing/unknown client, which an agent would want to know before calling.

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

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

Schema description coverage is 100% and there is a single required parameter ('client': id or exact client name), which the schema documents fully. The description adds nothing about how to form that argument, 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?

Clearly conveys that this retrieves billing details for a single client, listing the concrete fields returned (legal name, address, invoice schedule). It reads as a noun phrase rather than a verb+resource statement and never names the near siblings (list_clients, update_client, get_invoice) it must be distinguished from, 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?

The singular-client scope implies when to use it (you know which client you want) versus list_clients, but there is no explicit when-to-use statement, no stated alternative, and no mention of what happens if the client is not found. Usage is inferred rather than 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 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, non-destructive, and closed-world behavior. The description adds useful behavioral detail beyond annotations: the output is a project-by-day grid with totals and includes weekdays with nothing logged, and non-billable days still count. It does not describe pagination or auth, but the added shape context 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?

The description is front-loaded with the return shape and then gives usage context. Every sentence carries useful information, and the dense enumeration of grid contents is appropriate for a tool whose value depends on knowing what the grid includes.

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 safety traits and an output schema present, the description does not need to explain return values in full. It covers date-range scope, optional client/project filtering, grid contents, and inclusion of non-billable days. Minor omissions such as timezone or maximum range handling keep it from being fully complete, but it 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 description coverage is 100%, and the schema already explains from/to as inclusive YYYY-MM-DD and client/project as id or name. The description confirms that client and project are optional filters for one client or one project, but adds little syntax or constraint detail beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb and resource — retrieving a timesheet for a date range — and details the returned shape: one row per project, hours per day, totals, and empty weekdays. This distinguishes it from generic entry listing or project-total tools by emphasizing a grid timesheet view.

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 this to 'show me my timesheet for last week' or to check a sheet before sharing it," which connects naturally to share_timesheet. It does not explicitly exclude alternatives like list_entries or project_totals, so it stops short of a full when/when-not routing rule.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower. The description adds genuine behavioral scope by restricting results to ACTIVE clients and explaining the rate-currency resolution rule, but says nothing about ordering, pagination, or result size.

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 result scope and followed by the currency rule. Every clause carries information; 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 scope (active only) plus currency/rate semantics. Ordering and pagination behavior are left unspecified, which is the only real gap for a zero-parameter list 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 tool takes zero parameters, so the baseline is 4; there is no parameter semantics to document. The description's note about currency resolution is data semantics rather than parameter guidance, but nothing is missing on the parameter front.

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 resource and scope: active clients, each with currency and active projects. An agent can distinguish it from get_client (singular) and list_projects, though the verb 'list' is only implied by the title rather than stated.

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

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

No when-to-use guidance and no alternatives named. With siblings like get_client, list_projects, and archive_client in the catalog, the description never says when to pick this tool over them or that it returns all clients unfiltered.

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 the safety profile (readOnly, idempotent, non-destructive), yet the description goes further by disclosing the 200-record result cap and the conditional output semantics of unpaid_totals (per currency) vs unpaid_total (only when a single currency matches). That is real behavioral context an agent could not 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?

Three dense sentences, with the scope constraint front-loaded ahead of the filter list. Every clause carries information, though the trailing unpaid_totals/unpaid_total sentence is somewhat compressed and takes a moment to parse.

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-value documentation is not required, and the description still fills the key gaps: result cap, per-invoice currency, filter dimensions, and the conditional totals fields. Only the sort behavior and any pagination/ordering interaction with the 200 cap go unexplained.

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 query, client, status, issued_from/issued_to and sort. The description restates the filter axes in prose but adds no syntax, formats, or precedence rules beyond the schema; baseline 3 applies. It also omits any mention of the sort parameter.

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 (invoice history) and adds concrete scope details: the 200-item cap, per-invoice currency, and the available filter dimensions. It clearly reads as a paginated list operation rather than the single-record get_invoice sibling, though it never names that sibling 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?

Filter dimensions are listed ('Filter by text, client, paid status or issue-date range'), which implies when the tool is useful, but there is no explicit when-to-use/when-not guidance or routing to alternatives like get_invoice for a single record.

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?

Goes well beyond the annotations: discloses that anyone with the link can read it until it expires, that rates and amounts are never shown, that notes are included unless include_notes is false, that the link is returned only once and must be passed to the user, and that demo accounts cannot use it. These are exactly the behavioral traits an agent needs before invoking a non-idempotent, irreversible link-creation 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?

Four sentences, each carrying distinct information: what it produces, what the link reveals, the confirm-before-calling rule, and the one-time-return plus demo restriction. Front-loaded with the core action.

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

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

With an output schema present, the description needn't explain return shape, and it still flags the critical one-time-visibility constraint. Annotations cover the safety profile and the description covers exposure, prerequisites and availability, leaving no meaningful gap for a 7-parameter tool.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds meaning by explaining that client/project scope the frozen hours, that include_notes=false suppresses work descriptions, and that the link expires. It does not add new detail on from/to/title/expires_in_days beyond what the schema already documents.

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 ('Freeze the hours of a date range ... into a private link') plus the recipient and scope (optionally one client or project). It is clearly distinguishable from get_timesheet because the output is an externally openable, account-free link rather than the caller's own view.

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

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

Explicitly says to confirm the range, the client and the include_notes choice with the user before calling, and adds a hard availability gate ('Not available on demo accounts'). That is concrete when-to-use and precondition guidance rather than vague context.

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 covered. The description adds genuinely useful behavior beyond the annotations: it is a partial/patch update where unspecified fields are left untouched, which is or is not obvious from a mutation tool. It stops short of what happens to existing time entries or reports when a rate or client 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 sentences, no filler, with the scope of changes front-loaded ahead of the patch-semantics clarification. Every sentence carries information an agent needs.

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 plus a fully documented 5-parameter schema cover most of the surface. Left implicit are the unstated required-parameter behavior (project is the sole required arg, but the description implies any field is optional) and any side effects of moving a project to a new client.

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 (name, client, project, billable, hourly_rate) already has a descriptive string, including the flexible "Client / Project" id resolution and the hourly_rate currency rule. The description only restates the field set, adding no syntax or constraint detail beyond the schema, so the baseline of 3 applies.

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

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

Names a specific verb set (rename, move, change rate/flag) against one resource (project), enumerating exactly which attributes the tool mutates. This cleanly separates it from update_client and from archive_project/unarchive_project in the sibling list.

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?

"Only the fields you pass change" tells the agent how to call it, but there is no explicit guidance on when to prefer this over siblings such as archive_project, unarchive_project, or project_totals, nor any prerequisites (e.g. needing write access or a resolvable project id).

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, destructiveHint=false and a closed world, so the safety profile is covered. The description still adds real value beyond them by disclosing what the call reports back — account identity plus the token's permission level — which tells the agent this is a preflight/authorization probe.

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 returned identity data, with the call-to-action appended at the end. No filler and nothing redundant with the annotations.

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 parameters, rich annotations, and an output schema present (so return shapes need not be explained), the description supplies exactly the missing piece: what the tool tells you and when to reach for it. Nothing an agent needs to invoke it correctly is absent.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate and it correctly does not invent parameter details.

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, concrete output: the signed-in account's identity fields (name, email, currency, invoice business details) plus the token's read/write capability. No sibling tool in this list does identity/authorization introspection, so it is cleanly 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?

"Call this first to confirm the connection" gives explicit ordering guidance and a clear trigger condition. It does not name a when-not case or an alternative, but no realistic alternative exists for this capability.

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