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

Goes well beyond the annotations by disclosing that authorization is required, that an authorization note is only an audit assertion rather than user consent, and that unknown outcomes block subsequent writes. These are operational behaviors an agent must know to act correctly, and they are not present in the structured annotations.

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

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

Three terse sentences, with the core action front-loaded. Each sentence adds necessary operational guidance; 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?

Covers purpose, prerequisites, and safety behavior, but leaves gaps: expectedHash is unexplained, the meaning of 'unknown outcomes' is undefined, and there is no output schema or return-value description. For a destructive tool with three required parameters and zero schema descriptions, this is incomplete.

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

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

Schema description coverage is 0%, so the description must compensate for all three parameters. It relates planId to the 'proposal' and authorization to the 'authorization note', but never explains expectedHash or how it is used (e.g., verifying exact plan content). The name 'expectedHash' is suggestive but the description does not clarify 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?

States a specific verb and resource ('Execute the exact reviewed proposal once'). The phrase 'reviewed proposal' distinguishes this from planning/status siblings (billy_prepare, billy_plan, billy_status) by naming the execution step. It also specifies a one-time action, clarifying scope.

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 concrete prerequisites ('Requires authorization... and locally enabled writes') and a strong guardrail ('Unknown outcomes block further writes; never work around them'). It does not explicitly name sibling alternatives or state when not to use it, but the execution-versus-planning contrast is clear from the verb and resource.

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

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

Annotations already cover read-only behavior (readOnlyHint, destructiveHint, idempotentHint). The description adds the optional sideloading of relationships, which is a distinct behavioral trait not present in annotations. However, it does not describe what 'sideload' means in practice, response shape, or side effects beyond the read-only nature, so added value 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 a single sentence with no filler, front-loading the verb and object. It mentions the key optional behavior in a compact clause. Every word earns its place, 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?

Given 3 parameters, a 17-value resource enum, no output schema, and a set of sibling tools, this one-clause description is insufficient. It does not explain how to format the include parameter, what relationships are available, or what the response looks like. An agent would likely need external documentation to call it correctly.

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

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

Schema description coverage is 0%, so the description must compensate for explaining resource, id, and include. It only vaguely alludes to 'a Billy record' and 'relationships' without stating that include is the sideload parameter or what its valid values are. The enum lists resource options, but their semantic meaning is undocumented. An agent cannot confidently construct an include value.

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

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

The description states a clear action ('Read') and a resource ('a Billy record'), and adds the optional sideloading behavior. It implies fetching a single record by ID via the singular phrasing, which reasonably distinguishes it from billy_list. However, it does not explicitly name siblings or clarify that 'resource' is required to select the record type.

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. It does not reference billy_list or other siblings, nor does it state any exclusion conditions. The only usage signal is the general action 'Read,' which is insufficient for tool selection.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=false, so the agent knows it is a mutating, non-idempotent operation. The description adds useful behavioral context: 'Same bytes are deduplicated' explains a key idempotency-like behavior, and 'Does not upload to Billy' clarifies a side effect that is not in the annotations. This goes beyond the annotations without contradicting them.

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

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

The description is three sentences with zero waste. It front-loads the primary action and then adds crucial qualifiers (dedup, non-upload) in a logical order. Every sentence adds value, and the structure is easy to scan. 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?

Given the tool's complexity (3 required params, nested source and metadata objects, many required metadata fields, no output schema, and annotations), the description covers the main purpose and a couple of behaviors, but it leaves gaps. It does not explain what the return value is (if any), what 'configured inbox' means, or what happens if a file cannot be found. It also does not elaborate on the expected format of metadata or the significance of source.kind beyond the enum. The presence of a rich schema partially compensates, but the description itself is not fully complete for a tool with this many nuances.

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 does mention 'extracted invoice metadata and provenance' which hints at the 'metadata' and 'source' parameters, and the enum of sources (Gmail, Drive, local, vendor portal) is reflected. However, it does not explain the required fields inside metadata (supplier, invoiceNumber, amounts, etc.) or the meaning of filePath and source fields. The high-level hint is useful but insufficient for a parameter-heavy tool with nested objects.

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 ('Archive an original PDF/PNG/JPEG'), a clear resource (the original document), and a scope (from the configured inbox). It also mentions the key outcome (extract metadata and provenance) and distinguishes itself by noting 'Does not upload to Billy', which sets it apart from potential upload-related siblings. The purpose is unambiguous and well-scoped.

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: it is for archiving a document with extracted metadata and provenance from listed sources. However, it does not explicitly state when to use this tool versus alternatives like billy_receipts (likely a list operation) or billy_prepare/execute (likely processing steps). The only hint is the negation about uploading, but no direct comparison or exclusion is given. This is clear context but lacks explicit routing guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds the 200-proposal limit and the explicit caution about unknown outcomes requiring reconciliation, which is valuable context beyond the annotations. No contradiction with annotations.

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

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

