FastBill MCP by usefulapi

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

Beyond the destructive and non-readonly annotations, it discloses key consequences: FastBill assigns the invoice number and PDF, the invoice becomes uneditable, it can only be canceled afterward, and no customer notification occurs. This is exactly the behavioral context needed for a destructive mutation.

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

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

The warning is front-loaded with 'WRITE, NOT REVERSIBLE', followed by the operational details and confirmation requirement. Every sentence contributes useful context, with no filler.

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

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

For a destructive, non-idempotent one-parameter tool with no output schema, the description covers irreversibility, side effects, resulting invoice state, customer notification behavior, and the required user confirmation. Nothing critical for correct invocation 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 schema has 100% description coverage and clearly identifies invoice_id as the FastBill id of the DRAFT invoice. The description reinforces that the target must be a draft, but does not add parameter-level details beyond the schema.

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

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

The description states a specific verb and resource: turning a draft invoice into a final invoice. It clearly distinguishes this operation from invoice creation or payment marking by explaining the draft-to-final transition and FastBill-side consequences.

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 clear precondition: only call after the user has confirmed the draft. It also clarifies that nothing is sent to the customer, but it does not explicitly name sibling alternatives such as creating a new invoice or canceling an existing final invoice.

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=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, so the safety profile is largely covered. The description adds "WRITE" and required fields but does not go beyond the annotations to explain duplicate article-number behavior, side effects, or authentication needs.

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

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

The description is a single front-loaded sentence with no wasted words. It puts the write action and core resource first, then lists required fields.

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 10-parameter create tool with only 20% schema description coverage and no output schema, the description is too thin. It covers the core action and required fields but leaves optional parameter semantics, duplicate handling, and return expectations undocumented.

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

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

Schema description coverage is only 20%, so the description should compensate for undocumented parameters. It mentions that article number, title, and unit price are required, but says nothing about the other seven parameters such as type, unit, is_gross, VAT, currency, tags, or description.

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

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

The description uses a specific verb, "create," and a clear resource, "a product or service," with the parenthetical clarifying required fields. It is distinguishable from sibling list tools and other create_* tools by resource, but it does not explicitly name alternatives or 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?

The "WRITE:" prefix signals that this is a mutation, and the description names required fields, but it gives no explicit when-to-use guidance, prerequisites, or alternatives. It does not say when to choose this over other create tools or how to handle existing article numbers.

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 non-read-only, non-destructive, non-idempotent; the description adds real value on top by warning that FastBill performs no duplicate detection and that bank/direct-debit data cannot be supplied here. It does not say what is returned on success (no output schema exists), which is the one notable behavioral gap.

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

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

Four dense clauses, front-loaded with the WRITE marker and the required field, then preconditions, then the failure mode, then the endpoint. No filler or repetition.

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

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

For a 22-parameter mutation with open-world and no output schema, the description covers the highest-risk facts: required type branching, duplicate risk, and the excluded bank-detail path. What it omits is the response shape (e.g., whether the new customer ID comes back) and permission/error behavior.

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

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

Schema coverage is only 41% across 22 parameters, so the description could compensate more. It does clarify the conditional requirement among customer_type/organization/last_name and the bank-details exclusion tied to payment_type 6, but most of the remaining ~18 fields get no meaning beyond their names and length limits in 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 precise verb and resource ("WRITE: create a customer") and grounds it with the underlying API call ("customer.create"). The create verb itself separates it from fastbill_update_customer and fastbill_get_customer, though no explicit contrast is drawn.

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 concrete preconditions (customer_type required; organization for business, last_name for consumer), a when-not (bank details are not accepted here, set them in FastBill), and an alternative tool with its condition (search with fastbill_list_customers first because duplicates are not checked). No guidance on routing an existing customer to update_customer.

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 'WRITE:' prefix and 'It is not sent' add meaning beyond annotations, which only declare readOnlyHint=false/openWorldHint=true and say nothing about whether the document is dispatched to the customer. It omits the non-idempotency consequence (retries may create duplicate estimates), which is the main remaining gap.

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

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

Three short fragments, front-loaded with the mutation marker and the key behavioral fact ('It is not sent'). Nothing 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?

