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

Adds real context beyond the annotations: it calls out to NAV, requires a live NAV Online Számla connection, and is unavailable on sandbox accounts. It does not cover failure modes for invalid numbers or response shape, but the external-dependency disclosure is 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?

Three tight sentences, front-loaded with the action and followed by usage and the key constraint. Nothing is redundant.

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 read-only lookup with full schema coverage, the description covers what it does, when to use it, and the account-level prerequisite. Return-value detail is limited to 'company data' given no output schema, but that is a minor gap.

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

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

Schema coverage is 100% with a single parameter fully described including a pattern and example. The description adds no additional parameter meaning, so the schema baseline of 3 applies.

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

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

States a specific verb and resource (looks up a Hungarian tax number at NAV) and what it returns (company data behind it). This is clearly distinguishable from sibling partner/listing tools.

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

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

Explicitly says to use it to validate a tax number before creating a partner, which is a clear usage context. It also states the operational precondition (live NAV Online Számla connection, not sandbox), though it names no alternative tool.

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

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

With readOnly/idempotent annotations already present, the description adds valuable behavioral detail: default public URL behavior, Claude Desktop incompatibility with base64, ~1.33x context overhead, and rendering risks. 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?

The description is three sentences that front-load the behavior, then add only necessary caveats. Every sentence earns its place, and the cost/rendering warnings are compactly expressed.

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

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

For a two-parameter read-only tool with no output schema, the description is complete: it states the return form, default behavior, when to override it, and the trade-offs. An agent has enough context to call it correctly and 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 schema already covers both parameters at 100%, so the baseline is 3, but the description adds significant meaning: it names 'url' as the default, instructs when to use base64, quantifies the context cost, and warns about client support. This exceeds schema-only information.

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 and resource: 'Gets the document PDF' and identifies two return formats. It is not a tautology, but it does not explicitly distinguish itself from the sibling billingo_get_document_public_url even though both can yield a public URL.

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

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

The description gives explicit format-selection guidance: default URL is 'what you want in almost every case' and base64 should be used 'only when a caller specifically needs the raw PDF bytes.' It does not, however, mention sibling tools or say when to prefer this tool over get_document_public_url.

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, and the description reinforces this with 'Nothing is modified.' It also discloses that the tool creates the export, waits for completion, returns the file, truncates very large exports with an explicit note, and that binary formats may not display inline. This is rich behavioral context 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?

Every sentence in the description contributes meaningful information. The main purpose is front-loaded, followed by behavioral notes and output-type distinctions. It is concise enough to read quickly while covering all important nuances.

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 5 parameters, no output schema, and a complex format-dependent return behavior, the description covers the key operational aspects: no side effects, waiting/truncation behavior, and inline-display limitations. Schema handles the remaining parameter details, so nothing critical is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining how the format parameter behaves (textual vs binary output, truncation behavior, and that a narrower date range returns the whole export). This extra semantic context justifies a 4.

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

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

Description opens with a specific verb and resource: 'Exports documents in a date range to a downloadable file'. It clearly distinguishes itself from siblings like billingo_download_document by emphasizing date-range export and multiple accounting formats. The explicit format examples further anchor the 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 gives clear scenarios: use for date-range exports in Billingo-supported formats, with guidance on textual vs binary outputs. However, it does not explicitly name alternatives such as billingo_download_document or say when not to use them, so it stops short of a full when/when-not routing.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered structurally. The description adds no behavioral context of its own - no indication of what happens for an unknown id (error vs empty) or how missing records surface.

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 short sentence with no filler, and the resource and keying mechanism are 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 trivial single-record getter with rich annotations, full schema coverage and an output schema, the description is sufficient to call it correctly. The only gap is error/not-found behavior for an invalid id.

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

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

Schema coverage is 100% with a single documented 'id' parameter ('Bank account id.'), so the schema carries the semantics. The description only restates that lookup is by id and adds nothing about format or validity constraints.

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

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

