Invoice Ninja MCP by usefulapi

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

Annotations only declare destructiveHint=true; the description adds real behavioral context beyond that by disclosing the side effect (the source quote is marked converted and linked) and the return value (the new invoice). It stops short of noting whether the operation is idempotent or what happens on repeat conversion.

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 action and side effect front-loaded; the trailing endpoint reference (GET /api/v1/quotes/{id}/convert_to_invoice) is mildly redundant but provides integration context at negligible cost.

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 conversion tool with no output schema, the description covers action, side effects, and return value, which is everything an agent needs to call it correctly alongside the destructiveHint annotation.

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 quote_id parameter is well documented with a hashed-id example, so the schema carries the meaning. The description adds nothing about the identifier format or handling, making the baseline 3 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 (convert) and both resources (quote -> invoice), and clarifies the resulting state (quote marked converted, links to new invoice). This clearly distinguishes it from sibling invoiceninja_create_invoice, which creates from scratch rather than from an existing quote.

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 single-sentence purpose makes the appropriate context implicit (you have a quote that should become an invoice), but there is no explicit when-to-use guidance or exclusion, e.g. vs. invoiceninja_create_invoice or what happens when converting an already-converted quote.

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 and title come from annotations, so the description doesn't repeat them. It adds the POST endpoint and the minimum-viable-input rule, but says nothing about side effects, duplicate handling, or permission requirements for a write operation with 14 optional 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?

Two tight sentences with the core constraint front-loaded. Including the raw REST endpoint is marginally useful but slightly noisy for an agent-facing definition.

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 write tool with no required fields, no output schema, and thin schema descriptions, the description is under-specified. It gives no sense of which fields map to the client record versus contacts, nor what a successful call returns.

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

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

Schema coverage is only 29% across 14 parameters, so the description must compensate and largely doesn't. 'At least a name or one contact' is the only param-level guidance and only touches two of the fourteen fields; the rest (address, vat_number, country_id, etc.) are undocumented in both places.

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 client') and adds that contacts can be created inline, which differentiates it from get_client/update_client/list_clients in the sibling set. It doesn't explicitly name an alternative, but the purpose 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?

'Give at least a name or one contact' supplies a genuine precondition for calling the tool, which is useful. It stops short of stating when to prefer this over siblings (e.g. update_client for existing clients) or how it interacts with list_clients lookups.

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 annotation already declares destructiveHint=true, so the mutation nature is covered structurally. The description adds real behavioral context beyond that: the expense may be tied to a vendor/client/project and can be flagged for re-invoicing, plus the underlying endpoint. It still omits permissions, reversibility, or confirmation behavior, so it is adequate but not rich.

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

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

Two tight sentences with the core purpose front-loaded and no filler. The trailing endpoint reference ('POST /api/v1/expenses') is slightly meta but useful for API mapping, keeping it just short of maximally efficient.

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

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

For a 14-parameter mutation with only one required field and no output schema, the description is thin: it never surfaces the required amount, gives no sense of the returned record, and says nothing about side effects. It covers purpose and some optional associations but leaves an agent under-informed about the write.

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%, just under the high threshold, and the schema already documents most parameters (date, amount, client_id, vendor_id, project_id, currency_id, etc.). The description's mention of vendor/client/project ties loosely mirrors existing param docs but adds no syntax or format detail, and the undocumented fields (tax_name1, tax_rate1, private_notes) remain unexplained.

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 ('Log an expense') and enumerates the optional associations (vendor, client, project) plus the re-invoicing flag, which goes beyond a bare restatement of the name. It does not, however, distinguish itself from the many sibling create_* tools, so an agent must infer that this one is the expense-specific creator.

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 and no routing to alternatives such as list_expenses or the invoice-creation tools. The description only implies usage through the optional associations; it never tells the agent when this tool is the right choice.

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 provide destructiveHint, so the description carries most of the burden and delivers the key behavioral fact: the record is created as a draft and will not be delivered. It does not describe what gets returned (notably the new invoice id needed for the follow-up calls) or the side effects of creating the resource.

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

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

Three short clauses, zero filler, and the lifecycle constraint (draft, not sent) is front-loaded before the next-step routing. Every sentence 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 creation tool with no output schema and thin annotations, the description covers purpose, state, and the follow-up workflow. It leaves a gap around the returned identifier needed to feed mark_invoice_sent/email_invoice, which is the one thing an agent must know to chain calls.

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

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