With 8 parameters, no output schema and no parameter-level return info, the description never says what comes back (presumably a new estimate id, needed for follow-up steps) or how template_id interacts with inline items. Adequate but leaves real operational gaps for a write 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 88%, so the schema already documents items, currency_code, template_id and the rest. The description only gestures at 'line items' and 'customer' without adding format or defaulting rules, so it sits at the schema-covered 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 ('create an estimate (quote)') plus the source of the data ('for a customer from line items'), and the parenthetical 'quote' disambiguates the term. It doesn't explicitly contrast with sibling fastbill_create_invoice, but the resource name is distinct enough to be actionable.

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

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

'It is not sent' is the only routing hint — it implies this is for a draft/proposal stage rather than billing. There is no explicit when-to-use vs fastbill_create_invoice or when to prefer template_id over inline items, so the agent must infer.

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

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

The description adds real context beyond the annotations: the record is persisted as a draft, it lacks an invoice number until completed, and no email is sent. This clarifies the lifecycle of a write that the readOnlyHint/destructiveHint flags cannot express. It stops short of covering duplicate-submission or idempotency risk, even though idempotentHint=false implies repeat calls create separate invoices.

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 front-loads the operation type ("WRITE:") and then gives the draft, finalize, and verify steps in compact sentences with no padding. The trailing "invoice.create." fragment is unexplained backend jargon that adds 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 17-parameter mutation with no output schema, the description covers the lifecycle and how to confirm the result. The remaining gap is that the vat_case enum and the gross/net and discount options are left to the schema, which only documents 65% of the 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 coverage is 65%, so the baseline is a 3. The description confirms the two required inputs conceptually (customer and line items), but adds no detail on the business-sensitive options such as vat_case, is_gross, or the two discount levels.

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 and resource ("create an invoice") plus the source of the data ("from line items" for "a customer"), which separates it cleanly from fastbill_complete_invoice and fastbill_get_invoice. An agent can identify the tool 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 states exactly when to use this tool versus its siblings: use fastbill_complete_invoice to finalize and assign a number, and use fastbill_get_invoice to verify the result. It also adds a negative constraint ("never sent by this tool") that prevents a common misuse.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the 'WRITE:' label mostly repeats structured data. The description adds nothing about permissions/auth, duplicate-name handling, or what side effects a creation has on the customer record.

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 short, front-loaded sentence with the mutation signal first and the required inputs stated early. The trailing 'project.create.' is dead weight but the overall footprint is efficient.

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 7-parameter mutation with no output schema, the description leaves too much unexplained: optional field meaning, defaults, and what is returned (e.g. new project id) are all absent. An agent can call it, but only by guessing at the optional fields.

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?

It restates 'name and customer are required', which the schema's required array already declares, and says nothing about the five optional fields (hour_price, vat_percent, start_date, end_date, currency_code). With schema coverage at 57% and vat_percent/currency_code having no descriptions at all, the description fails to compensate for the gap.

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

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

States a specific verb and resource ('create a project') and scopes it to a customer, so it is clearly distinguishable from the read-side sibling fastbill_list_projects. The trailing 'project.create.' is a redundant internal tag that adds no clarity, keeping it 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 guidance on when to use this versus alternatives such as fastbill_create_customer or when a project should be created at all. The 'WRITE:' prefix hints at a mutation but there are no prerequisites, exclusions, or routing hints.

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=false, idempotent=false, destructive=false and openWorld=true, so the 'WRITE:' label largely repeats structured data. The description adds nothing about the non-idempotency consequence (repeat calls create duplicate entries) or how date, start_time, end_time and minutes relate to each other—context an agent would need to book time correctly.

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 compact sentence with the mutation signal and the required-field precondition front-loaded; nothing is padded. It is arguably too terse for a 9-parameter write tool, but that is a completeness issue rather than wasted 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?

A 9-parameter write tool with no output schema and only 56% schema coverage needs more than a single clause. The description leaves unanswered whether end_time can be omitted when minutes is supplied, what date does when start_time is required, and what the tool returns.

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

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

