Billy MCP by usefulapi

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

Annotations only provide a destructiveHint, so the description carries the main burden and does so well: it discloses WRITE behavior, lack of duplicate checking, non-idempotency with duplicate creation on repeat calls, no notification being sent, and the underlying POST endpoint. These are exactly the behavioral traits an agent needs before invoking a write tool.

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

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

The description is front-loaded with 'WRITE: create ONE new contact' and packs duplicate behavior, notification behavior, idempotency, and endpoint into a compact paragraph. Every sentence earns its place and there is no redundant or filler 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?

For a mutation tool with a rich 13-parameter schema and minimal annotations, the description covers behavior, duplicate risk, idempotency, and endpoint well. The main gap is that there is no output schema and the description does not mention what the tool returns, such as the created contact or its ID, which an agent might need for follow-up calls.

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

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

Schema description coverage is 100%, and all 13 parameters are documented in the schema. The description only implies that the contact can be a customer and/or supplier, which maps to flags already explained in the schema, but adds no syntax, format, or constraint details beyond what is provided. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description states a specific verb and resource: create ONE new contact (customer and/or supplier) in the company's Billy account. It distinguishes the tool from siblings by noting that it does not check for duplicates and points to billy_list_contacts as the alternative. An agent can identify exactly what this tool does without opening the schema.

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

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

It explicitly instructs to call billy_list_contacts first to avoid duplicates, states that nothing is sent to the contact, and warns that a repeat call creates a second contact. This gives clear when-to-use and prerequisite guidance, including a named sibling alternative.

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

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

The single destructiveHint annotation says nothing about side effects, and the description fills that gap richly: not approved, not booked, not numbered into the ledger, not sent, no payment created, and explicitly non-idempotent ('a repeat call creates a second draft'). It also names the endpoint and that Billy assigns the invoice number.

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?

Front-loaded with a 'WRITE:' marker, then tight declarative sentences — state, what does not happen, idempotency, endpoint. No filler and no redundancy.

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

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

With no output schema, the description covers what the operation does and its lifecycle well, but it never hints at what the caller gets back (e.g., the created invoice id) to feed a later get/approve step. Small but real gap for a create tool.

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

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

Schema description coverage is 100%, so the parameters are already documented. The description adds only the state=draft mapping and that the contact must pre-exist; it does not extend line, currency, or tax_mode semantics beyond the schema, so the baseline 3 is right.

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 plus the exact resulting state: 'WRITE: create ONE invoice in the DRAFT state for an existing contact.' No sibling tool in the list creates invoices, so the agent can immediately distinguish this from the list/get 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?

Explains the intended context clearly — this produces a draft the user reviews, approves and sends in Billy itself, not a finalized or booked document. It also implies the prerequisite (contact must already exist), though it stops short of naming alternatives or explicit when-not-to-use cases.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description usefully discloses that line items are included in the response and gives the underlying endpoint, but says nothing about missing-id behavior (404), permissions, or response shape beyond 'its lines'.

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 very short sentences, front-loaded with the resource and return content, with the endpoint as supplementary context. Nothing 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?

With no output schema, the description carries some return-value burden and does state that lines are included, which is the key expectation for a single-bill fetch. It is nearly complete for a one-parameter read, with only error/edge behavior left unstated.

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

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

Schema description coverage is 100% and the single id parameter is fully documented, including its origin ('from billy_list_bills'). The description adds no format or constraint detail beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('One supplier bill by id') and adds the return scope ('with its lines'), so an agent knows this is a single-record fetch rather than a list. It doesn't explicitly name siblings, but 'get' vs 'list' and 'bill' vs 'invoice' are clear enough from the name and description.

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: fetch one bill when you have its id, as opposed to enumerating. There is no explicit when-to-use/when-not guidance or a named alternative such as billy_list_bills in the description itself (that reference lives in the schema).

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 readOnlyHint annotation already establishes this is a safe, non-mutating read, so the description's main burden is lifted. It adds that the response nests contact persons with names and e-mail addresses, but says nothing about error behavior for a missing id, permissions, or rate limits.

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 payload description before the endpoint notation. The raw 'GET /contacts/{id}' adds little for an agent but costs almost nothing.

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

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

There is no output schema, so the description should carry more of the return shape; it mentions only the nested contact persons collection and leaves the primary contact fields, error cases, and any pagination/expansion behavior unstated. Adequate but with a clear gap for a lookup tool.

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

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

Schema description coverage is 100% and the single 'id' parameter already documents its pattern and provenance ('from billy_list_contacts'). The description only restates 'by id', adding no format or constraint detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('One contact by id') and names the primary payload ('contact persons (names and e-mail addresses)'), which cleanly separates it from the sibling billy_list_contacts. It does not explicitly name that sibling as the alternative, so it stops short of a 5.

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

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

