Billify

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

The readOnlyHint already marks this as a safe read operation. The description adds important behavioral context: results are suggestions only and the seller confirms tax treatment, which prevents the agent from treating output as authoritative.

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, front-loaded with the main purpose, then adds the optional invoice-specific use and the advisory caveat. Every sentence adds useful information without 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 one-parameter, read-only tool with no output schema, the description is largely complete: it explains what is checked, how invoice_id changes scope, and that results are non-authoritative. Minor output-format details are absent but not essential.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It does explain that invoice_id scopes the check to one invoice and that omitting it applies the check more broadly, though it does not repeat the UUID format.

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

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

The description states a specific check/resource: invoicing rules by seller jurisdiction, including VAT/GST, tax ID, local-currency tax, and e-invoicing mandates, plus remediation guidance. It is clearer than the tautological title, but it does not explicitly differentiate itself from siblings or name alternatives.

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

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

It explains that omitting invoice_id checks the seller's jurisdiction generally, while passing invoice_id checks a single invoice. That gives clear usage context, though it does not state exclusions or alternatives.

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

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

Annotations say readOnlyHint=false with idempotentHint=true, which implies some non-read side effect on repeated-safe calls, yet the description reads like a pure status lookup and never explains that side effect, nor what happens for unknown/unpaid invoices or how fresh the on-chain observation is. The tension between 'check' phrasing and readOnlyHint=false is left unresolved for the agent.

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

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

A single front-loaded sentence covering both the paid/not-paid verdict and the on-chain evidence, with no filler. Slightly awkward trailing phrase ('for it') is a minor blemish.

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, no parameter descriptions, and annotations that only flag non-read-only plus idempotency, the description should explain the shape of the answer (what fields the on-chain transfer evidence contains) and what triggers any write behavior. Neither 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?

