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

The description claims 'Reads stored data only,' which indicates a read-only operation, but the annotations set readOnlyHint to false. This is a direct contradiction between the description and the structured annotation, so behavioral transparency fails.

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 with no wasted words. It front-loads the core question and thresholds, then adds the prerequisite and data-source clarification.

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 tool with no output schema, the description thoroughly covers purpose, thresholds, change percentage, and the watch_refresh prerequisite. An agent has enough information 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?

This tool has zero parameters and 100% schema description coverage, so there are no parameter semantics for the description to add. The zero-parameter baseline applies.

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

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

The description states a specific action and resource: 'Answer whether anything you watch got cheaper' and defines the exact alert criteria (at/below target_price or down 5% since previous observation, with change %). This clearly distinguishes it from siblings like watch_list or watch_refresh.

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 provides the prerequisite 'run watch_refresh first' and clarifies that it reads stored data, giving clear when-to-call context. It does not explicitly name alternatives to avoid, but the usage context is sufficient.

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

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

With no meaningful annotations (all hints false), the description carries the transparency burden and does a good job: it discloses inclusivity, the presence of weekend/holiday counts, and the critical 'no holiday calendar' behavior. It does not describe the exact return structure, but the output components are named.

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 main purpose is front-loaded, and the crucial no-holiday-calendar caveat is placed immediately after, making the most important limitation easy to notice.

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 calculation tool with full schema parameter descriptions, the description is largely complete: it states purpose, inclusivity, result components, and the holiday limitation. It does not spell out the exact return format or behavior for edge cases like from > to, but those are not essential 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%, so the schema already documents all four parameters. The description adds context like 'inclusive' and the weekend/holiday-count behavior, but it mostly reinforces the schema rather than adding new parameter-level meaning.

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

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

The description names a specific action (count), a specific resource (business days between two dates), and the scope (in a place, inclusive). It also states what the result includes (calendar total, weekend count, holiday count), which clearly distinguishes it from sibling time/calendar tools like convert_time or dst_changes.

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 clear context for when the tool is appropriate and explicitly warns that the result is not holiday-adjusted unless holidays are passed. It does not name sibling alternatives or give an explicit 'use X instead' rule, but the limitation is stated strongly enough to prevent misuse.

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. The description adds meaningful behavioral context beyond those: the cache can become unparsable and 'quarantined and named', and the tool reports refresh timing. This enriches the agent's understanding of cache health without contradicting 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 three sentences with no wasted words. It front-loads the primary purpose, then adds the when-to-use hint and the quarantine caveat. 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 zero-parameter, read-only status tool, the description is complete: it states what is reported, when to check it, and a key failure behavior. No output schema exists, but the description does not need to enumerate return fields for an agent 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?

The tool has zero parameters and the schema is empty, so there are no parameter semantics to clarify. Per baseline for zero-parameter tools, a score of 4 is appropriate; the description correctly focuses on the tool's no-input status behavior.

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 uses a specific verb ('Report') and resource ('ECB rate cache'), and details exactly what is reported: held dates, age, and refresh timing. It clearly distinguishes this cache-status tool from sibling rate-conversion and rate-query tools like rates_latest and rate_history.

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 context for when to use the tool: 'Check it before trusting a rate after time offline.' It also explains the quarantine behavior. It does not explicitly state when not to use it or name alternatives, but the usage trigger is clear enough for an agent to decide.

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, covering the safety profile. The description adds valuable behavioral context beyond annotations: it names stored .ics files with no calendar row and describes the fallback behavior of printing export steps when there are none. This is genuinely useful edge-case disclosure that the annotations do not 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 two sentences, front-loaded with the core purpose and fields. The first sentence immediately states the action and result set; the second sentence adds two edge-case behaviors. There is no filler, redundancy, or irrelevant detail. 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?

For a simple listing tool with no parameters and no output schema, the description covers what is returned (fields and edge cases) and even the no-result fallback. It does not specify the exact output formatting, but that is minor given the tool's low complexity. An agent can predict behavior and interpret results without ambiguity.

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 has zero parameters, so the schema provides no parameter documentation. Per the rubric, a 0-parameter tool gets a baseline of 4. The description does not need to add parameter meaning, and it does not attempt to invent any. The description's focus on output is appropriate given the lack of 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 starts with 'List imported calendars' — a clear verb-resource pair — and enumerates the exact fields returned (name, event-definition count, size, source, import time, free-tier use of 2 slots). It also distinguishes itself from siblings by noting it handles .ics files without calendar rows and prints export steps when empty, which is specific and non-overlapping with import/export 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 clearly states what the tool does, but it does not explicitly say when to use it versus alternatives like ics_import or ics_forget. The context makes it self-evident (you call it to view your calendars), yet there is no explicit 'use this when...' or 'instead of...' guidance. It relies on the tool's purpose being obvious.

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

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

The annotations only provide generic hints (readOnlyHint: false, etc.), so the description carries the responsibility for behavioral disclosure. It clearly indicates a write operation ('Save') and adds valuable detail about the response, including the stored id, detected variables, and updated clause count. It does not discuss duplicate handling or quota failures, but the free-tier note appears 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?

The description is a single dense sentence with no wasted words. It front-loads the action and resource, then efficiently covers return value details that would otherwise be missing without an output 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 seven parameters and no output schema, the description plus the detailed input schema provide enough context to call the tool correctly. The description usefully fills the output gap by naming the returned fields. A small omission is the lack of guidance about alternative tools, but that does not block 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 86%, and the schema already provides rich parameter explanations, such as {{variable}} placeholders, known category names, and auto-detection of variables. The tool-level description adds little parameter-specific meaning, but it does not need to because the schema carries the detail.

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 action verb ('Save') and identifies the exact resource: a reusable contract or proposal clause stored in a library. It clearly distinguishes this from sibling tools like clause_update and clause_delete, and from contract_assemble, by focusing on adding to the library.

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 the tool is for adding a new reusable clause, which is clear enough context. However, it does not explicitly state when to prefer it over alternatives such as clause_update for modifying an existing clause, nor does it mention any exclusions or prerequisites.

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

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

The annotations already declare destructiveHint=true, so the destructive nature is known. The description adds valuable context beyond that: it discloses that deletion is irreversible, that starter clauses are not re-seeded, and that the tool reports the remaining count. These specifics help the agent set expectations for the call outcome.

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 with no redundancy. The primary action and input method are front-loaded, followed by the two critical warnings and the alternative tool. 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 single-parameter destructive tool, the description fully covers what an agent needs: the input, the return behavior (reports count left), the irreversible nature, the non-reseeding caveat, and the alternative tool. With no output schema, the description adequately handles the response expectation.

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 schema description for the 'id' parameter already states 'Clause id or exact title' with 100% coverage. The tool description merely repeats this phrase without adding new constraints, formats, or examples. Since the schema fully documents the parameter, a 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 action ('Delete one clause'), the resource ('clause'), and the input method ('by id or exact title'). It also differentiates from the sibling clause_update by explicitly naming it as the alternative for editing, so an agent can immediately tell this tool apart.

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 guidance: 'Use clause_update to change one you want to keep' – this is an explicit when-not and alternative. It also warns about the irreversibility ('There is no undo') and the non-reseeding of starter clauses, which informs when to use the tool cautiously.

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 states the tool will 'write the whole library to one file,' which is a side-effecting operation, while the annotation declares readOnlyHint=true. This directly contradicts the annotations, so the behavioral transparency score is the minimum per the rubric.

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 adding useful information: what the tool does, the ordering/round-trip behavior, and the format restriction. The core action is front-loaded and there is no filler.

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

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

With no output schema, the description usefully discloses the return tuple (path, format, count) and the re-import behavior. It is mostly complete for a simple export tool, but the contradictory readOnlyHint creates ambiguity about side effects.

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 documents all three parameters with 100% coverage, so the baseline applies. The description repeats the markdown/json pricing distinction already present in the schema and adds no meaningful parameter semantics beyond it.

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 phrase, 'write the whole library to one file and return the path, format and count,' which clearly identifies the operation. It also distinguishes itself from the sibling clause_import by noting the export re-imports the same way.

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 opens with 'Call this tool to write the whole library to one file,' which gives clear guidance on the intended use. It does not explicitly list exclusions or alternative tools, but the purpose is well-scoped enough that an agent can infer when it applies.

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 mark the tool as read-only, idempotent, and non-destructive. The description adds behavioral nuance beyond those annotations: the revision count 'stays 0 on free', and an ambiguous partial title match 'is refused with the candidates'. These are useful, non-obvious behaviors that help an agent predict outcomes. No contradiction with annotations 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?