Schema coverage is only 56% and 9 parameters exist, so the description should compensate. It instead repeats the three required fields already marked required in the schema and says nothing about comment, article_id, billable_minutes, or the date-vs-start_time-vs-minutes relationship the schema only partially 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 and resource ('book a work time entry on a project') and names the three required fields, so an agent can tell it apart from the sibling list_time_entries. It stops short of naming alternatives explicitly, but the create-vs-list distinction 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 'WRITE:' prefix implies this is the mutation path as opposed to reading entries, and the required-field callout gives a minimum bar for invocation. No explicit when-not-to-use guidance, no mention of duplicate handling, and the sibling list_time_entries is never named.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the underlying API call ('customer.get with CUSTOMER_ID'), which is mildly useful for debugging, but says nothing about error behavior for missing ids or the shape of the response.

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 fragments, front-loaded with the resource and key. The trailing 'customer.get with CUSTOMER_ID' is slightly cryptic internal jargon but costs little space.

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 lookup with rich annotations, the definition is adequate but leaves gaps: no output shape hints (there is no output schema) and no behavior for a non-existent id. An agent can call it correctly but cannot anticipate the response.

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 parameter is documented in the schema as the FastBill customer id with an integer/exclusiveMinimum constraint. The description only restates the id requirement, adding no format or sourcing 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 the resource (a single FastBill customer) and the lookup key (customer id), which clearly separates it from fastbill_list_customers and the create/update siblings. It is a noun phrase rather than a verb, but 'One customer by ... id' leaves no ambiguity about what is returned.

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 by id when you already hold a customer id. It never explicitly says to use fastbill_list_customers instead when you need to search or don't have an id, nor what happens if the id is unknown, so routing is left to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine value by disclosing exactly what is returned (line items, VAT, payments, document URL), which matters because there is no output schema; it stops short of noting auth or error behavior.

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

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

Two short sentences, zero filler, and the return-content detail is front-loaded before the terse API hint. 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?

For a one-parameter read tool with no output schema, the description covers the return shape well enough for an agent to know what it will get. Minor gaps: no note on behavior for missing/invalid ids and no signal on nesting or size of the response.

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

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

With a single required parameter and 100% schema description coverage, the schema already documents invoice_id fully. The description reinforces that the id is a FastBill invoice id (not an external/number reference), which is a small but real clarification beyond the schema.

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

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

States a specific verb and resource ('One invoice by FastBill invoice id') and even enumerates the payload the caller gets back (line items, VAT, payments, document URL). It implicitly contrasts with the list_* siblings by emphasizing a single record, though it does not name an alternative 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?

'One invoice by ... id' implies the fetch-by-identifier use case, and 'invoice.get with INVOICE_ID' hints at the underlying call. But there is no explicit guidance on when to prefer this over fastbill_list_invoices or the other invoice tools, and no mention of what happens for an unknown 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 and destructiveHint=false, so the safety profile is covered, and the description usefully lists returned fields in the absence of an output schema. It does not explain pagination behavior beyond what the schema says, nor whether article_id/article_number narrow the result set or fetch a single record.

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 tight sentence that front-loads the resource and the field list; nothing is padded. The bare 'article.get.' token is unexplained noise 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?

Listing return fields partially compensates for the missing output schema, which is good. But with no guidance on what article_id/article_number do and no statement of default listing scope, an agent cannot confidently decide whether to pass filters or paginate through everything.

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

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

Schema coverage is only 50%: limit and offset are documented in the schema, but article_id and article_number have no description anywhere. The description says nothing about parameters, so it fails to compensate for the undocumented filter arguments.

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 and services') and even enumerates the returned fields (article number, type, title, unit price, VAT, unit), which clearly separates it from fastbill_create_article. It does not explicitly contrast with other list_* siblings, but the resource 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?

There is no statement of when to use this tool versus alternatives (e.g. create_article, or any product-lookup path), and no prerequisites or exclusions. The trailing 'article.get.' hints at the backing endpoint but gives no usage condition.

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 destructiveHint=false, so safety is covered structurally. The description adds only the field list and the raw endpoint name; it says nothing about result limits or API quota despite the schema's warning that every call counts against an hourly quota.

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 clauses, front-loaded with the resource and followed by returned fields and filters. Zero padding, though the 'contact.get.' fragment is noise an agent does not need.

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 listing tool with no output schema, the description supplies what the schema cannot: what each contact record contains (name, position, e-mail, phone). Pagination and quota exist in the schema, 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 83%, so the schema already documents term, limit, offset and the id filters precisely. The description restates three of six parameters ('customer, search term or contact id') without new syntax or behavior, leaving customer_number, limit and offset entirely to the schema. 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 ('List contact persons of customers') and enumerates the returned fields, which cleanly separates it from fastbill_list_customers and fastbill_get_customer. The trailing 'contact.get' is an API endpoint hint rather than added clarity.

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 names the available filters (customer, search term, contact id), which implies how to narrow results, but it never says when to choose this over fastbill_list_customers or fastbill_get_customer, nor when not to use it. Usage is inferable but not guided.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that values are "as stored in FastBill" and cites the underlying "customer.get" endpoint, but says nothing about pagination behavior or quota consumption beyond what the schema notes.

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 that front-load the resource and returned fields, then the filters. The trailing "customer.get" is a minor opaque artifact left over from API documentation but otherwise there is no filler.

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

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

