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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable context by specifying that it checks reachability of both the backend and the FYI browser session, and reinforces non-mutation with 'Makes no changes.' No contradictions with annotations.

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

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

The entire description is a single, front-loaded sentence that states the action, the resource, and the non-mutating nature. No wasted words or redundant details—every word earns its place.

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

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

For a zero-parameter health-check tool with no output schema and strong annotations, the description is fully complete. It tells the agent exactly what is checked and that no changes are made, leaving no critical gaps.

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 per the rubric. The description does not need to add parameter meanings, and it correctly stays silent on parameters, letting the empty schema suffice.

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 ('Check') and explicitly names the resources being checked ('deployed backend and its FYI browser session'). It clearly distinguishes this health-check tool from sibling tools that deal with client/billing data.

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 'Check whether ... are reachable' makes the intended use obvious. It doesn't explicitly name alternatives or exclusions, but given the tool's simple health-check nature and distinct siblings, the context is clear enough for a 4.

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

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

Annotations already provide idempotentHint and non-destructive hints, so the additional explicit note that the cancel is local and sends no request to AutoFYI/FYI adds valuable behavioral context beyond the structured data. This clarifies side effects without contradicting annotations.

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

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

Two short sentences, front-loaded with the action and immediately adding the key scope qualifier ('locally', 'No request is sent'). No redundant words or 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 one-parameter tool with no output schema, the description covers the essential behavior and important caveat (local, no network request). It does not describe error handling for invalid confirmation_id, but the simplicity and annotation coverage make the description reasonably complete.

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

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

The schema has one required parameter, confirmation_id, with no description (0% coverage). The tool description does not explain where the confirmation ID comes from or how to obtain it, so it fails to compensate for the absence of 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 names a specific verb ('Cancel') and resource ('prepared action'), and immediately distinguishes the local, no-op behavior from potentially remote alternatives by stating 'No request is sent to AutoFYI or FYI.' This clearly identifies the tool's unique scope among siblings.

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

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

Usage is implied: cancel a locally prepared action before execution. However, there is no explicit mention of when NOT to use it or comparison to alternatives like execute_confirmed_action or get_prepared_action, leaving the context only implicit.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds value by specifying the content coverage (business rules, tool order, excluded admin endpoints) but does not describe the actual output format or any other behavioral traits. This is adequate but not rich, hence a 3.

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, readable sentence: 'Explain the AutoFYI business rules, safe tool order, and deliberately excluded admin endpoints.' It is front-loaded with the verb 'Explain' and lists three specific content areas without any filler. Every word contributes meaning, making it highly concise and well-structured.

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 informational tool with no output schema, the description adequately covers what the tool does and what it addresses. It specifies the three key educational components (business rules, safe tool order, excluded admin endpoints) and, combined with the annotations, gives the agent sufficient context to invoke it correctly. No additional information is needed.

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

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

The tool has zero parameters, and schema coverage is trivially 100%. With no parameters to describe, the baseline for this dimension is 4. The description correctly does not attempt to invent parameter details, though it also adds no parameter-specific value because none exist.

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 the specific verb 'Explain' and clearly identifies the resource: AutoFYI business rules, safe tool order, and deliberately excluded admin endpoints. This distinguishes it from sibling tools that focus on client catalog, billing, or job preparation operations. The scope is unambiguous and informative.

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 this tool: to understand business rules, the safe order of operations, and which admin endpoints are not exposed. It provides clear context for a new user or agent needing orientation. However, it does not explicitly mention alternatives or 'when not to use', though the unique explainer role among operational siblings makes this less critical.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering safety. The description adds useful context about the tool's behavior: requesting a column returns up to 10 common values and that the list is 'truncated is not exhaustive.' This informs the agent about output limitations, which is valuable beyond the annotations.

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

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

The description is two concise sentences that front-load the primary action and resource. It avoids extraneous prose and every clause adds meaningful information, from the queryable columns to the truncation caveat.

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 simplicity (2 optional params, no output schema), the description provides a reasonable overview but lacks some context. It doesn't explain what 'FYI' refers to, what happens if 'column' is null (all columns?), or how 'include_common_values' alters the output. The truncation note is helpful, but overall it feels incomplete for an agent to fully predict behavior.

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

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

With 0% schema description coverage, the description must compensate for parameter meaning. It only mentions 'Request one column,' which maps to the 'column' parameter, but it fails to clarify the role of 'include_common_values.' The phrase 'up to 10 common values' could relate to that boolean, but it's ambiguous whether common values are always included or only when the flag is true. This leaves significant ambiguity for a key parameter.

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

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