States a specific verb+resource: 'Returns a single bank account by id.' The singular 'single...by id' implicitly distinguishes it from the plural sibling billingo_list_bank_accounts, though it never names that sibling explicitly.

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 only implied: the phrase 'by id' signals you need a known identifier, which steers agents toward list_bank_accounts first when they don't. There are no explicit when-to-use/when-not statements or named 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 readOnly, idempotent, and openWorld, so safety is covered. The description adds meaningful context by specifying this is the rate Billingo itself would apply rather than a market rate. It stops short of disclosing rounding/precision, direction semantics, or freshness behavior, which are relevant for a rate lookup.

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 compact sentence with the key qualifier ('Billingo would apply') front-loaded. No wasted words.

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

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

An output schema exists so return-value explanation isn't required, and the schema fully documents parameters. But for a tool whose main misuse risk is fetching today's rate for a historical document, the description omits that context entirely, leaving the schema's date note to carry it.

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

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

Schema description coverage is 100%, with clear enum and a well-annotated date parameter, so the baseline of 3 applies. The description itself contributes nothing to parameter meaning — it never mentions source/target ordering or the date option.

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?

Names a specific verb ('Returns') and resource ('conversion rate') with a scope qualifier ('between two currencies'), and the phrase 'Billingo would apply' distinguishes it from a generic market-rate lookup. No sibling tool offers a comparable function, so no explicit differentiation is needed, but the definition doesn't call out its uniqueness.

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

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

The description gives no guidance on when to call this versus other tools, no mention of prerequisites, and no hint that the date parameter supports historical rates — that crucial guidance ('for a backdated document pass its fulfillment_date') lives only in the schema, not the prose.

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 openWorldHint, so the safety profile is covered and the description's job is lighter. It adds the lookup-mode distinction, but says nothing about error behavior when neither identifier is given, precedence when both are given, or auth requirements.

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, the action first and the parameter rule second, with no filler. Every clause carries information an agent needs before calling.

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 an output schema present, return values needn't be described, and the identifier semantics are handled. The only gap is edge-case behavior (no identifier supplied, or both supplied), which is minor for a simple read 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 coverage is 100%, so baseline is 3, but the description adds real meaning the schema lacks: it explains that the two parameters are mutually exclusive alternatives rather than both-optional fields, and clarifies vendor_id is a reference set at creation time. That resolves an ambiguity the bare schema leaves open.

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 ("Returns a single document"), which cleanly separates it from the plural billingo_list_documents sibling. It doesn't name adjacent document tools like download_document or get_document_public_url, but the singular-retrieval framing is unambiguous.

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

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

The alternation rule "Give either `id` or `vendor_id`" gives usable calling guidance, but there is no explicit statement of when to pick this over list_documents, get_document_public_url, or download_document, nor what happens if neither argument is supplied. Usage is implied rather than directed.

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 openWorldHint, and the description is consistent with them. However, it adds no behavioral context beyond the annotations—no pagination, empty-result behavior, or scope 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?

A single front-loaded sentence with no wasted words. It states the operation and return subject immediately.

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

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

The tool is simple: one required id parameter, annotations present, and an output schema exists. The description tells the agent what the call returns, which is sufficient for correct invocation, though it could mention empty or paginated results.

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 100% description coverage and only one parameter, 'id', already documented as 'Document id.' The description adds no additional meaning or format constraints beyond the schema baseline.

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

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

States a specific verb and resource: returns payments recorded against a document. It distinguishes itself from the sibling get_document by focusing on the payments subresource, though it does not explicitly contrast with get_document or get_document_reminders.

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

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

Provides no explicit guidance on when to use this tool, when not to, or which sibling to choose instead. The intended use is only implied by the phrase 'payments recorded against a document.'

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered; the description adds the non-obvious fact that the resulting URL grants public, unauthenticated access. It does not say whether the link expires or can be revoked, which is the one remaining behavioral detail an agent would want.

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; the public-access caveat is packed into the same sentence rather than trailing as an afterthought.

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 an output schema present, the return shape needn't be described, and one fully-documented parameter plus rich annotations make this adequate. Only URL lifetime/revocability is missing, a minor gap for such a narrow 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?

