tallied

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

Annotations only provide basic hints (readOnlyHint=false, etc.), and the description adds meaningful context: it creates a draft, marks unbilled entries as invoiced (a behavioral side effect), and is non-destructive in terms of sending. It doesn't cover idempotency (annotations say false), but that's already hinted. The description adds value by explaining the draft-only nature and the marking behavior.

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

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

The description is three sentences, front-loads the trigger context, then the key behavior ('draft only'), and ends with actionable guidance. Every sentence adds unique information; no fluff.

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 tool with 6 parameters, no output schema, and moderate complexity, the description provides essential context: draft behavior, inclusion of unbilled entries, and next steps. It doesn't mention error conditions or return format, but the description's guidance is sufficient for an agent to invoke it correctly and interpret the result as a draft.

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 50%, with parameters like due_in_days and through_date having defaults in the schema description. The tool description doesn't repeat parameter details but implicitly explains that through_date determines which entries are included. Since half the parameters are documented in schema, and the description clarifies the core semantics (including 'all unbilled entries'), it compensates reasonably.

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

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

The description clearly states the verb (create), resource (draft invoice), and scope (all unbilled billable entries for the client), and distinguishes it from sending via invoice.send. It is semantically rich and unambiguous, matching the title and name while adding functional detail.

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 explicitly says when to use this tool (invoice request, billing period, unbilled hours), and directs the agent to use invoice.send when the user asks to send, providing a clear alternative. It also notes that nothing is sent, guiding expectation management.

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 that it accepts an invoice id or number and 'renders an invoice preview', which is useful context, but it does not disclose return format, error behavior, or what happens with invalid identifiers. This is adequate but not rich.

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

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

Two sentences, front-loaded with the usage trigger, followed by the accepted input format and the output behavior. Every sentence earns its place; there is no fluff or repetition of the schema or 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?

For a single-parameter read-only tool with strong annotations, the description covers the main invocation path and expected output. It is complete enough for an agent to call it correctly, though it does not specify failure modes or explicitly route between draft and finalized invoice siblings.

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 labels invoice_id as 'Invoice id or number'. The description adds a concrete example ('INV-0007') and clarifies that either an id or a human-readable number is acceptable, giving the agent more practical guidance than the raw schema alone.

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

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

The description uses a specific verb ('get') and resource ('specific invoice'), and lists the exact scope: lines, total, due date, payment link, or payment status. This clearly differentiates it from sibling tools like invoice.list or invoice.preview_draft, which serve different purposes.

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 explicitly opens with 'Use this when the user asks about a specific invoice's...', giving a clear triggering condition. It does not mention when not to use it or name alternatives, such as invoice.preview_draft for drafts or invoice.list for browsing, so it falls just short of a 5.

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

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

Annotations already define the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the description only needs to add context beyond that. It adds that the output is 'invoice summaries with status and totals,' which clarifies the shape of results without relying on an output schema. It does not mention pagination or auth rates, but this is a read-only list and the annotations shoulder much of that burden.

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 deliver high-value information with no redundancy. The opening sentence centers the use-case scope, the second defines the return shape, and the third points to the sibling alternative. This leaves zero waste and delivers all key selection criteria 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?