Two sentences, no filler. The core action and lookup keys are front-loaded, and the second sentence covers the important edge case without over-explaining. 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?

For a simple read tool with two optional parameters, the description covers the return contents and the main edge case. The absence of an output schema is mitigated by listing the returned fields. The only minor gap is that neither parameter is formally required by the schema, so an agent might wonder what happens if both are omitted, but 'by id or title' strongly implies one is needed.

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

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

Schema coverage is 100%, so the schema already documents id and title individually. The description adds value by clarifying the relationship between the two parameters: they are alternative lookup keys ('by id or title'), and one can be partial while the other is exact. It also explains the consequence of an ambiguous title match, which the schema does not convey.

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

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

The description opens with a specific verb and resource: 'Return one clause in full by id or title.' It also enumerates what 'full' includes (body, category, tags, jurisdiction, variables, revision count), and the word 'one' distinguishes it from listing/searching tools. This is unambiguous and clearly separates clause_get from clause_list and clause_search.

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 makes the selection context clear: use this tool when you need a single complete clause and have an id or title. The partial-title refusal behavior also tells the agent how the tool behaves in ambiguous cases. It does not explicitly name alternatives like clause_list or clause_search, but the 'one clause in full' framing makes the intended usage evident.

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 provide broad hints (non-read-only, non-idempotent, non-destructive). The description adds genuine behavioral detail: duplicate titles are skipped unless overwrite is set, and the tool reports added/replaced/skipped/capped counts. This aligns with the annotations and goes beyond 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?

Three short sentences, with the core action and results front-loaded. Every sentence adds information, though 'Free: 10 of your own' is telegraphic and could confuse an agent without more context. Still, the description is economical and well-ordered.

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

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

For a two-parameter import tool, the description plus schema cover file formats, overwrite behavior, plan limits, and reported counts, which is enough for correct invocation. It lacks explicit error semantics and a full return shape, but the listed counts partially compensate for the missing output schema.

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

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

Schema description coverage is 100%, so the schema already fully documents both path and overwrite. The description's 'duplicate title is skipped unless overwrite' and 'json is Pro' largely restate what the schema says, adding little new parameter-level meaning.

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

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

The description opens with a specific action ('load clauses from a .md or .json file') and names the observable outcome (added/replaced/skipped/capped counts). It is clearly distinct from siblings like clause_add or clause_export, but it never names those alternatives, so differentiation is implicit rather than explicit.

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 first sentence explicitly tells the agent when to call it: to import clauses from a file. It also adds plan-level context (JSON is Pro, markdown works in free tier, 10-clause cap). However, it does not name alternative tools or state when not to use them.

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 safety profile is covered. The description adds useful behavioral detail beyond annotations: the output field set, the sort order by category then title, and the relationship to contract_assemble. It does not mention pagination or exact-match semantics, but those are not critical for this simple read operation.

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

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

The description is a single dense sentence that front-loads the action and result fields, then provides ordering and routing guidance. Every phrase earns its place: output shape, sort order, category narrowing, and the clause_search alternative.

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?

This is a simple, one-parameter read-only list tool. The description covers the returned data shape, the optional category filter, the ordering semantics, and the sibling tool to use for word searches. There is no output schema, but the description itself supplies enough return-shape information for an agent to use 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 carries the burden for explaining the category parameter. 'Narrow with category' adds meaningful filter semantics beyond the bare string type in the schema, though it does not specify exact-match behavior or provide allowed values. Still, for a single optional parameter, this is sufficient guidance.

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 verb 'List' and the resource 'the library', and explicitly enumerates the returned fields: id, title, category, tags, and variables. It also distinguishes itself from clause_search by noting that clause_search is for words, so an agent can tell the two apart 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 clear usage direction: narrow with the category parameter, and use clause_search when searching by words. It also explains that the list ordering is the same order contract_assemble uses, which gives helpful context for when an agent should call this tool.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds meaningful behavioral context beyond those annotations: title/tag matches outrank body matches, jurisdiction filtering is free, and tag filters are skipped on free plans rather than causing an error.

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 carry all the essential information: what is searched, how results are ranked, and which filters are free or Pro. There is no filler or repetition of schema details.

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

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

For a read-only search tool, the description covers the searchable fields, ranking, and filter behavior. No output schema exists, so return-value details are not specified, but the essential call semantics are clear. The only notable gap is the meaning of the category 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 documentation covers query, tags, and jurisdiction, while category has no schema description. The description enriches query semantics through ranking behavior and explains the practical effect of tag and jurisdiction filters. Category remains underspecified, but the overall parameter guidance is strong.

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

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

The description names a specific verb and resource: ranked search across clause titles, tags, categories, and bodies. It also distinguishes the tool by explaining ranking behavior, so an agent can tell it apart from clause_list or clause_get.

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

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

The description clearly implies a search use case, but it does not explicitly state when to choose this over clause_list or clause_get. It gives useful context about filters and Pro behavior, but no direct comparison with 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?

The description adds meaningful behavior beyond the annotations by disclosing versioning behavior: Pro retains the previous text as a version, while the free tier applies changes without history. This is useful context that annotations do not convey.

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

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

Two tightly written sentences: the first states the core operation and target fields, the second adds behavior context. 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 the main action and versioning behavior, but for an 8-parameter mutation tool without an output schema, it leaves out important guidance such as expected response, error behavior, or confirmation of success. Some parameters are also 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?

With only 13% schema description coverage, the description helps by naming several updatable fields (text, category, tags, variables, jurisdiction). However, it omits title and language parameters, so it does not fully compensate for the sparse 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 ('Change') and identifies the exact resource ('a clause') along with the editable fields. This clearly differentiates it from sibling tools like clause_add, clause_delete, and clause_get.

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 the tool is for modifying existing clauses, which is clear enough to distinguish it from clause_add or clause_delete. However, it does not explicitly state when to use this tool over alternatives or mention any preconditions 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?

The description discloses substantial behavior beyond the sparse annotations: re-adding the same name updates stored address, email, and VAT id, while an identical record is refused with the existing record's id. This gives the agent a precise mental model of the upsert and duplicate-handling 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 tightly written sentences with the primary purpose first and the behavioral edge cases second. Every clause contributes new information, with no filler or repetition 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?

The definition covers purpose, usage, update semantics, and duplicate-conflict response, which is substantial for a tool with no output schema and sparse annotations. The agent has enough information to invoke it correctly and anticipate key edge cases.

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

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

With only 25% schema description coverage, the description compensates by explaining that name is the identity key and address/email/vat_id are the updateable fields. It does not provide format or validation details, but it adds meaningful semantic context beyond the raw 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 opens with 'Store a client', a specific verb and resource, and immediately adds the purpose: so invoice_create can refer to them by name. This clearly distinguishes client_add from read-only siblings like client_list or invoice 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 clear context by tying the tool to invoice creation and explaining that re-adding the same name updates an existing client. It does not explicitly name alternatives or state when not to use it, so it falls short of full exclusion 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?

The destructive hint annotation already flags mutation, but the description adds valuable behavioral detail: deletion is conditional on absence of references, and refused deletions list the offending documents. This goes beyond the annotation and helps an agent predict failure modes.

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 carry the full meaning: the first states the operation and precondition, the second states the failure behavior. There is no redundant phrasing or filler.

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

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

For a single-parameter destructive tool with annotations and full schema coverage, the description is complete: it defines the valid target, the constraint, and the refusal response. No output schema is needed to make correct use unambiguous.

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 client parameter already specifies 'Client name or id, exactly as client_list shows it'. The description adds no parameter-specific information, 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 opens with a specific verb and resource: 'Delete one stored client', and adds a distinguishing scope condition ('that nothing refers to'). This separates it clearly from sibling tools like client_add and client_list, and the reference-refusal behavior adds further specificity.

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

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

It states the condition under which the tool is appropriate: only clients with no references can be deleted, and it explicitly describes the refusal case when the client appears on any listed document. It does not name alternative sibling tools explicitly, but the condition is clear enough to guide selection.

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 bar is lower. The description adds useful behavioral context beyond annotations: it states the empty-list behavior ('With none stored it says so') and notes that invoice_create can create a client, which helps interpret an empty result. No contradictions 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 short and front-loaded with the main purpose. The final note about invoice_create is slightly tangential but still adds context about empty results; overall it earns its place without excessive verbosity.

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 list tool without an output schema, the description is complete: it names the result fields, states the empty-case behavior, and confirms no side effects. Nothing an agent needs to invoke this correctly is missing.

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

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

