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

With no annotations, the description carries the burden. It clearly states 'reads stored data only', disclosing read-only behavior, and the dependency on watch_refresh. It also describes the output logic (change %), though it doesn't mention edge cases like empty responses or exact return format. Still, it provides key behavioral context that an agent needs.

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

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

A single, tightly packed sentence that front-loads the core question, then specifies criteria and dependency. Every phrase adds value, with no redundancy 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 zero-parameter read-only tool with no output schema, the description fully explains what it does, how it selects data, and its dependency on watch_refresh. An agent can call it correctly without ambiguity; the only minor omission is specifying the exact return structure (e.g., list vs. boolean), but the criteria are so precise that this is unlikely to cause issues.

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 baseline is 4. The description doesn't add parameter-specific info (none exist), but that's expected. The empty schema is fully described, and the description adds meaning about the data transformation performed, which 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 clear purpose: 'Answer whether anything you watch got cheaper' and defines the exact criteria (at/below target_price or down 5%+). It distinguishes itself from siblings by explicitly referencing watch_refresh as a prerequisite, making its role as a query tool 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 provides an explicit instruction to run watch_refresh first, establishing when to use this tool (after refreshing data). It doesn't explicitly mention alternatives or when NOT to use it, but the prerequisite and 'reads stored data only' hint at its passive role, which is sufficient 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?

No annotations are provided, so the description carries the full burden. It clearly discloses that this tool has no national holiday calendar and only excludes weekends unless holidays are passed. Also notes in the schema that invalid dates are refused. This is good behavioral disclosure for a counting tool.

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

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

Two sentences: the first states the operation and outputs, the second states the key caveat. Efficient, front-loaded, no wasted words.

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

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

Given the complexity of a business-day calculator, the description covers the core behavior and its main limitation. It doesn't describe the exact return structure, but the mention of counts implies it. Lacks explicit details about worst-case behavior or timezone handling, but those are presumably in the schema. Overall 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 covers all parameters with descriptions (100% coverage), so the baseline is 3. The tool description adds nothing beyond what the schema already states about parameters; it mentions inclusivity but that's already in the schema. The holidays parameter has extra explanation in the schema, not the description.

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: counting business days between two dates. Mentions inclusivity and the components (calendar total, weekend, holiday counts). Distinguishes itself from date/time tools like convert_time and now by focusing on business-day arithmetic.

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?

Does not explicitly name alternatives or conditions for using this tool vs others. The disclaimer about having no holiday calendar is a limitation note rather than usage routing. Implies usage when business-day counts are needed, but no explicit exclusions or sibling tools are referenced.

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?

No annotations are provided, so the description carries the full burden. It states the tool is read-only, explains that it reports freshness and refresh timing, and discloses the quarantine behavior for a cache that no longer parses. It does not cover error cases or output format, but for a simple read-only report this is reasonable coverage.

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

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

Three sentences, with the primary purpose front-loaded in the first line. Every sentence earns its place: what is reported, read-only nature, the use case, and what happens when a cache fails to parse. No fluff.

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

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

For a parameter-less, no-output-schema status tool, the description covers everything an agent needs: resource, contents, read-only behavior, refresh insight, and operational guidance. Nothing required to call it is missing.

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

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

The input schema is empty, so there are no parameters to document. Per the calibration rules, a 0-parameter tool earns a baseline of 4. The description adds semantic value by indicating what the report contains, which is enough for this no-argument tool.

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 ('Report the ECB rate cache') and the resource, then lists precisely what it reports: which dates are held, their age, and when they refresh. The 'Reads only' line plus the cache-status focus differentiates it from sibling conversion tools like rates_latest or fx_rates_for, even though no sibling is named.

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?

Clearly tells the agent when to use the tool: 'Check it before trusting a rate after a time offline.' This gives local context that ties to an actual decision point. It does not explicitly name alternatives or give when-not-to-use conditions, but the practical guidance is strong enough.

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 annotations provided, the description carries the full burden. It discloses non-obvious behaviors: listing .ics files that lack a calendar row, and printing export steps when no calendars exist. However, it does not explicitly state that the operation is read-only or mention any side effects, permissions, or rate limits. The disclosure is partial but useful.

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 concise sentences. It leads with the core purpose, then efficiently lists the output fields and special cases. Every clause adds value, with no redundant or filler text. The structure is front-loaded and 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?

For a parameterless list tool with no output schema, the description adequately covers what the agent needs to know: the fields returned, the handling of orphaned .ics files, and the fallback when no calendars exist. It does not describe the exact output format (e.g., JSON vs. text) but that is a minor gap for such a simple tool.

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

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

The tool has zero parameters, so the schema provides no information to complement. Per rubric, a baseline of 4 is appropriate. The description does not need to explain parameters, and it doesn't—it focuses on the output. There is nothing missing regarding parameters.

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

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

The description clearly states the verb 'List' and the resource 'imported calendars', then enumerates the exact fields returned (name, event-definition count, size, source, import time, free-tier slot usage). It also mentions handling of .ics files without calendar rows and the export-steps fallback, making the purpose unambiguous and distinct from sibling tools like events_list or free_busy.

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 does not provide any explicit guidance on when to use this tool versus alternatives. It does not mention exclusions or conditions that would route an agent to another tool. The only contextual hint is the edge case 'With none it prints the export steps', but there is no direct comparison to siblings or when-not-to-use.

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?

There are no annotations, so the description carries the behavioral burden. It discloses the primary side effect ('Save'), and explicitly states what the operation returns: stored clause id, title, category, tags, detected variables, and the updated count of owned clauses. This gives the agent a concrete model of the operation's effect, though it does not cover duplicate handling, permissions, or 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?

The description is a single, front-loaded sentence that states the action first and then the return value. Every phrase contributes useful information, and there is no filler, repetition, or unnecessary background.

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 provides a helpful list of return fields and gives the agent a clear sense of the operation's outcome. The input schema covers parameter details thoroughly. It is not fully complete because it omits the output format and any caveats about limits or duplicate titles, but those are not critical for selecting and 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 description coverage is 86%, so the structured schema already documents most parameters well. The description adds only a small amount of parameter-related meaning by mentioning that variables are 'detected in its body,' which relates to the body placeholder behavior already covered in the schema. No further compensation is required.

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

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

The description uses a specific verb and resource: 'Save a reusable contract or proposal clause to the library.' This clearly indicates a creation/persistence operation and makes the tool understandable next to siblings like clause_update, clause_delete, and clause_get. However, it does not explicitly distinguish itself from clause_import or other similarly named 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 implies this tool is for adding a new clause to the library, which is clear context for creation. It does not explicitly state when to prefer this over clause_update, clause_import, or contract_assemble, nor does it mention any exclusions or 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?

With no annotations provided, the description carries the full burden. It discloses that deletion is irreversible, mentions the count report, and notes that starter clauses are not re-seeded. This covers key behavioral traits, though it doesn't detail permissions or error handling, which is a minor 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?

The description is three sentences, each adding value: the action, the irreversible consequence and result, and the alternative. Critical information is front-loaded with the purpose and side effects stated early. No wasted words.

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

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

For a single-parameter delete tool with full schema coverage and no output schema, the description provides necessary safety warnings and post-condition (count remaining). It doesn't specify return format, but given the simplicity, it's adequately complete. The only minor gap is lack of explicit error scenarios.

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 the 'id' parameter as 'Clause id or exact title'. The description repeats this information and adds that it reports how many are left, but it doesn't clarify the format or ambiguity resolution. Baseline 3 is appropriate given full schema coverage.

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

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

The description clearly states the tool deletes a clause by id or exact title and reports the count remaining. It distinguishes itself from siblings like clause_update by explicitly mentioning the alternative. The verb 'Delete' and resource 'clause' are 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?

The description explicitly says to use clause_update if the user wants to keep the clause, providing a clear alternative path. It also states when not to use this tool implicitly. This is direct usage guidance that helps an agent decide between delete and update.

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?

No annotations are provided, so the description carries the burden. It discloses the writing behavior, return values (path, format, count), and the contract-order preservation. The overwrite behavior is only in the schema param description, not in the tool description, but otherwise it is transparent about what happens.

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, all useful: the main action, the contract-order behavior, and the format pricing. It is brief, front-loaded, and contains no filler or redundant restating 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?

