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

Annotations already declare readOnlyHint=true, destructiveHint=false and idempotentHint=true, so the safety profile is covered and the bar is lower. The description still adds real behavioral value beyond the schema by stating that omitted dates fall back to the instance's default period, which the null defaults in the schema do not convey. It stops short of describing aggregation scope or counting rules.

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

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

Two sentences, zero padding, with the returned-metric list front-loaded and the default-period caveat following it. 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?

With no output schema, the description carries return-value duty and does so by naming the metrics and the per-currency grouping. Annotations cover safety, and all params are schema-documented, so the agent has nearly everything; only the derivation/boundary semantics of the period are left implicit.

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 three parameters (start_date, end_date, response_format) are documented in the schema itself, so the baseline is 3. The description reinforces the period semantics but adds no format, timezone, or inclusive/exclusive-boundary detail beyond what the schema already provides.

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 precise verb and resource ('totals per currency for a period') and enumerates the exact metrics returned (invoiced, paid, outstanding with count, expenses). It is clearly distinct from the many list_*/get_* siblings, though it never names an alternative it should not be confused with (e.g. get_statics or run_report).

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

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

Usage is only implied: the metric set and 'period' framing suggest this is the dashboard summary tool, but there is no explicit when-to-use/when-not or pointer to the reporting siblings (run_report, get_statics) that could overlap. Minimum-viable guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered without the description. 'With all details' is a weak signal that conflicts slightly with the schema's response_format default of markdown and its fields/include projection options, which the description never mentions.

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 short sentence, front-loaded with verb and resource, no filler. Every word 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 simple single-record getter with no output schema, the description plus fully documented parameters are close to sufficient. The one gap is the notable default of markdown output versus json, which lives only in the schema and could matter for an agent expecting structured data.

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%: id format, fields projection, include relations and response_format semantics are all documented in the schema with examples. The description's 'hashed id' merely restates the schema and adds nothing about fields, include, or the markdown-vs-json default.

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

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

States a specific verb and resource ('Get one client') plus the lookup key ('by its hashed id'), which cleanly separates it from invoiceninja_list_clients and from get_* siblings for other resources. It stops short of explicitly naming the list alternative, but the singular-vs-plural distinction is self-evident.

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 'one client' versus the sibling list_clients, and the required hashed id signals you must already know the record. There is no explicit statement of when to prefer this over a search or list call, and no prerequisite note that the id must be obtained 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 already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered by structured data. The description's only added behavioral note is that all details including line items are returned, which is modest but useful 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?

A single front-loaded sentence with no filler, and the scoping qualifier 'with all details (line items included)' is placed where it matters. It is efficient, though it could carry one more clause of routing guidance at no 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?

There is no output schema, but the description signals the return shape ('all details, line items included'), and the schema plus annotations fully cover the input and safety profile. For a simple single-record getter, this is close to sufficient; only the routing-to-list-tools gap remains.

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 each of the four parameters documented in the schema itself (including the hashed id example and the fields/include/response_format semantics). The description adds nothing 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 (Get) and resource (one credit), and scopes it to a single record by hashed id, which implicitly distinguishes it from invoiceninja_list_credits. It stops short of explicitly naming the sibling it contrasts with, so it lands just under the top mark.

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 prerequisites, and does not point to alternatives such as invoiceninja_list_credits for browsing multiple credits. Usage is only inferable from the verb and the singular object.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds 'with all details,' signaling full-detail return, but its claim of all details is slightly undercut by the fields/response_format trimming params. No mention of auth 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?

A single front-loaded sentence with no filler, stating the action, the record, the identifier type, and the detail level. Efficient, though very sparse.

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 tool whose annotations cover safety and whose schema is 100% documented, the description does the minimum. It does not reconcile 'all details' with the fields/response_format options that can reduce output, leaving minor ambiguity.

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 id, fields, include, and response_format parameters are already fully documented in the schema. The description restates 'hashed id' without adding syntax or format meaning beyond the schema. Baseline 3 applies.

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

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

Clear verb+resource+scope: 'Get one expense by its hashed id' distinguishes this single-record fetch from the sibling invoiceninja_list_expenses. It does not name a sibling explicitly, but the singular/plural contrast makes the distinction inferable.

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 the alternate list_expenses path to discover ids, and no prerequisites. The 'hashed id' input implies you must already have the id, but the agent is left to infer this.

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, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds that all details including line items are returned, which is useful, though it sits in mild tension with the schema's markdown-default summary 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?

A single short sentence with zero filler, front-loading the verb, resource and access key. Nothing is wasted and nothing important 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?

There is no output schema, but the description tells the agent what comes back (full invoice detail with line items), which is the key missing piece. The one gap is that it doesn't reconcile 'all details' with the markdown-default response_format that trims data.

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 id, fields, include and response_format are fully documented in the schema itself. The description's only semantic contribution ('hashed id') merely restates what the schema already says, 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 ('Get one invoice') and pins the identifier type ('by its hashed id'), which cleanly separates it from the plural list_invoices sibling. It doesn't explicitly name that sibling, so it falls just short of a 5.

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

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