The tool has zero parameters and the schema is an empty object with 100% coverage, so there is essentially no parameter semantics to add. The description explicitly confirms 'No arguments,' which is sufficient and aligns with 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 ('List') and resource ('every stored client') plus the exact fields returned (id, address, email, VAT id). It is immediately distinguishable from siblings such as client_add and client_delete, and even clarifies the no-argument nature of the call.

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 clear context for when to call this tool (need to see all stored clients) and explicitly notes it takes no arguments and writes nothing, signaling it is a safe read-only list operation. It does not explicitly enumerate when not to use it, but the purpose is self-evident among the 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 provide no behavioral hints, so the description carries that burden. It discloses the pairwise overlap behavior, collision minutes, whole-day event separation, calendar scope default, and a 31-day free bound. The phrase 'Free: 31 days' is a bit cryptic but still adds behavioral context. No contradiction 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?

Four short sentences, each carrying real information and no filler. The core definition is front-loaded, and the sibling distinction and edge-case handling are placed after the main purpose, which is an ideal 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?

For a tool with no output schema and no annotations, the description covers the main aspects an agent needs: what is returned conceptually, how whole-day events are handled, how calendar scoping works, and a usage boundary. The main gap is that the response format is not explicitly described and 'Free: 31 days' is ambiguous, but the description is still largely 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?

The schema already describes all three parameters at 100% coverage, so the baseline is 3. The description adds only mild clarification with 'unless you name one' for the calendar parameter. It does not meaningfully add to from/to beyond the cryptic '31 days' reference.

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: 'Find double bookings' and defines precisely what counts as one—'every PAIR of timed events that overlap, with the minutes they collide.' It also distinguishes from free_busy by noting that free_busy 'shows gaps,' so the tool's 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 useful context for when to use the tool: overlap detection across calendars, with an optional calendar scoping. It explicitly names free_busy as the alternative for gaps. It does not enumerate exclusions versus every sibling, but the mention of free_busy is a clear enough routing signal.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds meaningful behavioral details beyond that: weekends are treated as outside working hours, and it also prints the requesting user's own zone from the shared business profile.

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

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

Two dense, front-loaded sentences cover the purpose and key behavioral nuances without repetition or filler. Every clause adds information the 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?

With no parameters and safety fully covered by annotations, the description sufficiently explains the return content: contact zones, current local time, working hours, in-hours status, weekend policy, and the caller's zone. Nothing critical 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?

There are zero parameters and schema description coverage is complete at 100%, so the baseline is 4. The description correctly focuses on output semantics rather than parameter documentation, and no parameters need clarification.

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'), the resource ('saved contacts'), and the distinctive output: zone, local time, working hours, and in-hours status. This cleanly separates it from sibling tools like contacts_set and the generic time utilities.

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 makes clear the tool is for listing saved contacts enriched with scheduling-relevant information年代中期 local time and working hours. It does not explicitly name alternatives or exclusions, but the use case is strongly implied and distinguishes it from other 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?

All annotations are false, so the description carries the behavioral burden. It discloses persistent saving, return of resolved zone and local time, replacement of same-name contacts, and the free limit of 5. It does not cover error cases or permission needs, but the key behaviors are present and non-contradictory.

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: core action, return behavior, and replacement caution plus limit. No fluff, front-loaded with the primary purpose.

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 save tool with no output schema and no helpful annotations, the description covers the essentials: what it does, what it returns, replacement behavior, and the free limit. Minor gaps around error handling and exact response structure are not necessary 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%, with descriptions for all four parameters, so the baseline is 3. The description adds the notion of zone resolution and working hours, but it does not provide meaningful format or usage details beyond the schema. Marginal added value over the structured fields.

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

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

The description states a specific action and resource: 'Save one person's zone and working hours' with a clear purpose ('so later calls can name them'). It is immediately distinguishable from siblings like contacts_list (save vs. list) and the time-conversion 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?

No explicit when-to-use or when-not-to-use guidance is given, and no alternative tools are mentioned. The purpose clause implies a use case, but the agent must infer when this tool is appropriate versus siblings like contacts_list or convert_time.

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 (readOnlyHint=false, destructiveHint=false) indicate a non-destructive write operation, which the description aligns with. Beyond annotations, it adds valuable behavior: omitted variables stay as bracketed prompts ('never invented'), clause_ids order equals document order, and the free-tier cap of 8 clauses. These are genuinely useful disclosures not present in structured fields.

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

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

Four tight sentences with the core purpose front-loaded, followed by two behavioral constraints (variable non-invention, ordering) and the tier limit. No wasted words; each 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 moderately complex tool (8 params, nested objects, no output schema), the description covers purpose, format, variable behavior, ordering, and usage limits. Schema handles parameter details. Minor gap: no statement about what happens on success/failure, but given 100% schema coverage this is not a serious omission.

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 8 parameters are already documented in the schema. The description reinforces the values/ordering behavior (already in the schema) and adds only the free-tier limit — marginal new value beyond the schema baseline of 3.

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

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

The description states a specific verb ('build') and resource ('a contract from library clauses'), with output formats specified. It clearly distinguishes from sibling tools, which are all clause-level operations (clause_add, clause_delete, clause_get) or license management — none assemble documents.

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 tool to build a contract from library clauses' gives clear, direct invocation context. No sibling offers an assembly alternative, so explicit exclusion isn't needed; the guidance is unambiguous about when this tool applies.

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 return behavior ('Returns the reference, the fee and the file path'), the nature of the output ('template skeleton for a lawyer to review, not legal advice'), and a rate limit ('Free tier: 3 agreements per month'). These add substantial context beyond the spartan 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 sentences, each earning its place: the first states the operation, the second lists return values, and the third covers the legal-review caveat and quota. No filler or redundant repetition of schema details.

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 create operation with no output schema, the description adequately covers return values and the draft nature of the document. Yet given the large sibling set and 9 parameters, a short note on why contract_create should be chosen over proposal_create or doc_create would make it more complete.

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

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

Schema description coverage is 89%, so most parameters are already documented in the schema. The description does not add meaning to any specific parameter; it only mentions 'fee' as part of the return value. 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 uses a specific verb ('produce') and a clear resource ('freelance service agreement .docx'), making the tool's function immediately understandable. It does not explicitly name or contrast with sibling tools like proposal_create or doc_create, but the resource type is specific enough to be distinguished in most cases.

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 an explicit call-to-action: 'Call this tool to produce a freelance service agreement .docx.' It adds context about the template being for lawyer review and the free-tier limit, but it does not state when not to use it or mention alternatives.

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

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

Beyond the all-false annotations, the description discloses exact return behavior: converted amount, cross rate to six decimals, rounding applied, and the rate date used. It stops short of discussing side-effect/read-only status, but for a conversion tool this is a meaningful behavioral disclosure.

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 names the action and scope, the second lists the return details. Every clause contributes information.

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

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

With no output schema, the description's return-value enumeration is valuable and mostly complete. The rich parameter schema covers date fallback and rounding rules; the only gap is explicit routing versus convert_many for multi-currency batches.

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

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

Schema coverage is 100%, so the parameters are already fully documented in the input schema. The description adds no parameter-level meaning beyond what the schema provides, which lands at the baseline 3.

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

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

The description states a specific verb and resource: convert an amount between ECB-quoted currencies. It also distinguishes from the convert_many sibling by focusing on a single amount, and from rate-focused siblings by emphasizing conversion output rather than raw rates.

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 opening phrase 'Call this tool to convert an amount...' gives a clear when-to-use trigger. It does not explicitly name alternatives like convert_many or state when not to use it, but the context is unambiguous enough to avoid misrouting.

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

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

The description adds meaningful behavior beyond the annotations: same ECB rate date, rounding to each target's own minor units, and unknown targets being listed rather than causing failure. The annotations are all false and uninformative, so the description carries the burden well.

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 no filler: core behavior is front-loaded, usage guidance follows, and the edge-case behavior is stated last. 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?

Given no output schema and sparse annotations, the description covers rate-date consistency, rounding, error handling, and batch usage. It does not mention source-currency failure behavior or the response shape, but these are secondary for invoking 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 coverage is only 33% because only 'to' has a description. The description partially compensates by explaining the amount, the target currencies, and rounding behavior, but it leaves 'from' semantics and amount units implicit.

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 ('convert'), the resource ('one amount into many currencies'), and a distinctive constraint (same ECB rate date, per-target minor-unit rounding). It also distinguishes this tool from sibling convert by emphasizing multi-currency and batch use.

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

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

It gives concrete when-to-use guidance: for mixed-currency invoice lines, call once per line so all lines share one rate date. It does not explicitly name convert as the alternative, but the usage context is clear enough for an agent to route 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?

