smallinvoice MCP by usefulapi

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

Annotations already declare write behavior, open-world access, non-idempotency, and non-destructiveness. The description adds concrete context beyond those hints: the POST /contacts endpoint, the 'contact' scope requirement, the fact that nothing is sent to anyone, and the unsupported private-person case.

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 WRITE intent and resource, then efficiently covers scope, endpoint, side effects, unsupported contact type, and duplicate prevention. Every sentence carries operational value and there is no filler.

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

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

For a non-idempotent create tool with no output schema, the description covers scope, endpoint, side-effect behavior, duplicate prevention, and unsupported private persons. It does not describe what the API returns after creation, which is a minor remaining gap given the otherwise rich context and full schema 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 schema already documents all 8 parameters, including formats, lengths, and patterns. The description adds only high-level context such as 'main address' and the company-contact focus, without clarifying optional fields like currency or relation. Baseline 3 is appropriate when the schema does the detailed work.

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

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

States a specific verb and resource: creates a new company contact/customer in smallinvoice with its main address. It also distinguishes this from private-person contacts, which are explicitly unsupported here, and references the relevant sibling list_contacts for duplicate checking.

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 usage guidance: check smallinvoice_list_contacts first to avoid duplicates, and do not use this for private persons because smallinvoice needs more fields for them. It also names the required 'contact' scope, so prerequisites are 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?

Beyond annotations, it discloses that the invoice is only created and not sent, its status is unchanged, the user reviews it in smallinvoice, and calling twice creates two invoices. These are important workflow and duplication consequences that annotations alone would not convey as clearly.

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

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

The description is compact and front-loaded with the WRITE marker and core action, followed by scope, endpoint, behavior, idempotency, and prerequisite lookup guidance. Every sentence adds useful 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 complex mutation with a rich schema and annotations, the description covers scope, side effects, non-idempotency, and prerequisite lookups well. It does not describe what the call returns, which is a minor gap given that no output schema is provided.

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

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

Schema description coverage is 100%, so the schema already documents all seven required parameters in detail. The description only adds that list tools should be used to find contact and unit ids, without enriching the meaning of the remaining parameters beyond the schema.

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

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

The description gives a specific verb and resource ('creates a new invoice for a contact') and explicitly distinguishes creation from sending or status changes. An agent can tell this apart from sibling read/list tools such as smallinvoice_get_invoice or smallinvoice_list_invoices.

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 provides clear usage prerequisites: the 'invoice' scope is required, and contacts/units should be listed first to obtain ids. It does not explicitly state when not to use it or name a full alternative workflow, so it falls short of the top score.

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?

Beyond the readOnlyHint/destructiveHint annotations, the description discloses the required auth scope and the exact REST path (GET /contacts/{id}), which an agent can use for debugging or permission planning. It does not cover error behavior (e.g. missing id) or whether the response is wrapped, but the safety profile is already carried by annotations.

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

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

Four short, front-loaded sentences: identity, expansion, permission requirement, endpoint. Nothing redundant and nothing 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?

This is a simple two-parameter read with a clear schema and no output schema; the description covers how to call it but says nothing about the shape of the returned contact beyond 'its fields', leaving an agent to discover the response blindly.

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 both parameters are already documented, including the comma-separated 'with' pattern and the 'main_address' example. The description repeats the example rather than adding new meaning, 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 resource and cardinality ('One contact by id, with its fields'), which clearly separates it from the list_* siblings such as smallinvoice_list_contacts. It does not say so explicitly, but the singular/plural split is unambiguous enough to act on.

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?

'Add with=main_address for the main address' and 'Needs the "contact" scope' give a prerequisite and an expansion recipe, but there is no explicit statement of when to reach for this over smallinvoice_list_contacts or sibling getters like smallinvoice_get_owner.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds genuinely non-redundant context: the OAuth scope required to call it and the underlying endpoint, which helps an agent diagnose auth failures. No rate-limit or pagination notes, 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 short, front-loaded clauses with no padding; the resource identity comes first. The raw endpoint path is marginal value for an agent but is at least compact.

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

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