Usage is only implied: an agent can infer this is the detail-fetch counterpart to invoiceninja_list_invoices, but the description never says when to use it versus a list or search. No prerequisites or exclusions are given.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds only 'with all details,' which is vague and does not disclose auth requirements, rate limits, or how fields/include/response_format affect the returned 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?

A single front-loaded sentence with no wasted words. It is appropriately terse for a simple get-by-id tool, though 'with all details' is slightly vague filler that does not add precision.

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 full schema coverage and annotations covering safety, the description need not explain parameters or read-only behavior. However, for an agent choosing among many get/list siblings, it lacks usage routing and does not clarify return-format implications, leaving it minimally 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%, and all four parameters are well documented with examples and defaults. The description adds no parameter detail beyond restating that the id is hashed, 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 ('Get one payment') and scope ('by its hashed id'), which distinguishes it from list_payments by singularity. However, it does not explicitly differentiate itself from sibling get_* tools or mention list_payments as the multi-record alternative.

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 prerequisites, and no mention of alternatives such as list_payments for retrieving multiple payments. The implied usage is retrievable only from the tool name and description's id requirement.

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, idempotentHint=true and destructiveHint=false, so the safety profile is fully covered. The description adds only 'with all details', which vaguely signals a full-detail return but says nothing about response_format behavior or the interaction with fields/include.

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

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

A single front-loaded sentence with no waste; the scope constraint ('one product') leads. It is arguably too terse to be maximally useful, keeping it below 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?

For a read-only getter with full annotations the safety story is complete, but with no output schema the description should hint at what 'all details' returns or how markdown vs json output differs. As written it is adequate but leaves that 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 id, fields, include and response_format are already documented. The description's 'by its hashed id' merely restates the id parameter and adds no syntax or format detail beyond the schema.

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

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

States a clear verb+resource ('Get one product') and narrows scope to a single record by hashed id, distinguishing it from invoiceninja_list_products. It does not explicitly name the sibling it pairs with, so it falls short of a 5.

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

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

The description implies usage (fetch a product when you have its id) but never states when to prefer this over list_products or search, nor any prerequisites. No alternatives or exclusions are named.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, covering the safety profile. The description adds nothing beyond a restatement of the name — no mention of permission requirements, error behavior for an unknown id, or pagination/relation loading, and 'all details' arguably conflicts with the fields/include filters.

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

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

A single front-loaded sentence with the verb, resource and identifier first and no filler. It is efficient, though the trailing 'with all details' is imprecise rather than informative.

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 getter with 100% schema coverage and a full annotation set, most of what an agent needs is present elsewhere. However, with no output schema the description could have said what a project object contains or how fields/include shape the response, and 'all details' is misleading against those 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 four parameters (id, fields, include, response_format) are already documented in the schema. The description only echoes the 'hashed id' aspect, adding no new syntax or format meaning. 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 ('Get one project by its hashed id') and scopes it to a single record, which distinguishes it from the sibling list_projects without naming it. 'With all details' is slightly loose given the fields/include parameters, but the core 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?

No when-to-use guidance, no mention of list_projects for browsing, and no note about when to prefer get_record or search. The agent must infer the retrieval-vs-list distinction from the description alone.

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

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

Annotations already declare the full safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower. The description adds useful context that full details including line items are returned, but says nothing about response format, permissions, or failure modes.

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

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

A single tight sentence that front-loads the verb and resource. Every clause earns its place 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 simple read-only fetcher with a fully documented 4-param schema and no output schema, the description covers the essential scope and notes line items are included. It could note formatting/pagination expectations but is adequate.

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 explains id, fields, include, and response_format. The description only echoes 'hashed id', adding no syntax or format detail beyond the schema, which matches 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 (Get), resource (purchase order), scope (one), and the required key (hashed id). The phrase 'one purchase order' implicitly distinguishes it from the sibling invoiceninja_list_purchase_orders.

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

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

Usage is implied – fetch a single PO when you have its hashed id – but the description names no alternative and gives no condition for choosing get vs list. No exclusions or prerequisites are stated.

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, idempotentHint, openWorldHint, and destructiveHint, so safety behavior is covered. The description adds useful return-scope context ('all details, line items included') but does not disclose error behavior, required permissions, or pagination.

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

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

A single, front-loaded sentence with zero filler. It immediately states the action, the identifying argument, and the return scope.

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-by-id tool with fully described parameters and strong safety annotations, the description is adequate and states what is returned. Minor gaps remain: no mention of response format handling or how to find the id, but those are covered by the schema.

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

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

Schema description coverage is 100%: all four parameters, including id, fields, include, and response_format, are fully documented in the schema. The description adds no parameter meaning beyond repeating that id is hashed, so the baseline of 3 for high coverage 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 'Get' and resource 'one quote', and explicitly scopes it as a single-record retrieval with 'all details (line items included)'. This distinguishes it from the list_quotes sibling by implying one vs. many, though it never names that sibling.

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?