For a six-parameter list tool with no output schema, the description compensates by enumerating the returned fields and the filterable dimensions. Pagination and quota details live in the schema, so the remaining gaps are small.

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 83%, so the schema already documents most parameters including term matching, limit defaults, quota cost, and offset semantics. The description restates the filter dimensions (search term, customer number, country, city) without adding format or behavior detail beyond the schema, which is the expected 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 ("List customers") and enumerates the fields returned, so an agent knows this is a read of customer records. It is clearly distinct from fastbill_get_customer by the 'list' vs 'get' framing, though it never explicitly contrasts itself with sibling tools.

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

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

The filter options imply when the tool is appropriate, but there is no explicit guidance on when to use it versus fastbill_get_customer or the create/update siblings, nor any prerequisites. Usage must be inferred from the filter list.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds genuine value by decoding the a–f state codes and saying totals and items are included in the response. It says nothing about pagination or quota behavior, both of which are 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?

A single compact sentence plus a short tag; the state-code enumeration earns its space. The 'estimate.get' suffix is the one wasteful fragment.

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 plain list tool with a read-only annotation set and no output schema, the description covers output content but leaves optional-filter usage and pagination behavior unexplained, which matters given seven optional parameters and zero required ones.

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 57%, and the description mentions no parameters at all. Three filters (customer_id, estimate_id, estimate_number) have no description in either the schema or the tool description, so the caller gets no semantic guidance on how those filters combine or whether they are exact-match.

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 estimates (quotes)') and clarifies the domain term, which distinguishes it from fastbill_create_estimate and the invoice-listing siblings. It also names the fields returned (state, totals, items). The trailing 'estimate.get' is an opaque internal reference that adds no clarity.

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 indication of when to use this versus fastbill_get_invoice-style lookups or the create/update siblings, and no mention of the filtering options (dates, customer, estimate id/number) that would guide a caller. Usage is only implied by the verb 'List'.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the returned field set, but says nothing about pagination behavior, rate limits (though the schema's limit param covers this), or result ordering beyond what annotations provide.

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 no filler, and the field enumeration is front-loaded. The 'expense.get' fragment is slightly cryptic but otherwise efficient.

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 annotations covering safety and no output schema, enumerating returned fields is valuable and mostly complete. The main gap is the absence of guidance on pagination or how the various date parameters relate, though the schema partially compensates.

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

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

With 75% schema description coverage, the baseline is 3. The description names invoice number and date-range filtering, which maps to some params, but does not clarify the distinction between start/end_date and start/end_paid_date, nor the meaning of invoice_id, leaving semantic gaps the schema doesn't fill.

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 expense entries') and enumerates the returnable fields (supplier, category, net/VAT/gross, dates, document URL), which is concrete. However, it does not differentiate itself from sibling list tools like list_revenues or list_invoices beyond the 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?

Mentions filtering by invoice number or date ranges, implying usage, but provides no explicit when-to-use guidance, prerequisites, or alternatives to the other list_ tools. Usage must be inferred from the filter options.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description still adds real value beyond that: it states what the response contains (totals, state, dates, line items) and enumerates the state vocabulary (draft, unpaid, overdue, paid, canceled), which no structured field provides. It omits ordering/pagination behavior, though the schema's next_offset text partially covers that.

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

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

Two dense sentences: return payload first, filter surface second – well front-loaded with no filler. The trailing 'invoice.get' is unexplained token-like clutter that does not earn its place.

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

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

With no output schema, the description usefully compensates by naming the returned fields and states, and it covers the breadth of the 13 optional filters. Remaining gaps are minor: no explicit escalation path to fastbill_get_invoice for line-item detail and no ordering guarantee.

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 85%, so the baseline is 3. The description adds the grouping of filterable dimensions ('invoice date, due date, paid date, last update'), which clarifies intent for the start_/end_ pairs, but adds no format or syntax beyond the schema's yyyy-mm-dd notes.

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?

Opens with a specific verb+resource ('List outgoing invoices, drafts and credit notes') and enumerates the returned fields and states, so the agent knows this is a read/collection operation. It does not explicitly distinguish itself from fastbill_get_invoice or fastbill_list_recurring_invoices, leaving the list-vs-single and invoice-vs-recurring distinction to inference.

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 the filter enumeration (customer, number, type, date ranges), which suggests 'use this to search/filter invoices'. There is no explicit when-to-use or when-not statement, and no pointer to siblings such as fastbill_get_invoice for a single record or fastbill_complete_invoice for a write.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower, but the description adds essentially nothing behavioral: it does not mention that results are paginated, that limit/offset must be chained via next_offset, or that calls consume FastBill's hourly quota. "project.get" is only a bare internal endpoint reference.

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 fragments, front-loaded with the verb and resource; nothing is padded. It loses a point because the trailing "project.get." is cryptic and the terse parenthetical reads more like a dump of fields than structured guidance.

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 genuinely useful and the tool is a simple read with no required params. However, pagination mechanics and the purpose of the two ID filters are unexplained, which for a quota-limited paged endpoint leaves a 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?

Schema coverage is 50%: limit and offset are well documented in the schema, but project_id and customer_id have no descriptions anywhere. The parenthetical lists return fields (name, customer, rate, VAT, dates) rather than parameters, so it does not compensate for the undocumented filters an agent would want to know are available for narrowing results.

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 ("List projects") plus a parenthetical of the fields returned and the underlying API endpoint (project.get). It is distinct from fastbill_create_project and the other list_* siblings, though it never names a sibling to route against.

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 statement of when to use this vs. alternatives (e.g., filtering a single project vs. listing all), no prerequisites, no mention of when the optional project_id/customer_id filters should be applied. The agent is left to infer usage from the schema alone.

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

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

Annotations already establish readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is clear. The description adds the return field categories, but does not mention pagination behavior, API quota impact, 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?

The description is compact and front-loads the resource and returned data. The trailing 'recurring.get.' is terse and somewhat opaque, but overall there is little waste.

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 read-only listing tool with fully documented parameters and strong annotations, the description provides enough context to select and invoke it. It could say more about pagination or response shape, but the core information is present.

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 three parameters are already well documented in the schema. The description does not add parameter-specific meaning beyond what the schema provides, making the baseline score 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 specifies the verb and resource clearly: it lists recurring invoice templates, with examples of included data (customer, interval data, totals, items). This distinguishes it from generic invoice or template listing siblings, though it does not explicitly name those alternatives.

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

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

Usage is implied by the purpose, but there is no explicit guidance on when to use this instead of fastbill_list_invoices or fastbill_list_templates. No exclusions, prerequisites, or alternative-selection cues are provided.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuine context beyond that: the fields carried by each entry (customer, totals, dates, payments) and the backing endpoint 'revenue.get', which helps an agent anticipate the shape of results for a tool with no output 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 plus an endpoint tag; the resource, its contents, and the filter analogy are all front-loaded with no filler.

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

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

For an 8-parameter, all-optional list tool with annotations covering safety and no output schema, the description supplies purpose, return fields, and a filter cue, which is close to sufficient. It leaves minor gaps around how multiple filters combine and how results are ordered.

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 75% and pagination parameters (limit, offset) are well documented in the schema, so the baseline is 3. The description's 'same filters as invoices' hints at the filter family but adds no meaning for the undocumented customer_id and invoice_number parameters or for how date and paid-date ranges combine.

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 revenue entries') and disambiguates the domain with a parenthetical ('income booked in FastBill'), plus the underlying API service ('revenue.get'). It is clear what the tool returns, though it never explicitly contrasts with the near-sibling fastbill_list_invoices beyond noting shared filters.

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?

'Takes the same filters as invoices' implies a relationship to fastbill_list_invoices and gives a usable mental model for filtering. However, it does not state when to choose revenues rather than invoices, expenses, or list_customers, nor any exclusions, so usage is only implied.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds a genuine behavioral trait beyond that: template ids are volatile and change on edit, which matters for any caching strategy. It omits the quota note, but that lives 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?

Three tight clauses with zero filler, front-loaded with the resource and its returned fields. The trailing fragment 'template.get.' is cryptic and unexplained, keeping it off a 5.

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?

No output schema exists, but the description names the returned fields (template id, name, hash), which is the key piece an agent needs. Pagination and quota details are in the schema. The only unexplained element is the trailing 'template.get.' token.

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 both parameters (limit, offset) are fully documented in-schema, including the quota caveat and the next_offset convention. The description adds nothing about them, so baseline 3 applies.

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

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

States a specific verb (List) and a specific resource (invoice/estimate templates) and even enumerates the returned fields (template id, name, hash). An agent can tell this apart from the list_* siblings that target invoices, estimates, articles, etc.

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?

'Use a template id with the create tools' tells the agent downstream usage, and 'Ids change whenever a template is edited' warns when a cached id may be stale. There is no explicit when-not or named alternative, 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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), and the description adds real behavioral value: the default no-filter behavior scopes results to the current month's latest entries. It omits quota/pagination behavior, though the limit parameter's schema text covers the API quota.

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 front-loaded sentences that carry the field list and default behavior with no filler. The trailing "time.get." endpoint token is jargon that does not earn much space 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?