The description explains the purpose, the output fields, and the format implications. It does not explicitly state the overwrite safety net (already in schema) or edge cases like empty libraries, but the description is otherwise complete for a simple export tool with only 3 parameters and no 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 explains path, format, and overwrite. The description adds only the phrase 'markdown is free; json is Pro', which essentially mirrors the schema enum description. It does not add new semantic depth; it earns the 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 ('write'), a specific resource ('the whole library'), and the outcome ('return the path, format and count'). It clearly distinguishes from sibling tools by focusing on whole-library export rather than single-clause operations like clause_get or clause_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?

It gives clear context: call when you want to export the whole library to one file, preserves contract order for re-import, and explains format pricing. It does not explicitly name alternatives like clause_import, but the intent is obvious; it lacks only an explicit when-not/alternative statement.

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 annotations, the description carries the behavioral burden. It adds valuable nuances: the revision count stays 0 on the free tier, and ambiguous partial-title matches are refused and returned as candidates. It doesn't cover not-found or permission behavior, but for a simple read this is solid.

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

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

Two compact sentences with the core purpose front-loaded and zero filler. Every clause adds useful 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?

The description summarizes the return payload and important edge cases, which is helpful given the lack of an output schema. It omits what happens on no match and does not explicitly state that id or title is required, but these are minor gaps for a straightforward getter.

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 matching semantics beyond the schema, especially the refusal behavior for ambiguous partial titles. It also implies id and title are alternative selectors, though it doesn't explicitly require at least one.

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') and resource ('one clause in full by id or title'), and enumerates the returned fields. This clearly separates it from sibling tools like clause_list or 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 context is clear: use it to retrieve a single clause by id or title. However, it never explicitly names alternatives such as clause_search or clause_list, nor does it state when not to use this tool. The distinction 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?

No annotations are provided, so the description carries the full disclosure burden for this mutating import tool. It does disclose meaningful behavior: duplicate titles are skipped unless overwrite is set, a 'capped' count signals a limit, JSON requires Pro, and the free tier caps at 10. This is genuine added value, though it stops short of covering response format details, error cases, or rollback 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?

Three tight fragments with zero waste: the main action, the overwrite behavior, and the licensing constraint. The core purpose is front-loaded, and each clause earns its place without redundancy.

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

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

For a 2-parameter import tool with no annotations and no output schema, the description covers the essentials: supported formats, the reported counts (added/replaced/skipped/capped), and the free/pro cap. It reasonably compensates for the missing output schema by stating what results are returned, leaving only minor gaps around precise cap mechanics.

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

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

Schema description coverage is 100%, and the schema already documents both parameters in detail, including the markdown/JSON file formats and the overwrite semantics. The tool description adds no parameter information beyond what the schema provides, so the baseline 3 applies.

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

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

The description states a specific verb ('load'), a resource ('clauses'), and a source ('a .md or .json file'), and adds the outcome ('reporting added, replaced, skipped and capped counts'). This clearly separates it from siblings like clause_add (single inline clause) and clause_export (the inverse direction). An agent can distinguish it without opening the schema.

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

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

The description gives clear context on when to use the tool: loading clauses from files, and it documents the overwrite-vs-skip behavior that governs outcomes. It provides licensing guidance (json is Pro, free cap of 10) which helps an agent decide feasibility. However, it doesn't explicitly name alternatives such as clause_add for single-clause entry, so exclusions are only 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?

With no annotations, the description carries the behavioral burden. It discloses the return fields, the sort order, the optional category narrowing, and the relationship to contract_assemble's order. It does not mention pagination, limits, or access requirements, but for a simple list operation 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 a single front-loaded sentence that packs the key facts: output fields, sort order, filtering option, and the sibling to use instead. No redundant wording exists.

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 simple one-parameter schema and no output schema, the description is largely complete: it names return fields, ordering, the filter parameter, and the alternative search tool. Slight gaps remain around whether all clauses are returned by default and potential pagination, but these are minor for this tool's complexity.

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 provides only 'category' as a string with no description, and schema coverage is 0%. The description adds the essential meaning 'Narrow with category', which tells the agent it is an optional filter. However, it does not specify whether matching is exact, how categories are formatted, or where valid values come from, so it only partially compensates for the missing schema 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 states a specific verb and resource ('List the library as id, title, category, tags and variables'), defines the output fields, and explicitly distinguishes itself from clause_search by noting that search is for words. This fully separates it from siblings without requiring schema inspection.

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 context: it is for listing the library in contract order, can be narrowed by category, and should be abandoned in favor of clause_search when searching for words. It names the alternative explicitly and the condition that selects 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?

With no annotations, the description carries the burden and does meaningful work: it discloses ranking precedence, the Pro-only tag filter behavior, and the fallback of skipping rather than refusing. It does not cover output shape or authorization requirements, but the core non-obvious call behavior is surfaced.

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

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

Three tight sentences with no filler. The most decision-relevant information (ranked scope, ranking priority, and free/Pro behavior) is front-loaded and 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 simple search tool, this is largely complete: it identifies the searchable resource, the ranking behavior, and the filter constraints. The main remaining gap is that the category parameter has no schema description and is only indirectly covered by the phrase 'categories', but this does not prevent a competent agent from 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?

The schema already describes query, tags, and jurisdiction, so the description adds limited parameter-level meaning. It does clarify category's role by mentioning categories as a search target, and it reinforces the tag-skipping behavior, but it does not substantially go beyond the schema.

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

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

States a specific verb and object: 'ranked search over clause titles, tags, categories and bodies'. The ranking detail further distinguishes it from a plain list (clause_list) and from other clause 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 implies this is the right tool when ranked keyword search over clauses is needed, and it explains filter availability. However, it does not explicitly say when to prefer clause_list or other clause tools instead, so usage guidance is mostly implied rather than explicit.

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

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

With no annotations, the description carries the responsibility of disclosing behavior, and it does add important context: Pro keeps a version of the previous text while the free tier overwrites without history. This is a meaningful behavioral caveat beyond the schema. It does not cover return values or permission requirements, but the key side-effect is stated.

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 concise sentences with no wasted words: the first states the operation and its targets, the second adds the critical versioning caveat. The information is front-loaded and easy to parse.

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

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

The description includes the core purpose and a notable behavioral distinction, but it leaves gaps around the full set of mutable fields and the actual meaning of 'text' versus 'body'. With no output schema and no annotations, an agent may not know what response to expect or how to set fields like language or title. This is a moderate gap rather than a severe one.

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

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

Schema description coverage is only 13% (only 'id' is described), so the description must compensate. It lists several updatable fields but uses 'text' where the schema property is 'body' and omits 'title' and 'language', leaving the parameter mapping ambiguous and incomplete. This is insufficient for an agent to confidently construct a full update request.

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 resource ('clause'), and it names several mutable fields, which clearly conveys the update intent and distinguishes it from sibling tools like clause_add or clause_delete. However, it omits 'title' and 'language' from the field list, so its differentiation is slightly incomplete.

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 wording implies updating an existing clause rather than creating or deleting one, but there is no explicit statement of when to prefer this tool or avoid alternatives. With many sibling tools in the same domain, an agent has to infer the usage context from the action verb and field 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?

With no annotations, the description carries the full behavioral burden. It discloses the non-obvious upsert behavior, that re-adding the same name overwrites address, email, and VAT id, and that an identical record is refused with the existing id named. Auth and return-value details are absent, but the mutating and overwrite semantics are clearly surfaced.

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 front-loads the purpose, and the second gives exact update and refusal semantics. Every sentence contributes non-schema information.

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

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

For a four-parameter tool with no annotations and no output schema, the description covers the essential call semantics: purpose, identity key, upsert behavior, and duplicate handling. The main omission is the success return value, but that is not critical because downstream invoice_create refers to clients by name.

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

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

Only 25% of parameters are described in the schema, so the description compensates by establishing 'name' as the lookup key and identifying address, email, and vat_id as the fields updated on re-add. It does not provide formats or constraints for email/address, but the essential parameter semantics for calling the tool are present.

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 ('Store a client'), the resource, and the downstream purpose: enabling invoice_create to refer to the client by name. This clearly differentiates client_add from sibling tools like client_list and client_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?

The description gives clear context on when to use the tool: before creating an invoice that needs to reference a client by name. It does not explicitly state when not to use it or name alternative tools, so it falls just short of fully explicit routing.

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

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

With no annotations, the description carries the behavioral disclosure burden. It does disclose an important behavior: deletion is refused if documents reference the client, and it lists the document types. However, it does not explicitly state that deletion is permanent/irreversible or describe the success/failure response beyond refusal.

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 tight sentences with no filler. The primary action is front-loaded, followed immediately by the key constraint, making it easy for an agent to parse quickly.

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 delete operation with no output schema, the description covers the essential calling context: what can be deleted, what blocks deletion, and the document types that cause refusal. Minor gaps like success return value and explicit irreversibility do not prevent 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% and the parameter description already explains that 'client' is a name or id exactly as shown by client_list. The tool description adds no additional parameter semantics beyond the schema, so the baseline 3 applies.

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

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