Provides no when-to-use guidance and does not mention list_quotes or invoiceninja_search as alternatives for locating a quote. The only implicit prerequisite is that the caller already has a hashed id, which is not framed as usage guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered by structured data. The description's only added behavioral context is the 'reference/secondary' scope; it says nothing about auth requirements, not-found behavior, or record visibility. Adequate but not enriching beyond 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 sentences, front-loaded with the action and scope; the entity enumeration is long but genuinely informative for scoping. No filler or repetition of the name/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?

With no output schema, the description still gives the agent enough to pick the right entity and format, and annotations cover safety. Return-shape detail (markdown vs json semantics) is delegated to the schema, which is acceptable.

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 id, entity, fields and response_format are each documented in the schema, including the id pattern and format enum. The description's entity list merely mirrors the enum and adds no syntax or format detail beyond it, 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 (Get) and resource (one reference/secondary record by id) and enumerates exactly which entity types are covered, which lets an agent separate it from primary-entity getters like get_client or get_invoice. The 'reference/secondary' framing is the key differentiator, though it is not stated as an explicit contrast to the sibling getters.

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

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

Usage is implied: fetch a single non-primary record when you already have its id. There is no explicit when-to-use versus invoiceninja_list_records or the typed get_* siblings, and no prerequisites are named. Functional 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, idempotentHint, non-destructive and openWorldHint, so the safety profile is fully covered. The description adds only 'with all details', which is arguably undercut by the fields/include/response_format parameters that narrow the payload, and it says nothing about the markdown-by-default response shape. Modest added value over the annotations.

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

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

A single front-loaded sentence that identifies the resource, the lookup key, and the payload depth with zero filler. Nothing could be removed without losing information.

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

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

For a single-record getter with no output schema but rich annotations and fully documented parameters, the definition is nearly sufficient. The one gap is that 'with all details' is slightly misleading given the default markdown summary and the fields/include narrowing options, which the agent must learn from the 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?

Schema description coverage is 100%, with id, fields, include and response_format all documented in-schema (including an example hashed id and an enum explanation). The description adds no semantic detail beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get one recurring expense') and scopes it to a single record via 'by its hashed id', which cleanly contrasts with the list-style siblings. It never names the sibling explicitly (e.g. invoiceninja_list_recurring_expenses), so differentiation is implied 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 description implies the natural usage (fetch a single recurring expense when you have its id), but gives no explicit when-to-use guidance, no prerequisites, and no statement about when to prefer the list tool or a search instead. Implied usage only.

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, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds that the full record including line items is returned, which is useful context, but it omits that response_format defaults to markdown (a summary, not the full detail) and says nothing about errors for bad ids.

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

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

A single front-loaded sentence with zero filler that puts the verb, resource, and identifier form first.

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 single-record fetch with no output schema, the description conveys the key payload expectation (all details, line items included) and annotations cover safety. It is slightly incomplete in not clarifying the default markdown summary versus json full-data mode.

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 (id, fields, include, response_format) is already documented with examples and defaults. The description only reinforces the hashed-id requirement and line-item inclusion, adding no new 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 (Get), resource (one recurring invoice), and identifier form (hashed id), which cleanly separates it from invoiceninja_list_recurring_invoices and invoiceninja_get_invoice. It does not name those siblings explicitly, so a small differentiation gap remains.

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: fetch a single recurring invoice when you already hold its hashed id. There is no explicit when-to-use statement and no guidance on preferring list_recurring_invoices for retrieval by other criteria.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds only the workflow dependency on invoiceninja_run_report, but says nothing about asynchronous behavior, timeouts, rate limits, pagination, or what happens when the report is not ready.

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

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

A single sentence with no wasted words, and the key dependency on the sibling tool is front-loaded. It is appropriately sized for a tool whose schema already carries the parameter 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?

The schema is rich and annotations cover safety, but the description does not mention the tool's asynchronous nature (e.g., returning an id if the report is not ready) or how rows are limited. It is minimally adequate, relying heavily on structured fields to fill the behavioral 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 all four parameters are already documented in the input schema. The description adds no additional 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 ('Fetch') and resource ('rows of a report') and explicitly ties it to the sibling tool that starts the report. An agent can distinguish this from invoiceninja_run_report 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 description implies usage context by saying the report was 'started by invoiceninja_run_report,' so an agent understands this is a follow-up call. However, it gives no explicit when-to-use, when-not, or alternatives beyond that implication.

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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered. The description adds no behavioral detail beyond that — nothing on pagination via limit, search matching behavior, or result shape. With annotations carrying the burden, a 3 is appropriate.

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

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

One sentence, front-loaded with the verb and resource and ending with the actionable use case. 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, so the description would ideally sketch the return shape (id/name pairs per section). It compensates partly by naming the sections and the id-to-name translation goal, but leaves an agent guessing about the returned structure and ordering.

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 section enum and limit/search documented inline, so the baseline is 3. The description restates the section families and frames their purpose (id translation) but adds no syntax or format detail beyond what the schema already provides.

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 (look up) plus resource (static reference data) and enumerates the section families returned. It further clarifies the practical purpose — translating ids like currency_id/country_id/type_id into names — which cleanly separates it from the entity list/get siblings.

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

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