For a two-parameter read tool with no output schema, the agent knows what to pass but not what comes back or how a missing note is signalled. Adequate for a simple getter, but not fully self-contained.

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

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

Schema description coverage is 100%, so both 'id' and 'with' are documented in the schema, including the comma-separated format. The description adds nothing about either parameter, 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 resource and retrieval scope ('One delivery note by id'), which cleanly separates it from the sibling smallinvoice_list_delivery_notes. The verb is only implied by the name/title rather than the description text, keeping it short of a 5.

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

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

Adds the required 'delivery_note' scope, which is a real usage prerequisite, but never says when to prefer this over smallinvoice_list_delivery_notes or what to do when the id is unknown. Usage is implied rather than guided.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds useful context: the required invoice scope, the GET endpoint, and that the response includes positions, totals, and status.

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

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

The description is three short sentences with no waste. The resource and scope are front-loaded, followed by the required scope and endpoint.

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 get-by-id tool with full schema coverage and annotations, the description is nearly complete. It briefly describes the returned content but does not detail return structure or error behavior.

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

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

Schema description coverage is 100%, so both id and with are already documented in the schema. The description only reinforces that retrieval is by id and adds no syntax or format details beyond the schema.

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

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

The description clearly states it returns a single invoice by id, including positions, totals, and status. This distinguishes it from list_invoices, though it does not explicitly name the sibling 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?

The description implies usage by saying it retrieves one invoice by id and requires the invoice scope. It does not explicitly state when to use this instead of smallinvoice_list_invoices or other get_* siblings.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description still earns credit by disclosing the required 'offer' permission scope, the underlying endpoint, and the shape of 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?

Two short sentences, zero filler, with the resource identification front-loaded ahead of the scope requirement and endpoint detail.

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

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

For a simple single-record read with fully documented params and no output schema, the description adequately notes what comes back (positions and totals). Minor gap: no mention of not-found/404 behavior or error semantics.

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%, including the note that the id comes from smallinvoice_list_offers and the 'with' expansion example, so the schema carries the parameter semantics and the description adds nothing further beyond 'by id'.

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

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

States a specific verb and resource ('One offer (quote) by id'), and adds what the payload contains ('its positions and totals'), which distinguishes it from smallinvoice_list_offers at a glance.

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: fetching the id returned by smallinvoice_list_offers is hinted at in the schema, and the required 'offer' scope is stated, but there is no explicit when-to-use or when-not versus the list/get siblings.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavioral context beyond them: the required OAuth-style scope and the concrete REST endpoint. It still says nothing about error behavior for missing 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?

Three short sentences with zero filler; the resource identity is front-loaded and the scope and endpoint follow in order of decreasing importance.

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-resource getter with full schema coverage and safety annotations, the description covers what is needed to call it: identity, auth scope, and endpoint. The only gap is the absence of any hint about the returned representation, which no output schema offsets.

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

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

Schema description coverage is 100%, and both parameters (id, with) are already documented in the schema, including the comma-separated include syntax. The description adds no syntax, constraints or examples of its own, 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 the specific resource (one order confirmation) and the selection key (by id), which is enough to tell it apart from list_order_confirmations. It reads as a fragment rather than a verb phrase, but the intent is unambiguous.

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

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

The prerequisite ('Needs the "order_confirmation" scope') gives a real usage condition, and the singular/by-id framing implies the list tool is the alternative for bulk retrieval. There is no explicit when-not or named sibling, so the guidance is only implied.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false. The description adds useful context that this is a cheap connection check and identifies the underlying endpoint, though it does not discuss error handling or auth requirements.

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

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