Schema description coverage is 100% across all 17 parameters, including formats (YYYY-MM-DD), the hashed-id convention, and the line_items replacement warning, so the schema already does the heavy lifting. The description adds no parameter-level meaning beyond that baseline.

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

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

States a specific verb (Create), resource (invoice), and a distinguishing state qualifier (DRAFT) up front. It explicitly separates itself from the send/email path, so an agent can tell it apart from invoiceninja_mark_invoice_sent and invoiceninja_email_invoice without opening any schema.

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

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

Gives clear sequencing guidance: it is not sent or emailed, and the two follow-up tools are named explicitly. It does not cover the other plausible alternative (invoiceninja_create_quote vs connoted convert_quote_to_invoice), but the primary routing decision is unambiguous.

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 provide destructiveHint=true, which is a coarse safety signal. The description adds that this is a POST creation endpoint and mentions optional fields, but it does not explain authentication requirements, whether duplicate project names are allowed, what happens to omitted fields, or any side effects.

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 compact single sentence plus a backend endpoint note. The main purpose is front-loaded, and there is little wasted text, though the POST endpoint 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?

With no output schema, the description should explain what the tool returns or confirm success behavior, but it does not. It also omits required fields, permission expectations, and any error or side-effect context for a creation tool with eight parameters.

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

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

Schema description coverage is 63%, so the schema partially documents parameters. The description names three optional fields (task_rate, budget, due_date) and implies name and client_id are required, but it omits color, public_notes, and private_notes and adds no format details beyond the schema.

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

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

The description states a specific verb and resource: create a project. It adds key optional attributes (hourly task rate, budget, due date) and the underlying POST endpoint. It does not explicitly differentiate from sibling create tools, but the resource is unambiguous.

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

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

There is no guidance on when to use this tool versus alternatives such as list_projects, create_task, or create_client. The description only states what the tool does, leaving all usage context to inference.

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

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

Annotations only carry destructiveHint=true and a title, so the description usefully adds that the created object is a draft, that no notification is dispatched, and that edits are non-final. It does not cover permission requirements or what happens to unset fields, but the draft/no-email disclosure is meaningful context beyond the structured hints.

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

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

Two tight sentences with the draft/no-email constraint front-loaded, plus the API endpoint for traceability. Very little waste, though the endpoint sentence is arguably redundant for an agent that only needs tool semantics.

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 one required field and full schema coverage, the description supplies the essential framing (draft state, no side-effect email). With no output schema, it could have noted what the response contains (e.g. the new quote id) for a follow-up call, which is the one remaining gap.

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

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

Schema description coverage is 100%, so parameter meaning is already fully documented (including line_items replacement behavior and hashed-id formats). The description adds only "for a client," which does not extend beyond the schema's required client_id hashed-id entry.

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

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

The description names a specific verb (Create) and resource (quote/estimate) and immediately pins the scope: it is a DRAFT, not a finalized or sent document. This separates it from siblings like invoiceninja_create_invoice and invoiceninja_email_invoice 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?

"Nothing is emailed" implies the agent should reach for invoiceninja_email_invoice (or convert_quote_to_invoice) as the next step, and implicitly contrasts with the draft-only path. But the when-to-use condition is only implied, with no explicit alternatives or preconditions (e.g. does the client need to exist first?).

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, and the description adds little beyond that — it notes the task can include time entries but says nothing about permissions, side effects on existing data, or whether the time_log overlaps are rejected (that constraint lives only in the schema). The POST endpoint reference is an implementation detail rather than useful behavioral context.

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 core action front-loaded and no filler. The trailing 'Invoice Ninja: POST /api/v1/tasks' is borderline unnecessary implementation detail but is short enough not to hurt 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 mutation tool with no output schema, the description covers the essentials and the schema is fully documented. However, it omits any behavioral or prerequisite context (auth, side effects) that an agent would want before creating a task, leaving a clear but moderate gap.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters thoroughly, including the time_log structure and rate default. The description paraphrases client/project/time-log applicability but adds no syntax or format detail beyond the schema, so it holds at the baseline 3.

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 task') and adds the key qualifier 'optionally with logged time entries, for a client or project,' which accurately distinguishes it from siblings like create_expense. It does not explicitly name an alternative tool, but the action itself 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?

