invoice-ninja

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

Annotations already declare destructiveHint=true, so the mutation warning is covered; the description adds meaningful context by disclosing that the source quote is marked converted and linked to the new invoice, and that the new invoice is returned. It stops short of covering authorization requirements or whether the conversion is reversible.

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 covering the action, the side effect, and the return, followed by the endpoint reference. Front-loaded with zero 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 one-parameter mutation with no output schema, the description supplies the side effect, the return value, and the endpoint, which is most of what an agent needs. Missing only prerequisite/eligibility conditions on the quote.

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

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

Schema coverage is 100% and the single quote_id parameter is fully documented with format example in the schema, so the description adds no syntax detail. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb+resource pair ('Convert a quote into a new invoice') and the endpoint, which cleanly distinguishes it from sibling creation tools like create_invoice and create_quote. An agent can identify this as the quote-to-invoice transformation 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?

Usage is implied by the conversion semantics and the side-effect note, but there is no explicit guidance on when to prefer this over invoiceninja_create_invoice or what prerequisite state the quote must be in. Adequate but leaves the agent to infer the trigger 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 supply only destructiveHint=true, so the description carries most of the behavioral burden. It contributes the minimum-input rule and the underlying endpoint, but says nothing about permissions, duplicate handling, or what a successful call returns. Useful additions, but well short of full disclosure for an unannotated 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?

Three short fragments, front-loaded with the action and constraint, with zero padding. The trailing endpoint reference is arguably redundant but is cheap and aids traceability.

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 moderate-complexity create tool with no output schema and thin annotations, the essentials (action, contacts support, minimum required input) are covered. The large set of optional fields is left undescribed, which is tolerable only because their names are largely self-explanatory.

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 29% across 14 parameters, so the description needs to compensate and largely does not. It touches only 'name' and 'contacts' (mirroring what the schema already says) and leaves fields like address1/address2, id_number, vat_number, public_notes and private_notes with no added meaning.

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 ('Create a client') and adds the notable scope detail that contacts can be created in the same call. It does not explicitly differentiate from the sibling invoiceninja_update_client, but create-vs-update is unambiguous from the 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?

Adds a real precondition not present in the schema — 'Give at least a name or one contact' — which matters because the schema declares zero required parameters. However, it names no alternatives (e.g. update_client for existing clients, get_client/list_clients for lookup) and gives no when-not-to-use guidance, 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?

The destructiveHint annotation already signals a mutating write, so the bar is lower, but the description adds nothing behavioral beyond it: no auth/permission requirements, no statement about what side effects occur (e.g., whether the re-invoice flag triggers downstream billing), and no return information. The 'optionally tied to...' clause restates parameters rather than disclosing 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 tight sentences with the core purpose front-loaded and the endpoint noted compactly. Nothing is wasted, though the endpoint string is marginally redundant given the tool 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?

For a 14-parameter mutation with no output schema and minimal annotations, the description covers the core intent but leaves gaps: it does not explain success/return behavior or how the optional relations interact. It is minimally adequate rather than complete.

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

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

Schema coverage is 79%, near the high band, so the schema documents most parameters (client_id, vendor_id, project_id, should_be_invoiced, etc.) itself. The description merely echoes a few of these relationships and adds no syntax, format, or default information beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb and resource ('Log an expense') and names the optional relations (vendor, client, project) plus the re-invoice flag, so the agent knows exactly what operation this is. It is distinguishable from sibling creators like create_invoice or create_client by resource, though it never explicitly contrasts them.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of the obvious alternative (list_expenses) or any exclusion. Usage is only implied by the verb 'Log'.

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 are thin (only destructiveHint=true), so the description carries extra weight, and it delivers the key behavioral fact: the created object is a draft that is not sent or emailed, validated by the named lifecycle alternatives. It does not address permissions/auth or explain the destructiveHint=true on a create operation, which is a notable omission.

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

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

Two short sentences with the scope constraint front-loaded, plus a terse endpoint note. No filler; every clause earns its place.

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

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