The description is three short sentences/fragments with no wasted language. The purpose and usage cue are front-loaded before the endpoint.

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 zero-parameter, read-only tool with annotations and no output schema, the description provides enough: what it returns, why to use it, and the endpoint. No important invocation detail 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 has zero parameters, so the baseline is 4. The description correctly does not introduce parameter semantics that are not needed.

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 that the tool returns the smallinvoice account owner's id and details, with the explicit endpoint GET /auth/owner. This is a specific resource and clearly distinct from the sibling contact, invoice, project, and list tools.

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

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

It explicitly identifies a useful scenario: 'A cheap check that the connection works.' It does not describe when not to use it or name an alternative, but the usage context is 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, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuine context beyond them by disclosing the required 'project' scope and the underlying endpoint GET /reporting/projects/{id}, which helps with auth planning and error mapping.

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 terse fragments with the key scoping fact up front and zero filler. The endpoint clause is somewhat redundant with the tool name but is short and occasionally useful for diagnostics.

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

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

For a two-parameter read tool there is no output schema, so the description's 'one project by id' is the only hint at the return shape, which it supplies at a high level. Combined with the annotations and fully documented schema, an agent has enough to call it correctly.

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

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

Schema description coverage is 100%: id is documented with its source (smallinvoice_list_projects) and 'with' is documented with a format example. The description adds only 'by id', which the schema already covers, 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: 'One project by id.' That implicitly contrasts with smallinvoice_list_projects, and the resource name distinguishes it from the other get_* siblings. It is clear but does not explicitly name the alternative tool.

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

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

The only guidance is the prerequisite 'Needs the "project" scope', which tells the agent an auth requirement but not when to prefer this over smallinvoice_list_projects or how to obtain an id. Usage is implied rather than 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, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds real context beyond that: the required 'activity' scope, the HTTP endpoint, and the shape of the response including paging fields – none of which is in the annotations or 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 short sentences, front-loaded with purpose, then prerequisite and endpoint, then return shape. Every sentence carries information not available elsewhere, 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?

There is no output schema, so the description usefully names the return fields (count, total, next_offset, items) and explains how to continue paging. Combined with full schema coverage and annotations, an agent has enough to call and page correctly; only the sibling-routing guidance is absent.

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

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

Schema coverage is 100%, so the six parameters are already documented in detail; baseline would be 3. The description earns an extra point by explaining the paging contract concretely – 'pass next_offset as offset for the next page' – which links the return value to a parameter in a way the schema cannot.

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

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

The description gives a specific verb plus resource ('List activities') and disambiguates the domain term with a parenthetical ('the kinds of work that hours are booked on'). It does not distinguish itself from plausible siblings such as list_services, list_efforts or list_working_hours, which an agent could easily confuse with activities.

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

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

It states the prerequisite ('Needs the "activity" scope') and the underlying endpoint, which implies a straightforward read-only listing. There is no explicit guidance on when to pick this over list_efforts or list_working_hours, and no exclusion or alternative-routing statement.

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

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

Annotations already declare readOnly/openWorld/non-destructive, so the safety profile is covered. The description adds material context beyond that: the required auth scope, the underlying endpoint, and the paging contract (next_offset must be passed back as offset), which the agent would otherwise have to discover by trial.

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

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

Three short sentences, each doing distinct work: what it lists, what permission it needs, and what comes back including paging. Front-loaded and free of 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 no output schema available, the description compensates by naming the return fields (count, total, next_offset, items) and the pagination mechanic, while the schema fully documents all six optional parameters. Nothing an agent needs to call and page through results 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; the description earns an extra point by explaining the relationship between the response's next_offset and the offset parameter, a semantic link the schema alone does not spell out.

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 (bank accounts) plus a clarifying scope note that these are the accounts as printed on documents. No sibling tool targets bank accounts, so an agent can immediately tell this apart from the other list_* tools.

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

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