Clearly conveys the context of use: consult it when you need to resolve an id into a human-readable name. No explicit exclusions or named alternatives are given, but for a reference-data lookup the trigger condition 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 already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered elsewhere. The description adds only that the full detail set is returned, with no mention of whether related records must be requested via 'include' or what happens on a missing id.

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

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

A single front-loaded sentence with no filler; it identifies the resource and key immediately. It is efficient, though it is arguably under-specified rather than optimally concise.

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 carry more of the return-shape burden, and 'with all details' is vague given that fields/include/response_format let callers trim or expand the payload. For a simple read-by-id tool whose annotations cover the safety profile, this is adequate but not complete.

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

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

Schema description coverage is 100%, so id, fields, include and response_format are all documented in the schema itself, including examples for the hashed id. The description repeats the id semantics without adding anything beyond the schema, 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 (get) and resource (task) and names the identifying key (hashed id), which separates it from the sibling invoiceninja_list_tasks. 'With all details' is slightly redundant but does signal a full-object fetch rather than a summary.

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 and no alternatives named. It does not say to reach for this only when a single task id is already known, nor does it point to invoiceninja_list_tasks for discovery, leaving the agent to infer the routing from the name alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so safety is covered. The description adds 'with all details,' which loosely signals return breadth but doesn't mention that the 'fields' and 'include' params can narrow/expand that, nor any rate or auth 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?

A single short sentence, front-loaded with the verb and key. It is efficient, though 'with all details' is slightly at odds with the existence of a 'fields' filter and could be tightened.

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 bears some burden for describing returns, and 'all details' is the only hint. For a simple single-record getter whose annotations cover the safety profile and whose schema is fully documented, this is adequate but minimal.

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 four parameters (id, fields, include, response_format) are already documented in the schema. The description adds no syntax, format, or default information beyond it, 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 ('Get one vendor') plus the lookup key ('by its hashed id'), which cleanly distinguishes it from invoiceninja_list_vendors. It stops short of explicitly naming the sibling alternative, but the singular-vs-list distinction is unambiguous.

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

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

Usage is only implied by the name/description: fetch a single vendor when you already have its hashed id. There is no statement of when to prefer this over list_vendors or get_record, nor any prerequisite guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered by structured data. The description's filter-operator details are useful context but are largely parameter semantics; it says nothing about rate limits, permissions, or what a paginated result set looks like. With annotations carrying the behavioral burden, a 3 is appropriate.

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?

Purpose and the get_client hand-off are front-loaded, and the dense extra_filters block is necessary content rather than filler. The operator enumeration is compact given how many keys it must cover, with only minor redundancy between the header ('filtering, sorting, pagination') and the schema-documented params.

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 9-parameter, zero-required list tool with no output schema, the description covers the one param the schema punts on and implies pagination behavior plus the follow-up call. It never mentions response_format's markdown/json distinction or response shape, but annotations and schema cover enough that nothing critical for invoking the tool 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 the baseline is 3, but the extra_filters parameter's schema explicitly defers to the description ('see the tool description'), and the description delivers the key list plus operator syntax ('gt:0', 'between_balance', 'YYYY-MM-DD,YYYY-MM-DD'). That materially exceeds what the schema alone provides, though other params (sort, fields, status, include, response_format) get 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?

The first sentence gives a specific verb and resource ('List clients from Invoice Ninja') plus the three capabilities (filtering, sorting, pagination), so an agent can distinguish it from invoiceninja_get_client, invoiceninja_list_invoices and invoiceninja_search 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?

It explicitly routes the agent: use invoiceninja_get_client with an id from this list for the full record, which is a clear list-then-fetch workflow. It does not, however, say when to prefer this over invoiceninja_search or how deep pagination should be handled, so it stops short of full when-not guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety is covered structurally. The description adds behavior annotations don't: related names are auto-resolved (client_name), and the semantics/format of extra_filters keys and date ranges. It doesn't cover pagination limits or result ordering, but with annotations carrying the safety profile this is solid added value.

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

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

Front-loads the core purpose, then adds the necessary reference detail (client_status values, extra_filters keys, related-name resolution, hand-off to get_credit). The extra_filters enumeration is dense but each entry carries real syntax an agent needs; little 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?