For a 17-parameter create tool with no output schema, the description covers creation semantics and lifecycle routing adequately, and the full schema covers parameter detail. It omits any note on return value or on the destructiveHint meaning, but the core call-time 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% across all 17 parameters, so the schema already documents each field (client_id hashed id, dates, discounts, line items). The description adds no syntax or format detail beyond that, so the baseline 3 applies.

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

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

States a specific verb (Create), resource (invoice), and a materially narrowing scope qualifier (DRAFT) for a client. An agent can immediately distinguish it from convert_quote_to_invoice or update_invoice.

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

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

Explicitly says the invoice is not sent or emailed and names the two follow-up siblings, invoiceninja_mark_invoice_sent and invoiceninja_email_invoice, that handle sending. This is an explicit when-to-use and when-to-use-something-else statement.

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?

Description says 'Create' while annotations declare destructiveHint=true, which is contradictory for a creation operation. No additional behavioral context such as permissions, side effects, or what gets destroyed is provided.

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, front-loaded with purpose and optional field summary, then endpoint. No fluff, though the endpoint line is technical detail rather than agent-critical.

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 mutation tool with no output schema and only a destructiveHint annotation, the description is too sparse. It omits required parameters, return behavior, and any behavioral caveats, leaving gaps an agent must fill from schema alone.

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?

Description mentions optional hourly task rate, budget, and due date, mapping to some parameters, but schema coverage is 63% and three parameters (public_notes, private_notes, budgeted_hours) are undocumented in both. The description adds marginal meaning 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 'Create' and resource 'project', and clarifies it's for a client with optional fields. Distinguishes from siblings by being a create operation, though it doesn't explicitly compare to alternatives.

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

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

No explicit guidance on when to use this tool versus alternatives like invoiceninja_create_task or invoiceninja_create_client, nor prerequisites or permissions. Only implies usage through the purpose statement.

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

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

Annotations only declare destructiveHint=true, so the description's disclosure that the result is a DRAFT and that no email is sent is genuinely useful side-effect context. It does not, however, address the surprising destructiveHint on a create operation, nor permissions, idempotency, or what happens to any pre-existing data.

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

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

Two short sentences with the draft/no-email constraint front-loaded, plus a compact endpoint reference. No filler or redundancy.

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

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

For a 17-parameter mutation tool with no output schema, the description supplies the essential orientation (draft quote, no email, API route) while the fully documented schema carries the field-level burden. It could say more about the draft lifecycle (e.g., how the quote later becomes an invoice), but nothing required to invoke it correctly 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 description coverage is 100% and every parameter is documented in the schema, so the baseline is 3. The description contributes no parameter-level detail beyond the schema, only the generic mention of "for a client" which maps to the required client_id.

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 DRAFT quote (estimate) for a client") and disambiguates the quote/estimate terminology. It also indirectly distinguishes itself from invoiceninja_create_invoice and invoiceninja_convert_quote_to_invoice by making clear this produces a draft quote rather than an invoice.

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 note "Nothing is emailed" gives the agent a clear condition for choosing this tool over emailing siblings like invoiceninja_email_invoice, and the DRAFT qualifier signals this is a preparatory step. However, it never explicitly names an alternative tool or states when a quote should be created versus an 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 provide only destructiveHint=true, so the description carries the bulk of the behavioral burden. It says nothing about what the write does beyond creating a record — no note on time_log overlap rejection, no auth/permission requirements, no return value (e.g., the new task id), and no explanation of why the operation is flagged destructive.

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

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

Two short sentences with zero filler and the core action front-loaded; the endpoint reference is a compact trailing detail. It is efficient, though the same brevity is also what leaves behavioral gaps.

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 only destructiveHint=true and no output schema, the description is too thin: it does not say what a successful call returns, whether a client_id/project_id is needed, or how logged time interacts with the task. The schema covers inputs, but the behavioral/return context an agent needs is absent.

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 six parameters are fully documented in the schema (rate defaults, hashed ids, Unix timestamp semantics, overlap rule). The description adds no parameter meaning beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('Create a task'), plus scope ('optionally with logged time entries, for a client or project') and the underlying endpoint. It is clear enough to distinguish from sibling creators like invoiceninja_create_expense or invoiceninja_create_project, though it never names those siblings 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?