Gives the precondition that the 'configuration' scope is required, which tells the agent whether it can call this at all, and the resource is narrow enough that no exclusions are needed. It stops short of naming an alternative or stating when-not to use it, but there is no competing sibling.

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 openWorldHint=true, so safety is covered. The description adds genuinely useful auth context ('Needs the "contact" scope') but says nothing about pagination behavior or result ordering beyond what the schema shows.

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 terse fragments, purpose front-loaded, zero padding. The raw endpoint path is mildly redundant given the parameter already named contact_id.

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

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

For a simple read-only list tool with annotations covering safety and a fully described schema, the description supplies the resource scope and the auth scope requirement. Nothing essential to invoking it correctly appears to be missing.

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

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

Schema coverage is 100% and all three parameters are documented in the schema, including limit/offset paging semantics. The description only restates the contactId path segment, adding no extra 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 the specific resource and scope: all addresses belonging to a single contact. This clearly separates it from smallinvoice_list_contacts and smallinvoice_list_contact_people, though the verb 'list' is only implied by the name.

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

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

Implies usage (fetch addresses for a known contact) and names the required 'contact' scope, but offers no when-to-use guidance against alternatives such as get_contact or list_contact_people.

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

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

Annotations already declare readOnlyHint and destructiveHint=false, but the description adds genuinely non-structured information: the required 'contact' scope and the underlying endpoint path. It also discloses the paging contract (next_offset → offset), which goes beyond a bare 'list' statement.

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

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

Four short sentences, front-loaded with the purpose, then scope, then endpoint, then return shape. Nothing is redundant and every sentence carries actionable information.

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

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

With no output schema, the description helpfully names the return envelope fields (count, total, next_offset, items) and the paging mechanics, and it states the auth scope. Only marginal gaps remain, such as what the items contain.

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

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

Schema description coverage is 100% and all six parameters are documented in the schema, including q, sort, with, limit, filter and offset with examples. The description only echoes the offset/next_offset relationship already stated in the schema, so it adds little beyond baseline.

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

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

States a specific verb and resource ('List the contact groups') plus the concrete endpoint GET /contacts/configuration/groups, which makes it distinguishable from sibling lists like smallinvoice_list_contacts or list_contact_people. It does not explicitly name those siblings, but the resource is unambiguous.

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

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

Adds useful call context — the required 'contact' scope — and implies a paging loop by explaining how to pass next_offset back as offset. It gives no guidance on when this tool should be preferred over related list tools or when not to use 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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the required OAuth scope, which annotations do not provide, but says nothing about pagination behavior or volume 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?

Three short fragments with zero filler, and the resource is front-loaded ahead of the scope and endpoint. It reads as terse documentation rather than a sentence, which is efficient but slightly clipped.

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

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

The tool is simple and the schema fully covers paging, but with no output schema the description never indicates what fields a contact person record contains or that results are a paged list. That is a modest but real gap for an agent deciding whether this call answers its question.

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 limit, offset, and contact_id all documented inline including the next_offset paging convention. The description adds no parameter-level detail beyond the raw endpoint path, 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?

The description names a specific resource (contact persons of one company contact) and pins it to an endpoint (GET /contacts/{contactId}/people), so the agent knows exactly what is returned. It does not explicitly differentiate itself from near-siblings such as smallinvoice_list_contact_addresses or smallinvoice_list_contact_groups, though the resource noun does most of that work.

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 scope requirement ('Needs the "contact" scope') gives a prerequisite, which is real guidance. However, there is no statement of when to prefer this over the sibling list tools for addresses, groups, or the parent contact itself, so selection still relies on inference from the name.

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

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

Beyond the readOnlyHint/openWorldHint annotations, the description discloses the required OAuth scope, the underlying endpoint (GET /contacts), and the exact return shape including paging fields (count, total, next_offset) with instructions on reusing next_offset as offset. That is precisely the added behavioral context annotations cannot convey.

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

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

A tight paragraph where every clause carries load: purpose, fields, address inclusion trick, auth scope, endpoint, and return/paging contract. Front-loaded with the verb and resource.

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

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