The annotations carry no positive hints (readOnlyHint is false), so the description carries the behavioral burden and it delivers: it explains that the input is wall-clock in from_zone unless it has an offset or trailing Z, that natural-language times work, and that output includes day-change markers and UTC instant. It does not detail gap/fold resolution, though the schema's parameter descriptions cover those cases.

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 short and front-loaded, with the core action in the first sentence and useful parsing detail in the second. The final example '3pm tomorrow works' slightly duplicates the schema's time examples, so it is not maximally tight, but it is not padding either.

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

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

For a no-output-schema tool with natural-language input and DST edge cases, the description gives the essential input semantics and a high-level return shape. It leaves exact output formatting implicit and relies on the schema for gap/fold behavior, which is an acceptable but not exhaustive treatment.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds value beyond the schema by clarifying the parsing rule for time ('wall-clock ... unless ... offset or trailing Z') and by specifying that all to_zones are included in the conversion. It adds no new detail for gap/fold, but those already have thorough enum descriptions 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 opens with the specific verb 'Convert' and a precise resource ('one time from from_zone into every zone in to_zones'), making the operation unambiguous. It also distinguishes this from date-time siblings like now, dst_changes, and overlap by stating exactly what it produces: zone conversions with day-change markers and the UTC instant.

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 provides clear context for when the tool applies: converting a point in time across zones. It does not name alternatives or explicitly state when not to use it, but the conversion-specific wording is enough to route an agent away from the sibling scheduling and business-day 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?

With no supporting annotations, the description carries the disclosure burden. It explains the generation source, the output format, the bracketed-prompt behavior, and the privacy rule that posting content is not restated as the user's. It does not cover failure modes or overwrite semantics, but those are partially documented in parameters.

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 deliver the core action, output behavior, privacy constraint, and quota. Every sentence adds distinct information with no filler, and the primary action 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?

For a tool with 8 parameters and no output schema, the description provides a solid summary of the artifact, source, return values, and an important constraint. It could be more complete by explaining what happens if no profile exists or by routing users to a sibling tool for resume generation, but the essentials are 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?

The schema already documents 5 of 8 parameters, so the description does not need to restate them. It adds useful context about 'bracketed prompts' and the no-restatement rule, but it does not explain company, role, or hiring_manager. Overall it neither strongly compensates for the missing schema coverage nor repeats schema details excessively.

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

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

The description names a specific verb and resource: 'write a one-page cover letter .docx' and clarifies the source ('from the stored profile') and the return value ('path, word count and bracketed prompts'). This clearly separates it from resume-focused siblings like resume_create and resume_read.

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

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

It states the clear trigger: 'Call this tool to write a one-page cover letter .docx.' This gives the agent a direct condition for use. It does not explicitly name alternatives or exclusions, but the purpose is specific enough to avoid obvious sibling confusion.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false. The description adds useful behavioral context beyond those: the result is the complete closed domain, contains rates and decimal places, and acts as an authoritative filter for other operations. This meaningfully complements 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 no filler. The first sentence states what the tool returns and the second immediately gives the operational implication. 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?

For a zero-parameter read-only list tool, the description is complete: it states the content, the scope, and the practical consequence for other tools. There is no output schema, but the description tells an agent enough about what to expect (currencies, rates, decimal places) to invoke and interpret the result 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?

The tool has zero parameters and the schema documents that fully, so there is nothing parameter-related to explain. The description correctly focuses on the returned content instead. The baseline of 4 applies because the schema already covers the complete parameter space.

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 exact resource (the ECB daily currency set), the content (rate against the euro and decimal places), and the scope (the whole domain). It also differentiates from sibling conversion/history tools by stating that any code not on this list cannot be used elsewhere.

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

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

The description clearly implies when to use this tool: to enumerate the complete set of valid currencies or validate whether a code is supported. It does not explicitly name sibling alternatives like convert or rate_history, but the domain-boundary statement ('a code not on this list cannot be converted, quoted or historised here') gives strong contextual 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 are mostly negative hints (not read-only, not idempotent, not destructive), so the description carries the burden of explaining behavior. It adds useful details: the file path, block count, layout used, and an availability claim ('Free and unlimited'). It does not contradict the annotations and describes the return behavior without an output schema.

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

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

The description is three short sentences, front-loaded with the action ('Call this tool to write...') and quickly covering return values and availability. Every sentence earns its place with 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?

Given a 7-parameter tool with a fully described schema and no output schema, the description provides the necessary return-value context. It is complete enough for an agent to invoke the tool correctly, though explicit routing among sibling document tools would make it stronger.

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 parameter descriptions already explain every input. The tool description adds little to param semantics beyond the phrase 'structured sections', which reflects the existing sections parameter. Therefore a 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 uses a specific verb and resource: 'write a real .docx file from structured sections.' This is precise enough to distinguish the tool from siblings like doc_from_markdown or doc_fill_template, even without naming them. It also identifies key return values, further clarifying the tool's role.

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

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

'Call this tool to write a real .docx file from structured sections' gives a direct and clear instruction on the intended use case. However, it does not explicitly state when not to use the tool or point to an alternative for markdown input, templates, or proposals.

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 readOnlyHint=false, destructiveHint=false and idempotentHint=false; the description adds real context on top: it writes a NEW file, reports filled/unfilled/ignored, and notes a free tier of up to 10 placeholders (implying a limit beyond that). No return format or pagination detail, but solid added value.

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

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

Three tight sentences, front-loaded with the primary action, then the discovery mode, then the pricing constraint. Zero filler.

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

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

No output schema exists, so the description's mention of reporting filled/unfilled/ignored carries the return-value burden, and it does so adequately. It's slightly incomplete on what happens to unmatched placeholders (left literal or removed) and the exact free/paid boundary.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description genuinely adds semantics: an empty/absent `values` object is a list-placeholders mode. That is behavior a caller cannot infer from the 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?

States a specific verb+resource: replace {{placeholders}} in a .docx and write a new file, with the extra reporting behavior described. It's clearly distinct from siblings like doc_create or doc_from_markdown, but it doesn't explicitly name an alternative to differentiate itself.

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 calling context, including the useful 'call it with no values to list them' discovery mode. It does not state when NOT to use it or name the sibling for related tasks (e.g. doc_create for a template-free document).

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?

It discloses meaningful behavior beyond the annotations: empty markdown is refused, overwriting without the flag is refused, and the response includes a file plus block-count breakdown. Since the annotations are sparse, these details carry real weight.

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 with no filler: purpose and return value first, supported features second, and constraints third. 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 tool with no output schema, the description covers the response shape, accepted input constraints, and error/overwrite behavior. Remaining details like output path defaults are already in the schema, so nothing critical 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 schema already covers markdown, title, out_path, and overwrite in detail, so the baseline is 3. The description adds a useful validation constraint—empty markdown is refused—and reinforces markdown features, but it does not clarify the style parameter, keeping it just above baseline.

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

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

The description clearly states the tool converts markdown into a .docx, names the return value (the file and block count), and is distinct from siblings like doc_to_html or doc_create. The verb+resource pairing is specific and actionable.

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 'Call this tool to turn markdown into a .docx,' giving an explicit use case. It does not explicitly name alternatives or say when not to use it, so it stops short of full routing guidance.

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

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

Annotations already declare the full safety profile (readOnly, idempotent, non-destructive, closed-world), so the description does not need to establish safety. It does add useful behavioral context beyond the annotations: the return shape (heading outline plus document-order text, or block structure) and the cost/throughput note 'Free and unlimited'. It still omits password/permission handling and behavior on malformed files, so a 3 is fair.

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 action front-loaded and no filler; 'Free and unlimited' is a compact, high-value trailing note. The lead-in phrase 'Call this tool to' is mild boilerplate but does not bloat the text.

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

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

There is no output schema, but the description adequately explains what is returned (heading outline, full text in document order, or block structure). Combined with a fully-covered input schema and complete annotations, an agent has enough to call this correctly, though explicit routing versus sibling readers is still missing.

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

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

Schema description coverage is 100%, so both parameters (path, format) are fully documented in the schema, including the .doc/.rtf exclusions and the enum semantics. The description adds no parameter detail beyond this, so the baseline of 3 applies.

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

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

States a specific verb (extract text) and resource (.docx), and the format-targeting language ('block structure', 'outline of the headings') makes it clearly a Word reader. It does not name or contrast itself against the many sibling read tools (resume_read, pdf_text, sheet_read), 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?

There is no when-to-use or when-not-to-use guidance and no named alternative, even though the toolset contains several other text-extraction tools (pdf_text, resume_read, sheet_read). The agent is left to infer that this is the .docx-specific reader from the description 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 mark this as a non-read-only, non-idempotent, non-destructive write, and the description adds genuinely useful context beyond them: it writes an .html file and returns that path, performs no PDF rendering itself, and is free/unlimited. It does not discuss failure modes for malformed .docx input, which is the remaining gap.

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

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