For a moderately complex tool with 5 optional parameters, no output schema, and a clear read-only nature, the description covers the main usage scenarios, the output (summaries with status and totals), and distinguishes from invoice.get. It could potentially mention sorting, pagination, or parameter interplay, but the schema already supplies those constraints. Overall, the agent can correctly decide when to invoke and broadly understand what to expect.

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 60%, so the description must partially compensate. It adds meaning to client ('specific client's invoices'), status ('outstanding, overdue, paid, drafts') and dates ('sent this month'), linking user scenarios to parameters. It does not explicitly explain 'limit,' but the schema already provides min/max and no required parameters, so the mapping is adequate.

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

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

The description clearly states the verb (list), resource (invoices), and provides a comprehensive list of user intents (outstanding, overdue, paid, drafts, sent this month, client-specific). It also distinguishes itself from invoice.get by noting that it returns summaries and delegates line items to the sibling. Agents can readily identify when this tool fits without opening 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?

The description gives explicit guidance: 'Use this when the user asks about invoices' and lists concrete query patterns (outstanding, overdue, paid, drafts, sent this month, which clients owe money, specific client). It explicitly points to the alternative: 'Use invoice.get for line items,' which addresses the main sibling. No when-not conditions are missing for this list-focused tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description only needs to add context. It reinforces 'Creates nothing' and adds return content ('lines, hours, and total') and equivalence to create_draft. It doesn't cover error behavior or tax handling, but the lower annotation bar makes this a 4.

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

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

Two sentences with no filler: the first gives the use case, the second states side effects and output. Every sentence earns its place and the most important information is front-loaded.

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

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

There is no output schema, so the description correctly summarizes the return shape ('lines, hours, and total'). It also communicates the no-side-effect nature and default date behavior indirectly via 'unbilled entries'. Missing details like tax handling and error cases are minor given the schema defaults and annotations.

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 75%, so the description carries a modest burden. It adds meaning by saying the same arguments would produce a create_draft result, but it doesn't explain the undocumented tax_rate_percent or provide any parameter-level detail beyond the schema. This is mild added value, so a 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 uses a specific verb ('Preview') plus resource ('invoice') and clarifies the scope: unbilled work for a client. The final sentence explicitly ties the output to invoice.create_draft, which distinguishes it from the sibling tool without opening any schema.

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

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

It opens with an explicit trigger: 'Use this when the user asks what they could invoice a client for...'. 'Creates nothing' functions as a when-not signal, and the reference to invoice.create_draft routes the agent toward the actual creation alternative.

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

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

The description discloses a key behavioral effect: 'Marks the invoice paid.' Additionally, it explains that Stripe payments are automatically recorded, which is contextualizing and beyond the annotations. The annotations already cover idempotency, destructiveness, and read-only status, so the description adds meaningful behavior context without repeating structured metadata.

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 very compact: three short sentences. Each sentence earns its place—usage, behavior, and exclusion. It is front-loaded with the most critical usage guidance and contains no redundant or filler content.

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

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

For a 4-parameter, 1-required, no-output-schema tool, the description fully covers the purpose, the when and when-not to use it, and the core visible effect. The schema handles parameter semantics, and the annotations handle side-effect metadata. No essential information needed to call this tool correctly is missing.

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

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

Input schema descriptions cover all 4 parameters (75% coverage) with clear examples for method and default for paid_on. The description does not add new parameter details, but it does reinforce that the method is for non-Stripe manual payments. Given high schema coverage, this is adequate and 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 clearly states 'Record a manual payment' and that it 'Marks the invoice paid', with explicit triggers (check, bank transfer, cash, etc.). It also distinguishes itself from the automatic Stripe payment flow, so an agent can unambiguously tell it apart from invoice.send or other invoice tools without opening the schema.

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

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

The description gives explicit when-to-use ('when the user says a client pays by check, bank transfer, cash, or otherwise outside the Stripe payment link') and an explicit when-not-to-use ('Stripe payments are recorded automatically; do not use this for them.'). This leaves no ambiguity and matches the sibling set.

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

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

The description discloses the real-world side effect ('This sends a real email to a real person') and the status change, adding context beyond annotations. Annotations already indicate readOnlyHint=false, but the warning about real email is valuable and consistent.

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 waste, and the critical usage condition is front-loaded. It efficiently conveys the action, the condition, and a caution. Excellent structure.

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 with no output schema, and the description covers what happens (sends email, changes status) and the required precondition. Nothing an agent needs to call it correctly is missing.

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

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

The input schema already has 100% coverage with descriptions for all three parameters. The description adds minor clarification about to_email being a fallback when no billing email exists, but does not add substantive meaning for message or invoice_id beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool sends an invoice with a Stripe payment link to the client's billing email (or to_email) and changes the status to sent. It explicitly distinguishes this from draft-related tools by requiring prior review, so an agent can tell it apart from invoice.create_draft and invoice.preview_draft.

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 provides explicit when-to-use guidance: 'Use this only after the user has reviewed the draft and asks to send it.' It also warns against re-sending unless asked. This is strong, direct usage direction.

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

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

The description adds substantial behavior beyond annotations: the confirm gate ('Requires confirm: true; without it returns the invoice for a final check'), the side effect of releasing time entries so they can be invoiced again, and the paid-invoice restriction. These are not already in the 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 sentences, front-loaded with the use condition, and every sentence adds a distinct actionable constraint: when to use it, the confirmation requirement, the side effect, and the paid-invoice limitation. No filler or redundancy.

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

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

The description covers the most important invocation details: confirmation, invoice eligibility, and post-void side effects. It does not describe the success return value or error details, and with no output schema that is a minor gap, but an agent has enough to call the tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate for all parameters. It adds meaningful semantics for confirm ('Requires confirm: true; without it returns the invoice for a final check') but does not explain invoice_id or the reason parameter at all. The optional reason string remains just a maxLength-limited string with no semantic value.

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?

Description clearly names the verb/resource pair ('void an invoice') and includes the direct use condition 'only when the user explicitly asks to void or cancel an invoice.' It distinguishes this tool from invoice creation, preview, payment, and sending siblings without ambiguity.

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

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

Gives an explicit trigger condition ('only when the user explicitly asks to void or cancel an invoice') and a when-not boundary ('Paid invoices cannot be voided'). It does not name sibling alternatives explicitly, but the purpose is narrow enough that an agent can select it correctly.

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 readOnlyHint=false, so the destructive nature is known. The description adds valuable behavioral context beyond the annotations: the confirm:true requirement and the two-phase behavior (omitting confirm returns the entry for a final check without deleting). It also discloses the sent-invoice restriction. This is strong behavioral disclosure, though it doesn't describe the return format or side effects in detail.

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, each earning its place: the first states the sole use case, the second explains the critical confirm behavior, the third gives the sent-invoice restriction and the alternative. The most important operational detail (confirm) is front-loaded. No filler or repetition of schema content.

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

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

For a destructive two-parameter tool with no output schema, the description covers the essential context: when to use, the confirm gate, the sent-invoice restriction, and the safer alternative. It doesn't describe what the response looks like or what happens to related data, but the annotations and schema cover the safety profile and required parameter. The only minor gap is the lack of detail on the 'final check' return value, but this is not critical 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 50%: entry_id has no description, while confirm has 'Must be true to actually delete.' The description compensates by explaining the confirm parameter's semantics in detail ('when omitted it returns the entry for a final check without deleting'), which is critical for correct invocation. It doesn't add meaning for entry_id, but the parameter name is self-explanatory and the required status is in the schema.

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

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

The description states a specific verb ('delete') and resource ('time entry'), and explicitly distinguishes it from the sibling time.update_entry by saying 'To fix a mistake, prefer time.update_entry.' This makes the tool's purpose unmistakable and differentiates it from related tools.

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

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

The description gives explicit when-to-use guidance: 'Use this only when the user explicitly asks to remove an entry.' It also provides a clear exclusion: 'Entries on sent invoices cannot be deleted.' And it names the alternative for fixing mistakes: 'prefer time.update_entry.' This is exactly the kind of routing an agent needs.

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

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

Annotations already establish the tool as read-only, idempotent, and non-destructive, so the description's burden is lower. It adds useful behavioral context beyond annotations: the default date range is the current week in the workspace timezone, and results include resolved names and per-entry rates. It does not mention pagination limits or cursor behavior, but those are captured in 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?

Four sentences, each earning its place: when to use, what it returns, when to use the alternative, and what not to use it for. The most actionable usage trigger is front-loaded, and there is no filler or repetition.

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

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

The description covers usage scenarios, output content, defaults, and sibling routing. With no output schema, mentioning that it returns individual entries with resolved project/client names and per-entry rates is helpful. Minor gaps remain around pagination and the exact meaning of billable_only, but those are reasonably inferable from the schema and sibling context.

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 high at 88%, so the description does not need to explain each parameter. It references project/client as useful dimensions but adds no detail beyond the schema. The description's mention of date defaults aligns with start_date/end_date defaults already declared in the schema.

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

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

The description uses a specific verb and resource ('list time entries') and clearly states what the tool returns: individual entries with resolved project/client names and per-entry rates. It also distinguishes itself from time.report by naming that tool for totals and breakdowns, and explicitly excludes calendar events, tasks, and reminders.

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 opens with concrete trigger scenarios ('asks what they worked on, what they logged, or wants entries for a day, week, project, or client'). It names the alternative tool for a different use case ('For totals and breakdowns use time.report instead') and gives negative guidance ('Do not use for calendar events, tasks, or reminders').

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 indicate this is a write operation with idempotentHint=true, but the description adds useful behavioral detail: each entry is validated independently, partial success is reported per row, and statuses match time.log_entry. It does not add details about auth requirements or output shape, but the added behavior exceeds what annotations alone provide.

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

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

The description is four sentences, each earning its place: when to use it, behavioral guarantees, error-reporting model, and an explicit prohibition. It is front-loaded with the most decision-relevant information and contains 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?

Given the tool's complexity (batch write, 10-field entry schema, no output schema), the description covers the key operational concerns: use cases, partial failures, and confirmation prerequisite. It does not describe the exact success/error response format, but it references statuses from time.log_entry, which is reasonably complete for 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 0%, so the description should compensate by explaining the entries parameter, but it does not. However, the schema's nested property descriptions are thorough, so the agent can still understand fields like start, duration, and project. The description itself contributes little to parameter semantics.

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

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

The description states a specific verb and resource: 'logging multiple entries at once.' It also gives concrete use cases (end-of-day recap, pasted list, after confirmation of proposed entries), which clearly distinguishes it from the single-entry time.log_entry and the proposal-stage time.propose_entries siblings.

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

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

It explicitly states when to use the tool ('Use this when logging multiple entries at once') and provides a direct exclusion: 'Do not call before the user has confirmed proposed entries.' This gives the agent actionable selection criteria without needing to inspect siblings.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds valuable behavioral context beyond annotations: it discloses that ambiguous projects return candidates instead of logging, that it never auto-creates a project, and that it echoes parsed duration and resolved date for confirmation. It doesn't explicitly mention idempotency behavior, but the idempotency_key parameter description covers that. The description is consistent with 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?

The description is compact and front-loaded: it opens with the primary use case, then exclusions, then edge-case behavior. Every sentence earns its place, covering trigger conditions, exclusions, ambiguity handling, project creation policy, and confirmation behavior in just four sentences. No redundancy with the schema.

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

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

For a tool with 10 parameters and no output schema, the description covers the key decision points: when to use, what to avoid, how to handle ambiguity, and what the tool echoes back. It doesn't describe the return format or error cases beyond ambiguity, but the schema covers parameter details and the description handles the main behavioral edge cases. The idempotency behavior is covered by the parameter description. A small gap is not explaining what happens when both duration and start/end are provided, but the duration parameter description covers that.

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 90%, so the schema already documents most parameters well. The description adds meaningful context beyond the schema: it explains the ambiguity behavior for the project parameter, clarifies that duration should be omitted when start/end are given, and notes that date should be omitted rather than guessed. These additions help the agent use parameters correctly without duplicating schema content.

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 ('log') and resource ('time entry'), and clearly distinguishes it from siblings by specifying the trigger condition: user states work done with a duration or start/end time. It also explicitly excludes future plans, reminders, timers, and calendar scheduling, which differentiates it from other tools.

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

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

The description provides explicit when-to-use guidance ('when the user states work they did with a duration or a start and end time'), and explicit when-not-to-use guidance ('Do not use for future plans, reminders, timers, or calendar scheduling'). It also names the alternative behavior (returns candidates when project is ambiguous) and instructs the agent to ask the user and retry, plus a clear directive to never auto-create a project.

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 indicate read-only, non-destructive, idempotent behavior. The description adds value by stating 'It saves nothing' and detailing the return contents: proposed entries with confidence scores, unmatched items, gaps, and overlaps. This goes beyond annotation coverage.

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

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

The description is compact and front-loads the primary use case, then gives workflow guidance and exclusions. Every sentence contributes useful decision-making 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?

Despite no output schema, the description summarizes the return shape enough for an agent to know what to expect. It also handles the follow-up action and exclusions. Some deeper output structure details are absent, but not critical for selecting and invoking the tool.

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

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

Schema description coverage is 80%, so the schema already explains most parameters. The description adds the useful notion of passing 'raw activity' and the downstream confirmed entry objects, but it does not materially clarify individual parameters beyond the schema.

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

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

The description clearly states the tool's purpose: proposing time entries from raw activity for reconstructing a day or week. It is explicitly distinguished from siblings like time.log_entry and time.log_entries_batch.

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

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

It gives explicit when-to-use context (reconstruct/catch up from calendar, commits, PRs, tickets, notes), describes the recommended workflow (present, confirm, then log), and explicitly says not to use it for logging a single known entry.

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

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

Annotations already cover readOnly, idempotent, and non-destructive behavior. The description adds useful behavioral detail beyond that: it defaults to the current week in the workspace timezone, returns aggregates rather than entries, and explains that group_by 'day' renders a week grid.

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 tightly written sentences, front-loaded with the primary use case, followed by the key distinction and defaults. Every sentence earns its place and there is no redundant restating of the title or 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 no output schema, the description still covers purpose, aggregation behavior, default time window, grouping options, and the main sibling alternative. It falls slightly short on fully specifying date-range semantics and the exact aggregate fields returned, but it is largely complete for a read-only reporting tool.

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

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

Schema description coverage is only 20%, so the description must compensate. It gives meaning to group_by through 'hours by day, project, or client' and mentions the current-week default, but it does not explain how start_date and end_date define a custom range or exactly how client and project act as filters.

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 specific use cases: hours worked, billable vs. non-billable split, hours by day/project/client, and unbilled amounts. It also distinguishes itself from time.list_entries by explicitly stating it returns aggregates, not individual entries.

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

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

It opens with 'Use this when the user asks...' and explicitly routes individual-entry needs to time.list_entries. This gives both a clear trigger condition and an explicit alternative, leaving little 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 say readOnlyHint=false and destructiveHint=true, so the description correctly aligns with a mutating operation. It adds useful behavioral context by disclosing the invoice restriction and the return value (previous and updated entry). It doesn't fully explain partial-update semantics, but the description still goes 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?

Three dense, purposeful sentences. The trigger is front-loaded, the precondition is next, and the limitation/return behavior follow without filler or redundancy.

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

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

The description covers when to use, where to get the ID, an important business rule (invoiced entries), and the response shape. Given that there is no output schema and 10 parameters, it would be even stronger with a note about rate or partial updates, but it is still substantially complete for an editing tool.

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

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

Schema description coverage is 0%, so the description must compensate. It names many relevant fields, but omits 'rate' and doesn't clarify value formats, duration syntax, or whether unspecified fields are preserved. It is helpful at the conceptual level but does not fully document all parameters.

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

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

The description uses a specific verb ('corrects') and resource ('existing entry'), and enumerates the editable fields (duration, description, project, date, times, tags, billable). It clearly differentiates from sibling tools like time.log_entry, time.delete_entry, and batch logging by emphasizing that this is for modifying an entry that already exists.

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 explicitly states 'Use this when the user corrects...' and gives the required precondition: the entry id from time.list_entries or a previous log result. It also provides a clear exclusion—cannot edit entries already on a sent invoice—along with what happens in that case.

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

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

Annotations already indicate a write, non-idempotent operation; the description adds the concrete business rule that the free plan allows only one client and the error contains upgrade_url. This failure-mode detail is useful, though the description does not discuss other side effects or post-conditions.

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

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

Three sentences, each with unique information: when to trigger, a caution against speculative use, and the free-plan limit/error behavior. No fluff; the actionable trigger is placed first.

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

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

For a moderate-complexity creation tool with no output schema, the description covers when/user intent, explicit non-usage, and the key plan-boundary error. It does not explain success response or required permissions, but these are not required for an agent to invoke it correctly.

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

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

Schema description coverage is only 40%, and the description compensates by tying 'rate' and 'billing email' to create triggers. However, it does not add meaning to two other non-schema-covered fields (name is implied, address is unmentioned) and does not fully compensate for the low coverage.

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

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

The description specifies the action (create), the resource (client), and the exact confirmation conditions. It clearly distinguishes from the sibling workspace.create_project by focusing on client creation and non-existent-client confirmation.

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 explicitly says when to use (user names a non-existent client and confirms, or asks to add with rate/billing email) and when not to use (do not create speculatively while logging time). It does not name alternative sibling tools, but the client-creation context leaves no direct alternative, so the guidance is strong.

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 indicate this is a non-read-only, non-idempotent, non-destructive operation. The description adds the policy that projects should not be created speculatively and explains that aliases support future fuzzy matching. It does not disclose return values or post-creation effects, but the annotations cover the core safety profile and no contradiction exists.

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 focused sentences, with the most important usage condition front-loaded. Every sentence adds value: trigger condition, alias purpose, and the 'do not create speculatively' guardrail. No filler or repetition.

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

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

For a straightforward creation tool with five parameters and no output schema, the description provides enough context for correct invocation: when to call it, required confirmation, and alias behavior. Parameter details are left to the schema, which is acceptable here. A minor gap is that no return value is described, but the low complexity keeps this from being a significant issue.

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 description adds meaningful context for aliases, explaining their role in future fuzzy matching, and ties the rate parameter to user intent. The schema already documents rate, client, and billable_default reasonably well. With 60% schema coverage, the description compensates for the most non-obvious parameters.

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

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

The description clearly identifies the action ('create a project') and the specific resource involved, while also stating the exact triggering conditions: the user names a project that does not exist and confirms creation. This differentiates it from related workspace tools like create_client and list_projects.

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

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

The description gives strong guidance on when to use the tool: only after user confirmation and for projects that do not yet exist. It also warns against speculative creation. However, it does not explicitly name alternative tools for existing projects or client creation, so the when-not-to-use guidance is present but not fully tied to sibling 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 cover readOnlyHint, idempotentHint, and destructiveHint, so the description is not burdened with those. It adds useful behavioral context: the call is cheap, and it returns clients with projects, aliases, and effective rates. It also notes a preference for a resource alternative. This goes beyond the annotations without contradicting them.

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

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

The description is two sentences plus a brief note. It front-loads the primary purpose and usage guidance, then adds a cost hint and resource alternative. No wasted words; 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 simple read-only list tool with one optional parameter, the description covers purpose, usage, and return contents. However, the include_archived parameter is completely undocumented, which is a significant omission given the 0% schema coverage. Also, the response structure is only vaguely described, though without an output schema that is somewhat expected. Overall, moderately complete but with a notable gap.

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

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

Schema description coverage is 0%, so the description carries the full burden for the include_archived parameter. The description never mentions this parameter or its effect on the result set. An agent cannot infer from the description whether archived items are excluded by default or what include_archived=true means. This is a clear gap.

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

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

The description clearly states the verb 'list' and the resources 'clients, projects, and rates'. It explicitly names the use cases (resolving ambiguous project names, checking rates) and differentiates from sibling creation tools like workspace.create_client and workspace.create_project. The purpose is unmistakable.

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

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

The description gives explicit 'when to use' conditions (user asks about projects/clients/rates, resolving ambiguity before logging time) and even recommends a cheaper alternative (reading workspace://context) when supported. It implies when not to use it by contrast with the creation siblings, providing clear routing guidance.

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