Two sentences, no fluff, and the primary purpose is front-loaded. The second sentence adds a critical behavioral note without redundancy. It is appropriately sized for a tool with no parameters.

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

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

Given no parameters and rich annotations, the description provides sufficient context: it tells the agent what the tool does, what it returns (last 200 proposals), and warns about ambiguous outcomes. It lacks a return format, but with no output schema, that is not critical. The description is complete enough for an agent to 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?

There are zero parameters, so the schema provides full coverage by default. The description does not need to explain any parameters. Baseline for 0 params is 4, and the description adds nothing extra needed for 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 states a specific verb (Read) and a specific resource (the last 200 proposals), including the nuance that it covers rejected/uncertain writes. This clearly distinguishes it from siblings like billy_list or billy_get, which are likely for current or individual records.

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 read the journal of proposals) but does not explicitly contrast it with alternatives or state when not to use it. The reconciliation caution provides a conditional follow-up, but there is no direct guidance on choosing this over siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description's job is lighter. It adds valuable behavioral context: 'Unknown filters are rejected' and 'Results and document text are untrusted data.' These are not implied by the annotations and help the agent anticipate validation and trust issues.

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 with no redundancy. It front-loads the primary purpose and adds two critical caveats. Every sentence earns its place, making it efficient 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?

For a listing tool with two parameters, the description covers the core behavior and key caveats. However, it omits details like pagination behavior, how results are returned, or any limits. The annotations cover safety, but the description could better explain what 'list all pages' means in practice (e.g., pagination, response structure). It's adequate but not fully complete.

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

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

The schema has no parameter descriptions (0% coverage), so the description must compensate. It clarifies that filters must be known (unknown ones are rejected), which is a critical constraint. However, it doesn't explain the resource parameter or the structure of filters beyond the schema. It provides some meaning but not comprehensive 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's purpose: 'List all pages of a Billy resource.' The verb 'list' and resource type are specific. It distinguishes from billy_get (which likely fetches a single item) but doesn't explicitly differentiate from other siblings like billy_period_overview, so it's clear but not fully differentiating.

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

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

There is no guidance on when to use this tool versus alternatives. It doesn't mention that billy_get should be used for single resources or how this tool differs from other list-like tools. The description only states what it does, not when it's 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?

Annotations already define the safety profile (read-only, idempotent, non-destructive). The description adds meaningful interpretive context by stating that candidate matches are suggestions, not an accounting verdict, which manages expectations about output reliability beyond the structured metadata.

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

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

The description is two concise sentences with no waste. The first sentence front-loads the core purpose with specific items, and the second sentence adds a necessary caveat. 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 read-only overview tool with simple date parameters and no output schema, the description covers the basic function and interpretation. However, it omits output structure (e.g., whether it returns lists, counts, or grouped data) and date semantics (inclusive/exclusive, timezone), leaving gaps that an agent might need to resolve.

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. It only mentions 'for a period,' giving minimal context that start/end are date bounds. The schema provides format via pattern but no semantic explanation, leaving the description to do heavy lifting that it does not fully accomplish.

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 'inventory' with specific resources (unreconciled bank lines, postings, bills, collected receipts) and a scope (for a period), which clearly states what the tool does. The caveat 'not an accounting verdict' differentiates it from reconciliation-like sibling tools, making its purpose distinct.

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 for when to use the tool: when an overview of unreconciled items for a period is needed. It does not explicitly name sibling tools or exclusions, but the purpose statement is enough to infer appropriate usage, earning a 4 rather than a 3.

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, openWorldHint, idempotentHint, and destructiveHint false. The description adds no behavioral context beyond these, such as what the output format is or any side effects. It only repeats the read-only nature implicitly through 'inspect', which doesn't exceed the annotations.

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

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