The description states a specific verb and resource: 'Delete one stored client'. It also distinguishes the operation by its referential-integrity condition, making it clear this is the removal tool rather than client_add or client_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?

It gives clear context: use this tool only when the client has no references, and it tells the agent that referenced clients will be refused. It does not explicitly name alternative tools or say 'use client_list to find the exact id', but the usage boundary is clear enough.

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 annotations provided, the description carries the full burden. It discloses that the tool writes nothing (read-only), takes no arguments, and reports when no clients are stored. It also adds the useful side note that invoice_create can create a client from a name, which helps the agent understand the relationship. It doesn't mention pagination or ordering, but for a zero-argument list tool this is adequate.

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 action and output fields, the second clarifies no-args and no-writes, the third covers the empty case and a relevant alternative. No fluff, front-loaded with the core 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 zero-parameter, read-only list tool with no output schema, the description is nearly complete. It covers the return fields, the empty case, and the no-write guarantee. The only minor gap is not describing the output format (e.g., array vs. object) or ordering, but that's not critical for a simple list tool.

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

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

The schema has zero parameters and 100% coverage, so the baseline is 4. The description reinforces this by explicitly stating 'No arguments', which removes any ambiguity. It also adds meaning by describing what the output contains (id, address, email, VAT id), which is beyond the empty schema.

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

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

The description states a specific verb ('List') and resource ('every stored client'), and enumerates the exact fields returned (id, address, email, VAT id). It also distinguishes itself from sibling tools by noting it takes no arguments and writes nothing, which clearly separates it from client_add and client_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?

The description explicitly says 'No arguments' and 'writes nothing', which tells the agent when to use it (when you need a read-only list of all clients). It also mentions the empty-case behavior and points to invoice_create as an alternative for creating a client from a name, though it doesn't explicitly say 'use this instead when...' for 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?

With no annotations, the description carries the behavioral disclosure burden and does substantial work: it reveals pair-wise output, collision minutes, all-day event separation, calendar scoping, and a 31-day free limitation. It stops short of discussing timezone handling or exact output shape, but the core behavior is transparent.

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, placing the key semantics in the first clause and adding short, useful qualifications. The 'Free: 31 days' fragment is cryptic, but overall there is no wasted content.

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

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

For a read-only lookup with three well-schema-documented parameters, the description supplies the essential selection and behavior information, including the free_busy alternative. Without an output schema, it could specify the returned pair structure more concretely, but an agent can still select and invoke 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 from, to, and calendar are already documented with formats and defaults. The description adds little beyond restating the calendar scope ('unless you name one') and an ambiguous 'Free: 31 days' constraint, staying at the high-coverage 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 names the operation directly ('Find double bookings') and defines it precisely: every pair of timed events that overlap, with collision minutes, across all calendars unless one is named. This clearly distinguishes it from event listing and free_busy sibling tools.

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

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

It provides a clear use case and explicitly routes to free_busy for gaps ('free_busy shows gaps'), giving the agent a useful alternative. It does not enumerate when not to use other event/calendar tools, but the overlap-vs-gaps framing is enough for correct 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?

With no annotations, the description carries the behavioral burden. It discloses the weekend rule ('weekends count as outside') and that it prints the caller's zone, offering useful context beyond the function name. It does not mention any side effects, but as a list operation, none are expected. No contradictions.

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 concise sentences that front-load the core purpose and follow with the key distinguishing detail (zone printing). Every word adds value, with no redundancy 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 simple list tool with no parameters and no output schema, the description covers the essential functional behavior and edge case (weekends). It doesn't specify return format or pagination, but these are minor for such a basic operation. Overall, an agent has enough 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?

The tool has zero parameters and the schema coverage is 100% (empty properties). The description adds no parameter details because none exist, which is appropriate. Baseline for 0 params is 4; no additional explanation needed.

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

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

States a specific verb ('List') and resource ('saved contacts'), and enumerates the exact fields returned (zone, local time, working hours, inside/outside, weekends logic). It also adds a unique behavior (prints YOUR zone) that clearly distinguishes it from sibling tools like business_days or contacts_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?

The description clearly communicates what the tool returns, which implies when to use it (when you need contact time/zone information). It doesn't explicitly name alternatives or exclusions, but the clarity of its function is sufficient for an agent to select it over siblings. No misleading context.

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

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

With no annotations, the description carries the behavioral burden. It discloses the replacement/upsert behavior ('Saving the same name REPLACES'), the return payload (resolved zone and local time), and the 5-contact quota. These are genuinely useful non-obvious behaviors.

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, each earning its place: purpose, return behavior, and replacement/quota caveat. The most important information is front-loaded.

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

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

The input schema covers the parameters, and the description compensates for the missing output schema by stating what the call returns. Behavioral caveats like replacement and quota limits are also covered. Minor gaps like error handling do not undermine usability for a simple setter.

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?

All four parameters already have individual schema descriptions, so the baseline is 3. The description adds little beyond saying 'zone and working hours' and the fact that the name is the key for replacement, so it meets but does not exceed that 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 action ('save'), a specific resource ('one person's zone and working hours'), and the intended benefit ('so later calls can name them'). This clearly identifies the tool's job and distinguishes it from sibling tools like contacts_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?

Gives clear context for when to use it: when saving a contact's zone/working hours for later calls. It does not explicitly contrast with alternatives or name prerequisites, but the use case is clear enough to select this tool 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?

With no annotations, the description carries the full burden and does well: it discloses that omitted variables become bracketed prompts ('never invented'), that clause_ids order determines document order, that the free tier is capped at 8 clauses, and that the document includes a not-legal-advice line regardless of format (via the format param). It also notes that overwrite=false protects existing files. These are meaningful behavioral traits beyond schema, though it doesn't mention output details or error handling.

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

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

The description is brief (two sentences plus a short clause about free tier) and front-loads the main action. It avoids redundancy with the schema, though the list of free-tier limits could be organized more cleanly. It's structured well enough for an agent to parse quickly.

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

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

Given the tool's complexity (8 params, nested object) and no output schema, the description covers key call‑time concerns: variable handling, ordering, format, overwrite safety, and free-tier caps. It does not explain the return value or error conditions, but for a file-writing tool that may be acceptable. Overall, it provides sufficient context for an agent to make a correct call.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value on top: it explains the consequence of omitting values (bracketed prompts), clarifies 'clause_ids order' as document order, and specifies that categories are an alternative to ids. It also gives examples for values and default out_path behavior, which are not fully in the schema. This lifts it above 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 states a specific verb ('build') and resource ('contract from library clauses') with output formats ('.docx or markdown'). It clearly differentiates from sibling tools, which focus on clause management, licensing, and variables, leaving assembly as the unique purpose.

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?

While it does not explicitly list sibling alternatives, the description's 'Call this tool to build a contract' establishes the primary use case, and the free-tier clause limit provides a practical constraint. The mention of 'clause_ids order is document order' clarifies assembly behavior, implicitly distinguishing from clause_export. It lacks explicit 'when not to use' guidance, but the context is clear enough.

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 annotations provided, the description carries the behavioral disclosure burden. It discloses that the output is a template skeleton for lawyer review, explicitly states it is not legal advice, and mentions the free tier limit of 3 agreements per month. It does not detail file overwrite behavior, but the schema already covers that through the overwrite parameter.

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 concise sentences with a clear front-loaded action, followed by return value note, legal disclaimer, and usage limit. Every sentence contributes information without repetition 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?

The description covers the key non-schema information an agent needs: what is produced, what is returned, the legal nature of the output, and a usage restriction. Since there is no output schema, the minimal return-value disclosure is helpful, though it could be more explicit about error cases or quota enforcement 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 89%, so the input schema already documents most parameters in detail. The description adds little beyond mentioning that the fee and file path are returned, which does not directly clarify parameter semantics. It neither compensates for undocumented parameters nor adds meaningful input guidance beyond the schema.

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

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

The description states a specific action ('produce') and resource ('freelance service agreement .docx'), making the core purpose clear. It does not explicitly distinguish itself from related sibling tools like contract_assemble or proposal_create, but the type of document is specific enough to guide selection.

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

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

It gives a direct imperative ('Call this tool to produce...'), which clearly indicates the intended use case. However, it does not mention alternatives or when not to use it, and with siblings like contract_assemble nearby, the lack of routing guidance leaves some ambiguity.

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 annotations provided, the description carries the full burden, and it delivers: it discloses the converted amount, the cross rate to 6 decimals, the rounding applied, and the rate date used. The parameter descriptions further reveal important behaviors like default-to-currency, minor-unit rounding, weekend/holiday fallback, and the 90-day window fallback. This gives an agent a reliable picture of the tool's behavior, including edge 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 two tightly written sentences: the first front-loads the call action and scope, the second compactly enumerates the return contract. Every clause adds value, and the parameter descriptions are detailed without being bloated.

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 compensates by listing the returned fields: converted amount, cross rate to 6 decimals, rounding applied, and rate date used. Combined with complete parameter documentation and fallback behaviors, an agent has enough information to invoke the tool correctly and interpret 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?

The input schema has 100% coverage, with rich descriptions for all four parameters including defaults, rounding behavior, date fallback, and the euro cross-rate path. The main description adds high-level context but does not need to restate parameter details; the schema already 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 operation ('convert an amount') with a clear resource scope: any two ECB-quoted currencies, today or on a past date. It is easily distinguished from sibling tools like convert_time or currency-rate lookups because it focuses on a single conversion and its output contract. The title and description reinforce each other without ambiguity.

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

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

The opening phrase 'Call this tool to convert an amount' gives a direct, actionable usage instruction, and the scope (single amount, ECB currencies, date choice) defines the context clearly. It does not explicitly name alternatives such as convert_many or fx_rates_for, so it stops short of a full 5, but the guidance is well 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?

With no annotations provided, the description carries full burden and does well: it discloses the consistent rate date, the per-currency rounding behavior, and that unknown targets are listed rather than causing failure. This is meaningful behavioral context beyond what the schema alone provides, though it does not cover every possible side-effect concern.

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 carrying a distinct necessary fact: core behavior with constraints, a usage pattern, and error handling. The description is front-loaded with the main action and has no filler words.

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

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

For a 3-parameter tool with no annotations and no output schema, the description covers the core behavior, consistency guarantee, rounding rules, error handling, and a realistic use case. It does not describe the output structure or rate source details beyond 'ECB', but these are secondary to 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 only 33% (only 'to' has a description), so the description must compensate. It clarifies that 'amount' is a single amount converted into multiple currencies and that 'to' holds the target currencies, but it does not explicitly explain 'from' beyond being the source currency or specify formats beyond the schema pattern. Partial compensation.

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') and a specific resource ('one amount into several currencies'), and adds distinguishing constraints (same ECB rate date, rounding to each currency's minor units). This makes it clearly distinct from the sibling 'convert' tool, which converts one amount to one currency.

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 a concrete usage rule: for several lines at once (mixed-currency invoice lines), call it once per line so all lines share one rate date. It does not explicitly name the alternative 'convert' tool, but the guidance strongly implies when this multi-currency variant is appropriate.

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 annotations provided, the description carries the behavioral burden and does a solid job: it explains that the input is wall-clock unless it has an offset or trailing Z, that every zone in to_zones is produced, that day changes are marked, and that the UTC instant is included. It does not mention failure behavior for nonexistent times, though the schema's gap parameter covers that.

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

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