The description clearly states the tool's function: 'Describe queryable FYI CSV columns.' This provides a specific verb ('describe') and resource ('queryable FYI CSV columns'), and the context of the sibling tools (e.g., describe_autofyi) distinguishes it by the resource being described. It is not a tautology and gives a concrete 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 does not explicitly state when to use this tool versus alternatives. It says 'Request one column' but provides no guidance on when to choose this over siblings like query_client_catalog or describe_autofyi, nor does it mention any exclusions or prerequisites. Usage context is only implied.

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

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

Annotations already declare this as destructive, non-idempotent, and a write. The description adds meaningful safety context beyond annotations: 'exactly one' and 'never retry.' This highlights the non-idempotent nature and the importance of not repeating the call, which is critical for a financial write. However, it does not elaborate on specific consequences or failure modes, so it does not fully exceed the annotation burden.

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

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

The description is two sentences, front-loaded with the core purpose, and every word earns its place. It states the action, the precondition, and the critical safety rule without waste. This is exemplary conciseness.

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 a 2-param schema, no output schema, and conservative annotations, the description covers the essential context: what it does, when to call it, and the key safety constraint. It does not describe return values or error handling, but given the tool's narrow scope and the presence of annotations, this is not a significant gap. It is complete enough for an agent to invoke correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It implies that 'user_confirmation' is the exact preview phrase ('Call only after the user supplies the exact preview phrase'), but it does not explicitly map this to the parameter. 'confirmation_id' is left unexplained; the connection to a 'prepared financial write' is inferential. The description adds some meaning but leaves significant ambiguity for both 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 tool's function: 'Execute exactly one prepared financial write.' This distinguishes it from sibling tools like 'prepare_direct_invoice' and 'cancel_prepared_action' by making the execution step explicit. The verb 'Execute' and resource 'prepared financial write' 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 provides a clear precondition: 'Call only after the user supplies the exact preview phrase.' It also gives an explicit exclusion: 'never retry.' While it does not name alternative tools for when-not-to-use, the context implies this is the final step after preparation, distinct from preparation and cancellation siblings. This is strong contextual guidance without listing 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?

Annotations already declare readOnlyHint and non-destructive, so the safety profile is covered. The description adds useful behavioral context: strict identical matching and the fallback to ranked candidates for AI review and user confirmation, which is valuable beyond annotations.

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

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

The description is a single, well-structured sentence that front-loads the main action and the fallback, with no redundant information. It is concise and fully earn 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 tool has no output schema, and the description does not explain the structure of ranked candidates or the effect of 'detail_level'. While the core purpose is clear, missing parameter details and return format reduce completeness for a tool with only two 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?

The schema has no descriptions (0% coverage), and the description only clarifies that 'query' refers to a client name. The 'detail_level' parameter is completely unexplained, leaving a significant gap in parameter understanding.

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 loads an exact client name or falls back to ranked candidates, which is a specific verb+resource and distinguishes it from sibling search_clients by its strict-match behavior.

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

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

The description implies usage when an exact client name is needed or when candidates require review, but it does not explicitly mention alternatives or when-not-to-use. The context is clear but not fully 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 readOnlyHint and idempotentHint annotations already indicating a safe read operation, the description adds useful context by specifying the exact output fields (version, age, rows, columns). This goes beyond the annotations but does not address potential side effects or edge cases, which are largely covered by the annotations.

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

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

One sentence, front-loaded with the main action, and no redundant words. Every piece of information ('published', 'version, age, rows, columns') 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 tool is simple with no parameters and no output schema. The description fully conveys the purpose and the returned data fields, which is sufficient for this complexity level. It effectively covers the core need without requiring additional 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?

The tool has zero parameters, and the input schema is empty. The baseline for no parameters is 4, and the description correctly avoids redundant parameter information. It clearly communicates that no inputs are 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 clearly specifies the verb ('Check'), the resource ('FYI CSV catalog'), and the exact output scope (version, age, rows, columns). It distinguishes itself from sibling tools like describe_client_catalog by focusing on publication status and metrics rather than content.

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 its use for checking catalog publication status but does not explicitly state when to use it versus alternatives or mention exclusions. No alternative tools or contrasting conditions 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?