No explicit when-to-use or when-not-to-use guidance, and no alternatives are named (e.g., list_tasks for retrieval). The phrase 'for a client or project' hints at context but does not tell the agent when this tool is preferable to others.

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

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

The description adds substantial context beyond the destructiveHint annotation: it discloses the exact audience (client's invited contacts), the irreversible nature ('Cannot be unsent'), and the side effect of marking the invoice sent. This is exactly the behavioral detail an agent needs before invoking a destructive, outward-facing operation.

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 critical warning is front-loaded, and the text is dense with no filler. The trailing API endpoint reference ('POST /api/v1/invoices/bulk with action=email') is implementation detail that does not help an agent select or invoke the tool, slightly weakening conciseness.

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

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

For a two-parameter tool with no output schema and a destructiveHint annotation, the description covers purpose, audience, side effects, irreversibility, and a user-confirmation requirement. Nothing needed 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%, so both parameters are fully documented in the input schema. The description adds no further meaning to invoice_id or email_type, so the baseline of 3 is appropriate given the schema already does the work.

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

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

The description names a specific verb and resource ('sends a real email with the invoice') and clarifies the side effect of marking the invoice sent. It implicitly distinguishes itself from invoiceninja_mark_invoice_sent by emphasizing the actual email transmission, but it never names that sibling explicitly, leaving a small inference gap.

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

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

It gives a clear precondition ('confirm with the user first') and signals the tool is outward-facing, which is strong contextual guidance. However, it does not explicitly state when not to use it or name the alternative tool for merely marking an invoice sent without emailing.

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 declares this is a safe read, and the description adds meaningful context beyond that: the returned payload contains contacts, address, balance and paid-to-date. Since no output schema exists, disclosing the response contents is genuinely useful. It omits error behavior (e.g. invalid or unknown id), which keeps it from 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 short sentences, zero waste. The verb and scope lead, and the endpoint reference is a compact secondary detail.

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 covers both what it takes (id) and what it returns (contacts, address, balance, paid-to-date), which is the bulk of what an agent needs. Missing only failure modes and any permission requirements.

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

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

Schema description coverage is 100%, so the schema already documents the single client_id parameter, including its hashed format example. The description only restates 'by id' without adding format or constraint 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 ('Fetch one client by id') and even names the underlying endpoint, so an agent can distinguish it from invoiceninja_list_clients or invoiceninja_create_client at a glance. It stops short of explicitly routing to those siblings, which is the only thing separating it from a 5.

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

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

The singular scope plus the required id implies 'use this when you already have one client's id and need its detail', which is adequate context. However, there is no explicit when-to-use statement, no mention of when to prefer invoiceninja_list_clients instead, and no preconditions.

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, so the bar is lower. The description adds genuine context by disclosing what the response contains (line items, totals, balance, dates, status, invitations) and the underlying API path, which compensates for the absence of an output schema.

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

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

A single tight sentence with the return contents front-loaded, plus the endpoint for reference. 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 one-parameter read tool with no output schema, the description is nearly complete: it names the input requirement and what comes back. Only the lack of explicit alternatives/usage routing keeps it from a 5.

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

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

Schema coverage is 100%, so the single parameter and its hashed-id format are fully documented in the schema. The description only restates 'by id' without adding syntax or constraints, 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 (fetch) and resource (one invoice) with the keying condition (by id), which cleanly distinguishes it from the sibling list_invoices. The enumeration of returned content further sharpens what 'get one' means.

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' tells the agent an id is needed, but there is no explicit when-to-use vs list_invoices or when-not guidance. Adequate but leaves routing to inference.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered and the bar is lower. Beyond that the description adds real behavioral context by enumerating the returned fields, including the noteworthy conditional that invoice_id is present only "if any" (i.e. only after conversion). It does not cover error behavior for an unknown id or auth requirements.

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

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

Two tight clauses, front-loaded with the action and its id argument before the payoff of what comes back. The appended "GET /api/v1/quotes/{id}" anchors it to a concrete endpoint with no wasted words.

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

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

There is no output schema, so the description must (and does) characterize the return payload — line items, totals, status, and the conversion link. Combined with a fully documented single parameter and readOnlyHint, an agent has everything needed to call 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?

The single parameter has 100% schema description coverage, including the hashed-id format example, so the schema does the heavy lifting and baseline 3 applies. "By id" in the description merely restates the schema and adds no syntax or format detail beyond it.

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 gives a specific verb and resource ("Fetch one quote by id") and enumerates the payload (line items, totals, status, converted invoice_id), so an agent can distinguish it from bulk siblings like invoiceninja_list_quotes. It stops short of naming any sibling explicitly, and the get_invoice/convert_quote_to_invoice overlap is left to inference.

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

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

Usage is implied by the shape of the tool — you call it when you have a quote id and need the detail record — but there is no explicit when-to-use, no when-not-to-use, and no pointer to invoiceninja_list_quotes for enumeration or invoiceninja_convert_quote_to_invoice for the conversion action. Adequate, not guiding.

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 this is a safe read. The description adds that results carry balances and contacts, which is useful context beyond the annotation, but says nothing about default page size, sorting defaults, or the shape of the paginated response.

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

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

Two tight sentences, front-loading the resource and returned fields before the filter options. The trailing API endpoint reference is slightly redundant but harmless 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?

With no output schema, the description usefully names what each record contains (balances, contacts) so the agent knows the return payload. Missing only pagination and ordering defaults for a nine-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 all nine parameters are already documented in the schema with examples (e.g. 'balance' operator syntax, per_page range). The description only echoes name/email/number search, adding nothing beyond the structured data; baseline 3 is correct.

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 names the fields returned plus the three searchable dimensions. It clearly separates itself from create/update/get_client in intent, though it doesn't explicitly state the difference from get_client.

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

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

The phrase 'optionally searched by name, email or number' implies when the filters apply, but there is no explicit guidance on when to use this over invoiceninja_get_client for a single lookup, nor any mention of pagination limits or rate limits.

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 is not obligated to restate safety. It adds the REST mapping (GET /api/v1/expenses) and the filterable facets, which is modest added context, but says nothing about pagination defaults or result volume behavior. Adequate but not rich.

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

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

Two short sentences, front-loaded with the core action and its filters. The trailing endpoint mapping is marginally redundant, but nothing is padded or buried.

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 read tool with full schema coverage and no output schema, the description covers the essential purpose and filtering scope. Pagination, sorting, and per-page limits are handled by the schema, so the remaining gap is minor.

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 (page, per_page, sort, filter, number, status, client_id, client_status) are already documented in the schema. The description only loosely gestures at client and state filtering without adding syntax or format 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 expenses') and names the filtering dimensions, which separates it from sibling list tools like invoiceninja_list_invoices or invoiceninja_list_payments by resource. It does not, however, explicitly differentiate itself from invoiceninja_create_expense or explain why one would choose this list over another expense-related tool.

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 hints at usage via 'filterable by client and invoicing/payment state,' implying you use it when you need expenses narrowed by those facets. There is no explicit when-to-use/when-not guidance and no named alternative, so usage must be inferred.

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 need not restate the safety profile. It does add genuine value with the status_id legend (1-6) for interpreting returned records and the underlying endpoint (GET /api/v1/invoices), but says nothing about pagination behavior or result caps. Note the legend describes a returned 'status_id' field distinct from the schema's 'status' (active/archived/deleted) and 'client_status' parameters, which could momentarily confuse an 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?

Three sentences, front-loaded with the purpose, then the status_id legend, then the endpoint. There is little waste, though the endpoint reference adds marginal value for an agent that never sees the transport layer.

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 list tool with no required parameters, no output schema, and readOnly annotations, the description plus 100%-covered schema gives the agent everything needed to call it correctly. Pagination mechanics live in the schema, so their absence from the prose is not a real gap.

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

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

Schema coverage is 100%, so every parameter is already richly documented in the schema; the baseline of 3 applies. The description adds only the payment-status vocabulary (paid/unpaid/overdue), which overlaps with client_status, and provides no format or syntax detail beyond what the schema already gives.

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 (list) and resource (invoices) and names the two filtering axes (client, payment status), so an agent understands what it returns. It does not explicitly differentiate itself from invoiceninja_get_invoice or the other list_* siblings, but the list verb makes the intent 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?

It implies the usage context by naming its filter dimensions (client and payment status), which is enough to infer common retrieval scenarios. However, it never states when to prefer this over get_invoice for a single record, and offers no exclusions or alternative-tool guidance beyond the implied filtering scope.

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' sentence largely restates structured data. The description does add genuine value by disclosing what the payload contains (applied/refunded totals, paymentables), but says nothing about pagination behavior, ordering, or result size even though page/per_page/sort exist as 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 tight sentences, no filler, and the most useful information — what the tool returns — is front-loaded before the read-only disclaimer and the endpoint reference.

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

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

With no output schema, the description usefully compensates by naming the returned fields, and the read-only stance is unambiguous. What remains missing is pagination/ordering behavior, which the agent must infer from the schema's page/per_page/sort definitions.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters with formats and ranges. The description adds no additional parameter meaning (e.g., how 'filter' interacts with 'number' or how 'sort' columns map to the listed fields), so the baseline 3 applies.

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

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

States a specific verb ('List') and resource ('payments received') and immediately enumerates the returned fields (amount, date, refunded/applied totals, paymentables). The purpose is unmistakable, though no sibling list_* tool can be confused with it, so the 'distinguishes from alternatives' clause is only trivially satisfied.

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: the agent infers this is the way to enumerate payments. The sentence 'this server never records or refunds payments' implicitly tells the agent there is no write counterpart to redirect to, but there is no explicit guidance on when this tool is appropriate versus a filtered or single-record lookup.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered by structured data. The description adds the underlying endpoint (GET /api/v1/products) and the fields surfaced, but says nothing about pagination defaults, result limits, or that archived/deleted records are excluded by default — the kind of context that would genuinely help here.

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 functional statement front-loaded; nothing is padded. The trailing 'Invoice Ninja: GET /api/v1/products.' is low-value boilerplate for an agent, which keeps this from a 5.

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

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

There is no output schema, and the description partially compensates by naming the returned fields (price, cost, default taxes). Combined with 100% schema coverage on all six optional parameters and readOnlyHint, an agent has enough to call it correctly; only pagination/total-count behavior is left unclear.

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, per_page, sort, filter, status, and product_key are already fully documented in the schema. The description adds no syntax, format, or default-value information beyond it, so the baseline 3 is appropriate.

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

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

The description states a specific verb (List) and resource (products / services in the catalog) and even names the notable fields returned (price, cost, default taxes). Against siblings like list_clients, list_invoices, or list_vendors, the resource noun alone lets an agent route correctly without opening any 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 only implied by the fact that this is a catalog listing endpoint; there is no statement of when to prefer it (e.g. for populating a product picker) or when not to use it. No alternatives or prerequisites are named. Adequate for a straightforward list tool, but no explicit guidance is provided.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds the upstream endpoint mapping (GET /api/v1/projects) and the field shape of the response, which are genuinely useful. However, it says nothing about pagination behavior or result limits beyond what the schema parameters imply.

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 returned field list and trailing with the API endpoint, with no filler. Minor redundancy is that the opening phrase restates the title 'List projects' verbatim, but the sentence remains dense and well ordered.

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 partially compensates by naming the returned fields, and the schema fully documents all filter/pagination parameters. The read-only nature is covered by annotations, so an agent has nearly everything needed; only pagination defaults and cross-tool routing are 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 seven parameters (page, sort, filter, number, status, per_page, client_id) are already fully documented including formats and examples. The description adds no parameter meaning of its own, 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?

The description states a specific verb and resource ('List projects') and enumerates the payload fields returned (client, budgeted hours, task rate, current hours, due date), so an agent knows exactly what this tool produces. It is clearly distinguishable from siblings like invoiceninja_list_tasks or invoiceninja_list_clients by resource name, but it never explicitly contrasts itself with those alternatives.

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

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

There is no when-to-use or when-not-to-use guidance, no mention of prerequisites such as needing a client_id, and no routing to siblings for related lookups (e.g. list_tasks for a project's tasks). Usage is only implied by the tool name and the verb 'List'.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered structurally. The description adds the underlying endpoint (GET /api/v1/quotes), which is mildly useful context, but says nothing about pagination behavior, default page size, or what a result set contains. Adequate given the lower bar set by annotations.

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

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

Two short sentences with the purpose front-loaded and the endpoint detail trailing; nothing is wasted or buried.

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 fully documented inputs and no output schema, the definition covers purpose, filterability, and the API mapping. It does not describe the returned record shape or pagination envelope, a minor gap since no output schema exists to fill it.

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

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

Schema description coverage is 100%, so every parameter already carries its own semantics (sort syntax, per_page range, status values, hashed client id). The description only restates that client and status filtering exist, adding no syntax or format detail beyond the schema. Baseline 3 is correct.

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 quotes') and disambiguates terminology with '(estimates)', which matters in Invoice Ninja where estimates and quotes are the same entity. It does not explicitly contrast itself with siblings like invoiceninja_get_quote or invoiceninja_list_invoices, 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?

The description notes it is 'filterable by client and quote status', which hints at how to narrow results, but gives no when-to-use guidance, no statement of when to prefer invoiceninja_get_quote (single record) over this list, and no prerequisites. Similar to the MID calibration example, this leaves routing to inference.

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

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

Annotations already declare readOnlyHint=true, and the description merely restates 'Read-only', which adds no new information. It does add modest context by naming the underlying endpoint and the shape of returned fields, but says nothing about pagination behavior despite page/per_page parameters, nor about rate limits or empty results. With annotations covering the safety profile, a 3 is fitting.

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

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

Three short clauses with no padding, front-loading the resource and the returned fields. The endpoint citation is mildly redundant but harmless and compact; nothing is buried.

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 fully optional-parameter, read-only list tool with 100% schema coverage and no output schema, the description plus annotations supply what an agent needs to call it. The only soft spot is the absence of any pagination or filtering narrative, which is minor given the schema's explicit per_page and sort documentation.

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, sort, number, status, client_id, client_status, per_page) are already documented in the schema. The description adds no syntax, format, or filtering semantics 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 (List) and resource (recurring invoice schedules) and enumerates the key fields returned (frequency, next send date, remaining cycles). This implicitly distinguishes it from invoiceninja_list_invoices, though it never names that sibling explicitly to sharpen the contrast.

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 offers no when-to-use guidance, no exclusions, and no pointer to alternatives such as list_invoices or get_invoice. Usage is only inferable from the verb 'List' and the read-only label; nothing tells the agent when recurring schedules are the right target.

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 at no cost to the description. The description's only added behavioral signal is that related entities (client, project, invoice) are included in results, which is mild context. It does not cover pagination behavior or result size, which with 8 filter params would have been useful.

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 with no padding; the resource and returned fields come first and the underlying endpoint is appended as a trailing reference. Nothing is wasted, though the second sentence is a raw API path that adds little for 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?

There is no output schema, so the description carries the burden of signaling return content, and it does so by enumerating the key fields and linked entities. Combined with a fully documented schema, an agent has enough to call and interpret the tool; only pagination/result-volume behavior is left unstated.

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

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

Schema description coverage is 100% with all 8 optional parameters documented in-schema (page, sort, filter, number, status, per_page, client_id, client_status). The description adds no parameter-level detail — not even which filters are the common ones — so the baseline 3 applies.

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

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

States a specific verb ('List') and resource ('tasks / time entries') and goes further by naming the relationships returned (time_log, duration, rate, client, project, invoice). An agent can tell it apart from the other list_* siblings by resource. It stops short of explicitly contrasting itself with sibling list tools, so it lands just below the top tier.

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 returned-field list; there is no statement of when to prefer this over list_projects or list_expenses, no mention of pagination expectations, and no prerequisites or exclusions. Adequate for an obviously-scoped list endpoint, but nothing routes 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 safety profile is covered structurally, and the description correctly stays consistent with that. It adds the returned fields (contacts, address) and the backing route, but says nothing about pagination defaults, result caps, or ordering behavior beyond what the schema 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 short sentences with the purpose front-loaded and zero filler. The trailing 'Invoice Ninja: GET /api/v1/vendors' is a route mapping that adds little to tool selection, a minor but real dilution.

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 saying what comes back, and it does so at a high level ('with contacts and address'). Pagination and per-page defaults live in the schema, so the remaining gap is mainly how results are ordered or shaped at the envelope 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% and all six parameters (page, per_page, sort, filter, number, status) carry their own descriptions, so the baseline of 3 applies. The description adds no syntax, default, or interaction detail beyond the schema, so it does not lift the score.

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 vendors) and immediately disambiguates the term with the synonym '(suppliers)', which matters because siblings are dominated by client/invoice/expense list tools. It also declares the payload shape ('with contacts and address'), so an agent knows what it gets 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?