Four short sentences, front-loaded with the action and the return value, then the PDF routing note and the pricing signal. Nothing is redundant with the title or schema, and 'Free and unlimited' is a legitimate decision-relevant fact.

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

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

With no output schema, the description correctly carries the return contract ('Returns the path of the .html file'), which is the key thing an agent needs to chain a follow-up step. It is complete for the common path, though it is silent on what happens on conversion failure or unsupported input.

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 all three parameters (path, out_path, overwrite) already documented including the default-next-to-source and no-overwrite behavior. The description reinforces out_path's purpose via the print-to-PDF workflow but adds no syntax, format, or edge-case detail the schema lacks, so this sits at the baseline.

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

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

States a specific verb and transformation chain (.docx to semantic HTML, then print to PDF) rather than restating the title. It also implicitly separates itself from the many PDF siblings by saying 'no PDF is rendered here,' though it never names a concrete sibling (e.g. invoice_pdf, resume_to_html, doc_read) for contrast.

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 use: this is 'the supported PDF route,' so an agent wanting a PDF knows to come here and print. It does not spell out when NOT to use it or which tool to prefer for direct PDF generation, so the routing guidance is strong 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?

Annotations declare a non-read-only write, and the description adds real context beyond them: the write lands in a shared profile also used by the invoice server, so a change here has cross-tool side effects. That is exactly the kind of consequence an agent cannot infer from the schema. It stops short of saying whether unspecified fields are preserved or wiped on a partial write.

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, front-loaded with what is stored and immediately followed by the cross-server consequence. No filler, no restatement of the title.

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

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

For a 17-parameter mutation with no output schema, the description covers the two things hardest to infer: what the fields mean in aggregate and that the profile is shared with the invoice server. The remaining gap — merge-vs-replace behavior on a partial update — is meaningful but narrower than what is already covered.

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

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

Schema description coverage is 100% and each of the 17 properties is documented in-schema (including alias handling and the email/phone 'only if supplied' rule), so the baseline of 3 applies. The description only groups fields into categories and does not add format or precedence semantics beyond the schema.

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

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

Specific verb ('store') plus the exact resource (sender details on proposals, contracts, letters) and the config categories it covers (currency, VAT, terms, prefix). It also disambiguates against the sibling invoice_business_set by stating both write the SAME shared profile, so an agent knows they are aliases rather than distinct stores.

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 scope statement (use when setting sender/branding defaults), and the shared-profile note usefully answers whether invoice_business_set must also be called. However, there is no explicit when-to-use/when-not framing and no mention of prerequisites or how this relates to proposal_create/contract_create that consume the profile.

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 are all false, providing no safety or side-effect hints, so the description carries the burden. It implies a read-only lookup by describing output (clock changes, UTC instant, offsets), but it does not explicitly state that no changes are made or mention any other behavioral traits such as auth or rate limits. 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 only: the first states the output and scope, the second gives a concrete use case. No filler or redundancy, and the core 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?

For a simple 2-parameter tool with no output schema, the description adequately explains what is returned (UTC instant, offsets before/after) and the typical use. It doesn't specify whether multiple changes per year are returned together, but 'the clock changes' implies plural. Minor gap but not enough to hinder 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 covers both parameters (zone required, year optional) with descriptions. The description adds no extra parameter detail (e.g., zone format or year range). Per the coverage baseline, 3 is appropriate since the schema already carries the semantic weight.

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 resource (clock changes in a place for a year) and the output (UTC instant and offsets before/after). The use case ('check whether a recurring call moves') distinguishes it from sibling tools like convert_time and now, though it lacks an explicit verb like 'returns'.

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 'Use it to check whether a recurring call moves for one of you in March or October' provides a concrete, clear context for when to use the tool. It does not mention alternatives or when not to use it, but the guidance is specific enough for an agent to route 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 declare readOnlyHint=false and idempotentHint=false, so the agent already knows this is not a pure read and is not safely repeatable. The description adds useful context the annotations do not (evidence is 'free', candidates require review, no payment approval), but it never explains the write implied by readOnlyHint=false — namely that save=true persists results — leaving the key behavioral question unanswered.

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

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

Two sentences, front-loaded with the core action and no filler; 'All evidence is free' and the review caveat are terse and each carries information. The first sentence is dense but not padded, so only marginal tightening is possible.

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 and no parameter descriptions, the description should at least sketch the return shape and the effect of 'save'; it gestures at output ('candidates require review') but never describes what a candidate group contains or that save=true persists it. Adequate to call the tool, incomplete for predicting the result.

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 carry the load; it partially does by naming the grouping keys (entity, supplier, type, currency, reference, amount, date), which map onto the nested record fields. However, the 'save' parameter is never mentioned, and the description does not add format or constraint detail beyond what the schema itself encodes.

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 action (group supplied records) and enumerates the matching rules (exact/normalized reference, exact amount/date within exact entity, supplier, type and currency), which lets an agent distinguish it from the report_*/license_* siblings. It never quite says 'detect duplicates' in prose, but the title plus the explicit match keys make the purpose unmistakable.

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

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

Usage is implied rather than stated: 'Candidates require review; no payment approval' tells the agent the output is advisory and not an approval mechanism, which bounds how the result should be used. There is no explicit when-to-use/when-not or any named alternative, though the sibling set (reports, licensing) contains no plausible substitute for this tool.

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

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

Beyond the sparse annotations, the description discloses important behavior: it returns id/duration/amount and explains that rate is frozen at creation time so later rate changes won't affect it. It also clarifies that rate is in MAJOR units, which is non-obvious. It does not cover every possible edge behavior, but it substantially 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?

Three short sentences convey the core behavior, return value, duration input options, and an important rate nuance with no wasted words. The most important usage constraint ('already worked') appears first, making the description easy to scan.

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 has 10 parameters and no output schema, the description covers the essential calling contract: what is created, how duration is supplied, and what the caller gets back. Optional fields and defaults are already documented in the schema, so the description doesn't need to repeat them. It is slightly short on edge-case guidance (e.g., conflicts between end and minutes, or partial project matching), but the schema covers those.

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

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

Schema coverage is 100%, so a baseline of 3 applies. The description adds value by explaining that the rate is expressed in MAJOR units and frozen on the entry, and by clarifying that start plus either end or minutes are the ways to specify duration. This is meaningful semantic context beyond the schema field descriptions.

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

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

The description states a specific action — 'Log time already worked as one entry' — and names the resource (time entry) plus the return payload (id, duration, amount). The phrase 'already worked' differentiates it from timer-based siblings like timer_start and timer_stop, and from mutation siblings like entry_edit/entry_delete.

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

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

It clearly says this is for time already worked rather than active tracking, and explains the two input modes: 'start plus end or minutes'. It does not explicitly name alternatives or give exclusions, but the context ('already worked') is enough to guide an agent away from timer 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 mark the tool as destructive, but the description adds important behavioral details beyond that: it reports project and hours removed, never touches a running timer, and deletes billed entries along with their invoice record. These are meaningful side effects the agent would not otherwise know.

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 core action and result, the running-timer safety guarantee, and the billed-entry caveat with the correct alternative. It is tightly written and 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?

For a simple one-parameter deletion tool with no output schema and destructive annotations, the description covers the action, the return information, the key non-effects, and the irreversible consequence. Nothing important 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?

The schema already fully documents the single parameter 'id' with 'Entry id from entry_list', so 100% coverage is present. The description adds 'by id' but does not meaningfully expand on the parameter meaning 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 states a specific verb ('Delete'), a specific resource ('one logged entry by id'), and the observable effect ('report the project and hours removed'). It clearly distinguishes this tool from siblings like entry_edit and entry_add.

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 covers when to use the tool (deleting a logged entry) and when not to: it warns that billed entries lose their invoice record and directs the agent to use entry_edit instead. This is strong usage guidance with an explicit 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 reveals important non-obvious behavior well beyond the annotations: partial-field merge semantics, minutes moving end while keeping start, refusal of end at/before start, tags REPLACING the list, and rate units in major currency units. These are exactly the traps an agent needs to know.

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

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

The description is a single dense sentence that front-loads the core purpose and then packs the critical edge-case rules without wasted words. Every clause contributes meaning.

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

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

The description covers the most important update semantics, but with 11 parameters and no output schema, it leaves some ambiguities: behavior when both end and minutes are passed, clearing fields with empty values, and what happens when the id is not found. It is adequate but not fully complete for a tool this parameter-rich.

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

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