No output schema exists, and the description compensates by explaining auto-resolved related names and pointing to get_credit for the full record. For an 11-parameter read tool with zero required params, this is close to complete, though the shape of the list response (pagination metadata, field selection interaction with response_format) is left implicit.

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 meaningfully exceeds it: the schema defers extra_filters documentation to the description ('see the tool description') and the description enumerates every key with date syntax and semantics, plus the valid client_status values. That said, some params (include, filter, sort) are only covered by the schema itself.

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 ('List credits from Invoice Ninja') with the scope of capabilities (filtering, sorting, pagination). It also distinguishes itself from the sibling invoiceninja_get_credit by naming that tool and the condition under which to use it.

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 routes the agent: 'Use invoiceninja_get_credit with an id from this list for the full record,' which tells the agent when to graduate from list to get. It stops short of stating when not to use this list (e.g. when a single known id is already available), so it isn't fully exhaustive.

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, idempotentHint, destructiveHint=false and openWorldHint, so the safe-read profile is fully covered without the description. The description does add one genuine behavioral detail — that related names like client_name and vendor_name are auto-resolved — but it says nothing about pagination behavior or result volume.

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?

Purpose is front-loaded, then the enum values, then the filter-key reference, then the routing note — a logical order. The extra_filters line is dense but every token is load-bearing. No filler sentences.

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 11-parameter list tool with no output schema and annotations covering the safety profile, the description supplies the filter vocabulary, the auto-resolution behavior, and the hand-off path to the detail tool. Nothing critical is missing, though return-shape expectations (markdown vs json) are left to the schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns more by enumerating extra_filters keys (number, amount, categories, vendor_ids, project_ids, payment_type, has_invoices, date_range, tag_ids, assigned_user_ids) that the schema only alludes to with 'see the tool description.' It also supplies the date-range format 'YYYY-MM-DD,YYYY-MM-DD' and notes comma-separated 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?

The description opens with a specific verb+resource+scope: 'List expenses from Invoice Ninja with filtering, sorting and pagination.' The resource name distinguishes it from the many sibling list_* tools, and it names invoiceninja_get_expense as the follow-up for full records. It stops short of explicitly contrasting with the closest sibling, invoiceninja_list_recurring_expenses.

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

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

It explicitly routes the agent: 'Use invoiceninja_get_expense with an id from this list for the full record,' which clearly separates the list and detail tools. However, it offers no when-not-to-use guidance or prerequisites for calling the list endpoint.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower, and the description still adds real context: it documents the otherwise opaque extra_filters key vocabulary and formats, and notes that related names (client_name) are auto-resolved. It does not, however, describe result ordering, page limits, or pagination behavior beyond what the schema states.

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

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

Front-loaded with the one-line purpose before the dense reference material, and every sentence is functional rather than filler. The extra_filters catalogue is long, but it is necessary detail the schema delegates here, so it earns its space.

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

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

With no output schema, the description must carry the contract, and it does reasonably: it flags the markdown/json response_format choice implicitly via filtering capabilities and explains the get_invoice follow-up for full records. An agent has enough to call this correctly, though return-shape details (what the markdown summary contains) remain implicit.

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 baseline is 3, but the description meaningfully exceeds it: the extra_filters parameter's schema entry merely says 'see the tool description,' and the description supplies the full key list, date-range syntax, and column semantics for it. It also restates the client_status enum values, which adds redundant but confirming detail.

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 invoices from Invoice Ninja') plus the supported capabilities (filtering, sorting, pagination). It reads clearly as the list-side counterpart to invoiceninja_get_invoice, so an agent can place it among the many list/get siblings 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?

Explicitly routes the agent to the alternative: 'Use invoiceninja_get_invoice with an id from this list for the full record.' That is a clear when-to-use-next rule, though it doesn't distinguish this tool from other list/search siblings like invoiceninja_search or invoiceninja_list_records.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds genuine behavioral context beyond that: related names are auto-resolved (client_name) and it clarifies that records here are partial vs. the full record via get_payment.

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

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

Front-loaded purpose sentence followed by dense but organized detail lines (client_status values, extra_filters keys, auto-resolution, get_payment routing). Every line carries useful information with no filler.

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

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

For a read-only list tool with full schema coverage and no output schema, the description covers routing, filter vocabularies, and relation auto-resolution. Nothing an agent needs 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 coverage is 100%, establishing a baseline of 3, but the description adds value the schema defers to it: extra_filters keys (number, date_range, created_between/updated_between, tag_ids, assigned_user_ids) are documented here because the schema itself says 'see the tool description,' and the client_status values are re-explained.

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

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

Opens with a specific verb+resource ('List payments from Invoice Ninja') and enumerates the capabilities (filtering, sorting, pagination). It explicitly names the sibling get_payment to distinguish a list operation from a single-record fetch.

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 routes the agent: 'Use invoiceninja_get_payment with an id from this list for the full record,' which clarifies the list-then-get workflow. It does not state any exclusions or when not to use this tool, but the alternative is named with its triggering condition.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered by structured data. The description's only behavioral addition is the extra_filters key semantics and the follow-up get_product hint, which is useful but modest for a read-only list tool.

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

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

Three sentences, all load-bearing: purpose first, then the extra_filters syntax, then the follow-up tool. No filler, and the most important routing information is front-loaded.

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

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

For a 9-parameter, zero-required list tool with full schema coverage and annotations, the description supplies the missing extra_filters vocabulary and the natural next step (get_product). No output schema exists, but response_format is self-documented in the schema, so nothing essential 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 the baseline is 3, but the description genuinely earns extra credit by spelling out the extra_filters keys (product_key, created_between / updated_between with 'YYYY-MM-DD,YYYY-MM-DD' format, tag_ids, assigned_user_ids) that the schema only gestures at with 'see the tool description'.

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

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