Three sentences with no filler. The main behavior is front-loaded, the wall-clock caveat is second, and the example is last. Every sentence contributes either action, semantics, or an illustration.

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 moderate complexity of five parameters and no output schema, the description covers the essential behavioral contract: inputs, natural-language support, day-change marking, and UTC instant. It does not spell out the exact output shape, but it gives enough for an agent to understand what results to expect.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics beyond the schema: it clarifies the interpretation of the 'time' parameter ('wall-clock in from_zone unless it carries an offset or a trailing Z') and gives a natural-language example ('3pm tomorrow works'). It also makes explicit that to_zones is exhaustive ('every zone').

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: 'Convert one time from from_zone into every zone in to_zones.' It clearly distinguishes this from sibling tools like 'now' or 'overlap' by framing it as a timezone conversion with day-change and UTC-instant output.

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 applies: converting an arbitrary wall-clock time across zones, including natural-language inputs. It does not explicitly name alternatives or exclusions, but its scope is evident enough that an agent can identify it as the conversion tool rather than the current-time or overlap 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 annotations supplied, the description carries the behavioral burden and does well: it states the file is written, what is returned, that posting content is never restated as the user's, and the free quota of 3/month. It does not cover failure modes like overwrite conflicts, but those are exposed through the input schema.

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

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

Three short sentences, no filler. The core behavior and return values are front-loaded, and the critical guardrail and quota are stated concisely in the following sentences.

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 includes the core behavior, outputs, the source data, a critical privacy/accuracy constraint, and a usage limit. An agent can reasonably predict the tool's behavior and invoke it successfully.

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 63%, and the description adds semantic context for the less obvious parameters: job_description is only used to select skills and never copied as facts, and highlights that cannot be verified surface as bracketed prompts. The basic fields (role, company, tone) are self-explanatory and mostly covered by 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 starts with a specific action, 'write a one-page cover letter .docx', and names the data source and return values ('path, word count and bracketed prompts'). This cleanly distinguishes the tool from siblings like resume_create and tailor_to_job.

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...' clearly indicates when the tool should be invoked, and the one-page cover-letter scope makes it distinct from resume-related siblings. The description does not provide explicit when-not-to-use conditions or name alternatives, so it is clear but not fully contrastive.

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 annotations, the description carries the full burden and does disclose key behavior: the list is exhaustive and authoritative, and contains rates and decimal places. However, it does not mention freshness, ordering, or whether the rates are live or static.

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 deliver the full purpose and domain scope without redundancy. The key constraint is placed in the second sentence, making the description easy to parse.

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

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

For a zero-parameter list tool, the description is complete: it defines the contents, the authoritative scope, and the practical consequence of a missing code. No output schema is present, but the listed fields are enough for an agent to understand 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?

The tool has zero parameters, so the baseline of 4 applies. The description adds meaningful context about what each listed item contains, compensating for the lack of schema 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 clearly states the tool exposes every currency in the ECB daily set, including its euro rate and decimal places. It also frames the resource as the authoritative domain list, distinguishing it from conversion and history 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 implies when to use it: to validate whether a currency code is supported before attempting conversion, quoting, or history retrieval. It does not explicitly name sibling alternatives, but the domain boundary is clearly communicated.

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 annotations provided, the description only mentions output (file path, block count, layout) and claims 'Free and unlimited'. It does not disclose side effects like file overwriting behavior (default false), the possibility of errors, or what happens if the file exists. This is a transparent 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?

The description is brief and front-loads the core purpose. However, the phrase 'Free and unlimited' is extraneous and adds noise without aiding tool selection, preventing a perfect score.

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 moderately complex nested schema (sections with headings, paragraphs, lists, tables), the description is sparse. It does not illustrate the concept of 'structured sections' or how the layout styles (plain, letter, proposal) affect output. While the schema fills many gaps, the description alone is not fully self-contained.

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

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

Schema coverage is 100% and every parameter already has a descriptive comment. The tool description adds no additional meaning about parameters beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description states a specific verb ('write') and resource ('a real .docx file') and clarifies the input format ('structured sections'). It also lists the return values, making the tool's purpose unmistakable. This clearly distinguishes it from siblings like doc_from_markdown or doc_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?

No explicit guidance is given on when to use this tool versus alternatives such as doc_from_markdown or doc_fill_template. The description does not mention scenarios or conditions that would prefer this tool, leaving the choice to inference.

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

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

With no annotations, the description carries the full burden. It discloses that the tool writes a new file, reports filled/unfilled/ignored placeholders, lists placeholders when called without values, and imposes a free-tier limit of 10 placeholders. These are meaningful behavioral traits beyond what the schema already expresses.

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 concise sentences, front-loaded with the primary action and followed by the no-values behavior and the free-tier constraint. Every sentence earns its place and there is no 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 moderately complex tool with no output schema, the description covers the main behavior, the alternative no-values invocation, and the key free-tier limitation. Parameter defaults and path behavior are handled by the schema. The only minor gap is the exact return format, though the filled/unfilled/ignored report is mentioned.

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. The description adds extra semantic value by explaining that omitting values triggers placeholder listing, which directly clarifies the optional values parameter. It also frames the meaning of placeholders in context, going slightly beyond the schema 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 and resource: replace {{placeholders}} in a .docx and write a new file. It also clarifies that calling with no values lists placeholders, which is a distinct behavior. This clearly separates it from sibling doc tools like doc_create, doc_read, or doc_from_markdown.

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

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