Only one parameter ('id') and schema description coverage is 100%, so the schema fully documents it; the description adds nothing about the id's meaning or scope. Baseline 3 applies when the schema carries the load.

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 ('Returns') and a precise resource ('shareable public URL for the document'), which clearly separates it from billingo_get_document (metadata/body) and billingo_download_document (file bytes). It stops short of naming those siblings explicitly, so differentiation is inferred rather than stated.

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

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

The phrase 'viewable without a Billingo login' implies the sharing use case but never says when to choose this over get_document or download_document, nor whether a prerequisite (existing document, permissions) applies. Usage is implied, not directed.

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 openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context by naming the reminder groupings returned, but it does not discuss permissions, scoping, or edge cases beyond that.

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

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

The description is a single tight sentence with no filler. It front-loads the action and resource and then lists the grouping categories efficiently.

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 an output schema, full parameter schema coverage, and read-only annotations, so the description only needs to orient the agent. It does that by stating the returned reminder categories. Minor missing context about error behavior or authentication does not significantly impair correct invocation.

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

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

Schema coverage is 100% and there is only one required parameter, whose description already says 'Document id.' The tool description does not add additional meaning beyond the schema, but the schema fully documents the parameter, so the baseline score applies.

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

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

The description states a specific verb and resource: it returns payment reminder events for a document. The grouping into sent, upcoming, and postal-mail reminders further clarifies the resource. It does not explicitly distinguish itself from nearby sibling tools such as billingo_get_document_payments, but the resource is clear enough to identify the operation.

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

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

The description gives no when-to-use guidance, no exclusions, and no named alternatives. It is implied that an agent calls this when it needs reminder events for a document, but there is no explicit routing information among sibling tools.

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

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

Adds valuable context beyond annotations by explaining the meaning of 4xx 'NavOnlineSzamla is not found' errors and clarifying that it indicates no NAV record rather than a failure. Annotations already cover safety (readOnly, idempotent, openWorld).

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 plus an error clarification, front-loaded with return details and usage. No unnecessary text.

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

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

Given the simple one-parameter input, output schema, and annotations, the description covers what is needed: return fields, usage context, and error behavior. No gaps for calling correctly.

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

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

Schema coverage is 100% with one parameter 'id' fully described. The description adds no additional parameter semantics, but none is needed.

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

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

States a specific verb (returns) and resource (NAV Online Számla reporting status of a document), and lists the return fields. However, it does not explicitly differentiate from sibling tools like get_document, though the resource is unique enough that confusion is unlikely.

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 a clear use case ('Use this to check whether reporting succeeded') and explains error conditions, but does not explicitly name alternatives or state when not to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds useful scope details: the data belongs to the organization owning the API key, includes specific fields, and explicitly excludes company-profile data like name, id, and address. It does not add auth or rate-limit context, but it meaningfully supplements the annotations.

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

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

Three short sentences, front-loaded with the return contents, followed by the key exclusion and the use case. Every sentence adds useful information with no repetition or filler.

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

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

An output schema exists, so the description need not document return values in detail. It explains the scope, included fields, and exclusions well enough to call the tool correctly. The only meaningful gap is not clarifying the relationship with the sibling NAV status tool.

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

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

The tool takes zero parameters, so the baseline is 4. There are no parameter semantics to explain, and the description does not need to compensate for any schema gaps.

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

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

The description clearly states the verb and resource: it returns account-level organization data tied to the API key, and specifies tax code, subscription, and NAV connection status. It also explicitly rules out company-profile fields such as name, id, and address. It does not distinguish itself from the sibling billingo_get_online_szamla_status, which also relates to NAV status.

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

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

It gives an explicit use case: checking subscription or NAV connection status. However, it does not explain when to use the dedicated sibling billingo_get_online_szamla_status instead, and it provides no further exclusions or prerequisites. The guidance is present but incomplete against the sibling set.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, and the description adds nothing beyond them. It says nothing about error behavior for an unknown id or whether related data (e.g. addresses, tax info) is included, so it contributes no behavioral value.

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

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