Opens with a specific verb+resource ('List products from Invoice Ninja') and enumerates the supported operations (filtering, sorting, pagination). The resource name distinguishes it from the many sibling list_* tools, though it does not explicitly contrast itself with list_records or search.

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 routes the agent forward: 'Use invoiceninja_get_product with an id from this list for the full record,' which is a clear when-to-use-this-vs-that instruction. It also documents the extra_filters vocabulary, though it gives no guidance on when to prefer this over the generic search or list_records tools.

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

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

Annotations already declare readOnly/idempotent/non-destructive and open-world, so the safety profile is covered. The description adds genuinely new behavior: relations are resolved automatically (e.g. client_name), and it documents the extra_filters contract that the schema defers to it for. Return-format behavior is left to the schema.

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

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

Three front-loaded lines: purpose first, then the dense extra_filters reference, then the routing hint. Every sentence carries information, though the extra_filters line is a compact key dump that demands careful reading.

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 10 parameters, no required fields, no output schema, and full schema descriptions, the only real gap the description must fill is the extra_filters contract — which it does — and it adds the relation-resolution note. Nothing an agent needs to call this correctly is missing, though it could say more about result shape.

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 baseline is 3, but the extra_filters parameter explicitly points back to the description for its key vocabulary, and the description supplies that vocabulary (number, assigned_user, created_between, tag_ids, assigned_user_ids). That meaningfully compensates beyond what the structured schema supplies.

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 from Invoice Ninja') plus the capabilities (filtering, sorting, pagination). It also names the companion tool invoiceninja_get_project, so an agent can distinguish list-vs-fetch 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?

Gives explicit guidance on the extra_filters keys, including accepted formats for date ranges, tag ids, and comma-separated values, and says to follow up with invoiceninja_get_project using an id from this list. It does not position itself against sibling list tools such as list_records or search, so it stops short of a full when/when-not 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?

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is handled. The description adds behavioral context the annotations lack: related names such as vendor_name are resolved automatically, and it spells out the filtering semantics of the extra_filters object. It stops short of describing pagination/rate-limit behavior or the returned record 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?

Front-loaded with the core purpose, then dense but well-organized detail on filter values and the get-sibling routing. Every line carries information; the extra_filters enumeration is long but necessary given the schema's deferral. Slightly packed, but no filler.

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

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

With 10 optional parameters, no output schema and no required args, the description supplies the missing filter-key vocabulary and the follow-up tool for full records. It leaves the actual response shape for a list call unspecified, but that is a minor gap for a paging list tool covered by readOnly annotations.

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 earns extra credit because the extra_filters schema entry merely says 'see the tool description' and defers entirely to this text. The description then enumerates the accepted keys and value formats (date_range, due_date, created_between, tag_ids, etc.), which is genuinely additive rather than duplicative.

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 purchase orders from Invoice Ninja') plus the capabilities it supports (filtering, sorting, pagination). It explicitly distinguishes itself from the sibling invoiceninja_get_purchase_order, so an agent can route 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 closing sentence gives a clear when-to-use-this-vs-that rule: list here, then call invoiceninja_get_purchase_order with an id for the full record. It does not address when to prefer this over invoiceninja_search or invoiceninja_list_records, but the primary routing decision is covered.

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/idempotentHint/destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: related names are auto-resolved (client_name), fields works in JSON format only, and extra_filters accepts column-specific syntax. It does not discuss pagination limits or rate limits, hence 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?

Purpose is front-loaded in the first sentence, then structured as filtered detail lines, with zero filler. Slight redundancy: the client_status value list is repeated verbatim from the schema, which is a minor waste of tokens.

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

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

With no output schema, the description carries the return burden reasonably: response_format (markdown summary vs json) is explained and the get_quote follow-up is noted. For an 11-parameter list tool it is nearly complete, though it says little about what the markdown summary actually contains.

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 genuinely adds meaning the schema lacks: the enumerated client_status values and the full extra_filters key vocabulary (date_range, due_date, created_between, tag_ids, etc.), which the schema itself defers to ('see the tool description').

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

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

States a specific verb and resource ('List quotes from Invoice Ninja') plus its scope (filtering, sorting, pagination), which cleanly separates it from the sibling list_invoices/list_credits tools without needing either schema opened. It also names the paired read tool (get_quote) for the full record.

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 routes the agent: 'Use invoiceninja_get_quote with an id from this list for the full record,' which is clear when-to-use-this-vs-sibling guidance. It stops short of stating when NOT to use it (e.g. vs invoiceninja_search for cross-entity lookups), so it is strong but not complete.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds the resolution/browsing intent but says nothing about pagination behavior, default page size, or result volume, and it leaves the referenced extra_filters behavior entirely unexplained. With annotations carrying the safety burden, a 3 is fair.

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 the entity list then the use case, with no filler. The long inline enum largely duplicates the schema enum, which is mild redundancy rather than bloat.

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 9-parameter tool with no output schema, the description covers purpose and use case but leaves a real hole: extra_filters' schema says to consult the tool description, and the description never mentions it. Nothing on pagination limits or result shape either. Adequate but with a concrete, self-referenced 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 page, sort, filter, status, per_page, fields and response_format in detail, making the 3 baseline appropriate. The description adds no parameter meaning beyond duplicating the entity enum, and it fails to supply the 'extra_filters' documentation that the schema explicitly defers to it ('see the tool description').

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

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