Usage is only implied: the phrase 'by id' tells the agent it needs an identifier already in hand, and the singular 'one contact' implies this is the single-record lookup counterpart to billy_list_contacts. No explicit when-to-use, when-not-to-use, or named alternative is given.

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

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

Annotations only declare readOnlyHint=true; the description adds real behavioral value by enumerating the returned line fields (product, description, quantity, unit price, amount, tax) and the payment associations, which is important since there is no output schema. It omits error behavior (e.g., missing id), auth scope, and rate limits, keeping it below a 5.

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

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

Two tight sentences with the payload contents front-loaded and no filler. The trailing 'GET /invoices/{id}' is mildly redundant given the tool name but efficiently encodes the REST mapping.

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

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

For a single-parameter read with an annotation covering safety and the return shape described in prose (no output schema), an agent has what it needs to invoke it correctly. Only the absence of error/empty-result behavior keeps it from being 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?

There is only one parameter and schema_description_coverage is 100%, so the schema already documents the id and its pattern; the schema even names billy_list_invoices as the source. The description adds no format or constraint detail beyond 'by id', so the baseline 3 applies.

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

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

States a specific resource (one invoice) and its scope (by id), and enumerates exactly what comes back, so it is clearly distinguishable from billy_list_invoices and billy_get_bill. It stops short of naming a sibling to route against, but the 'one invoice by id' scoping makes the boundary obvious.

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

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

Usage is only implied: 'by id' signals the agent should call this once it holds an invoice id, and the schema points at billy_list_invoices as the source. There is no explicit when-to-use statement, no when-to-prefer-billy_list_invoices guidance, and no mention of 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 declare readOnlyHint=true, so safety is covered; the description adds value by disclosing the exact HTTP surface (GET /organization) and the full set of sensitive company configuration returned. It does not discuss auth scope beyond the token implication or rate limits, keeping it short of a 5.

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: identity/resource first, the return payload next, then the routing hint and endpoint. No sentence is redundant, and the field list earns its length because there is no output schema.

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

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

With no output schema, the description carries the burden of documenting the return payload, and it does so field by field. Combined with the readOnly annotation, an agent has everything needed to call this and consume 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?

Zero parameters and an empty schema, so there is nothing for the description to disambiguate; baseline for a param-less tool is 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?

States a specific verb+resource (the Billy company / organization the token belongs to) and enumerates the exact fields returned (id, name, address, CVR, base currency, VAT settings, fiscal year, payment terms, invoice numbering, default accounts). No sibling tool returns organization data, so the agent can immediately distinguish it from the contact/invoice/product 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?

"Good first call" gives a clear usage context: call this to bootstrap company context before other operations. It does not name alternatives or exclusions, but none of the siblings are substitutes for this resource, so the guidance is adequate without them.

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

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

The annotations already declare readOnlyHint=true, so the safety profile is covered structurally. The description adds return-content context ('with its unit prices per currency') and the underlying endpoint, which is modestly useful, but says nothing about auth requirements or error behavior for an unknown id. With annotations carrying the safety story, this is adequate but not rich.

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

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

Two short sentences with no filler, and the substantive content (single product plus per-currency prices) is front-loaded ahead of the endpoint notation. The endpoint string is arguably redundant for an MCP tool but costs little.

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 with no output schema, describing the return as a product with per-currency unit prices gives the agent enough to know what comes back. Nothing critical is missing, though it could mention what happens if the id is not found.

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 is a single parameter and schema description coverage is 100%, so the schema fully documents 'id' including its pattern and provenance. The description only restates 'by id' and adds the per-currency output notion, which is not parameter syntax. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('One product by id with its unit prices per currency'), and the phrase 'one product by id' implicitly distinguishes it from the sibling billy_list_products. It stops short of explicitly naming the list counterpart as the alternative, so it is clear but not fully sibling-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?

No when-to-use, when-not-to-use, or alternative guidance appears in the description. The only routing hint ('from billy_list_products') lives in the schema, not the description, so the agent gets no explicit signal about when to call this versus list_products.

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

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

Annotations already establish readOnlyHint=true, so safety is covered. The description still adds real value beyond that: it discloses pagination ('Paged'), the concrete field set returned, and the downstream dependency on billy_list_bank_lines. It omits auth requirements and rate limits, which keeps it below a 5.

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

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

Two dense sentences with no filler, front-loading the resource and field list before the filtering hint and endpoint. The telegraphic phrasing ('Paged. GET /accounts.') is efficient, though the opening reads as a fragment rather than a clean statement of action.

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

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

With no output schema, describing the returned fields is genuinely necessary and it is done well; pagination and read-only status are also covered. Nothing critical is missing for a simple filtered list call, though a note on the default paging behavior or auth would make it 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 page, page_size and is_bank_account are already documented in the schema, making 3 the baseline. The description restates the is_bank_account semantics and adds the reason to use it, but supplies no syntax or format detail beyond the schema.

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

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