A single front-loaded sentence with no wasted words. However, the brevity reflects under-specification rather than disciplined density.

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

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

This is a simple single-parameter read with an output schema and full annotation coverage, so the safety and return shape burdens are handled elsewhere. The description is adequate, though a note on missing-record behavior would make it complete.

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

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

Schema description coverage is 100%, with the single id parameter documented in the schema, so the baseline is 3. The phrase "by id" merely restates the schema and adds no format or constraint detail.

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

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

States a specific verb and resource ("Returns a single partner") plus the lookup key, which implicitly separates it from the sibling list_partners. It does not explicitly name the sibling or clarify it is a full-detail read, so it falls 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?

No indication of when to call this instead of billingo_list_partners, nor any precondition such as needing a known partner id. The agent must infer usage entirely from the name.

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 openWorldHint, so the safety profile is covered. The description adds nothing beyond the bare operation – no error behavior for missing ids, no note about which organization's data is queried despite openWorldHint being true.

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

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

A single front-loaded sentence with no filler. It is efficient, though the terseness leaves the reader with nothing beyond the bare statement of the operation.

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?

An output schema exists, so return values need not be described, and annotations cover the safety profile for this simple one-parameter read. The only gap is the lack of any error or not-found guidance, which is minor here.

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

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

Schema coverage is 100% and the single id parameter is documented in the schema as "Product id." The description restates the same fact without adding format, range, or source-of-id guidance, so the schema does all the work.

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 (returns) and resource (a single product) scoped by id, which clearly separates it from a list operation. It does not name a sibling such as billingo_list_products, so differentiation is only implicit in the wording.

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 "single product by id" implies this is the fetch-one counterpart to a list tool, which an agent can infer from the sibling names. There is no explicit when-to-use or when-not-to-use statement, and no mention of what happens if the id is unknown.

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, and idempotentHint=true, covering the safety profile. The description adds only that the returned quantity is 'current', which is mild behavioral context but does not disclose potential caveats such as data freshness, units, or whether the quantity represents available vs. physical stock. Since annotations carry most of the burden, a mid-range score is appropriate.

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

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

The description is a single, front-loaded sentence with no filler or repetition. It conveys the action, the resource, and the returned information efficiently.

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 getter with rich annotations, the description is nearly complete. It tells the agent what will be returned ('current inventory quantity'). However, since there is no output schema, a slightly more explicit statement about the return format could improve completeness, though it is not essential for such a trivial tool.

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

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

The schema already provides 100% coverage with a clearly described 'id' parameter. The description does not add any parameter-level meaning beyond what the schema states, so the baseline score of 3 applies.

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

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

The description names a specific verb ('Returns'), a specific resource ('inventory quantity'), and the target ('a product'). This clearly distinguishes it from siblings like billingo_get_product, which would return broader product details. The tool's name and title reinforce the purpose without adding confusion.

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

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

The description gives no guidance about when to use this tool versus alternatives such as billingo_get_product or billingo_list_products. There is no stated context, prerequisite, or condition that would help an agent choose it over similar product-related tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is covered structurally. The description adds nothing beyond that — no note on what happens with an unknown id, whether the response is a live upstream fetch (openWorld), or any rate/consistency caveat.

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 short, front-loaded sentence with no filler or redundancy. It is arguably too terse rather than padded, but nothing in it is wasted.

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?

An output schema exists, so return-value explanation is not required, and the single parameter is fully described in the schema. However, for an open-world fetch by id, the description never says whether a missing/invalid id errors or returns empty, leaving a small but real 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?

Only one parameter exists and the schema documents it fully ("Spending id.", 100% coverage, required). The description's "by id" is consistent with the schema but adds no meaning beyond it, so the baseline 4 for a fully documented single-parameter tool applies.

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

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

States a specific verb and resource ("Returns a single spending") and the qualifier "by id" scopes the operation. The word "single" implicitly contrasts with the sibling billingo_list_spendings, though the alternative is never named, so differentiation is only inferable.

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

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