No output schema exists, yet the description fully describes the response envelope and paging, and it names the auth requirement. For a 6-parameter read-only list tool, nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so all six parameters are already documented. The description restates the 'with' behavior and the offset/next_offset paging link, which the schema also covers, so it adds little beyond structured fields. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('List contacts'), clarifies the entity as 'customers and suppliers', and enumerates the fields returned. An agent can distinguish it from get_contact or create_contact, though it does not explicitly distinguish it from list_contact_people / list_contact_addresses.

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 concrete operational guidance: the 'contact' scope is required and 'with=main_address' is the way to pull address data inline. Usage is clear, but there are no explicit exclusions or 'use X instead' routing against the sibling list/get contact 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 cover the read-only/safe profile, yet the description adds the OAuth scope requirement and the exact HTTP path, neither of which appears in structured fields. Since there is no output schema, it also discloses the response envelope (count, total, next_offset, items) and the paging protocol, which is real 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?

Four short sentences, front-loaded with purpose, then permission, endpoint, and return shape — no padding. The telegraphic fragments ('Needs the "cost_unit" scope. GET /reporting/cost-units.') are efficient, though slightly clipped.

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 6 optional params fully documented in schema and no output schema, the description supplies what's missing: the return envelope and next_offset-as-offset paging loop, plus the scope requirement. It does not explain what a cost unit is or the default ordering, which are minor for a list endpoint.

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

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

Schema description coverage is 100%, so all six parameters are already documented, including the filter syntax and the offset/next_offset paging hint. The description's only parameter-related content restates the pagination convention rather than adding new semantics, 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 uses a specific verb ('List') plus resource ('cost units') and confirms the underlying GET endpoint, so the operation is unambiguous. However, it never distinguishes cost units from the nearby sibling smallinvoice_list_units, which an agent could easily confuse.

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

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

It states the required 'cost_unit' scope, which is a genuine usage prerequisite, but gives no explicit when-to-use guidance or routing to alternatives (e.g. list_units). Usage is implied by the resource name rather than explained.

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

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

The annotations already declare a safe read-only, non-destructive, open-world operation. The description adds useful behavioral context: the required scope, the endpoint, and the pagination contract where next_offset should be passed back as offset. It stops short of describing error 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?

The description is short and front-loaded with the core action, then adds filtering, scope, endpoint, and return/paging details. Most sentences earn their place, though the raw endpoint reference is marginal for an agent.

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

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

With no output schema, the description appropriately explains that the tool returns count, total, next_offset, and items, and it explains how to page. Given complete schema coverage and annotations, this is nearly complete, though it could mention other filter/sort options at a high level.

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

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

Schema description coverage is 100%, so all seven parameters are already documented by the schema. The description only restates contact_id filtering and the next_offset-to-offset paging relationship, which the schema also covers, so it adds little beyond the structured fields.

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

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

The description states a specific verb and resource: list delivery notes. It also names the supported filters and the endpoint. It does not explicitly distinguish itself from the sibling get_delivery_note, but the list-versus-get distinction is clear enough from the name.

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

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

It says the tool can filter by contact_id or a JSON filter and notes the required delivery_note scope. However, it never states when to use this list tool instead of get_delivery_note or other list endpoints.

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

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

Annotations already establish that this is a read-only, open-world, non-destructive operation. The description adds useful behavioral context beyond that: it names the required "effort" scope, identifies the HTTP endpoint, and explains pagination via next_offset. It does not cover rate limits or error behavior, so it stops short of exhaustive.

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

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

The description is four short sentences, front-loads the resource definition, and then gives only the scope, endpoint, and return/pagination details. Every sentence carries operational value with no wasted prose.

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 rich schema documentation and safety annotations, the description covers the required scope, endpoint, pagination, and top-level return fields. It does not describe the shape of individual effort items, which is a minor gap given the absence of an output 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% and every parameter is already documented, including offset as the previous reply's next_offset. The description repeats that pagination mapping but adds no new meaning about filtering, sorting, or the other optional parameters, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: list efforts, then clarifies that efforts are expenses and services recorded against projects. This is clear enough to understand the domain object, but it does not explicitly distinguish the tool from nearby siblings such as list_services or list_working_hours.

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 only gives an implied usage context by naming the resource and noting the required "effort" scope. It does not say when to choose this tool over alternatives such as list_services or list_working_hours, so the guidance is minimal but not misleading.

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

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