The description explicitly says when to call the tool: to replace placeholders or to list placeholders with no values. It gives clear usage context, though it does not mention alternatives or exclusions such as 'use doc_from_markdown instead when creating a document from scratch.'

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 annotations supplied, the description carries the full burden and does well: it discloses the return shape (file plus block count), supported syntax features, the empty-markdown refusal, and the overwrite-requires-flag safety gate. It stops short of explicitly stating that a file is written to disk as a side effect, but the overwrite mention strongly implies it.

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

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

Three sentences with zero filler: the core action and return value are front-loaded, followed by feature support and then refusal conditions. Every sentence earns its place and the most critical behaviors appear first.

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

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

For a 5-param conversion tool with 80% schema coverage and no output schema, the description is nearly complete: it covers the return value, supported syntax, and both refusal/error branches. The only gap is an explicit statement of the disk-write side effect and default destination, though out_path's default is in the 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 coverage is 80%, so the schema already documents markdown, title, out_path, overwrite, and the style enum. The description adds genuine behavioral context beyond the schema—empty markdown is refused and overwrite requires the flag—but does not elaborate parameter semantics further. This is a standard baseline-3 case where 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 opens with a specific verb+resource pair: 'turn markdown into a .docx,' and states the exact outcome (returns the file and a count of blocks by type). This cleanly distinguishes it from the likely sibling doc_to_html (markdown to HTML instead of Word) without needing the schema.

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

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

It clearly says 'call this tool to turn markdown into a .docx,' giving a strong trigger condition. However, it never names alternatives or exclusion cases, despite relevant siblings like doc_to_html, doc_create, and doc_fill_template existing. The reader must infer when this tool is preferable to its 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?

No annotations are provided, so the description carries the behavioral burden. It discloses the return behavior: outline of headings, full text in document order, or block structure, and notes that usage is free and unlimited. 'Extract' also implies a non-destructive read operation, though it does not explicitly state 'does not modify the file.'

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, front-loaded with the invocation guidance, and delivers the output behavior in a singlefollow-up sentence. The 'Free and unlimited' note is brief and adds useful operational context without bloating 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?

For a simple two-parameter read tool with 100% schema coverage and no output schema, the description provides the essential decision and invocation information: what file type to target, what the tool returns, and the two output flavors. 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 description coverage is 100%, so the schema already fully documents both 'path' and 'format.' The description's mention of outline/headings and block structure loosely maps to the format enum, but it does not add meaningful parameter 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?

The description uses a specific verb and resource: 'extract the text of an existing .docx.' It clearly differentiates this tool from siblings like doc_to_html, pdf_text, and resume_read by specifying the .docx text-extraction behavior and the outline/block-structure output.

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 extract the text of an existing .docx' gives explicit guidance on when to use it. It does not name alternative tools or exclusion cases, but the context is clear enough for an agent to select it for reading .docx text.

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?

No annotations are present, so the description carries the burden. It discloses that the tool returns a path, does not render PDF directly, and is 'free and unlimited.' This gives useful behavioral context, though it doesn't cover all edge 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 two sentences, concise, and well-structured. It covers purpose, output, and a key usage hint without fluff or redundancy.

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

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

For a simple tool with three well-documented parameters, the description provides enough context: converts docx to semantic HTML, returns path, supports PDF workflow, and is free/unlimited. It lacks an output schema but doesn't need one. Minor gaps like error behavior are not critical.

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 describes all three parameters (path, out_path, overwrite) with clear descriptions. The tool description adds context about the conversion purpose but does not add new meaning to the parameters themselves, matching the baseline for full schema coverage.

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

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

The description clearly states the tool converts .docx to semantic HTML, mentions the output is a file path, and highlights its use for printing to PDF. This is specific and distinct from sibling tools.

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

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

It explicitly says 'This is the supported PDF route; no PDF is rendered here,' which directs when to use this tool (when HTML is needed for PDF output) and what to avoid (expecting direct PDF). While it doesn't name alternative tools, the condition is clear.

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 annotations, the description must carry the behavioral disclosure burden. It does disclose that this tool writes to a shared profile and that the stored details appear on every relevant document, but it does not mention that the profile is overwritten, whether auth is required, or that the effect is global and irreversible. Partial transparency, but not a contradiction.

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 two sentences with no filler words. The second sentence connects this tool to the invoice server's business_set, a valuable structural note, and the whole text fits in a small space while conveying the key 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?

Given 17 parameters and no output schema, the description gives an appropriate high-level summary, and the schema carries the per-parameter detail. However, it does not state what happens to existing documents or existing profile values, nor does it clarify whether the write is a full overwrite or partial update. For a global settings setter, these caveats matter to agents.

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%, and each parameter already has a rich description (e.g., the email rule). The tool description only adds a high-level category summary (currency, VAT, terms, prefix) and does not introduce new parameter semantics beyond the schema, so the baseline 3 applies.

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

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

The description clearly states the tool stores sender details and defaults that appear on proposals, contracts, and letters, and it references the shared profile relationship with the invoice business_set. However, it does not explicitly distinguish when to prefer this tool over a sibling like invoice_business_set, so it falls short of a fully differentiated purpose statement.

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

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

There is no explicit when-to-use or when-not-to-use guidance. The description implies the tool is for docx-generated documents but does not contrast with invoice_business_set or offer alternatives, leaving an agent without enough context to avoid the wrong sibling.

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?

No annotations are present, so the description carries the burden of explaining behavior. It discloses the key output traits: exact UTC instant and offsets before/after the change. This is meaningful for an agent. It could say more about empty results or return shape, but for a simple query tool this is reasonably transparent.

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 concise sentences. The first states the output content, and the second provides a practical use case. Every sentence earns its place, 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?

For a low-complexity, two-parameter tool with no output schema, the description gives enough context: what is returned, the time detail, and the intended use. It could be slightly richer by noting what happens when a zone has no daylight-saving changes, but nothing critical is missing for normal use.

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 clear descriptions for year ('Calendar year, default this year') and zone ('Place or IANA zone'). The description adds no extra parameter 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 identifies what the tool provides: daylight-saving clock changes for a place/year, with UTC instants and before/after offsets. It does not use a strong verb like 'returns' or 'lists', but the resource and output content are specific. It is distinguishable from time-related siblings by focusing on DST transitions.

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 use case: checking whether a recurring call moves for one participant in March or October. This is practical and helps an agent know when this tool is relevant, though it does not name alternatives or explicitly say when not to use it.

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

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

No annotations are provided, so the description carries the full burden. It discloses a key behavioral detail (rate is frozen on the entry) and the return values, but omits prerequisites, error handling, side effects, or any state changes beyond creation. Partial disclosure only.

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—two sentences with no fluff. It front-loads the purpose and integrates the critical rate behavior efficiently. Slightly dense, but appropriately sized for the tool's complexity.

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 10 parameters, no output schema, and no annotations, the description is thin. It doesn't mention required fields (project, start), the conflict if both end and minutes are provided, default billable behavior, or error handling. It covers the essentials but leaves significant gaps for a tool of this complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying the start+end vs. minutes alternative and explaining that 'rate' is in MAJOR units and frozen, which goes beyond the schema's property descriptions. This is a meaningful addition.

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 ('Log time') and the resource ('one entry'), and distinguishes from timer tools by specifying 'already worked'. It also lists return values (id, duration, amount), making the 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 phrase 'already worked' implies this is for completed time vs. ongoing timers (timer_start), but it never explicitly names alternatives or conditions for using entry_edit or when not to use this tool. No explicit when-to-use or when-not-to-use guidance is given.

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

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

With no annotations, the description carries full burden. It discloses two key behaviors: it never touches a running timer, and it deletes billed entries with loss of invoice record. It also indicates a return report. However, it doesn't explicitly state that deletion is irreversible, though that is implied by the delete verb.

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 primary action and immediate caveats. No filler, every sentence earns its place.

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

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

For a one-parameter delete tool with no output schema, the description covers the essential usage, side effects, and alternative. It is complete enough for an agent to invoke correctly without additional 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 covers the single parameter (id) with a description. The tool description restates 'by id' but adds no new semantic detail. Baseline 3 for high schema coverage 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 the action (delete), the resource (logged entry), the identifier (by id), and differentiates from siblings by noting it doesn't touch a running timer and that billed entries are affected, contrasting with entry_edit. This clearly distinguishes it from entry_edit and timer 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?