There is no explicit guidance on when to use this tool versus billingo_list_spendings or any other sibling, no prerequisites, and no error/not-found conditions mentioned. The only usable cue is the implicit 'you need one record and already have its id'.

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 openWorldHint=true, so safety and repeatability are covered. The description adds that results are scoped to the organization's own configuration, but says nothing about pagination behavior or ordering. Acceptable given the annotation coverage, but thin.

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. It is efficient, though the terseness leaves room for one more useful clause about paging or the singular sibling.

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-required-parameter list tool with full schema coverage, an output schema and read-only annotations, the description covers the essentials. Only minor gaps remain around pagination behavior and sibling routing, which structured fields largely absorb.

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

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

Schema description coverage is 100%, with page and per_page fully documented including ranges and defaults, so the schema carries the parameter burden. The description adds nothing about pagination semantics, which is acceptable at this baseline.

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

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

States a specific verb ('Lists') and resource ('bank accounts') along with scope ('configured on the organization'), which cleanly separates it from the singular sibling billingo_get_bank_account. It stops short of naming that sibling explicitly, so it is clear but not fully differentiated.

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

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

The description gives no when-to-use context and never mentions the obvious alternative (billingo_get_bank_account) or any prerequisite such as authentication. Usage is only inferable from the tool name.

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 openWorldHint, so the safety profile is covered. The description adds genuine domain context beyond that — that blocks are invoice number ranges and that every document belongs to one — which explains the data model rather than repeating the schema.

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

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

Two short sentences, front-loaded with the definition and followed by the practical reason to call it. Nothing here is padding.

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 an output schema present and both parameters documented, the description only needs to convey the concept and the use case, which it does. A note on result volume or typical block count would have closed the remaining gap.

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

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

Schema description coverage is 100% (page and per_page are fully documented in the schema), so the baseline is 3. The description adds no pagination or filtering semantics of its own.

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 ('Lists document blocks') and immediately glosses the domain term as 'invoice number ranges', which is the key disambiguation. It does not name any sibling tool, but no sibling deals with blocks, so the risk of confusion is low.

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

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

Gives a concrete use condition: 'you need a block id to create an invoice', which tells the agent why and when to call it. It stops short of explicit when-not-to-use guidance or naming an alternative, so it lands at clear context rather than full routing.

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

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

Annotations already declare readOnly, idempotent and openWorld, so the safety profile is covered structurally. The description adds one genuine behavioral fact — results are returned newest first — but says nothing about pagination limits, total counts, or rate behavior beyond what the schema states.

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 operation and ordering, then the filter set. No filler or repetition; the small cost is a dense comma-list that is slightly harder to scan than a structured breakdown.

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 15-parameter read-only list tool with an output schema and 87% schema coverage, the description establishes scope, default ordering and the filter surface adequately. The missing piece is paging guidance, which is left entirely to the schema.

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

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

Schema description coverage is 87%, so per-parameter meaning is largely already documented. The description's filter list (type, invoice date range, fulfillment date range, payment date range, last modification time, partner, payment status/method, block) maps onto parameters but adds no format, interaction, or precedence 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?

Specific verb + resource ("Lists documents") with an enumeration of what counts as a document (invoices, receipts, proformas, drafts) and an explicit default ordering ("newest first"). An agent can distinguish this list operation from the singular get_document sibling, though no sibling is named directly.

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 enumerates the filter axes, which implies usage for filtered retrieval, but never states when to prefer this over siblings such as billingo_export_documents (bulk export) or billingo_get_document (single record). No exclusions or prerequisites are given.

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

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

Annotations already mark this as read-only, idempotent, and open-world. Beyond that, the description discloses useful behavior: results are ordered newest first, paging is supported, and search is limited to partner name. It does not cover rate limits or response shape, but the output schema exists.

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

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

Two short sentences, front-loaded with the operation and followed by key behavioral details. Every phrase earns its place, with no repetition or filler.

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

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