It names the exact resource (the chart of accounts) and enumerates the returned fields (account number, name, group, nature, VAT rate, bank-account flag, IBAN/bank name), plus the underlying endpoint GET /accounts. It also distinguishes itself from the sibling billy_list_bank_lines by stating the relationship between 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?

It gives a concrete selection condition (use is_bank_account=true to get the bank accounts whose ids billy_list_bank_lines needs), which routes the agent to a sibling correctly. It stops short of stating when not to use it or naming alternative list tools for non-account data, so it is clear context rather than full when/when-not 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=true, so the description's added value is the note that nothing is matched or reconciled and that results are scoped to a single account. It also flags paged retrieval, though it leaves ordering/pagination depth to the schema. Useful additions without contradicting 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 tight sentences: what it lists, what it returns, where to get the id, plus pagination and endpoint. Front-loaded with the core action and no filler.

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

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

With no output schema, the description compensates by naming the returned fields (date, description, amount, side, reconciled flag, receipt state). Combined with the account-id sourcing hint, read-only semantics, and pagination note, an agent has everything needed to invoke it correctly; the rich 100%-documented schema handles parameters.

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 15 parameters (q, side, status, date range, amounts, sort, entry_date_period) are already documented in the schema. The description lists output fields rather than explaining parameter semantics, adding no meaning beyond structured data; baseline 3 applies.

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

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

Specific verb (List) + resource (bank-statement lines) with explicit scope ('of ONE bank account') and an enumerated set of returned fields. The parenthetical '(read only; nothing is matched or reconciled)' preempts confusion with reconciliation tools, so an agent can tell what it does without opening the schema.

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

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

Gives a concrete prerequisite and routing hint: obtain account_id from billy_list_accounts filtered by is_bank_account=true. It scopes to bank lines rather than postings, but never explicitly states when to prefer a sibling (e.g. billy_list_postings) or 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?

readOnlyHint=true already tells the agent this is a safe read. The description adds that results are 'Paged' and gives the GET /bills endpoint, which is useful context beyond the annotation, but it says nothing about ordering guarantees, result-set size behavior, or how to continue past the first page (that detail lives only in the schema).

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

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

Two dense sentences: resource plus return shape first, then filters and paging, then the endpoint. Nothing is wasted and the most decision-relevant information is front-loaded.

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

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

With no output schema, listing the returned fields is a meaningful addition, and the filter/paging summary covers the 13-parameter surface. The remaining gap is that pagination continuation and default sort are left entirely to the schema, but for a read-only list tool this is close to complete.

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

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

Schema description coverage is 100%, so all 13 parameters are already fully documented including enums and date formats. The description only restates the filter dimensions at a higher level (state, supplier, dates, paid status) without adding syntax or format meaning, so 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?

States a specific verb and resource ('List bills') and immediately disambiguates the resource from the sibling invoice tools with '(purchase invoices from suppliers)'. It also enumerates the returned fields (supplier, dates, state, amount, balance, isPaid, invoice number), so an agent knows exactly what a bill is and what comes back.

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?

'Filter by state, supplier, dates or paid status. Paged.' describes capability rather than when to choose this tool over billy_get_bill or billy_list_invoices. No when-not or alternative is named; an agent must infer that this is the bulk/query path and get_bill is the single-record path.

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

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

Annotations declare readOnlyHint=true, and the description adds non-obvious behavior: search is not a server-side filter and applies only to the current page, and results are paged. It also names the HTTP method, though it omits auth/rate-limit 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?

Two compact sentences: the returned field list is front-loaded, followed by pagination/search caveats and the endpoint. No filler.

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

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

For a read-only list endpoint with 3 fully documented params and no output schema, the description covers return fields, search limitation, and pagination. 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 parameters are fully documented. The description still adds the case-insensitive matching scope for search and reiterates next_page paging, which goes slightly beyond the schema.

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

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

States a specific verb (List) and resource (contacts/customers and suppliers) and enumerates the returned fields. The plural/list scope is distinct from billy_get_contact and other billy_list_* siblings by resource.

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

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

Explains that search is applied to the returned page only and directs pagination via next_page, which is crucial usage context. However, it does not explicitly say when to choose this over billy_get_contact or how to filter server-side.

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?

readOnlyHint=true already covers the safety profile, and the description adds useful context: default ordering, that results are paged, and the endpoint. One caveat: it claims 'newest first by default' while the schema defaults to entryDate ASC (oldest first), a minor internal inconsistency the description does not reconcile. It also does not describe how to page beyond 'Paged'.

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

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