Explicitly warns against using on billed entries because it loses the invoice record, directing to entry_edit instead. Also clarifies it doesn't affect running timers, so it's safe in that context. This gives clear when-to-use and when-not-to-use guidance with a specific 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?

With no annotations, the description carries the full burden, and it discloses important non-obvious behaviors: minutes adjusts end, invalid end times are refused, tags replace rather than merge, and rate is in major currency. It does not mention permissions or response behavior, but the mutation-related surprises are largely surfaced.

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 entire description is one efficient sentence that front-loads the target and scope, then adds the important behavioral caveats. There is no filler or repetition of obvious schema content; 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 mutation tool with 11 parameters, no annotations, and no output schema, this description is fairly complete. It covers the tricky mutation semantics: which fields move, what is rejected, what is replaced, and what units are used. A brief note about the return value would have made it fully self-contained, but the definition is sufficient for correct use.

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

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

Schema description coverage is only 55%, so the description meaningfully compensates by explaining the relationships among start/end/minutes, the replace behavior of tags, and the units for rate. Many simpler fields like note, task, project, and billable remain without schema descriptions, but the description's coverage of the ambiguous parameters 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 clearly states a specific verb and resource: change one logged entry by id. It also distinguishes this from siblings by clarifying patch semantics ('only the fields you pass move'), which separates it from entry_add, entry_delete, and entry_mark_billed. This adds real value beyond the title.

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 guidance on how to use the tool: target an existing entry by id and pass only the fields to update. It does not explicitly name alternatives or state when not to use it, but the context is strong enough that an agent can choose it over add/delete/mark tools without much risk.

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 annotations, the description carries the behavioral disclosure burden. It explains the output shape, sort order, total hours, and plan-based read limits, which is meaningful transparency beyond a generic 'list entries' statement. It stops short of stating authentication, rate limits, or whether the operation is read-only, though 'reads' strongly implies non-mutation.

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 deliver the essential information with no filler. The output format, ordering, total hours, and plan limitation are front-loaded in a compact, scannable 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?

Given there is no output schema, the description compensates by describing the returned columns and key behaviors. It is complete enough for a straightforward listing tool, with only minor gaps such as default range semantics when no from/to parameters are supplied.

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 parameters already carry adequate documentation. The description adds no extra semantics about how from/to bounds interact with the default range or how limit interacts with total hours, so the baseline 3 is appropriate.

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

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

The description clearly states the tool lists logged entries and specifies the output fields, ordering, and total hours. It is unambiguous against mutation siblings like entry_add or entry_delete, though it doesn't explicitly differentiate itself from export_csv or other read-style 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 implies the tool is for listing time entries, and the free/Pro history limitation gives useful context about when results are restricted. However, it does not explicitly state when to prefer this tool over alternatives such as export_csv or timer_status.

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 annotations, the description carries the full burden, and it does disclose the main behaviors: entries get stamped, reports and invoice_summary stop offering them, and double-billing is prevented. The ids parameter description adds that already-billed entries are left alone and listed back, which is useful idempotency behavior. It does not detail reversibility or permissions, but the core mutable effect is transparent.

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 one tight sentence that front-loads the purpose and consequence. Every clause earns its place, with no repetition of the title 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 mutation tool with no output schema and no annotations, it covers what it does, when to run it, why it exists, and how to select entries. Minor gaps are an explicit statement of what is returned for successfully billed entries and whether the change can be undone, but the tool is callable with the information provided.

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 descriptions already cover parameters, so the baseline is 3. The description adds meaningful selection semantics: 'Pass either ids or project plus from and to' plus the typical source 'entry_ids invoice_summary returned'. This clarifies the two mutually exclusive calling modes and helps an agent avoid passing conflicting parameters.

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

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

The description uses a concrete verb and object ('stamp the tracked hours ... with the invoice number') and explains the business purpose ('so report and invoice_summary stop offering them and the same hours are never billed twice'). This clearly differentiates it from siblings like invoice_mark_paid, which marks an invoice paid rather than the underlying time entries.

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

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

It gives an explicit trigger condition ('after an invoice is issued') and references invoice_summary as the source of entry ids, making the workflow placement clear. It does not enumerate exclusions or alternatives, but an agent can infer when this tool is the right step.

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?

No annotations are provided, so the description carries the burden of explaining behavior. It discloses that a new .ics file is written, that UTC times are used, and that the file is intended for sending or importing elsewhere. It does not describe error cases or what happens if both ids and from/to are supplied, but the core behavior is transparent.

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 focused sentences, no filler. The purpose and key usage distinction are front-loaded, and the timezone detail is placed where it matters. 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?

The description is adequate for a straightforward export tool, but gaps remain: it does not clarify what happens when both ids and from/to are omitted or supplied together, and it only references events_list as the source for ids while the schema also allows events_search and next_event. With no output schema, a bit more detail about expected results would strengthen 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?

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful cross-parameter guidance by presenting ids and from/to as mutually exclusive alternatives, and explains why UTC matters for the output. This goes beyond simply restating 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 action and resource: 'write chosen events to a new .ics file'. It clearly separates this from siblings like export_csv or ics_create by focusing on exporting existing events into an .ics file.

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 tells the agent how to scope the operation: pass either ids or a from/to window. It does not explicitly name sibling tools to avoid, but the context of sending or importing the .ics elsewhere is clear enough for correct use.

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 annotations provided, the description carries the burden of behavioral disclosure. It usefully communicates recurrence expansion, sorting by start, timezone fallback behavior, and ID reusability. It does not describe response shape or pagination, but still provides meaningful behavioral context beyond a simple 'list events' statement.

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, information-dense sentences: the first states scope and ordering, the second clarifies timezone behavior, and the third explains useful downstream tool compatibility. Every sentence earns its place with no filler.

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

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

For a simple list operation with no output schema, the description covers the essential behavioral context: date window, recurrence expansion, sorting, timezone handling, and ID usefulness for related tools. It does not detail the response envelope, but the gap is modest given the clear scope and title.

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 all four parameters with 100% coverage, so the description does not need to define them. It adds one useful nuance about the 'zone' parameter and local time display, which goes slightly beyond the schema, but the schema remains the primary source of parameter 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 core behavior is clear: 'Every event between two dates, recurring expanded to occurrences, sorted by start' names the resource and the operation. It does not explicitly contrast with sibling tools like events_search, so differentiation is implied rather than stated.

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

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

The description implies this tool is for retrieving all events in a date range and notes that resulting IDs work for event_export or event_to_time_entry. However, it does not explicitly say when to use events_list versus events_search, free_busy, next_event, or other calendar-related 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?

With no annotations, the description carries the burden. It discloses plan-dependent default time ranges, giving some insight into behavior, but it does not explicitly state that the operation is read-only or describe any side effects, rate limits, or data sensitivity.

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 concise sentences, with the main purpose stated upfront and additional behavior details in the second sentence. No fluff or redundancy is present.

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?

In the absence of an output schema, the description does not clarify the return format (e.g., list of event objects, count, metadata). While 'find events' implies a result set, the lack of detail on what the response contains could leave an agent uncertain about downstream processing.

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

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

Schema coverage is 100%, and the description adds meaningful context by explaining how from/to behave when omitted (default windows) and what fields are searched. This goes beyond the schema's simple date and query definitions, providing practical usage semantics.

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

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

The description uses a specific verb ('find') and clearly identifies the resource (events) and the search scope (title, description, location, attendees). It distinguishes this from a plain listing tool by emphasizing the phrase search across imported calendars.

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 that it searches every imported calendar and describes default date windows based on plan, but it does not explicitly mention when to prefer this over sibling tools like events_list or how it differs from them. Guidance on when-not-to-use or alternatives is missing.

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?

Explicitly states 'Writes nothing', which is a key side-effect disclosure given the lack of annotations. It also clarifies that it returns arguments rather than performing the entry creation, but doesn't mention potential validation or error 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 concise sentences with no redundant wording. The key information—what it does, its side-effect-free nature, and the follow-up action—is front-loaded and efficiently communicated.

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?

Sufficient for a tool with 4 straightforward parameters. It tells the user exactly what to do with the output ('pass the JSON straight to entry_add'), though a bit more detail about the return shape would have been helpful given the absence of an 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?

The schema already covers all parameter meanings (event_id source, project/client, rate format, currency fallback). The description adds no extra parameter detail, so it stays at the baseline for full schema coverage.

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

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

Clearly states it takes an event and returns the exact arguments for entry_add, with the specific purpose of converting a past meeting into billable time. This distinguishes it from sibling tools such as entry_add or events_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?