One required parameter with 0% schema description coverage: invoice_id is only typed as a uuid, with no statement of which invoice identifier namespace it belongs to or how errors surface for a bad id. The description does not compensate for that gap at all.

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 concrete resource (invoice payment status) and a specific extra payload (on-chain stablecoin transfers seen to the seller's wallet), which distinguishes it from generic invoice getters like get_invoice. It does not name a sibling explicitly, 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?

There is no statement of when to call this versus get_invoice or get_invoice_passport, no prerequisites (e.g. whether the invoice must be finalized/sent), and no exclusions. Usage is only implied by the tool name.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, and the description adds genuinely new context: the original invoice stays unchanged and this is a legal requirement. It also discloses the integration dependency. It does not mention the effect of repeat calls, though idempotentHint=false already flags that no de-duplication happens.

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

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

Three short sentences led by the 'Use when' trigger, so the routing information is front-loaded. "As the law requires" is slight color but earns its place by signaling the behavior is mandatory rather than a setting.

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

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

For a mutation tool with no output schema, the description never indicates what comes back (credit note identifier, status, document link), so an agent cannot plan follow-up calls. Preconditions and behavioral facts are otherwise adequately covered.

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

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

With 0% schema description coverage the description must carry both parameters, and it does: invoice_id is the invoice to be credited in full, and reason is optional and is printed on the credit note ("shown on it"), which is real semantic value beyond the bare string type. Length/format constraints (maxLength 300, uuid) are left to 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+resource ("issues a credit note") and pins the scope: "for the whole invoice," which implicitly separates it from any partial-credit or invoice-editing path such as create_invoice. The only ambiguity is that the trigger phrase says "cancelled or reduced" while the operation covers the whole invoice only, leaving partial reduction undefined.

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 when an invoice must be cancelled or reduced" gives an explicit trigger condition, and the availability precondition (Billify connected to the user's account) is stated up front. It does not name a sibling or alternative for the partial-reduction case it alludes to, leaving that route 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?

Goes well beyond the annotations (readOnly=false, idempotent=true, destructive=false) by disclosing the return value (payment link), accepted payment rails, plan/limit failure behavior, the approval-threshold path with pending_approval and approval_id, and the exact-amount requirement for stablecoin payers. These are non-obvious outcomes an agent cannot infer from structured fields.

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 trigger and core action, then layered detail; nearly every sentence adds actionable information. It drifts into run-on sentences and includes fairly niche crypto-payment mechanics that could be split for 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?

With no output schema, the description usefully covers the return value and the non-happy-path outcomes (limit failure, pending_approval). It is complete on behavior, though thin on the required input parameters given the low schema coverage.

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 14%, so the description must carry parameter meaning, but it only explains idempotency_key (retry safety) and partially touches amount (exact vs rounded for crypto). The four required parameters client_email, client_name, due_days, and especially 'description' (the line-item text) get no clarification at all, leaving the ambiguous 'description' field undocumented.

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 ('creates an invoice with one line item') plus what it returns ('returns its link'), and distinguishes itself from send_invoice and get_approval by describing the handoff. An agent can tell it apart from siblings like create_credit_note or list_invoices 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?

Opens with an explicit trigger ('Use when the user wants to bill someone') and names alternatives with their conditions: send_invoice afterwards to email, get_approval to check pending_approval, crypto_payment for stablecoin details. Both when-to-use and follow-up routing are spelled out.

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?

Goes well past the annotations (readOnly=false, idempotent=true, destructive=false) by describing the full state machine: buyer accepts or disputes, hash enters the signed Invoice Passport, refused after acceptance, and Billify does not verify the work. It stops short of saying what a re-declaration does to the previously recorded hash/version, which matters given idempotentHint=true.

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

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

Four short sentences, front-loaded with what is recorded, followed by lifecycle outcome, retry rule, and the trust disclaimer that prevents an agent from over-claiming verification. Nothing is redundant.

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

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

For a mutation tool with no output schema, the description covers lifecycle, refusal conditions, and trust boundaries well. The gap is the return/state effect of a declaration (what the agent gets back, what happens to a prior declaration), which an agent acting on the invoice would 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 coverage is only 25% (only content_hash is documented), so the description must compensate, and it does: it identifies 'a description' as the core content, 'a link' as the optional url, and 'a SHA-256 hash of the content' and ties the hash to the signed Invoice Passport. It does not say whether the link must be publicly reachable or whether a re-declare replaces the stored values.

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: 'Record what was delivered for an invoice', naming exactly the fields it captures, then explains the acceptance/dispute lifecycle. This clearly separates it from siblings like create_invoice, send_invoice, and get_invoice_passport.

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?

Explicit conditions are given for both directions: re-declare only 'if the buyer disputed ... after fixing it', and the call is 'refused once the buyer has accepted'. An agent can decide whether to invoke it without opening 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 the safe-read behavior. The description adds useful status semantics and notes that an approved result includes invoice_id and pay_link, which is valuable extra context absent from structured fields. It does not cover polling behavior, auth needs, or rate limits, but the annotation lowers the disclosure burden.

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

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

The description is a single efficient sentence that front-loads the resource and includes the key status values. Every clause contributes either scope or return-value information.

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

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

For a simple read-only tool with one required parameter, the description covers the main statuses and the approved response shape. However, it omits how to obtain approval_id and gives no guidance on polling while pending or interpreting rejected versus failed. With no output schema, a little more completeness would help.

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

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

Schema description coverage is 0%, so the description must explain approval_id but does not. It implies the approval request originates from create_invoice returning pending_approval, but never explicitly says that approval_id comes from that response or how to obtain it. The single parameter is therefore only indirectly inferable.

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

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

The description clearly identifies the resource: the approval status of an invoice request queued by the seller's API key policy. It also links the tool to create_invoice returning pending_approval, which helps an agent distinguish it from invoice retrieval tools. However, it does not explicitly contrast with sibling tools such as get_invoice or check_payment.

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 a clear trigger for use: after create_invoice returns status pending_approval. It does not state when not to use the tool or name alternatives, but the operational context is explicit enough for correct selection.

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

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

Annotations already declare readOnlyHint and openWorldHint; the description goes further by disclosing that the tool can return a missing-data list instead of XML, that validate triggers an external ANAF validator call, and that no SPV upload side effect occurs. It does not mention validator latency or failure modes when ANAF is unreachable.

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 sentences, front-loaded with what is returned, then the flag semantics, then the workflow constraint. Each sentence carries distinct, non-redundant information.

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

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

With no output schema, the description carries the return-value burden and does so (XML document or missing-data list). It leaves open how the XML is delivered (inline string vs. download) and how invalid invoice_id is reported, minor gaps for a read-only 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?

At 50% schema coverage, invoice_id has no schema description at all; the description only implies it must be one of the seller's invoices. The validate flag is well covered ('also runs ANAF's public validator'), matching the schema text, so the gap is mostly on the required parameter.

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

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

States a specific resource — the RO e-Factura XML in UBL 2.1 / CIUS-RO 1.0.1 — for a single seller invoice, plus the alternate return of a missing-data list. That format specificity clearly separates it from get_invoice and get_invoice_passport, though no sibling is named.

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 validate flag's use and the workflow boundary ('Billify does not upload to SPV here: the seller uploads the file') are stated, which prevents a wrong assumption. However, it never says when to reach for this versus get_invoice or get_invoice_passport, so selection among siblings 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?

readOnlyHint already covers the safety profile, so the description's added value is in disclosing the returned payload, including the crypto_payment.send_exactly detail for stablecoin invoices. It stops short of noting auth needs or behavior for missing/nonexistent 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?

A single dense sentence that front-loads the core action and enumerates return content without any filler. 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 the burden of explaining returns and does so reasonably well by naming line items, client, payment status, and crypto payment fields. It could go further on error behavior or how missing invoices are handled, but it is adequate for a single-id read.

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

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