The tool is simple, its parameters are fully documented in the schema, and an output schema exists. The description covers ordering, paging, and search scope. The only minor gap is explicit routing guidance relative to billingo_get_partner.

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 already 100%, with all three parameters fully documented. The description reinforces paging and free-text search over partner name, but adds no syntax, defaults, or constraints beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states a specific verb and resource: it lists partners (customers). It also adds useful distinctions such as 'newest first' and free-text search over partner name. It could more explicitly contrast with the sibling get_partner, but the plural list operation is clear.

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

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

Usage is implied: this is the listing tool, and search/paging are supported. However, the description does not explicitly say when to use this versus billingo_get_partner or other retrieval siblings, nor does it mention exclusions or prerequisites.

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

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

Annotations already state readOnlyHint=true, idempotentHint=true, and openWorldHint=true, covering the safety profile. The description adds no behavioral context beyond the purpose statement, such as pagination behavior, search semantics, or catalogue scope 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 a single front-loaded sentence with no wasted language. It immediately communicates the tool's resource and scope.

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

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

This is a low-complexity list operation, and the schema, annotations, and output schema already cover parameters, safety, and return values. The description is sufficient for correct invocation, though it could mention search or pagination to be fully self-contained.

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

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

Schema description coverage is 100%, so the schema already documents page, query, and per_page clearly. The description adds no parameter-level meaning beyond what the schema provides, so the baseline 3 is appropriate.

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

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

The description uses a specific verb and resource: 'Lists products and services from the product catalogue.' It is clear what the tool does, though it does not explicitly distinguish this listing tool from sibling retrieval tools like billingo_get_product.

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

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

Usage is implied by 'Lists products and services from the product catalogue,' but there is no explicit guidance on when to use this versus billingo_get_product or billingo_get_product_quantity, nor any stated prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is clear. The description adds little beyond 'recorded' and optional filtering; it does not elaborate on pagination behavior, return format, or rate limits. With annotations covering the core behavior, a 3 is appropriate.

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

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

The description is a single, front-loaded sentence with no wasted words. It efficiently conveys the core action and the optional filter.

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 presence of an output schema, complete parameter descriptions, and clear annotations, the description is sufficient for an agent to call the tool correctly. It could mention pagination defaults, but that gap is minor because the schema covers it.

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

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

Schema description coverage is 100%, so all four parameters (page, per_page, start_date, end_date) are fully documented in the schema. The description only restates the date-range filter and adds no semantics beyond what the schema provides. Baseline 3 is correct when the schema does the heavy lifting.

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

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

The description specifies a clear verb ('Lists') and resource ('recorded spendings (costs)'), and mentions the optional date-range filter. It distinguishes itself from the singular 'billingo_get_spending' by implication, though it does not explicitly name the 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 'optionally filtered by date range' implies when to use the date parameters, but there is no explicit guidance on when to choose this tool over 'billingo_get_spending' or other list tools. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds the output format (PDF receipt) and POS sizing intent, which is useful, but it does not disclose additional behavioral details such as error handling, authorization requirements, or document availability 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 front-loaded sentence with no filler. It efficiently conveys the output type, the target use, and the format in one line.

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

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

For a simple two-parameter read-only tool with full schema coverage, the description plus schema adequately cover what an agent needs: the document id, the size, and the PDF output. An explicit pointer to sibling document-retrieval tools would strengthen routing, but nothing critical is missing.

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

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

The input schema already fully documents both parameters: id as 'Document id' and size as thermal paper width with 58/80 enumeration. The description adds no new parameter-level meaning beyond reinforcing the POS sizing context, so baseline 3 is appropriate.

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

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

The description uses a specific verb ('Returns') and clearly identifies the deliverable: a printable PDF receipt for a document, sized for a POS thermal printer. This distinguishes it from sibling document tools like billingo_download_document by its receipt-specific POS 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 phrase 'sized for a POS thermal printer' gives a clear contextual signal for when this tool should be chosen over generic document download or public-URL tools. However, it does not explicitly name alternatives or state when not to use it, so it falls short of full guidance.

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