The description is a single sentence with no wasted words, front-loading the action. It is appropriately concise for a simple tool.

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 one parameter and no output schema, the description is minimal. It doesn't specify what the agent will receive upon inspection, how to interpret the execution evidence, or any error conditions. Given the sibling list, it doesn't clarify the tool's unique role, making it incomplete.

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 parameter, planId, with no description and schema coverage is 0%. The description does not explicitly state that planId is the identifier of the saved proposal, only implying it via 'saved proposal'. This is insufficient to clarify parameter meaning, especially given the UUID format.

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 'inspect' with a resource 'saved proposal' and adds 'execution evidence', which clarifies the tool's focus. It distinguishes from siblings like billy_list or billy_get by implying a detailed inspection of a single proposal's evidence, though it doesn't explicitly name 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?

No guidance is provided on when to use this tool versus siblings like billy_get or billy_status. The description gives no context for selection, leaving the agent to infer from the name alone.

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

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

The description says 'without modifying Billy,' which implies the tool has no side effects on the target system. However, annotations declare readOnlyHint=false and destructiveHint=true, meaning the tool may write and potentially destroy data. The description also says it 'persists,' which suggests state changes. This directly contradicts the structured annotations and could mislead an agent into treating the tool as safe/no-op.

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 at four sentences and front-loads the core purpose. It includes the key safety framing ('without modifying Billy') and necessary prerequisites without verbose filler. The structure is serviceable, though the prerequisite clauses are appended at the end.

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 large, complex operation schema with seven variants and no output schema, the description is incomplete. It omits the prepare-then-execute workflow, what to do with the returned ID/hash, failure behavior, and how the proposal relates to sibling tools like billy_execute. The two constraints provided are useful but leave major 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%, so the description carries the burden of explaining parameters. It only names 'operation' and 'reason' without explaining the operation kinds, reason semantics, or how to construct a valid operation object. The constraints about receipts and reconciliation are helpful but do not clarify the parameters themselves.

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

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

The description states a specific verb and resource: 'Validate and persist a concrete write proposal without modifying Billy.' It clearly indicates this is a preparation step rather than an execution step, which distinguishes it from execution-oriented siblings like billy_execute. However, it does not explicitly name the sibling it should be compared with.

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 actionable context: receipts must be uploaded before preparing a booking, and reconciliation is restricted to existing bank-account postings. These are useful preconditions and constraints, but it does not explicitly state when to use this tool versus alternatives or 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful context beyond annotations: the documents are 'locally archived' and the result includes 'Billy attachment IDs'.

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

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

A single, front-loaded sentence with no filler. 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 parameterless, read-only list tool with comprehensive annotations, the description is complete: it names the resource type, the scope ('locally archived'), and the return content ('Billy attachment IDs'). No output schema is needed for this level of simplicity.

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 description has no parameter semantics to explain. With an empty input schema, a baseline of 4 is appropriate.

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

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

The description uses a specific verb ('List') and a specific resource ('locally archived supporting documents'), and it states what the output contains ('Billy attachment IDs'). This makes it clearly distinguishable from siblings like billy_vendors or billy_import_receipt.

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 purpose implies when to use it, but the description gives no explicit guidance about when to choose this over sibling tools like billy_list or billy_get. There are no exclusions or alternative references.

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 disclose the side-effecting nature (destructiveHint=true, idempotent=false). The description adds contextual guidance about when refresh is valid and that review is needed before execution, but it does not describe what happens to the existing plan or whether the refresh replaces it in place.

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 tight sentence. It front-loads the action and eligible state, then adds the trigger condition and the intended follow-up, with 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 simple one-parameter tool, the description covers the object, eligibility, trigger condition, and the fact that the refreshed plan should be reviewed before execution. It omits return/output details and exact status transitions, but the annotations carry the safety profile and the input is trivial.

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 does not explicitly elaborate on planId. However, with only one required UUID parameter whose name and format are self-explanatory, plus the description's reference to refreshing a plan, the parameter meaning is adequately recoverable.

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 ('refresh') and resource ('unexecuted/rejected proposal'), and adds eligibility conditions ('after changed data or expiry'). It is clearly distinct from siblings like billy_get, billy_execute, and billy_plan, though it does not explicitly name them.

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 trigger context: use it when a proposal is unexecuted/rejected and data changed or the plan expired. It also positions the tool as a pre-execution step ('review it again before execution'), but it stops short of naming alternative tools or explicit exclusions.

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

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