Usage is implied rather than stated: there is no explicit when-to-use, when-not, or alternative named, but there is no sibling 'get_vendor' that competes with it, so the selection decision is unambiguous by default. It never tells the agent how this relates to filtering (e.g. use 'number' for a single vendor vs 'filter' for broad search), leaving that to 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?

Annotations only supply destructiveHint=true, so the description carries the real disclosure burden and does well: it reveals the status transition (out of draft) and the financial side effect (amount added to client balance), plus the underlying API route. It omits reversibility and whether the balance effect can be undone, which matters for a destructive mutation.

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

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

Two tight sentences: the core action and its key caveat are front-loaded, followed by the side effects, with the API route last. 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 one-parameter mutation with no output schema and only a destructiveHint annotation, the description supplies the essential state change and balance impact an agent needs. It could go further on reversibility or the expected response, but nothing critical is missing.

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

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

Schema coverage is 100% and the single invoice_id is fully documented with format guidance (hashed id example), so the schema does the heavy lifting. The description adds no parameter-level meaning beyond that, making the baseline 3 correct.

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') and immediately narrows scope with 'WITHOUT emailing it', which cleanly separates it from the sibling invoiceninja_email_invoice. An agent can pick between the two 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?

The 'WITHOUT emailing it' clause gives clear context for when this tool applies versus the email path, and 'moves it out of draft' implies the required precondition state. It never names the alternative tool explicitly or states what happens if the invoice is already sent, so it stops short of full when/when-not guidance.

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

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