With 55% schema description coverage, the description compensates by adding meaning for minutes, end/start validation, tags replacement behavior, and rate units. It does not individually explain note, task, project, billable, or currency, but their types and names are reasonably self-explanatory and currency is partially covered 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 opens with 'Change one logged entry by id', which names the verb, resource, and scope precisely. This clearly distinguishes entry_edit from siblings like entry_add, entry_delete, and entry_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?

The description gives clear operating context: it edits one existing entry by id and only moves provided fields. It does not explicitly name alternatives or exclusion conditions, but the sibling set makes the intended use obvious.

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 safety is covered. The description adds meaningful behavioral context beyond the annotations: the exact output columns, sort order (newest first), the inclusion of total hours, and the plan-dependent data scope. This gives the agent useful expectations without being verbose.

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

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

Two sentences, zero filler. The main behavior and output format are front-loaded, and the plan limitation is stated efficiently in the second sentence. 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?

Given there is no output schema, the description fully enumerates the returned fields, ordering, and the total-hours summary. It also discloses the Free vs Pro scope, which is critical for setting correct expectations. Nothing an agent needs 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?

Schema description coverage is 100%, so all four parameters (to, from, limit, project) are documented in the schema. The description does not add parameter-specific semantics beyond the schema, which is acceptable given the full coverage. It mentions 'project' as an output column but not as a filter, so no extra value is provided.

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 ('List'), a resource ('logged entries'), and the exact output shape: a table of named columns, newest first, with total hours. This clearly distinguishes it from sibling tools like entry_add, entry_delete, and report.

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 clear context: this tool returns a table of entries and is appropriate when that tabular view is needed. It also notes the Free vs Pro data availability limitation. It does not explicitly name alternatives like export_csv or report, but the intended use is strongly implied.

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

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

Annotations already cover the safety profile (not read-only, not idempotent, not destructive). The description adds genuinely non-obvious behavior: the entry's start is backdated to now minus the minutes so it falls on today's day/week summaries. It omits what happens if the client name is ambiguous or fails to resolve.

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, front-loaded with the action and followed by the one non-obvious behavioral detail. No filler.

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

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

With no output schema and annotations covering the safety profile, the description covers the essential behavior for a small mutation tool. It could state the return value and client-resolution failure behavior, but nothing critical is missing.

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

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

Schema coverage is 100%, so the schema already documents all four parameters, including the partial-name resolution rule. The description only restates minutes and the optional note, adding no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

Specific verb+resource: logs work time for a client/project with minutes plus optional note. It is clear what the tool does, but it never distinguishes itself from the sibling entry_add, which an agent must choose between.

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 'in one step' implies a shortcut for logging completed work rather than running a timer, but no explicit when-to-use, when-not-to-use, or alternative (entry_add, timer_start) is named. 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?

The description discloses that the operation stamps entries with an invoice number, causing report and invoice_summary to stop offering them and preventing double billing. This adds meaningful side-effect context beyond the annotations, which only indicate the operation is not read-only and not destructive.

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

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

One front-loaded sentence that states the purpose, mechanism, and consequences without padding. Each clause contributes directly to the agent's understanding, and there is no redundant or vague wording.

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

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

The description provides the workflow rationale and effects, while the schema supplies all parameter details, including the idempotent skip-and-return behavior for already-billed entries. With no output schema and no safety annotations, this is adequate for correct invocation, though the description could more explicitly mention the two invocation modes (ids vs. project+from+to).

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 six parameters have descriptive text. The tool description itself adds no parameter-specific meaning beyond what the schema already provides, so the baseline score 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 uses a specific verb ('stamp') applied to a specific resource ('tracked hours') and explains the downstream effect on report and invoice_summary. This clearly distinguishes it from sibling entry-editing tools by tying it directly to the invoicing workflow.

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 opening phrase 'Close the loop after an invoice is issued' explicitly gives the trigger condition for using this tool. It does not name alternatives or exclusions, but the workflow context is clear enough that an agent can decide when to invoke it.

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

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

Annotations already declare the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's main added value is the UTC serialization detail, which is genuinely non-obvious and useful for consumers. However, for a tool that writes a file, it omits key behavioral facts: whether an existing out_path is overwritten, whether the directory is created, and where the file is written relative to the caller.

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

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

Three tight sentences, front-loaded with the action and immediately followed by the two selection modes and the timezone caveat. No filler or restatement of the title.

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

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

For a file-export tool with no output schema and full schema coverage, the description covers selection modes, output format, and timezone handling, which is most of what an agent needs. The remaining gap is file-overwrite/error behavior, which the annotations do not cover either.

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 five parameters including the from/to inclusivity, the calendar scoping with from/to, and the acceptable id sources. The description's 'pass either ids or a from/to window' adds the mutual-exclusion intent, but that is largely implied by the schema text, so baseline 3 is appropriate.

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

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

States a specific verb and resource: writing chosen events to a new .ics file, and clarifies the artifact is portable ('send or import elsewhere'). It is clear on its own, but does not distinguish itself from nearby siblings such as ics_create or the generic export_csv/report_export_csv, leaving the agent to infer which export path applies.

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 tells the agent the two ways to select data: pass ids (sourced from events_list) or a from/to window. That is actionable selection guidance. It stops short of when-not guidance, e.g. what to do when both are supplied or which mode to prefer for large ranges.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description discloses important behaviors: recurring events are expanded to occurrences, results are sorted by start, and timezone handling defaults to the profile's or machine's zone unless overridden. It also states that returned ids are compatible with event_export and event_to_time_entry. These details add meaningful context beyond the structured 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 concise and well-structured: three sentences each earn their place. The core function and scope are front-loaded, followed by timezone behavior and integration guidance. There is no redundant or vague wording.

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

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

The description covers the essential behavioral context and integration points, and annotations handle the safety profile. It does not describe the returned event fields or pagination, but for a read-only list tool with fully described parameters, it is largely sufficient. The lack of an output schema could be compensated by a note on the return structure, but it is not a critical omission.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds nuance to the 'zone' parameter by specifying the fallback order ('profile's, else this machine's'), which is not in the schema. It also implicitly explains how from/to define the window. This extra clarity justifies a slight increase over the baseline.

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

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

The description clearly states a specific verb and resource: it lists events between two dates, with recurrence expanded and sorted by start. It does not explicitly contrast with sibling events_search, but the phrase 'Every event' implies broad, unfiltered coverage, which helps distinguish it. Overall the purpose 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?

The description gives clear context for when to use the tool: when all events in a date range are needed. It also notes that each id works for event_export or event_to_time_entry, providing guidance on related follow-up tools. It does not explicitly name alternatives or exclusion cases, but the primary use case is evident.

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 no contradiction exists. The description adds meaningful behavior beyond the annotations, especially the plan-dependent default date range ('a year back and a year forward on Pro, and the free window either side of today') and the cross-calendar search scope.

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

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

Two sentences, front-loaded with the core behavior and free of filler. However, the phrase 'and the free window either side of today' is slightly imprecise—it doesn't specify the window size or clearly frame the free-versus-Pro distinction—so it saves words at a small cost to clarity.

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 no output schema, the description covers the essential invocation details: searchable fields, calendar scope, required query, and default date behavior. It stops short of describing result shape, ordering, or pagination, but an agent has enough to select and 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 coverage is 100%, so the baseline is 3, but the description adds real semantic value: it explains which fields query searches (title, description, location, attendees) and clarifies the runtime meaning of omitting from/to. This goes beyond the schema's bare 'Words to look for' and date descriptions.

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: 'Find events whose title, description, location or attendees contain a phrase.' It also states the scope ('Searches every imported calendar'), which clearly distinguishes it from list-style siblings like events_list. The purpose is immediately 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?

The description gives clear situational context: this is a full-phrase search across all imported calendars, and it explains the default time window when from/to are omitted. It does not explicitly name an alternative tool or exclusion, but an agent can infer when search semantics are appropriate versus a plain calendar list.

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 explicitly states 'Writes nothing', but the annotation declares readOnlyHint: false, meaning the tool is not read-only. This is a direct contradiction. The description also fails to disclose any other behavioral traits such as idempotency or side effects, though the annotation contradiction is the primary failure.

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

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

The description is two sentences, front-loading the core purpose and adding the key behavioral note about writing nothing. It is efficient and structured without unnecessary verbosity, though it could be slightly more compact.

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 lacks an output schema but indicates the output is 'the exact arguments for entry_add' and instructs to 'pass the JSON straight to entry_add', giving the agent a clear idea of the return format. However, it does not specify error handling, edge cases, or any constraints on event_id/project beyond the schema. The contradiction with annotations further reduces completeness.

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 provides full descriptions for all four parameters (100% coverage). The description does not add additional semantic detail beyond what the schema already specifies, such as formats or examples. The baseline of 3 applies because the schema carries the burden of documentation.

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 action ('Take one event and return the exact arguments'), the resource (an event), and the purpose (converting a meeting to a billable time entry). It distinguishes itself from the sibling listing/search tools by focusing on transformation rather than retrieval.

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 a clear use case: 'so a meeting that already happened becomes billable time without retyping it.' It implies when to use (when you have an event to bill) but does not explicitly exclude alternatives or state when not to use it. The context is sufficient for an agent to infer appropriate usage.

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 goes beyond the annotations by disclosing that a file is written and that the path is returned. It does not mention overwrite behavior or idempotency, but the tier-based clamping is covered in the parameter schema, so the gap 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?