Annotations already mark the tool as read-only, idempotent, and non-destructive, which aligns with the description. The description adds behavioral context beyond the annotations by specifying the exact data categories read and warning that 'full' detail should be used sparingly, implying potential performance or data volume implications. This is valuable supplementary 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 sentences, front-loaded with the action and resources, and the second sentence provides a concise operational hint. Every word earns its place 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 read-only tool with rich annotations, the description gives a reasonable overview of the data returned. However, it lacks clarity on when to use this tool versus closely related siblings (e.g., describe_client_catalog, get_client_catalog_status), and does not explain output structure or what 'FYI information' or 'prepared allocations' entail. This leaves some contextual gaps for an agent deciding between tools.

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

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

Schema description coverage is 0%, so the description must compensate. It implies the client_id parameter via 'selected client' and hints at detail_level through 'Use full only when necessary', but it does not explicitly define valid detail_level values (e.g., 'summary' vs 'full') or explain the semantics of client_id further. This partial clarification adds some value but does not fully bridge the schema gap.

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

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

The description clearly states the tool reads a selected client's FYI information, Xero templates, and prepared allocations, using the specific verb 'Read' and identifying distinct resources. It does not explicitly name sibling tools or differentiate itself, such as noting when to use get_client_catalog_status instead, so it stops short of a 5.

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

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

The description provides no guidance on when to use this tool versus alternatives, only a note about using 'full' detail level when necessary. This is a parameter-level hint rather than a tool-selection guideline, and no exclusions or alternative tool names are mentioned.

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

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

Beyond annotations, the description discloses that the tool is 'Browser-driven and may take minutes', indicating a slow, non-API operation. This adds significant behavioral context not captured by the readOnlyHint.

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

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

Two sentences, no filler, information-dense and front-loaded with the primary action.

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

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

Given the simplicity (one param, no output schema) and strong annotations, the description provides the core purpose and performance caveat. However, it lacks details on return format or edge cases, leaving some context to be inferred.

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 does not explain the client_id parameter, and the schema provides no description (0% coverage). The tool name implies the client relationship, but no format or source for the ID is given.

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 the verb 'Read' with a specific resource 'live FYI jobs available to invoice' and mentions 'work amounts', clearly distinguishing this from sibling tools like get_jobs_and_interim_table by focusing on invoice-ready jobs.

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 on when to use this tool versus alternatives like get_jobs_and_interim_table. The only contextual hint is the performance warning, but no exclusions or alternative recommendations are provided.

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

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

Annotations already mark this as read-only and idempotent, but the description adds useful behavioral traits: 'Makes no FYI changes' reinforces the read-only nature (though redundant) and 'may take minutes' warns about latency, while 'live' indicates data freshness. This exceeds what annotations provide without contradicting them.

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

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

The description is two sentences, with the primary action front-loaded in the first sentence. Every word adds value; there is no 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?

The description covers the core purpose and warns about runtime, but with no output schema, it fails to describe the return format or what constitutes 'interim dates and amounts.' Given the moderate complexity of merging two data sources, more context about the output would be expected, though the basic purpose is sufficiently clear.

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 one required parameter, client_id, with no description (coverage 0%). The description does not explain or mention the parameter at all, leaving its meaning and format entirely to inference. Since schema coverage is low, the description was responsible for compensating but did not.

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 'Read' and identifies two resources: 'live FYI jobs' and 'billing-job interim dates and amounts.' This clearly states what the tool does, though it does not explicitly differentiate from sibling tools like get_client_jobs_to_invoice or query_client_catalog.

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 use when you need live job data plus interim billing information, and warns that it 'may take minutes,' which gives context about the operation's nature. However, it provides no explicit when-to-use versus alternatives or exclusions, so guidance remains 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds the specific constraint that it never executes the action, which is beyond the generic read-only hint. It also introduces the 'unexpired' condition, adding useful context about expiration behavior.

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

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

The description is a single sentence that packs the core purpose, scope, and a key constraint without any redundancy. Every word earns its place.

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

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

With strong annotations and a simple one-parameter design, the description covers the essential behavior. It doesn't detail return values, but no output schema exists and the tool's purpose is straightforward, so the description is sufficiently complete.

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

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

The schema has zero description coverage for the single parameter confirmation_id. The description doesn't explicitly define it, but the tool name and description ('prepared action') strongly imply it is the ID of a prepared action. For a single self-explanatory parameter, this is adequate, though it could have been more explicit.

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 reads prepared actions and never executes them, which directly distinguishes it from execution tools like execute_confirmed_action. The verb 're-read' and 'retrieve' precisely communicate the read-only nature.

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 an explicit when-not instruction ('Never executes it') and indicates usage for re-reading or retrieving results of unexpired prepared actions. It doesn't explicitly name alternative tools, but the sibling names (e.g., execute_confirmed_action, cancel_prepared_action) make the contrast 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the classification categories, which hints at the output, but does not disclose any side effects, return format, or constraints beyond that. This is acceptable but not rich.

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

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