Indicates when to use it ('a meeting that already happened becomes billable time') and directs the user to pass the result to entry_add. It doesn't explicitly contrast with every alternative, but the use case is clear.

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?

No annotations are provided, so the description carries the full burden. It discloses the write behavior ('Returns the file path written'), the output content, and the format. It does not mention overwrite or clamping behavior, but the input schema already documents the free-tier/pro clamping for date ranges.

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 primary purpose, and every sentence adds essential information: what it exports, for whom, the row structure, and the return value. 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?

With no output schema, the description correctly explains the return value ('file path written') and the file content. It covers the essentials for an agent to select and invoke the tool. Minor omissions like file overwrite behavior or encoding are acceptable given the schema richness and simple nature of the export operation.

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

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

Schema description coverage is 100% with clear descriptions for all four parameters (to, from, path, project). The description does not add parameter-specific meaning, but the baseline of 3 is appropriate because the schema fully covers the parameters.

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

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

The description states a specific verb ('export'), resource ('the timesheet'), output format ('CSV file, excel-friendly'), and purpose ('hand to a bookkeeper'). It also specifies the row structure ('one row per entry with hours, billable, rate, currency and amount'), which clearly distinguishes it from other export-related siblings like clause_export or event_export.

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 tells when to use the tool ('Call this tool to export the timesheet to a CSV file...') and for whom ('hand to a bookkeeper'). It does not name alternative tools or state when not to use it, but among the siblings there is no direct alternative for timesheet CSV export, so the guidance is clear.

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 annotations, the description carries the transparency burden. It does disclose return content (UTC instant, local time per participant, fairness score) and ordering, but it leaves side-effect/read-only status implicit and does not mention behaviors like saved-contact resolution or free-tier truncation, although some of those appear in the schema descriptions.

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 concise sentences lead with the core action and then describe the output shape and ordering. No filler, no repetition of schema content, and 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?

There is no output schema, but the description usefully summarizes the return values, and the rich parameter schema covers the inputs thoroughly. It is complete enough for correct invocation, though explicit usage guidance and side-effect disclosure would make it fully self-sufficient without annotations.

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

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

Schema description coverage is 100%, so the schema already explains every parameter. The description adds context about output format and ranking but no additional parameter-level meaning, matching the 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 uses a specific verb ('Rank') and clear resource ('times when every participant is inside their own working hours'), and separates this tool from siblings like free_busy or conflicts by describing the fairness-ranked slot output. The title and description together leave no ambiguity about what the tool does.

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: the tool clearly exists for finding mutually workable meeting times across participants. However, it does not explicitly say when to choose this over alternatives like free_busy, conflicts, or overlap, nor does it state when not to use it.

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

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

With no annotations provided, the description carries the transparency burden. It discloses important behaviors: invoiced and skipped periods are not included, paused schedules are shown separately, and plan limits are free vs. Pro. It does not mention response shape or update timing, but for a read-only forecast tool these are less critical.

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

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

Three short sentences deliver highly relevant information with no filler. The main purpose is front-loaded, and the additional constraints are packed into the following sentences without redundancy.

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

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

For a single-parameter tool with no output schema, the description covers the key usage context well: what is forecast, what is excluded, how paused schedules are handled, and plan limits. A more explicit note about response shape would make it stronger, but the tool is simple enough that the description is adequate.

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

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

The schema fully covers the only parameter with name, type, min, max, and default. The description adds value beyond the schema by stating plan-specific limits (Free: 3 months; Pro: up to 120) and clarifying that the horizon is measured in months, which helps an agent pick a meaningful 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 opens with a specific verb and resource:

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: use this tool to obtain a revenue forecast from active schedules, with a timeframe controlled by the plan limit. It does not explicitly name or compare alternatives among the sibling tools, but no sibling serves the same forecasting purpose, so the lack of explicit exclusions is not a significant gap.

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

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