Two sentences with zero filler: the purpose is front-loaded, the output format and row content are specified, and the return value is stated. Every phrase 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 export tool, the description covers the essential decision inputs: output format, row content, intended use, and return value. The parameter schema handles defaults and tier clamping. A mention of overwrite behavior would make it fully complete.

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

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

Schema description coverage is 100%, so the schema already thoroughly documents all four parameters. The description adds useful output context like row fields and the returned path, but it does not add new meaning to the parameters themselves.

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 ('export'), a clear resource ('the timesheet'), and a concrete output ('CSV file'), along with the intended audience ('bookkeeper') and the row content. It is clearly distinguishable from sibling list/report 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 explicitly opens with 'Call this tool to export the timesheet to a CSV file', which gives clear context for when to use it. It does not explicitly name alternatives or state when not to use it, so it stops short of a 5.

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

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

With all annotation hints false, the description carries the transparency burden. It discloses the returned shape and ranking behavior ('UTC instant with the local time for every participant and a fairness score, best first'), and the verbs 'Rank' and 'Returns' imply a read-only search, though it never explicitly states that no data is modified.

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

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

Two sentences, front-loaded with the core behavior and no filler. Every clause adds either the ranking rule or the return format.

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 plus the exceptionally detailed input schema covers behavior, defaults, free-tier limits, and argument semantics. Since no output schema exists, the description's mention of UTC, local times, and fairness score provides the essential return-shape information.

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

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

Schema description coverage is 100%, and the schema itself explains defaults, limits, and the fairness-score meaning, e.g., 'distance in hours from 13:00 local'. The description only mentions fairness at a high level and adds little 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 opens with a specific action ('Rank the times') and names the resource ('meeting slots') and constraint ('every participant is inside their own working hours'). It also states the return format (UTC instant, local times, fairness score), which distinguishes it from sibling tools like overlap or business_days.

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 explicit when-to-use or alternative routing, such as naming a sibling to prefer in another case. The intended context is only implied by the tool's name and the 'every participant' phrasing, so an agent must infer when this beats the 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 are all false and provide no safety or behavior coverage, so the description carries the burden. It discloses important behaviors: invoiced/skipped periods are excluded, paused schedules are listed apart, and plan-based month limits apply. It does not state what happens if a request exceeds the plan limit, but the disclosed behavior is substantial.

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, with the core meaning stated first and exclusions/plan limits after. Every clause adds useful information and there is no filler or repetition of 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 one-parameter tool with no output schema and uninformative annotations, the description is mostly complete: it covers the output dimension, scope, exclusions, paused-schedule handling, and plan limits. The main missing piece is explicit behavior when the requested months exceed the free/pro allowance (clamp vs. error), which would make it fully self-sufficient.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful parameter context beyond the schema by tying the 'months' ceiling to plan level ('Free: 3 months; Pro: up to 120'), which the schema does not express. This helps an agent choose a safe 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?

The description states a specific resource ('expected invoiced revenue') and precise scope: per calendar month, per currency, from active schedules. It also distinguishes the tool from siblings by noting exclusions and special handling of paused schedules, so an agent can tell it apart from schedule_* and invoice_* 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 useful context about what is included/excluded and plan-based limits ('Free: 3 months; Pro: up to 120'), but it does not explicitly say when to use this tool versus an alternative or when not to use it. Usage is mostly implied by the tool name and title.

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 useful semantics not present in the annotations: events marked free are ignored, whole-day events block the entire day, and a 31-day limit is indicated. These rules materially change the result and would be easy to miss. It does not mention side effects or auth needs, but the annotations do not establish a read-only profile, so the description carries more of the transparency burden than in a tool with readOnlyHint=true.

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: the core behavior appears first, followed by edge-case rules and the sibling pointer. The cryptic 'Free: 31 days' costs a little clarity; otherwise this would be excellent for size and 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?

There is no output schema, and the description only characterizes the result as 'merged busy blocks and free gaps' without specifying response structure or how zone/calendars influence the output. It does cover core event-filtering rules and the conflicts alternative, making it usable, but an agent would still have to assume return format details.

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

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

Schema description coverage is 100%, so every parameter including from, to, zone, work_start, work_end, and calendars is already explained by the schema. The description only adds 'working hours' and the cryptic 'Free: 31 days,' neither of which materially deepens parameter understanding. 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 identifies the tool's deliverable: 'Merged busy blocks and the free gaps inside your working hours over a day range.' It also distinguishes from the 'conflicts' sibling by pointing out the overlap-pair use case. It lacks an explicit action verb such as 'Get' or 'List,' 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?

'Use conflicts for overlapping pairs' is an explicit alternative and a clear when-not signal for overlap analysis. The rest of the description implies this tool is for aggregate availability over a day range, which is useful context. It does not spell out when to choose events_list/events_search instead, so the guidance is good but not complete.

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

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

With all annotations false, the description carries the disclosure burden. It does describe the return behavior (fx_rates object plus rate date), which is useful, but it does not mention whether rates are freshly fetched, whether external calls/failures are possible, or that the operation has no side effects. Acceptable 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 tight sentences with no filler. The trigger condition is front-loaded, and every phrase adds value: when to call, what not to do, and what to expect back.

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

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

For a two-parameter tool with fully documented schema, the description adds the missing context: the multi-currency invoicing scenario and the shape of the return value. With no output schema, a bit more detail on the exact fx_rates object structure could help, but the cross-reference to expense_to_invoice and the rate date 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%, including the direction semantics of currencies and the meaning of target. The description adds no parameter-level meaning 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 clearly states when the tool applies (rebill/invoice spanning multiple currencies) and what it produces (the fx_rates object expense_to_invoice takes, plus the rate date). It does not name sibling alternatives, so it stops short of fully explicit differentiation, but the purpose is specific and 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?

It gives an explicit trigger condition — 'when a rebill or an invoice spans more than one currency' — and an explicit alternative to avoid: asking the user for rates. It does not name sibling tools like convert or rates_latest, so exclusion guidance is contextual rather than 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?

Annotations cover the safety profile (readOnly=false, destructive=false, openWorld=false), so the description's job is to add context it does not already carry. It does: it discloses a rate limit ("Free: 3 files a month") and the return payload (path, start in UTC and in the caller's zone), plus the UTC-storage rationale. It omits whether writing to an existing out_path overwrites, which is the one remaining behavioral gap.

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

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

Three short sentences, front-loaded with the action and result, and the quota note is compact. Nothing is padded, though "Call this tool to" is a slightly wasteful opener.

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, and the description compensates by stating the return values, which many definitions would omit. It also flags the quota. For a 12-parameter, non-idempotent write tool it is close to complete; the missing piece is overwrite/conflict behavior on out_path.

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

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

Schema description coverage is 100%, so every parameter — including the tricky gap/fold DST cases and the attendee/email distinction — is already documented in the schema. The description only reinforces zone/UTC semantics and adds no new parameter syntax or constraints, so baseline 3 applies.

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

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

The description names a concrete verb+resource pair ("write a .ics for one meeting") and scopes it to a single meeting, which separates it from batch/import siblings like ics_import. It also states what comes back (the path plus start times), so the agent knows what the call produces. It stops short of naming any sibling it is the alternative to, so it lands at 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?

"Call this tool to write a .ics for one meeting" implies the usage context and the single-meeting boundary hints that bulk work belongs elsewhere, but no alternative (ics_import, event_export, schedule_create) is named and no when-not-to-use condition is given. 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 say destructiveHint=false, but the description says 'delete this server's local copy of its .ics', which is a destructive action. This is a direct contradiction. The description does add context about what is untouched (own calendar, source file), but the contradiction is severe and misleads an agent about the tool's side effects. Without the contradiction, the description adds useful transparency.

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, each carrying distinct information: the core action and side effect, then scope limitations and the sibling distinction. Front-loaded with the main verb and resource; no redundant filler.

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

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