The description is a single sentence, front-loaded with the action verb, and contains no filler. Every word contributes to the meaning.

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

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

With three parameters, no output schema, and 0% parameter coverage, the description is too sparse. It does not explain how to select months, the role of client_id or invoice_key, or what the classification result looks like. The categories provide some context but not enough for an agent to confidently invoke the tool.

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

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

Schema description coverage is 0%, so the description must compensate. It adds the qualifier 'live FYI months' for the months parameter, but does not explain client_id or invoice_key, leaving two parameters completely undocumented. The description provides only minimal added meaning beyond the schema.

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

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

The description uses a specific verb 'Classify' and clearly specifies the resource ('selected live FYI months') and the output categories (unsplit, split, partially allocated, ambiguous, missing, inconsistent). This distinguishes it from sibling tools like prepare_interim_split or plan_client_billing, which suggest mutating or planning actions rather than 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 implies usage by stating what the tool does, but provides no explicit when-to-use or when-not-to-use guidance, and does not mention alternative tools. The phrase 'selected live FYI months' gives some context but no exclusions or scenarios.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds behavioral context by emphasizing 'no-write' and 'next safe live check', reinforcing safety and the specific planning behavior. It does not contradict annotations and provides useful extra context beyond them.

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

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

The description is a single well-constructed sentence that front-loads the verb and core purpose, with no wasted words. It efficiently covers both the plan construction and the output of the next safe check.

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 gives a clear overview of what the tool does and its safety profile, and with annotations covering the read-only nature, it is reasonably complete for a high-level understanding. However, it lacks parameter explanations and does not clarify how it differs from sibling planning tools like prepare_interim_split or prepare_job_allocation, nor does it describe the plan's structure or return value in 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?

Schema description coverage is 0%, so the description must compensate for parameter meaning, but it does not explicitly explain client_id, target_month, target_year, or invoice_key. The phrase 'client/Xero/allocation information' only vaguely hints at client_id and possibly invoice_key, leaving target month/year unaddressed. This is minimal compensation at best.

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

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

The description clearly states the tool's purpose with a specific verb 'Build' and resource 'no-write billing plan', and adds a distinct output 'identify the next safe live check'. This distinguishes it from sibling tools like prepare_direct_invoice or execute_confirmed_action by emphasizing it is planning-only and does not write.

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 conveys clear context: it builds a plan and identifies a safe next step, implying it should be used before executing write actions. However, it does not explicitly name alternatives or state when not to use this tool, 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?

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds a behavioral rule about blocking repeating clients without override, which is useful. However, it does not disclose what 'prepare' actually returns or what happens on successful preparation, so value beyond annotations is moderate.

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

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

The description is two sentences, front-loaded with the core purpose, and every word adds value. 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?

With 7 parameters, no output schema, and no parameter descriptions in the schema, the description is far too sparse. It does not explain the jobs array structure, what 'prepare' returns, or how to provide the override parameter. The tool cannot be correctly invoked based on this description alone.

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 7 parameters with 0% description coverage, so the description must compensate. It partially does by implying invoice_type='Final' via 'no-interim' and by referencing allow_repeating_client via 'duplicate-billing override'. But it fails to explain jobs, amount, theme, approve_invoice, or client_id, leaving most parameters ambiguous.

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 'Prepare a no-interim direct invoice' with a specific verb and resource. The 'no-interim' qualifier distinguishes it from sibling tool prepare_interim_split, 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 description gives clear context for use: direct invoices only, not interim. It also explicitly states a usage rule for repeating clients: they are blocked unless the duplicate-billing override is explicit. However, it does not name alternative tools or explicitly state when not to use it beyond the repeating-client block.

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

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

The description says 'prepare' which implies creating a mutable prepared action, but the annotations declare readOnlyHint=true. This contradicts the read-only behavior. The description does add 'but do not execute' which is helpful, but the contradiction with the annotation is a serious issue.

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, well-structured sentence that front-loads the primary actions. It is concise and contains no fluff, every word adds value.

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 too short given the tool's complexity. It does not explain what 'prepare' actually does, whether it creates a draft, how it interacts with cancel/execute sibling tools, or what the output looks like. With no output schema and minimal annotations, this leaves significant gaps.

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

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