Annotations already cover the safety profile (readOnlyHint, destructiveHint=false, openWorldHint), so the bar is lower. The description still adds real context beyond them: the required auth scope and the underlying endpoint shape, which tells an agent this is a scoped read against a specific invoice.

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

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

Three short sentences, front-loaded with what the tool returns, then prerequisites, then the endpoint. No filler and no repetition of the title.

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

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

For a 3-parameter filtered list with no output schema, the definition covers purpose, scope requirement, and endpoint. The main gap is that it doesn't describe the shape of the returned payment records, but annotations and the fully documented paging parameters cover most of what an agent needs to call it correctly.

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

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

Schema coverage is 100%, with limit, offset, and invoice_id each carrying their own descriptions (defaults, maxes, and next_offset paging hint). The description adds nothing about parameter syntax or semantics, 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-in-effect (retrieves) and resource (payments recorded on one invoice), which is clearly narrower than sibling list tools like smallinvoice_list_invoices. It doesn't explicitly name a sibling to route against, but the scoping to a single invoice makes the distinction obvious.

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 'recorded on one invoice' plus the required invoice_id, and the description adds a prerequisite ('Needs the "invoice" scope'). There is no explicit when-to-use or when-not guidance relative to get_invoice or other list tools, so it stops at implied context.

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

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

Annotations already cover read-only and non-destructive behavior, while the description adds the required 'invoice' scope, the endpoint, and the pagination convention for next_offset. It does not cover rate limits or error behavior, but it is substantially more informative than the annotations alone.

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

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

Front-loads the resource and returned fields, then covers filtering, scope, endpoint, and pagination with no wasted sentences. The structure lets an agent quickly extract both selection and invocation details.

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?

Despite no output schema, the description explains the response shape (count, total, next_offset, items) and how to page using offset. For a read-only list tool with 100% schema coverage and clear annotations, this is complete enough to invoke correctly.

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

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

Schema description coverage is 100%, so parameters like q, sort, with, limit, filter, offset, and contact_id are already well documented in the schema. The description highlights contact_id, filter, and the next_offset-to-offset paging pattern but does not add detail beyond the schema for the remaining parameters.

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') and enumerates the returned fields (number, contact, dates, total, currency, status). This clearly distinguishes it from sibling detail tools such as smallinvoice_get_invoice.

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

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

Explains how to narrow results via contact_id or a JSON filter and notes the required 'invoice' scope. It does not explicitly name when to use smallinvoice_get_invoice instead, so the alternative routing is only implied.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), so the description's added value is the auth requirement ("offer" scope) and the response envelope (count, total, next_offset, items). The explicit instruction to pass next_offset as offset is real operational context the annotations do not provide. It does not state default page size or error behavior, keeping it at 4.

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

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

Three tight sentences, front-loaded with purpose, then filtering, then the return shape. Every clause carries information an agent needs; there is no filler.

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

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

There is no output schema, so describing the return envelope and the pagination contract is necessary and is done here. With all seven parameters fully documented in the schema and annotations covering safety, the only residual gap is error/rate-limit behavior. Strong enough for a simple read-list tool.

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

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

Schema description coverage is 100%, so the schema already documents q, sort, with, limit, filter, offset and contact_id thoroughly, including filter comparators. The description only restates the contact_id/JSON-filter split and the offset/next_offset round-trip, adding little beyond the structured fields.

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?

Names a specific verb and resource ("List offers (quotes)") and even the underlying endpoint GET /receivables/offers, which makes the list-vs-get split against smallinvoice_get_offer obvious without consulting the schema. It stops short of explicitly naming a sibling, so it is clear but not maximally differentiating.

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?