With no annotations provided, the description carries the full burden of disclosing behavioral traits. It does well by explaining the treatment of free events and whole-day events, and the 31-day limit appears to be a hard constraint (likely an API limit). However, it doesn't disclose details like whether the tool requires authentication, rate limits, or how it handles time zones beyond what the zone parameter implies. The 'Free: 31 days' is ambiguous—could mean the max range is 31 days, which is useful but not fully explicit.

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, three substantial sentences, and front-loads the core output ('Merged busy blocks and the free gaps inside your working hours') before diving into constraints. The sentence about free events and whole-day events is critical and placed early. The 'Free: 31 days' and 'Use conflicts for overlapping pairs' add value without bloat. It earns a 4 for being tight and informative.

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 6 parameters but only 2 required, and no output schema, the description gives enough for basic usage: date range, working hours, calendars, and time zone. It clearly communicates the core output. However, it lacks details on the output format (e.g., does it return blocks in a specific structure?), error handling, or edge cases (e.g., what if no free gaps exist). For a scheduling tool, these could be relevant for agents, but the complexity is moderate, so a 3 is fair.

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 is described in the schema. The description adds some semantics by explaining that 'free' events don't count and whole-day events block the day, which relates to the 'calendars' and 'work_start'/'work_end' parameters. However, it doesn't add detail about formats or default values beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: it provides merged busy blocks and free gaps within working hours over a date range. This distinguishes it from sibling tools like conflicts and events_list, though it doesn't explicitly contrast with them. The verb 'Merged' and resource 'busy blocks and free gaps' are specific enough to convey purpose.

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 explains when to use this tool: for checking busy blocks and free windows over a day range, with important exclusions (events marked free don't count, whole-day events block the day). It also gives a hint to use 'conflicts' for overlapping pairs, which is an explicit alternative suggestion. However, it doesn't cover all possible alternatives or negative use cases in depth.

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?

No annotations exist, so the description carries the full burden. It discloses the return value and its purpose, but does not explicitly state read-only/non-mutating behavior, rate source, freshness, or error conditions. It is adequately transparent for a lookup, but not exhaustive.

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

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

Two compact sentences, front-loaded with when to use, followed by the return contract. No filler or redundancy.

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

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

For a simple two-parameter read tool with a thorough schema, the description covers when to call it and what it returns. The main gap is that the output shape is defined only by reference to 'expense_to_invoice', which may be ambiguous if that concept isn't known to the agent.

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%, with good detail about target, currencies, direction, and defaults. The description adds no additional parameter meaning beyond what the schema already explains, 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?

clear and specific: it is a call-to-get FX rates for multi-currency invoices/rebills, returning a shaped object and rate date. It does not explicitly contrast itself with sibling rate tools like rates_latest or convert, so it stops short of full sibling differentiation.

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

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

Gives an explicit trigger condition (rebill or invoice spans more than one currency) and an explicit alternative (asking the user for rates). It lacks comparison to sibling FX rate tools, so it doesn't fully cover when-not-to-use cases.

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 annotations provided, the description carries the full disclosure burden. It reveals that the tool writes a file, returns a path and start time, stores times in UTC, and has a monthly quota of 3 files. It does not mention overwrite behavior or edge cases like DST refusal, but the core behavioral traits are covered.

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

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

Three short sentences carry the essential usage instruction, return-value summary, timezone rationale, and quota limitation. Every sentence earns its place and the main 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?

The rich input schema covers all parameters, and the description supplies the missing return-value and timezone context. There is no output schema, and the description does not specify the exact output format beyond 'path plus the start in UTC and in your zone', but it is still sufficient for an agent to call the tool successfully.

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 12 parameters in detail. The tool description adds no parameter-specific meaning beyond the overall write-an-.ics behavior, so a baseline score 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 uses a specific verb and resource: 'write a .ics for one meeting' and states the return values (path plus start time in UTC and local zone). This clearly distinguishes it from siblings like ics_import and events_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 begins with 'Call this tool to...' and clearly identifies the use case: writing a single calendar invite. It does not name alternative tools for importing or exporting events, so it lacks explicit exclusions, but the context is unmistakable.

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 annotations, the description carries the full burden and discloses key side effects: deleting the local .ics copy, freeing a slot, and preserving both the user's own calendar and the source file. It does not mention irreversibility or error behavior, but the main behavioral traits are transparent.

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 action and side effect in the first, the boundary of what is untouched in the second, and the relevant sibling behavior in the third. No filler or repetition of the title.

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

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

For a single-parameter tool with no output schema, the description is complete: it tells what is removed, what is deleted, what is preserved, and that names can be replaced via ics_import. An agent has everything needed 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?

The schema already fully describes the 'name' parameter as 'The calendar name from calendars_list', so the description adds little parametric meaning beyond clarifying that it identifies an imported calendar. This matches the baseline 3 for high schema coverage.

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

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

The description uses a specific verb and resource: 'Remove one imported calendar by name and delete this server's local copy of its .ics'. It clearly distinguishes this from sibling tools by specifying 'imported calendar' and noting that 'Your own calendar and the source file are untouched'.

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: it applies to imported calendars and frees a slot, while explicitly contrasting behavior with ics_import ('replaces a name in place'). It does not fully enumerate when-not-to-use or all sibling alternatives, but the usage context is clear.

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 annotations, the description carries the behavioral burden. It usefully discloses that re-importing a name replaces the existing entry and that URL feeds are a Pro feature, but it does not describe the return value, success/failure behavior, or persistence semantics beyond 'keep it under a name.'

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

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

Three compact sentences, front-loaded with the main action and no filler. Each sentence contributes a distinct piece of information: the operation, the input modes, provider compatibility, and overwrite behavior.

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?

Inputs and the important replace-on-reimport behavior are covered, and the schema documents all four parameters. However, because there is no output schema and no annotations, the agent is left without any stated return value or error semantics, which is a meaningful gap for an import operation.

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

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

Schema description coverage is 100%, so the baseline is 3. The main description adds helpful context by naming path, text, and URL as input alternatives and noting Pro for URLs, but it does not clarify whether exactly one source is required or what happens if multiple are supplied.

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

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

States a concrete action: read an .ics export and store it under a name. It clearly identifies the resource and avoids tautology, though it does not explicitly differentiate itself from sibling calendar tools like ics_create or ics_forget.

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?

Opens with a direct 'Call this tool to...' directive, so the primary use case is clear. It names the three input modes and flags the Pro requirement for URLs, but gives no explicit when-not-to-use guidance or routing among the many calendar-related 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?

With no annotations provided, the description carries the full behavioral burden. It does disclose a genuine side effect — persistence to a shared profile consumed suite-wide — and the one-time intent ('Call it once, first'). However, it does't state whether a subsequent call with only a subset of fields merges into or overwrites previously stored values, nor does it mention any return/confirmation, both of which matter for a write tool with 15 optional 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?

Two sentences with the scoping claim front-loaded. The content list, persistence fact, and usage directive each earn their place, and there is zero filler. The emphatic 'ONE' may be stylized but it functionally reinforces differentiation from sibling tools.

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-time setup call, the description covers scope, contents, persistence, and invocation order, and the rich schema covers parameter details. The remaining gaps are partial-update semantics on re-invocation (merge vs overwrite) and explicit routing relative to docx_business_set; with no output schema there is no hint at the return 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%, the baseline is therefore 3. All 16 fields are already documented in the schema, including alias relations (vat/tax_rate/vat_rate → default_tax_rate) and the conditional email/phone rules. The description adds only high-level category grouping (name, address, VAT id, bank details, defaults) and no per-parameter 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 clearly identifies the resource — the single suite-wide business profile — and enumerates its contents (name, address, VAT id, bank details, defaults). It differentiates from siblings by declaring itself 'THE ONE...for the whole suite' and stressing that 'every other server reads' it, which separates it from docx_business_set and prophile_set/prophile_get, though it never naes those alternatives.

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' is an explicit temporal instruction placing this tool before any other invoicing work, and the claim that the profile is what 'every other server reads' tells the agent this is the shared setup entry point. No when-not-to-use guidance or naed alternatives are given, so it doesn't quite reach 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 no annotations provided, the description carries the burden of behavioral disclosure. It explains important non-obvious behavior: never-reused numbers, major-unit pricing, line rounding before summation, one-currency enforcement, and the 3-per-month free quota. It does not discuss broader side effects or permissions, but the core behavior is well covered.

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

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

Four short sentences with no filler. The purpose is front-loaded, followed by the most decision-relevant constraints: pricing units, rounding behavior, currency, and quota.

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 rich and covers all parameters, and the description names the key return behavior (the record with its never-reused number). There is no output schema and no annotations, so a bit more detail about the response shape or quota enforcement would make it fully complete, but what is present is sufficient for correct invocation in most 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?

Schema description coverage is 100%, so the baseline is 3. The description restates major units, rounding, and one-currency constraints that already exist in the unit_price, items, and currency schemas, adding no new parameter-level meaning beyond what the schema already provides.

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: "Create an invoice from line items" and adds the key output trait of a never-reused invoice number. This clearly distinguishes it from read/manage siblings like invoice_get, invoice_list, and invoice_from_hours.

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 "from line items" gives clear context: this tool is for explicit itemized invoicing rather than hour-based invoicing, which separates it from invoice_from_hours. It does not explicitly name alternatives or state when-not-to-use, so it falls 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 no annotations, the description carries the behavioral disclosure burden. It clearly states the side effect ('Creates... an invoice') and the result behavior ('returns a single-line invoice, converting the rate... and echoing back any entry_ids'). This gives an agent a solid sense of what will happen, though it could also mention that the invoice is not automatically marked billed until entry_mark_billed is called.

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 essential use case, then the key behavioral details. Every sentence adds value without unnecessary elaboration or restating the tool name.

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

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

Despite a rich schema, the tool has 14 parameters, no annotations, and no output schema, so the description alone is not enough for an agent to fully understand the return shape or the full behavior across optional parameters. It explains the core case well but leaves significant context to be inferred from the 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?

The description adds meaning for the core fields client/hours/rate and the relationships around fx_rates and entry_ids, but schema coverage is only 50% and many optional parameters (notes, due_days, tax_rate, discount_percent, issue_date) are not addressed in the description. It partially compensates for the schema gap but does not fully carry the burden for all 14 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?

States a specific operation: 'Creates and returns a single-line invoice' for bill one client for N hours at an hourly rate. Differentiates from sibling tools like invoice_create by framing it as a 'Shortcut' for the common case, making its scoped purpose clear.

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?

Provides clear context for when to use it: 'Shortcut for the common case: bill one client for N hours at an hourly rate.' It also notes the conversion behavior when fx_rates is provided. It falls short of explicitly naming alternatives or saying when not to use it, but the context strongly implies its intended niche.

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 annotations, the description carries the burden of disclosing side effects, and it does: it creates 'real' invoices, renders PDFs, and returns a summary of created, skipped, and still-due items. The parameter descriptions add idempotency, dry-run, and limit details, further improving 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?

The description is two tight sentences: it leads with the core behavior and follows with the return summary. No redundant phrasing or filler, and it is well-structured for quick agent parsing.

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

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

The tool has no output schema, but the description names the three return categories and the parameter descriptions cover defaults, idempotency, dry-run, and the 60-invoice cap. This is sufficient for an agent to invoke the tool correctly, though return structure details are absent.

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

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

Schema description coverage is 100%, so the parameters are already fully documented in the schema. The main description does not add parameter-level meaning beyond the schema, which matches the baseline of 3 for high coverage.

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

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

The description states a specific action: create real invoices for schedule occurrences on or before as_of that haven't been invoiced, and render PDFs. This clearly identifies the resource and behavior, distinguishing it from siblings like invoice_create or invoice_from_hours by focusing on schedule-driven batch generation.

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 context is implied: this is for generating due invoices from schedules, especially in bulk. However, it does not explicitly state when to choose this over alternatives like invoice_create or invoice_from_hours, 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?

With no annotations provided, the description carries the full burden, and it does well by disclosing not just that it returns a record but also the nested richness of that record, including the unusual credit-note-adjusted open balance. It does not discuss error cases or permissions, but the read-only nature is clear from 'Return'.

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

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

The description is a single front-loaded sentence that efficiently conveys the core purpose and key return-value details. The parenthetical '(see credited_minor)' is somewhat cryptic and unexplained, slightly reducing clarity, but overall there is no wasted wording.

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

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

For a simple single-parameter get operation with no output schema, the description covers the essential information an agent needs: what it returns, the scope ('one invoice number'), and notable computed fields. It could be more complete with explicit not-found behavior, but the core call context is adequately 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?

The schema only documents 'number' as a string with zero description coverage. The tool description adds that it identifies the invoice, which is minimal but useful; it does not specify format, uniqueness requirements, or how to discover valid invoice numbers.

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 ('Return') with a clear resource ('the full stored record for one invoice number'), making the tool's purpose unmistakable. It also highlights distinctive content (line items, tax breakdown, credit-note-adjusted balance) that separates it from siblings like invoice_summary or invoice_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 implies when to use the tool: when you have an invoice number and need the full record rather than a summary. However, it does not explicitly contrast it with alternatives such as invoice_summary, invoice_list, or invoice_pdf, leaving routing decisions partly to inference.

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