With no output schema, the inline field enumeration is genuinely useful compensation, and the default-month behavior is disclosed. However, for an 8-parameter filter tool with 3 undocumented id filters and an ambiguous date/start_date/end_date triad, the description leaves real gaps.

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

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

At 63% schema coverage, the schema already documents date, limit, offset, start_date and end_date. The description only hints at filtering ("without filters") and does not explain the undocumented time_id, project_id, and customer_id filters or clarify date vs date-range, so it adds little 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?

Specific verb+resource ("List work time entries") with an enumeration of the fields returned, which lets an agent distinguish it from fastbill_create_time_entry and the other list_* siblings. It does not explicitly name a sibling alternative, keeping it out of 5 territory.

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?

"Without filters FastBill returns the latest entries of the current month" implies how to call it and what happens with an empty filter set, but there is no explicit when-to-use or when-to-prefer-another-tool guidance, and no explanation of when to use date vs start_date/end_date.

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=false, destructiveHint=true, and idempotentHint=true, so the description does not need to restate the safety profile. However, it adds a useful behavioral constraint by specifying that only a 'final invoice' should be marked paid. It stops short of explaining what happens to invoice state, whether the action can be reversed, or what side effects to expect beyond the annotation hints.

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

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

The description is short and front-loaded with the action ('WRITE: mark a final invoice as paid'). Every sentence is relevant, though the trailing method name 'invoice.setpaid' is of marginal value to an agent selecting the tool.

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

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