"Filter by contact_id or a JSON filter" gives two concrete entry paths and "Needs the 'offer' scope" states a hard prerequisite the agent must satisfy before calling. No exclusion cases or alternative tools are named, which is a minor gap for a plain 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 declare readOnly/no-destructive semantics, and the description adds real context beyond them: the required auth scope, the HTTP endpoint, and the pagination contract ('pass next_offset as offset'). It doesn't discuss rate limits or error behavior beyond what the schema already notes for bad filter fields, which keeps it from a 5.

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

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

Four short sentences, front-loaded with the action and followed by filtering, auth, endpoint, and return shape, with no filler. The bare endpoint mention is mildly redundant but not wasteful.

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 naming the return fields (count, total, next_offset, items) and explaining the pagination loop. Combined with full schema coverage for all seven optional parameters and the scope requirement, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents q, sort, with, limit, filter, offset, and contact_id in detail. The description only restates contact_id, filter, and the offset/next_offset relationship, adding no syntax or semantics beyond the structured fields — the baseline 3 applies.

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

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

States a specific verb and resource ('List order confirmations') and the underlying endpoint, which is enough to separate it from the sibling get_order_confirmation (single fetch) and the other list_* tools. It stops short of explicitly saying how it differs from those siblings, so it lands just below 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?

It gives concrete selection mechanics ('filter by contact_id or a JSON filter') and a prerequisite ('Needs the "order_confirmation" scope'), which implies when the tool applies. There is no explicit when-not guidance or steering toward get_order_confirmation when a specific id is known, so usage is implied rather than spelled out.

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

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

Annotations already declare readOnlyHint, openWorldHint, and destructiveHint=false. The description adds real value beyond that: the required auth scope, the underlying endpoint (GET /catalog/products), and the shape of the response including the pagination token. It doesn't mention error behavior beyond that, but for a read-only list tool this is solid coverage.

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

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

Four short sentences, front-loaded with the purpose, then scope, endpoint, and return/paging info. Every sentence carries distinct information with no redundancy.

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

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

With no output schema, the description compensates by naming the return fields (count, total, next_offset, items) and explaining how to use next_offset. Auth scope and endpoint are also covered, leaving nothing an agent needs in order to call this correctly.

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

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

Schema description coverage is 100%, so each of the six parameters is already documented, including filter syntax and sort patterns. The description reinforces the offset/next_offset linkage but adds no new syntax or constraints, so the baseline 3 applies.

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

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

The description gives a specific verb and resource ('List the catalog's products (articles)'), which distinguishes it from sibling list tools like list_services and list_contacts by resource alone. It stops short of explicitly naming when to prefer it over those related catalog tools, so it doesn't reach the sibling-routing clarity 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?

It states the required 'catalog' scope and gives an explicit paging workflow ('pass next_offset as offset for the next page'). No when-not-use or alternative guidance is provided, so it is clear context without exclusions.

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

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

Annotations already declare readOnly, non-destructive, open-world, and the description is consistent with them. It goes further by disclosing the auth scope and the pagination contract (next_offset must be passed back as offset), which the agent cannot infer from annotations. It stops short of describing rate limits or result ordering defaults.

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

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

Four short sentences, nothing wasted, and the scope plus endpoint come before the return-shape note. The telegraphic fragments ("GET /reporting/projects.") are compact rather than confusing.

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

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

With no output schema, the description correctly spends its words on the response shape (count, total, next_offset, items) and how to page. Given 100%-covered parameters and existing annotations, what remains missing is minor.

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

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

Schema description coverage is 100%, so baseline is 3; the six parameters including the filter DSL and sort syntax are already fully documented in the schema. The description only reinforces the offset/next_offset loop, which the schema itself also states.

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

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

States a specific verb and resource ("List projects") and adds the endpoint GET /reporting/projects, so an agent knows exactly what it retrieves. It is distinguishable from the singular smallinvoice_get_project by name, though the description never says so 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?

The required "project" scope is a useful prerequisite that tells the agent whether it can call at all. However, there is no guidance on when to prefer this list over smallinvoice_get_project, nor any mention of conditions or exclusions.

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

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

Annotations already declare readOnly/openWorld/non-destructive, and the description adds value on top: the required OAuth-style scope, the underlying GET endpoint, and an explicit paging contract (feed next_offset back as offset). It doesn't mention rate limits or ordering defaults, keeping it from a 5.

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

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

Three short sentences, front-loaded with purpose, followed by the scope/endpoint and the return shape. Nothing is repeated and every sentence carries 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 zero-required-parameter read tool with full schema coverage and readOnly annotations, the description is essentially sufficient: it covers auth scope, transport, and the pagination loop. The only soft gap is that 'items' contents are not characterized, though filter/sort/with parameters imply the 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 all six parameters are already documented, including the offset/next_offset paging hint. The description restates the paging loop but adds no new syntax or constraint detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the catalog's services') and names the endpoint, so it is clearly distinguishable from siblings like smallinvoice_list_products or smallinvoice_list_contacts. It stops short of explicitly contrasting itself with those siblings.

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

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