Only one parameter (invoice_id, uuid), which is self-explanatory and needs little elaboration; the description adds no format or lookup semantics beyond what the schema conveys. Baseline 3 is appropriate for a single obvious identifier.

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 ("Get one invoice") and enumerates what is returned: line items, client, payment status, and stablecoin payment details. It is clearly distinguishable from list_invoices by the singular scope, though it does not explicitly name siblings like get_invoice_passport or get_efactura_xml.

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 the name and the "one invoice" phrasing; there are no explicit when-to-use or when-not conditions, and no pointer to the sibling tools an agent should prefer for lists, passports, or XML output.

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 real value beyond that: it discloses that the returned passport is cryptographically signed with an ES256 JWS and includes on-chain hashes and Stripe ids. It does not cover error/precondition behavior (e.g. what happens if the invoice is missing or unsigned).

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

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

One sentence, front-loaded with the verb and resource, followed by the payload contents. Efficient, though the dense parenthetical of evidence types could be trimmed or split for 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 single-param read tool with no output schema, the description substantially documents the return payload (signed JWS proof and evidence fields), which is exactly what the absent output schema would otherwise need to carry. Only usage/precondition guidance 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?

There is a single invoice_id parameter with UUID format, and schema description coverage is 0%. The description implies it identifies the invoice whose passport is fetched but adds no detail on format or validation beyond what the name conveys; with only one obvious param, this is adequate but not enriched.

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 ('Get') and a distinctly named resource ('Invoice Passport') and enumerates its contents (invoice, parties, payment evidence, history, JWS proof). This clearly separates it from get_invoice or get_efactura_xml in spirit, though it never names a sibling to make the distinction explicit.

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 when-to-use or when-not-to-use guidance, nor any mention of prerequisites (e.g. must the invoice exist, must it already be signed). The agent must infer that this is the signed-bundle counterpart to get_invoice without being told.

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 usefully adds the ordering guarantee ("newest first"). However it says nothing about result truncation, default page size, or what happens past the 50-item maximum — meaningful behavioral gaps for a list 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?

Two short sentences, front-loaded with the resource and ordering before the optional filter. Slight redundancy in re-listing the enum values that the schema already defines.

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?

Adequate for a simple two-parameter read tool, but with no output schema the agent gets no hint of the return shape, and the undocumented limit parameter plus absent pagination/truncation notes leave real gaps for a list operation.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, but it only restates the status enum values already present in the schema and never mentions the limit parameter at all. Default (20) and maximum (50) are left entirely to the agent to discover in the raw 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 ("List your Billify invoices") plus a scope detail ("newest first"). It distinguishes a list operation from siblings like get_invoice, though it never names a sibling explicitly.

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

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

"Optionally filter by status" implies when the status filter is useful but gives no explicit when-to-use vs when-to-use-an-alternative guidance. Nothing tells the agent when to prefer get_invoice or when listing is the wrong approach.

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

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

Annotations already cover read-only and open-world safety, so the description's added value is the register routing and the returned field set (name, registered office, VAT registration, active status, RO e-Factura register). It does not mention latency, rate limits, or behavior when a tax ID is unknown, so the picture is strong but not complete.

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

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

Two sentences, zero filler. The lookup scope and register routing come first, the use case second, so the agent gets the essential framing immediately.

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

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

With no output schema, the description correctly enumerates what comes back and explains the routing logic for the single parameter. Only failure/not-found behavior and any request cost are left unstated, which is a minor gap for a one-parameter read tool.

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

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

Schema coverage is 100% and the schema already gives format examples. The description adds real meaning beyond that by explaining that the ID's jurisdiction determines which register is queried (ANAF vs VIES), which the schema examples alone do not convey.

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 (look up a company by tax ID) and immediately scopes it to public registers, naming ANAF for Romanian CUIs and VIES for other EU VAT numbers. No sibling tool does company resolution, so the differentiation is implicit but 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?

Gives concrete when-to-use cases: populate a client before create_invoice, or vet a supplier. That is clear context that ties it to sibling tools. It stops short of stating when not to use it or what to do if the lookup fails, which keeps it below 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 the write-but-not-destructive, non-idempotent, open-world profile, so the bar is lower. The description usefully adds that this fires an external email to a client, that only the caller's own invoices are eligible, and that it requires Billify to be connected — real context beyond annotations — but says nothing about resend behavior for an already-sent invoice or failure handling.

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 sentence, front-loaded with the trigger condition, then the effect, then the eligibility constraints. No filler or restatement of the name.

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 the action, recipient override, ownership restriction, and connection prerequisite — enough to call it correctly. Missing only what the agent should report back or expect on send failure, a minor gap for a 2-parameter tool.

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

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

Schema coverage is 50%: recipient_email is documented in the schema, but invoice_id has no description. The description compensates partially by clarifying that the recipient may be overridden "(or the one given)" and constraining invoice_id to the signed-in user's invoices, though it adds no format or identifier guidance. Baseline 3 is appropriate.

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

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

The description pairs a specific verb (emails/sends) with a concrete resource (the invoice link) and states the destination (the client's address), which cleanly separates it from create_invoice, get_invoice, and list_invoices. An agent can identify the action and effect 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 gives explicit trigger phrasing ("Use when the user wants an invoice sent to the client") plus scope restrictions: only invoices of the signed-in user, and only when Billify is connected in ChatGPT/Claude/Grok. It does not name a sibling alternative or state when not to use it, so it stops short of a full when/when-not routing rule.

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