Schema description coverage is 0% and the description provides no explanation of client_id, target_month, target_year, or invoice_key. With four parameters and no parameter-level descriptions, the agent has to guess how to populate them.

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 validates live FYI interims and prepares a permanent full-invoice service split without executing it. The verb 'prepare' and resource 'service split' are specific, and the contrast with 'do not execute' distinguishes it from execution tools.

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

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

The description gives clear context: it is for validating interims and preparing a permanent split. It does not name explicit alternatives, but the context is sufficient for an agent to recognize when to use this tool, especially with sibling tools like prepare_direct_invoice and prepare_job_allocation.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds the 'never mix service types' constraint and the merge behavior, but does not clarify what 'prepare' actually does (e.g., whether it creates a draft action) or address the openWorldHint annotation. This is comparable to the get_calls calibration example where annotations cover safety and the description adds scoping details.

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 short sentences, front-loaded with the main purpose and a critical constraint. Every word earns its place; there is no filler or repetition.

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

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

With 9 parameters, 4 required, no output schema, and zero parameter description coverage, the description is far too sparse. It does not explain the role of theme, invoice_key, approve_invoice, confirm_ambiguous_remaining, or the relationship between months and jobs. An agent would struggle to invoke this tool correctly without additional context.

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

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

Schema description coverage is 0% for top-level parameters, and the description only vaguely references 'months' and 'jobs'. It provides no details about client_id, service_line, invoice_type, approve_invoice, confirm_ambiguous_remaining, theme, or invoice_key. Even the $defs descriptions are part of the schema, not the tool description, and the description fails to compensate for the missing parameter 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 uses a specific verb 'Prepare' with a clear object 'one complete service-type allocation' and adds the action 'Merge that service's months/jobs'. The constraint 'never mix service types' distinguishes it from sibling tools like prepare_interim_split and prepare_direct_invoice, making its unique scope obvious.

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

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

The description clearly implies when to use the tool: to prepare an allocation for a single service type, merging that service's months and jobs. The 'never mix service types' rule provides a strong usage boundary, but it does not explicitly name alternatives or describe when not to use it, though the sibling tool list gives context.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds context by clarifying the data source (imported snapshot) and explicitly excluding raw SQL and live-job claims, which helps the agent set expectations. It doesn’t describe return format or filtering semantics, but the annotations lower the bar and the added constraints are valuable.

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?

Extremely concise: two sentences, no filler. The key safety constraint is front-loaded, and every clause earns its place.

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

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

Given moderate complexity (6 parameters, 5 operations, nested filter object) and no output schema, the description covers purpose and safety but leaves gaps: how filters are combined, what each operation returns, and what columns are valid. It is minimally viable but not comprehensive.

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

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

Schema description coverage is 0%, yet the description only says 'count/filter/group,' which maps loosely to operation, filters, and group_by but adds no detail about valid column names, filter behavior, or how limit/offset apply. The schema’s enum for operation and named parameters provide some self-documentation, but the description does not compensate for the lack of parameter-level guidance.

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

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

Clear and specific: the tool 'count/filter/group the imported FYI client snapshot,' exactly describing its function with a concrete resource and operations. This distinguishes it from siblings like describe_client_catalog or search_clients.

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 only usage-related guidance is a constraint ('structured operations only—never raw SQL or live-job claims'), which implies a safe query tool but does not explicitly say when to choose this over alternatives like search_clients or find_client. No when-not-to-use conditions or direct comparisons.

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

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

Annotations already cover readOnly, idempotent, and non-destructive traits, so the bar is lower. The description adds meaningful behavioral context: it ranks candidates proposes a non-exact match and requires user confirmation, which goes beyond the structured fields and clarifies the tool's interactive nature.

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

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

The description is two sentences, front-loaded with the primary action 'Rank client candidates,' and every word adds value. It is concise without sacrificing essential 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 tool is simple with 2 parameters and no output schema. The description covers the core purpose and workflow but omits details like return format and limit behavior. It is adequate for a basic search tool but leaves some gaps for an agent relying solely on this description.

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

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

Schema description coverage is 0%, so the description must explain parameters. It only hints that 'query' is a name to compare, but fails to define the 'limit' parameter or how results are returned. This is insufficient for an agent to fully understand parameter behavior.

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

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

The description uses a specific verb 'rank' with resource 'client candidates', clearly distinguishing this from sibling tools like find_client and query_client_catalog. It further specifies a non-exact matching workflow with user confirmation, which is unique and actionable.

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

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

The description implies usage for fuzzy client name matching with user confirmation, suggesting when this tool is appropriate. However, it does not explicitly contrast with sibling search tools or state when to prefer one over another, leaving some ambiguity.

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