With only destructiveHint=true available in annotations, the description does real work: it discloses partial-update semantics ('only the fields you pass change') and that passing contacts triggers a destructive full replacement of the contact list. It stops short of covering permissions or what happens to contacts previously attached, but the collision behavior is surfaced.

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, with the partial-update rule front-loaded and the contacts caveat second. Zero filler; every clause carries information an agent needs.

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 description covers the essential update semantics and the single destructive path, which is the minimum viable set. It leaves gaps around the many undescribed scalar fields and any error/permission behavior.

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

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

Schema description coverage is only 33%, so ~10 of 15 parameters (city, phone, state, website, address1/2, postal_code, vat_number, public_notes, private_notes) are undocumented anywhere. The description compensates only for the omittable-fields rule and contacts replacement, leaving the rest of the parameter surface to the bare 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 ('Update a client's details') and immediately disambiguates the operation from create/get sibling tools by declaring it a partial update. It never names a sibling explicitly, so it stops short of full sibling differentiation.

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 implies a standard edit scenario but gives no when-to-use guidance, no prerequisites, and no routing to alternatives such as invoiceninja_create_client when the client does not yet exist. Nothing tells the agent when this tool is the wrong choice.

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 earns credit for explaining WHY it is destructive: 'only the fields you pass change, but line_items (if passed) replace every existing line' plus 'Does not send anything.' That patch-vs-replace distinction and the no-side-effect-on-send note are exactly the behavioral context an agent can't get from the annotation flag alone.

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

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

A single compact sentence delivers the patch semantics, the destructive line_items caveat, the no-send guarantee, and the endpoint mapping. Every clause earns its place and the most important caveat is front-loaded.

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

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

For a 17-parameter mutation with no output schema, the description covers the two things an agent most needs: partial-update behavior and the destructive line_items replacement. It omits any mention of required permissions or how a successfully updated invoice is surfaced, which is a minor gap given no output schema exists.

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 baseline is 3, but the description adds non-obvious semantics the schema only repeats: that line_items is a wholesale replacement of all existing lines rather than a merge. That materially changes how an agent should populate the 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 verb and resource ('Edit an invoice') and pins the underlying operation to PUT /api/v1/invoices/{id}, which cleanly separates it from create_invoice or email_invoice. It stops short of naming any sibling explicitly, so the differentiation is implied by the verb rather than stated.

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

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

The phrase 'Does not send anything' hints that sending is handled elsewhere (email_invoice / mark_invoice_sent), but the alternative is never named and no when-to-use condition is spelled out. 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.