No when-to-use guidance, no mention of alternatives (e.g., invoiceninja_list_tasks for reading existing tasks), and no prerequisites such as needing a client_id or project_id. Only the implied 'this is how you create things' usage is present.

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

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

Annotations only declare destructiveHint=true; the description adds the materially important behavior that a real email is dispatched to invited contacts, that the invoice is marked sent as a side effect, and that the action is irreversible. It also discloses the underlying API call (POST /api/v1/invoices/bulk with action=email), which is unusually rich disclosure for a mutation 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?

Three short sentences, front-loaded with the risk label 'OUTWARD-FACING' and the irreversibility warning. No filler, and the API mapping is compressed into a single clause.

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 only two fully-documented parameters, a destructiveHint annotation, and no output schema, the description covers everything an agent needs: what it does, the side effect, the irreversibility, and the confirmation requirement. Nothing material is missing.

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

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

Schema coverage is 100%, so the schema already documents both invoice_id (hashed id format) and the email_type enum. The description adds no parameter-level detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('sends a real email with the invoice to the client's invited contacts, and marks the invoice sent'), which cleanly separates it from the sibling mark_invoice_sent, whose scope is only the status change. An agent can select correctly without opening either 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?

'OUTWARD-FACING' plus 'Cannot be unsent — confirm with the user first' gives clear when-to-use context and a hard guardrail. It stops short of explicitly naming mark_invoice_sent as the lighter alternative when no email is wanted, so it is strong but not fully routing.

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

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

The annotations already declare readOnlyHint=true, covering the safety profile. The description adds useful context by naming the return payload (contacts, address, balance, paid-to-date), which goes beyond the annotations. It does not disclose error behavior, permissions, or rate limits, so it remains at a moderate level.

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

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

The description is two sentences with no wasted words. The first sentence front-loads the purpose and returned fields, while the second provides the API endpoint mapping. It is appropriately sized for a simple getter.

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 getter with 100% parameter coverage and a readOnlyHint annotation, the description is complete enough. It names the returned fields, compensating for the lack of an output schema. Nothing an agent needs in order to call it correctly 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 description coverage is 100%, and the single parameter client_id is fully documented with a hashed ID example. The description adds only 'by id', which does not provide syntax or format details beyond what the schema already offers. The baseline of 3 is appropriate when the schema does the heavy lifting.

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

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

The description states a specific verb and resource: 'Fetch one client by id.' It also lists returned fields (contacts, address, balance, paid-to-date), making the purpose clear. However, it does not explicitly differentiate itself from siblings like list_clients, create_client, or update_client, so it falls short of the top score.

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 explicit guidance on when to use this tool versus alternatives such as list_clients or get_invoice. The phrase 'by id' weakly implies retrieval of a known client, but there is no stated condition, exclusion, or alternative tool to route the agent.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature needs no restating. The description adds useful context by enumerating what the response contains (line items, totals, balance, dates, status, invitations), but says nothing about auth requirements, error behavior for unknown ids, or rate limits.

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

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

Two compact sentences with the resource and scope front-loaded and the endpoint appended as supporting detail. Nothing is redundant or padded.

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 summarizes the returned fields, which is the main missing structured data. It is nearly complete for a single-entity read, lacking only edge-case behavior for invalid or missing ids.

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

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

Schema coverage is 100% and the single parameter is fully documented in the schema (hashed id with example), so the description only echoes 'by id'. Baseline 3 is appropriate when the schema carries the parameter semantics.

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

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

States a specific verb (fetch) and resource (one invoice) with the identifier qualifier 'by id', clearly distinguishing it from invoiceninja_list_invoices. The endpoint reference (GET /api/v1/invoices/{id}) reinforces the single-resource scope.

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

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

The phrase 'one invoice by id' implies when to use it versus list_invoices, but the alternative is never named and no prerequisites (e.g. needing the hashed id from a list call) are stated. Usage is inferable rather than explicit.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the safety profile is covered. The description usefully adds that the payload includes line items, totals, status, and the conversion target (invoice_id), but says nothing about error/not-found behavior or permissions, so it adds moderate value over the annotation.

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, front-loaded with the core action and scoping, with no filler. The trailing API-endpoint mapping is slightly redundant but cheap and confirms the underlying resource.

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

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

For a single-parameter read tool with no output schema, the description compensates by summarizing the return shape and the conditional invoice_id. Safety is handled by annotations, leaving only minor gaps (error cases) that are not critical for calling it correctly.

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

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

With 100% schema description coverage and a single fully documented parameter (hashed id with example), the schema already carries the semantics and the description adds no format or syntax detail. 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?

States a specific verb and resource ('Fetch one quote by id') and even enumerates the returned contents (line items, totals, status, converted invoice_id). It is clearly the singular counterpart to list_quotes, though it never explicitly names a sibling to differentiate itself.

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

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

Usage is only implied: 'by id' signals you call it when you already know the quote's identifier. There is no explicit when-to-use, no when-not-to-use, and no pointer to alternatives such as list_quotes or convert_quote_to_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 readOnlyHint=true annotation already establishes this is a safe, non-destructive read, so the description only needs to add context beyond that. It does add useful detail — that results include balances and contacts and that the underlying call is GET /api/v1/clients — but says nothing about pagination behavior, result caps, or whether the balance data is computed vs stored.

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

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

Two tight sentences with the scope and return contents front-loaded before the endpoint reference. No filler, though the trailing endpoint note is closer to implementation trivia than agent-facing 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?

There is no output schema, so the description carries some burden of explaining results, and it does mention balances and contacts. However, for a nine-parameter paginated list endpoint it omits pagination semantics and result-shape expectations, leaving the agent to infer how pages interact with per_page and status filters.

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 nine parameters (including sort syntax, balance operators, and per_page limits) are already documented in the schema. The description restates the name/email/number search axes but adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb (List) and resource (clients), and adds scope detail: it returns balances and contacts and supports search by name, email or number. It is distinguishable from invoiceninja_get_client by the plural 'List' framing, but it never explicitly contrasts with that sibling, which keeps 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?

Usage is implied rather than stated: 'List clients' suggests browsing/retrieval, and the search phrase hints at lookup use cases. There is no explicit guidance on when to pick this over invoiceninja_get_client (single client by id) or the other list_* siblings, and no stated exclusions or prerequisites.

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

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

The readOnlyHint annotation already establishes this is a safe, non-mutating read, so the description's burden is reduced. It adds the useful detail that this maps to GET /api/v1/expenses, but says nothing about pagination behavior, result ordering, or the response shape.

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

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

Two short sentences with the capability statement front-loaded and the API endpoint trailing — no filler or repetition. It is efficient, though the extreme brevity leaves the definition doing little work beyond the structured 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 an 8-parameter list tool with no output schema, the agent still lacks any description of what an expense record contains or how results are paginated/ordered, which the description does not address. The fully documented schema and the readOnlyHint annotation compensate for most of the gap, keeping this at a minimum-viable level.

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 8 parameters are already documented in the schema with formats, ranges, and examples (e.g., sort syntax, status values). The description's note about client and invoicing/payment-state filters loosely maps to client_id and client_status but adds no syntax or semantics beyond the schema, 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 and resource ("List expenses") and names the filter dimensions (client, invoicing/payment state). It does not distinguish itself from sibling list tools such as invoiceninja_list_invoices or invoiceninja_list_payments, but the noun 'expenses' makes the target 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 mention of client and invoicing/payment-state filtering implies when the tool is useful, but there is no explicit when-to-use or when-not-to-use guidance and no pointer to alternatives. Adequate but with a clear gap for an agent choosing among ~10 list_* siblings.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description goes beyond that by supplying the status_id code legend (1 draft … 6 reversed), which is genuinely useful behavioral context for interpreting returned records given there is no output schema. It stops short of describing pagination defaults or result ordering, so not a 5.

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

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

Three tight sentences, each earning its place: purpose first, then the filterable dimensions, then the status-code legend and endpoint. The most decision-relevant information is 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 a nine-parameter, zero-required listing tool with no output schema and only a readOnly annotation, the description supplies the missing piece an agent needs to interpret results (status code meanings). It leaves minor gaps around pagination behavior and sorting defaults, which the schema partially covers.

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 nine parameters are already documented; the baseline is 3. The description echoes the client and payment-status filtering (client_id, client_status) but adds no format or syntax detail beyond the schema, and its status_id legend refers to a returned field, not an input 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?

The description states a specific verb and resource ('List invoices') and immediately narrows the scope to client and payment-status filtering, which cleanly separates it from sibling get_invoice (single record) and from the other list_* tools keyed to different resources. An agent can identify the tool's role 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 notes what the results can be filtered by, which hints at usage, but never says when to choose this over get_invoice or the other list tools, nor does it state any precondition or exclusion. Guidance is implied at best and absent in any comparative sense.

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 reinforces it ('this server never records or refunds payments') while adding useful shape information about what is returned, including applied-invoice relationships. It does not mention pagination limits or ordering behavior, keeping it short of a 5.

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

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

Two sentences plus an endpoint reference; the return content is front-loaded, the read-only constraint follows immediately, and nothing is redundant or padded.

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 summarizes the return payload and its relationships, and the schema covers all inputs. Minor gap: no mention of pagination/default page size behavior, which matters for a 7-parameter list tool.

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

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

Schema description coverage is 100%, so page, sort, filter, number, status, per_page and client_id are already fully documented. The description adds no filtering or pagination semantics 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?

Specific verb (list) plus resource (payments received) and an enumeration of the returned fields (amount, date, refunded/applied totals, paymentables). This clearly distinguishes it from the many sibling list_* tools and from get_invoice.

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 conveys that this is a read path and notes that the server never records or refunds payments, which implicitly frames usage. However, it names no alternative tool or condition (e.g., when to prefer get_invoice for one payment, or list_invoices for invoice-level views), so routing guidance 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=true already declares this as a safe read, so the description's added value is the note that prices, costs and default taxes are returned. It does not disclose pagination/return-shape details beyond that, which is acceptable given the annotation covers the safety profile.

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

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

Two compact sentences, front-loaded with the operation and the notable returned fields; the trailing API endpoint mapping is mildly redundant but useful for orientation. 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?

There is no output schema, and the description only briefly hints at returned fields; it also says nothing about pagination behavior even though per_page defaults to 20 and the status filter can return archived/deleted records. Adequate but leaves gaps an agent may care about.

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

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

Schema description coverage is 100% with all six parameters documented, including page, per_page, sort syntax, filter, status and product_key. The description adds no parameter detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('List products / services in the catalog') and even names the returned attributes (price, cost, default taxes), which clearly separates it from sibling list_* tools covering other resources. It stops short of explicitly contrasting with alternatives like a single-product fetch, 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?

Usage is implied by the read-only listing nature, but there is no explicit statement of when to use this versus other tools or when to narrow results (e.g. use filter/status for large catalogs). It provides context without guidance or exclusions.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description's burden is lower. It adds the upstream endpoint (GET /api/v1/projects) and the set of returned fields, but says nothing about pagination behavior or default result limits beyond what the schema already documents.

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

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

Two compact sentences with zero filler, and the core purpose is front-loaded before the endpoint detail. Efficient, though the second sentence is largely redundant with the title.

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 list tool with a fully documented schema, the description is adequate. Since there is no output schema, enumerating the returned fields (client, budgeted hours, task rate, current hours, due date) usefully compensates, though pagination behavior remains unstated.

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

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

Schema description coverage is 100% and every parameter (page, sort, filter, number, status, per_page, client_id) is fully documented in the schema. The description adds no additional syntax or semantic detail, so the baseline 3 applies.

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

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

States a specific verb and resource ("List projects") and enumerates the fields returned, which distinguishes it from the many other list_* siblings by resource. It stops short of noting any scoping or filtering behavior that would fully separate it from siblings like list_tasks or list_clients.

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, no mention of pagination or filter-driven retrieval despite the schema exposing page, per_page, filter, status, client_id. The agent is left to infer usage entirely.

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

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

Annotations declare readOnlyHint=true, so the safety profile is covered. The description adds the GET endpoint which is redundant with readOnlyHint but confirms the read semantics. It does not disclose pagination defaults, response shape, or filtering limits beyond what annotations and schema state.

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?

Single tight sentence with the verb and resource front-loaded, followed by a note on filtering and the API endpoint. Efficient with no wasted prose, though the endpoint reference is somewhat 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 an 8-parameter list tool with readOnlyHint and full schema coverage, the description covers the essential purpose and filtering. However, it doesn't clarify relationship to siblings (get_quote, list_invoices) or pagination behavior, leaving a gap for an agent choosing between tools.

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

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

Schema coverage is 100%, so all 8 parameters are already documented in the schema. The description mentions client and status filtering but adds no syntax or semantics beyond that. Baseline 3 is appropriate given the schema does the heavy lifting.

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

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

States a specific verb (list) and resource (quotes), and clarifies the synonym 'estimates' which is helpful given the domain. Sibling differentiation is not explicit, though 'list quotes' vs 'get quote' is distinguishable by name. Solid but no explicit sibling comparison.

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 mentions filterability but gives no guidance on when to use this vs get_quote for a single quote, or list_invoices. It does not state when-not-to-use or alternatives. Only implied usage at best.

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

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

The annotations already declare readOnlyHint=true, and 'Read-only' merely repeats that, earning no extra credit. What the description does add is beyond the annotations: the shape of the returned schedule data (frequency, next send date, remaining cycles), which is useful when no output schema exists. It stops short of explaining pagination or sort behavior for a list endpoint.

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

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

Three short sentences, front-loaded with the resource and its returned fields, then the safety note and the raw API endpoint. Every sentence carries information, though the GET path is marginal value for an agent that only invokes 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?

For a read-only list tool with no output schema, the description adequately covers what is returned and the read-only nature, and the schema fully carries the filtering parameters. The missing piece is pagination/filtering guidance, which matters given seven optional filters and no defaults stated.

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 seven parameters (page, per_page, sort, number, status, client_id, client_status) are already documented in the schema with examples and ranges. The description adds nothing about parameter semantics, so the baseline of 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?

States a specific verb (List) and a specific resource (recurring invoice schedules), and names the salient returned fields (frequency, next send date, remaining cycles). The word 'recurring' cleanly separates it from the sibling invoiceninja_list_invoices, so an agent can pick it 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 description gives no when-to-use guidance, no mention of alternatives such as invoiceninja_list_invoices, and no note about pagination or filtering strategy despite seven available filter parameters. Usage is only implicit from the verb.

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

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

The readOnlyHint annotation already establishes this is a safe read, so the description is not carrying the full burden. It adds value by describing the shape of returned data (time_log, duration, rate, linked entities) and the underlying endpoint, but says nothing about pagination behavior, default result limits, or ordering despite exposing page/per_page/sort parameters.

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 verb and resource, with the returned-field list second. Nothing is wasted, though the API-endpoint note is of marginal value to an agent.

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 100% schema coverage, readOnlyHint annotations, and no output schema needed, the description supplies enough context to select and invoke it correctly. Only the absence of any when-to-use guidance keeps it from being fully complete.

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

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

Schema description coverage is 100% across all 8 parameters, so the schema already documents page, sort, filter, number, status, per_page, client_id and client_status in detail. The description adds no parameter-level meaning beyond that, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb (List) and resource (tasks / time entries) and even enumerates the returned fields (time_log, duration, rate, linked client/project/invoice), which lets an agent tell it apart from the create_task and list_projects siblings without opening schemas. However, it does not explicitly contrast itself with any sibling by 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?

There is no guidance about when to use this tool versus alternatives such as list_projects or create_task, nor any mention of prerequisites or the meaning of the filters. Usage is only implied by the name and verb.

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 establishes the safe, non-mutating profile, and the description usefully discloses the API endpoint and that records include contacts and address. It adds no pagination or rate-limit context, but the schema already documents paging, so the incremental value over structured data is modest.

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 verb and resource, with no filler. The endpoint reference is compact and earns its place; 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 simple read-only list tool with complete schema coverage and a readOnlyHint annotation, the description covers purpose, payload, and endpoint adequately. An agent has everything needed to invoke it correctly; only richer usage context 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 description coverage is 100%, so all six parameters (page, sort, filter, number, status, per_page) are fully documented in the schema itself. The description adds no filtering or sorting syntax beyond that, which is acceptable given the schema does the heavy lifting.

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

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

States a specific verb (List) and resource (vendors/suppliers) and notes the returned payload (contacts and address), so an agent knows exactly what it fetches. There is no competing vendor-list sibling, so no differentiation is needed, but it also does nothing to distinguish itself from the broader list_* family 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?

No when-to-use guidance, no mention of when this tool is preferable to searching clients via list_clients or filtering vendors by number. Usage is only implied by the tool name; nothing tells the agent how it fits in a workflow.

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

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

With destructiveHint=true already declared, the description adds meaningful behavioral context beyond the annotation: it moves the invoice out of draft and adds the amount to the client's balance. It does not state whether the transition is reversible, which would complete the picture for a 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?

Two tight sentences with the key distinction (no email) and the state effect front-loaded, followed by the backing endpoint. No filler.

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

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

For a one-parameter mutation with no output schema, the description covers the essential side effects and the underlying endpoint. It is nearly complete, missing only reversibility/return behavior, which is minor here.

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

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

Schema description coverage is 100% and the single invoice_id parameter is fully documented (hashed id with example). The description adds no format or constraint detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Mark a draft invoice as sent') with the crucial scope qualifier 'WITHOUT emailing it', which cleanly separates it from the sibling invoiceninja_email_invoice. An agent can tell exactly what this does and how it differs from the email path 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?

The phrase 'WITHOUT emailing it' implicitly routes the agent here instead of email_invoice when no email should be sent, giving clear usage context. It stops short of explicitly naming the alternative or stating when the tool should not be used.

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

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

Annotations only supply destructiveHint=true, but the description adds genuinely useful semantics: omitted fields are preserved, and passing 'contacts' destroys and replaces the existing contact list. That destructive sub-behavior is exactly the kind of context an agent needs to avoid accidental data loss. It stops short of covering permissions, error behavior, or response shape.

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 lead with the action and the partial-update rule before the destructive contacts caveat and the raw endpoint. No filler, well front-loaded.

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

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

For a 15-parameter mutation with no output schema and low schema coverage, the definition covers the update semantics and the destructive contacts edge case but leaves the majority of fields and all failure/response behavior unaddressed. Adequate but with clear gaps.

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

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

Schema description coverage is only 33%, so most of the 15 parameters are undocumented in both places. The description partially compensates by explaining that unpassed fields stay unchanged and that 'contacts' is a full replacement, but it leaves city, phone, state, website, addresses, vat_number, notes, and others without added meaning.

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 ('Update a client's details') and immediately scopes the operation as a partial update. It is readily distinguishable from the sibling create_client, get_client, and list_clients by verb alone, though it never names those alternatives 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?

Use is implied by the verb and the 'only the fields you pass change' clause, which tells the agent this is a patch-style update rather than a full overwrite. There is no guidance on when to prefer this over create_client, when get_client should precede it, or any prerequisite/exclusion.

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 destructiveHint annotation only signals 'this mutates'; the description specifies exactly what is destroyed ('line_items ... replace every existing line') and scopes the blast radius ('only the fields you pass change'). It also confirms no side-effect sending occurs, which the annotation does not convey.

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 carries the verb, the partial-update contract, the destructive caveat, the no-send guarantee, and the endpoint. Every clause earns its place and the most consequential fact (line replacement) is stated early.

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-param mutation tool with no output schema, the description covers the essentials an agent needs to call it safely. Minor gaps remain: no mention of what the call returns, and no auth/permission prerequisites, though nothing required to invoke it is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a semantic the schema only half-captures: partial-update semantics ('only the fields you pass change') for all 17 parameters and the replacement behavior of line_items. That is real value beyond the field-level descriptions.

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 ('Edit an invoice') and distinguishes itself from sibling write/read tools like create_invoice and get_invoice. It even names the underlying endpoint (PUT /api/v1/invoices/{id}), leaving no ambiguity about what the tool does.

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?

'Does not send anything' implicitly routes the agent away from send/email siblings (e.g. invoiceninja_email_invoice) and clarifies this is a data-only edit. It gives clear context for use but never names an explicit alternative or a when-not-to-use condition.

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