The tool is a simple mutation with full schema coverage and rich annotations, so the description need not explain return values or safety hints. It covers the core action and the key precondition that the invoice must be final. It could still say more about prerequisites or expected post-state, which keeps it from a 5.

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 defines invoice_id, paid_date, and payment_method clearly. The description mentions payment date and method, consistent with the schema, but adds no extra format details, constraints, or examples beyond what the parameter descriptions already provide.

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: 'mark a final invoice as paid, with the payment date and method.' This is clear and distinguishes the action from generic invoice updates. It does not explicitly differentiate from nearby siblings such as fastbill_complete_invoice, 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?

The description gives no guidance on when to use this tool versus alternatives or when not to use it. It mentions 'final invoice,' which implies a precondition, but does not explain prerequisites, exclusions, or the relationship to comparable tools like fastbill_complete_invoice.

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 destructiveHint/idempotentHint, so the safety profile is covered. The description adds real value beyond them: PATCH-style partial update semantics (only passed fields change) and the fact that bank-detail-dependent settings (direct debit) cannot be set here. It stops short of saying what makes the call destructive or how invalid ids behave.

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 the operation class and packed into two short clauses with no filler. The trailing "customer.update." tag is opaque jargon 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?

A 23-parameter mutation with no output schema and thin schema descriptions needs more than two clauses. Missing are the required-id contract, conditional field dependencies, and what an agent should expect on failure; the description alone would not let an agent call this correctly.

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

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

Schema description coverage is only 39% across 23 parameters, so the description should compensate and it does not. It says nothing about customer_id being required, the conditional rules (organization required for business, last_name for consumer) or the payment_type/days_for_payment interaction, leaving the undocumented half unaddressed.

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?

"WRITE: update fields of an existing customer" gives a specific verb, resource and operation class, and the patch clause ("only the fields you pass change") separates it cleanly from fastbill_create_customer and fastbill_get_customer. An agent can pick this tool without opening the schema.

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

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

The WRITE prefix implies when to use it, and "Bank details are not accepted by this tool" sets one scoping exclusion. But there is no guidance on prerequisites (e.g. reading current values via fastbill_get_customer first) or on when to prefer create vs update.

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