The 'Needs the "catalog" scope' line gives a real prerequisite, which is helpful for eligibility. However, there is no explicit when-to-use guidance relative to alternatives such as list_products, nor any statement of when not to use 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 this a read-only, non-destructive, open-world list operation, and the description still adds useful context: the required 'configuration' scope, the underlying endpoint, and the pagination contract (pass next_offset as offset). It doesn't mention error behavior or ordering defaults, but the safety profile is fully covered.

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

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

Four short sentences, front-loaded with purpose, then scope requirement, then endpoint, then return/paging shape. Nothing is redundant or padded.

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

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

No output schema exists, so the description carries the return contract and does so (count, total, next_offset, items) plus the auth scope. For a parameterless-required read-list tool, an agent has everything needed to call and page it correctly.

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

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

Schema coverage is 100%, with each of the six parameters (q, sort, with, limit, filter, offset) documented in-schema, including next_offset paging. The description restates the paging mechanism but adds nothing new about filter/sort syntax, so baseline 3 applies.

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

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

States a specific verb and resource ('List the units') and immediately disambiguates them by role: the ids an invoice position's unit_id refers to, with concrete examples (piece, hour). That distinguishes it from nearby list tools such as list_cost_units and list_services.

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

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

The phrase 'which an invoice position's unit_id refers to' tells the agent exactly when to call it: resolving unit ids to labels. It does not say when to prefer a sibling list tool or whether units are ever created/edited elsewhere.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description still adds real value by disclosing the required 'working_hours' scope and the shape of the response, including the next_offset continuation token that must be fed back as offset.

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 compact sentences front-load purpose, then scope, then return shape. Nothing is redundant and the pagination hint is placed exactly where an agent needs 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 no output schema, the description correctly compensates by naming the returned fields (count, total, next_offset, items) and the paging convention. It stops short of covering what the items contain or how to filter working hours specifically, but the essential calling information is present.

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

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

Schema coverage is 100%, so every parameter (q, sort, with, limit, filter, offset) is already documented in the schema with examples. The description only restates the offset/next_offset paging linkage, adding no new parameter semantics beyond what the schema 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 and resource ('List recorded working hours') and clarifies the domain with '(time tracking entries)', which disambiguates it from generic list tools. It does not, however, distinguish itself from sibling list tools like smallinvoice_list_efforts or smallinvoice_list_activities, so it falls short of the top score.

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

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

The description names the endpoint and scope but gives no guidance on when to choose this tool over smallinvoice_list_efforts or smallinvoice_list_activities. There are no exclusions, prerequisites, or usage conditions beyond the implicit 'use this to list working hours'.

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