The description states a specific verb (list) plus an explicit enumeration of the reference record types covered, so the agent knows exactly what resource set this tool serves. It implicitly distinguishes itself from the sibling list_invoices/list_clients/etc. tools by scoping to 'reference/secondary records', but it never names those siblings as the alternative for primary entities.

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 concrete usage contexts: 'resolve ids found on other records (e.g. category_id, status ids, tax names)' and 'browse the activity log'. That is a real when-to-use signal. It offers no explicit when-not or routing to a sibling, keeping it short of a 5.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), so the description adds real value beyond that: the client_status allowed values, the extra_filters keys and formats, and automatic relation-name resolution. It doesn't mention pagination limits or default page size behavior beyond schema, nor rate limits, keeping it short of a 5.

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

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

Front-loaded with the tool's action and scope, then compact enumerations for filters and a final routing sentence. Every line earns its place; no redundancy. Slightly under-structured as a bullet-less block but readable and tight.

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 11-parameter list tool with no output schema but rich annotations, the description supplies the filter semantics, resolver behavior, and the follow-up call needed after retrieval. Missing: pagination/response_format guidance and sort examples overlap schema but would have helped. Overall complete enough for correct invocation.

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 baseline is 3. The description goes further by enumerating extra_filters keys (number, created_between, updated_between, tag_ids, assigned_user_ids) and the client_status values, which the schema only vaguely references ('see the tool description'). That compensates for the schema's indirect pointer and adds genuine 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 (List) and resource (recurring expenses) with scope (filtering, sorting, pagination). It clearly distinguishes from invoiceninja_list_expenses (non-recurring) and invoiceninja_get_recurring_expense (single record), but doesn't explicitly name those siblings as 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?

Explicitly routes the agent: use invoiceninja_get_recurring_expense with an id from this list for the full record. That is a clear when-to-use-this-vs-alternative handoff. No explicit exclusions or when-not-to-use, so not a 5.

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

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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: automatic resolution of related names (client_name) and the exact accepted key/value formats for extra_filters. It does not describe pagination limits or result size, keeping it out of 5 territory.

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

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

Front-loaded with the core action, then organized into scannable lines for client_status, extra_filters keys, and the related-tool pointer. Dense but every line carries operational information; only the client_status line duplicates the schema description.

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 11-parameter read-only list tool with no output schema, the description covers the non-obvious parameter semantics and the follow-up tool. Response shape is left to the schema's response_format field, which is acceptable given no output schema exists, but nothing explains default ordering or pagination behavior.

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

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

Schema coverage is 100%, so baseline is 3, but the description genuinely adds meaning: the schema for extra_filters explicitly defers ('see the tool description'), and the description supplies the allowed keys, the frequency_id enumeration (1 daily … 10 annually) and the differing date-range separators for next_send_between vs created_between/updated_between. It also restates client_status values. It does not add anything for the remaining nine parameters, so not a 5.

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 recurring invoices from Invoice Ninja') plus the supported operations (filtering, sorting, pagination). It is clearly separable from invoiceninja_list_invoices and invoiceninja_get_recurring_invoice, 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?

Explicitly routes the agent forward: 'Use invoiceninja_get_recurring_invoice with an id from this list for the full record,' which tells the agent when this list tool is the right entry point vs. the get tool. It gives no exclusion guidance (e.g. when to prefer invoiceninja_search), so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and openWorld, so the safety profile is covered. The description adds genuinely useful behavior beyond that: related names (client_name, project_name, status_name) are resolved automatically, and the extra_filters contract is spelled out. It omits any note on pagination limits or response shape, so it is not fully transparent.

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

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

Front-loads the core purpose, then groups value lists and the sibling hand-off into short, scannable sentences. The dense filter-key enumeration is justified by the undocumented extra_filters object, though the description is on the long side.

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 11-parameter, no-output-schema list tool, the description covers the ambiguous surface (extra_filters keys, automatic name resolution, and the get_task follow-up). It leaves return/pagination behavior unstated, but with read-only annotations and a documented schema the 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 coverage is 100%, so the baseline is 3, but the description earns above baseline by documenting the otherwise opaque extra_filters object keys (number, project_tasks, project_ids, task_status, user_id, assigned_user, activity_dates, created_between/updated_between formats, tag_ids, assigned_user_ids) that the schema itself only gestures at with 'see the tool description'.

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

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