Two dense, front-loaded sentences plus the HTTP path; the return-field list is long but genuinely informative. Nothing is wasted, though the field enumeration could be trimmed since no output schema exists to rely on.

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 list tool with no output schema, the enumerated return fields (number, date, due date, state, amount, tax, balance, isPaid, contactId, currency) usefully fill that gap, and paging is flagged. The only shortfall is not explaining pagination flow or reconciling the stated default sort with 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 100%, so the schema already carries parameter meaning and the baseline is 3. The description's filter list ('state, customer, number, date, period, paid status or free text') maps onto existing params but adds no format, default, or interaction detail beyond what the schema documents.

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

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

States a specific verb ('List') and resource ('sales invoices and credit notes'), then enumerates the returned fields. The 'sales' qualifier plus the field list cleanly separates it from billy_list_bills and billy_get_invoice, so an agent can pick it without opening sibling schemas.

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

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

It lists what can be filtered (state, customer, number, date, period, paid status, free text), which implies the tool is for browsing/filtering invoice collections. However it never states when to use this over billy_get_invoice (single record) or billy_create_draft_invoice, and gives no 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 declare readOnlyHint=true, so 'Read only' is partly redundant, but the description adds traits the annotations do not cover: 'Paged' discloses pagination behavior and 'GET /postings' reveals the underlying read endpoint. It stops short of describing pagination limits or ordering, so not a 5.

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 dense paragraph that front-loads the resource, then the returned fields, then filtering, then behavior. Every clause carries information with no filler.

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

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

With no output schema, the description usefully enumerates the return fields (date, text, account, amount, side, currency, voided flag), and covers read-only and paged behavior plus filter dimensions. It is nearly complete, missing only ordering/default-sort or pagination-limit details that an agent might want.

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 eight parameters are fully documented in the schema itself, including formats, ranges, and the next_page hint. The description's 'Filter by account, date or period' maps onto existing params but adds no syntax or format detail beyond them, so the baseline 3 applies.

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

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

States a specific verb (List) and resource (ledger postings) and immediately disambiguates the domain with '(the bookkeeping entries)', then enumerates the fields returned. An agent can distinguish this from siblings like billy_list_bank_lines or billy_list_accounts without opening a schema.

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

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

It says 'Filter by account, date or period', which implies how the tool is used, but there is no explicit when-to-use/when-not guidance and no mention of an alternative sibling (e.g. when to prefer bank lines over postings). 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=true, and the description adds genuinely new behavior: there is no documented server-side search filter, so `search` filters only the current page, and results are paged via GET /products. That is exactly the kind of non-obvious trait an agent needs. It doesn't cover page-size defaults or ordering, keeping it below 5.

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 tight paragraph, front-loaded with what the tool returns and followed by the two behavioral caveats (search scope, paging) and the endpoint. No filler, though the field list is slightly list-like rather than prose.

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, fully documented, non-nested listing tool with no output schema, the description supplies the crucial search-scope caveat and paging note; the only minor gap is not describing how `next_page` is surfaced in the response, which the schema hints at.

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 page, search, and page_size are already documented in the schema; the description's restatement of the search semantics is corroborating rather than additive. Baseline 3 applies.

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

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

States a specific verb (list) and resource (products/services usable as invoice lines) and enumerates the returned fields, which cleanly distinguishes it from billy_get_product (single product) among the siblings.

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

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

It explains when the paging contract matters and explicitly warns that search is client-side over the returned page, which tells the agent how to actually use the tool. It does not name alternative tools (e.g. billy_get_product for a single item) or exclusions, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds useful domain context — the returned fields, the fraction convention for rate (0.25 = 25 percent) — and notes the result is paged and comes from GET /taxRates, but says nothing about pagination termination, ordering, or rate limits.

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

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

Extremely compact: resource and its fields first, then pagination, then the HTTP endpoint. No filler, though the telegraphic field list sacrifices some readability.

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, zero-required-parameter list tool with a fully documented schema, the description is largely sufficient, and it partly compensates for the absent output schema by naming the fields each record carries. It stops short of explaining what a filtered or empty result looks like.

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

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

Schema description coverage is 100%, so both page and page_size are fully documented in the schema, including the cross-reference to next_page. The description's single word 'Paged' adds no syntax or defaults beyond that, so the baseline 3 applies.

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

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

Names the resource (the company's VAT rates) and enumerates the fields the resource carries, plus the underlying endpoint GET /taxRates. The 'list' verb is implied by the tool name rather than stated in the description, and there is no explicit differentiation from sibling list tools such as billy_list_products or billy_list_accounts beyond the distinct resource name.

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?

'Paged' hints that pagination is involved but gives no guidance on when to reach for this tool versus a lookup elsewhere, and no prerequisites or exclusions. This mirrors the sibling list tools with no routing signal.

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