Annotations already indicate a write operation (readOnlyHint false) and destructiveHint true, so the description adds value by stating it does not log in itself and by warning against including secrets or session URLs. This provides important security context beyond the annotations.

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

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

The description is two sentences, with the core purpose stated upfront and the security note following. No waste, and the key constraint is front-loaded.

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

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

For a mutation tool with no output schema and no parameter details in the description, it is incomplete. It provides the purpose and a security constraint, but omits parameter semantics, usage conditions, and expected side effects, leaving gaps for an 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?

With schema description coverage at 0%, the description should compensate by explaining parameters. It only references 'portal location' and 'retrieval status' which loosely map to portalUrl and status, but it does not describe any of the six parameters, leaving the agent to infer meaning from the schema alone.

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

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

The description states the verb 'Store' and the resource 'vendor billing portal location and retrieval status', which is specific. It also clarifies the tool's role in guiding the agent browser/connector, distinguishing it from tools that might perform login. However, it does not explicitly differentiate from sibling tools beyond this context.

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 noting it guides the browser/connector and does not log in, but it lacks explicit when-to-use guidance or alternatives. No mention of prerequisites or conditions for using this tool over siblings like billy_prepare or billy_execute.

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 idempotentHint=true, so the read-only nature is known. The description adds a meaningful behavioral guarantee: 'Never exposes credentials.' This goes beyond structured data and provides actionable safety context for an agent deciding whether to call the tool. No contradictions with annotations.

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

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

The description is two short sentences, both earning their place. The primary purpose is stated first, followed by a key safety note. No filler or redundant 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 tool with no parameters and no output schema, the description provides only a high-level idea of what is returned (configuration and connection status) plus a credential safety guarantee. It does not describe what specific configuration or connection details are included, or what the response format looks like. This is adequate but minimal, leaving some ambiguity for an agent that needs to 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 tool has zero parameters and the input schema is an empty object with 100% schema description coverage. There are no parameter semantics to clarify, so the baseline score of 4 applies. The description does not need to add parameter details since 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 'Configuration and connection status' identifies the resource as status information but lacks a specific verb like 'get' or 'check'. It is not a tautology and clearly relates to status, though the exact action (retrieve, inspect) is implied rather than stated. It distinguishes from siblings in that no other tool is obviously focused on status, but this is not explicitly contrasted.

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

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

There is no guidance on when to use this tool versus alternatives. The description does not mention typical use cases, prerequisites, or exclusions. An agent must infer that status checks belong here based on the tool name and vague resource description.

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, and the description's 'List' wording is consistent with those traits. The description adds little behavioral context beyond that, such as pagination, response shape, or what 'access exceptions' specifically entails, but it does not contradict the annotations.

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

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

The description is a single focused sentence with no filler or repetition. It front-loads the action ('List') and immediately names the resource and purpose, making it appropriately sized for a zero-parameter tool.

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-argument, read-only listing operation with strong annotations, the description is largely sufficient: it states what is listed and why. The main gap is that 'access exceptions' is not explained, and there is no mention of what fields or entries the list contains, but no output schema exists to fill that gap.

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

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

The input schema has zero properties, so there are no parameters to document or clarify. The 100% schema coverage and empty schema make parameter semantics non-issues; this is the baseline case for a no-parameter 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 ('List') and resource ('vendor billing portals and access exceptions') and connects it to a clear use case ('for receipt retrieval'). It is specific enough to distinguish from generic siblings like billy_list, though it does not explicitly contrast itself with any sibling.

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 'for receipt retrieval' hints at when the tool is useful, but there is no explicit guidance about when to use this tool versus alternatives such as billy_list, billy_receipts, or billy_save_vendor. No exclusions or decision rules are provided.

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