States a specific verb and resource ('List tasks from Invoice Ninja') plus the supported capabilities (filtering, sorting, pagination). It distinguishes itself from invoiceninja_get_task by routing full-record lookups elsewhere, though it does not clarify its boundary against generic siblings like invoiceninja_list_records or invoiceninja_search.

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

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

Gives concrete usage context: the valid client_status values, the full set of extra_filters keys, and an explicit hand-off ('Use invoiceninja_get_task with an id from this list for the full record'). It does not state when NOT to use this tool or contrast it with the other 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, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds that the tool is paginated/filterable and that full details require a follow-up get_vendor call, but it does not disclose rate limits, auth requirements, or the shape of returned vendor summaries.

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 front-loaded sentences with no wasted words. The extra_filters detail is dense but necessary because the schema points to the description for it.

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 9 parameters, full schema coverage, and rich annotations, the description is nearly complete. It covers listing behavior, extra filter syntax, and the follow-up get_vendor path, though it does not mention response_format or restrict guidance to avoid generic search 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 the baseline is 3, but the description adds necessary meaning for the extra_filters object that the schema itself defers to ('see the tool description'). It documents supported keys and the date format for created_between/updated_between, which goes beyond the schema.

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

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

States a specific verb (List) and resource (vendors) with product context (Invoice Ninja) and scope (filtering, sorting, pagination). It implicitly distinguishes itself from the sibling get_vendor tool, which returns the full record.

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 routes the agent: use this list for vendor overviews, then call invoiceninja_get_vendor with an id from this list for the full record. This names the alternative and the condition that selects it.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuine value beyond that by disclosing what the call returns (the token's company and user), which is behavioral context the annotations cannot convey. It does not mention auth failure behavior 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?

A single front-loaded sentence with no filler; the connection check comes first and the identity disclosure second. 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?

With no output schema, the description carries the burden of explaining the return value, and it does so ('which company and user the API token uses'). For a zero-parameter diagnostic tool with full annotation coverage, nothing an agent needs 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?

The tool takes zero parameters, so per the rubric this is a baseline 4. There is nothing for the description to clarify about arguments, and it correctly avoids inventing any.

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 ('Check the connection') and goes further by naming the exact payload returned ('which company and user the API token uses'). This clearly separates it from all sibling listing/getter tools, which retrieve invoice-domain data rather than validating connectivity/identity.

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 — a connectivity/identity probe is naturally run before relying on other tools — but the description never states when to use it, when not to, or names any alternative. No prerequisites or failure-handling guidance is given.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, openWorld), and the description adds genuinely new behavior: reports are generated asynchronously, max_wait_seconds bounds the wait, and a report_id is returned on timeout for later retrieval. It also discloses the default markdown vs. json response shape. It doesn't mention rate limits or cost, 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 front-loaded sentences: purpose with examples, usage recommendation, then the async contract. Every sentence carries information and nothing is repeated from the schema.

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

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

For a 14-parameter tool with no output schema, the description covers the essentials an agent needs: what comes back (rows), the markdown/json toggle, and — critically — the asynchronous timeout path and how to resume via invoiceninja_get_report_result. Report-specific parameter nuance is left to the schema, which is reasonable given 93% coverage.

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

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

Schema coverage is already 93%, so the baseline is 3; the description adds value by explaining the async contract of max_wait_seconds (returns an id rather than data on timeout) and noting that report_keys are listed in every result. It references the 'extra' escape hatch indirectly but doesn't detail per-report parameter differences, which the schema also leaves implicit.

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 ('Run an Invoice Ninja report ... return its rows') and enumerates concrete report types (invoices, payments, expenses, profit & loss, aged receivables, tax summaries, product sales). The clause 'Best for aggregates over many records' distinguishes it from the many list_* siblings that return individual records.

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 explicit selection guidance ('Best for aggregates over many records') and names the follow-up path when the report isn't ready — invoiceninja_get_report_result keyed by report_id. It stops short of stating when NOT to use it (e.g. for single-record lookups), but the routing to the async sibling and the aggregate framing make usage clear.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety and idempotency profile is covered. The description adds that results are id-focused, which helps, but does not disclose result grouping (despite the 'Max matches per group' param) or that no output schema exists for richer framing. Adequate with annotations carrying the load.

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 the action and resources, then the routing guidance. 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 three-parameter, read-only search with full schema coverage and no output schema, the description covers purpose, trigger, and output kind (ids). It could mention that results are grouped by record type (implied by 'per group') or result-count behavior, but it is sufficient for correct invocation.

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 query, limit, and response_format including defaults, bounds, and enum values. The description adds no parameter-level 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?

The description states a specific verb (find) and enumerates the resources (clients, client contacts, invoices, projects) plus the fields searched (name, email, number), and states the output (their ids). This clearly distinguishes it from siblings like invoiceninja_list_clients or invoiceninja_get_invoice, which enumerate rather than search across record types.

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 directs usage: 'Start here when the user mentions a record by name.' This gives a clear trigger condition that routes the agent to this tool over the many list_* and get_* siblings when the user provides only a name/email/number.

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