For a single-parameter deletion tool with no output schema, the description covers the operation, side effects, exclusions, and a sibling alternative. It lacks explicit error/reversibility info, but the main gaps are acceptable; however, the contradiction with destructiveHint undermines overall completeness by sending conflicting signals about safety.

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 schema already fully documents the `name` parameter (100% coverage), including its source (calendars_list) and type. The description only repeats 'by name' and does not add constraints, formats, or behavioral details beyond the schema, so it does not exceed the baseline.

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

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

The description clearly states the action (remove/delete), the target resource (imported calendar by name), and the side effect (deletes server-side .ics copy, frees a slot). It also explicitly distinguishes from sibling tool ics_import, which replaces instead of removes, making purpose 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?

The description signals this tool is for removing/freeing imported calendars and notes that ics_import handles replacing in place, giving an implicit when-to-use versus an alternative. It does not explicitly enumerate scenarios when not to use it (e.g., for non-imported calendars), though 'imported' is mentioned, so it 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?

Annotations already declare the mutation profile (readOnly=false, destructive=false, idempotent=false, openWorld=false), but the description adds real value: 'Re-importing a name replaces it' discloses overwrite semantics, and 'Fetched once, only because you asked' describes the network behavior for url. It does not cover permissions/auth or what the result looks like, and the replace-vs-idempotentHint:false pairing is a mild unaddressed tension.

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 with no waste, front-loaded with purpose before the input options and the overwrite caveat. 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 4-parameter import tool with 100% schema coverage and full annotations, the description covers purpose, input methods, source compatibility, Pro gating, and overwrite behavior. No output schema exists, but an import's return value is not essential to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters (path, text, url, name). The description restates the three input methods and notes url is Pro, which largely duplicates the schema rather than adding new syntax or format detail. Baseline 3 applies when the schema does the heavy lifting.

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

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

The description states a specific verb and resource: read a calendar export and store it under a name. An agent can tell this is an .ics ingestion tool rather than a calendar-creation or listing tool, though no sibling (e.g., ics_create, calendars_list) is named to sharpen the boundary.

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

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

It gives clear context for use: three mutually exclusive input methods (path, text, url), the fact that Google/Apple/Outlook exports are supported, and the Pro-only constraint on url. It stops short of any when-not-to-use guidance or explicit alternative tools, so no exclusions are 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 declare this is a non-read-only, non-destructive, non-idempotent write, and the description adds the key cross-server behavior ('Saved to the shared profile every other server reads'). It does not state whether existing profile values are overwritten or merged on a repeat call, which matters given idempotentHint=false, but the shared-persistence detail is genuine context 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 compact sentences with the scope claim front-loaded, followed by the persistence behavior and the calling guidance. No sentence is redundant with the schema and nothing is padded.

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

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

For a 16-parameter, name-only-required write with no output schema and full schema coverage, the description conveys scope, shared-profile effect and call ordering. It stops short of clarifying overwrite/merge semantics or auth requirements, a minor gap given the annotations already establish the safety profile.

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 16 parameters in detail, including aliases (vat/tax_rate/vat_rate) and the email/phone caution. The description only names field categories rather than adding syntax or format 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 specific verb ('Set') plus resource ('business profile') and enumerates the exact fields it manages (name, address, VAT id, bank details, defaults). It explicitly claims the distinguishing scope 'The ONE business profile for the whole suite', which separates it from sibling set-style tools like profile_set, contacts_set and docx_business_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?

'Call it once, first.' gives clear ordering/timing guidance and implies it should not be repeatedly invoked. However, it never explicitly contrasts this tool with the nearby profile_set or docx_business_set tools, so an agent must infer which 'set' tool applies in which 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?

Beyond the annotations (readOnly=false, etc.), the description discloses meaningful behaviors: the invoice number is next and never-reused, unit prices are in major units, lines are rounded then summed, and only one currency is allowed per invoice. It also mentions the free-tier limit of 3 per month, which is useful operational context.

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

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

The description is only four sentences long and every sentence earns its place: the first defines the action and return value, the second clarifies unit and rounding semantics, the third states a key constraint, and the fourth gives the free-tier quota. Information is front-loaded and there is 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?

The input schema is fully self-describing, and the description adds the key behavioral facts an agent needs: the returned record includes a never-reused number, unit prices are major units, and rounding/currency rules. It doesn't mention sibling alternatives or idempotency, but for a write tool with a rich schema this is a minor gap.

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

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

The schema description coverage is 100%, so the baseline is 3, but the tool description adds global semantics not obvious from the schema: unit_price is in MAJOR units, lines are rounded individually before summing, and one currency per invoice is enforced. These invariants clarify how the parameters interact.

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 ('Create') and resource ('invoice') and defines the input as line items, making the core purpose unmistakable. It doesn't explicitly distinguish itself from the sibling 'invoice_from_hours', but 'from line items' implies that alternative path.

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 guidance on when to use this tool versus siblings such as invoice_from_hours or invoice_mark_paid. No when-to-use, when-not-to-use, or alternative tool is mentioned, so an agent must infer usage from the tool name and parameter names.

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 provide false hints, so the description carries the burden. It discloses the create side effect and adds useful behavioral details: rate conversion when fx_rates is supplied and echoing back entry_ids. However, it omits broader side effects, return shape specifics, or prerequisites beyond what the schema implies.

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 front-load the core purpose and then add the most important behavioral nuances. No filler or redundant restatement of the tool name 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?

Given 14 parameters, nested objects, no output schema, and sparse annotations, the description provides only a minimal working picture. It covers the common-case invocation and key conversion/echo behavior, but an agent lacks guidance on return format and the many optional parameters that affect invoice output.

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

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

Schema coverage is only 50%, and the description compensates partially by explaining the roles of target_currency, fx_rates, and entry_ids. It also implies the required client/hours/rate relationship. But many optional parameters (tax_rate, due_days, discount_percent, notes, etc.) receive no semantic guidance here or in the schema.

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

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

The description clearly states the tool's purpose with a specific verb ('Creates'), the resource (a single-line invoice), and the exact business scenario (billing one client for N hours at an hourly rate). It is more specific than the generic sibling invoice_create, though it does not explicitly name that sibling as the alternative.

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

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

'Shortcut for the common case' establishes a clear usage context: use this when a simple time-based invoice is needed. It does not state exclusions or explicitly compare against invoice_create, but the common-case framing is enough to guide an agent.

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

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

The annotations are all false hints and therefore carry no real behavioral signal. The description compensates fully: it discloses write side effects, PDF rendering, idempotency keyed by occurrence date, the 60-invoice run cap, and the created/skipped/still-due return categories.

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 main description is one dense sentence that front-loads the core effect, then states the output categories. Each parameter description earns its place with distinct operational facts; there is no filler or redundancy.

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

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

Even without an output schema, the definition tells the agent what side effects to expect, how to preview with dry_run, how many invoices can be created per run, how idempotency works, and what the response reports. That is sufficient to select and invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3, but the parameter text adds more than a bare schema: as_of includes the dedup key and idempotency, dry_run adds the 60-invoice cap and oldest-period-first ordering, and schedule_id notes free/unlimited scoping.

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 precise verb and resource: create real invoices for uninvoiced schedule occurrences on or before as_of and render PDFs. The return summary (created/skipped/still due) makes the scope concrete and separates it from read-only schedule tools like schedule_upcoming and forecast.

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

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

The trigger condition is explicit ('occurrences on or before as_of that have not been invoiced yet'), and dry_run plus schedule_id provide clear scoped/test usage. It does not name an alternative or state a when-not-to-use case, but no sibling tool performs invoice generation, so that omission 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context about the return content: every line, tax breakdown, and the open balance after credit notes. The parenthetical 'see credited_minor' is somewhat cryptic but does not contradict 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?

The description is a single, front-loaded sentence that communicates the core action and return contents efficiently. The parenthetical 'see credited_minor' is slightly ambiguous, but it does not significantly bloat the description.

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 is a simple single-parameter read operation, the description covers the most important contextual aspects: what is returned, the scope, and the credit-note balance nuance. There is no output schema, so describing the return contents is valuable. The description is sufficient for an agent to select and invoke the tool correctly in most cases, though it omits error behavior for missing invoices.

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 schema only provides a required 'number' parameter with zero description coverage. The description adds the key semantic that this is an invoice number, which is essential. However, it does not specify expected format, examples, or edge cases, and with 0% schema coverage a stronger parameter explanation would have been helpful.

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 ('Return'), a specific resource ('the full stored record for one invoice number'), and the exact scope (one invoice). It clearly distinguishes itself from invoice_list by focusing on a single full record and from invoice_pdf by returning the stored record rather than a generated document.

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: call this tool when you need the complete stored record for one invoice number. However, it does not explicitly specify when not to use it or name alternatives such as invoice_list for summaries or invoice_pdf for a document. The contrast with list-like siblings is only implicit.

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