SuperFaktura MCP by usefulapi

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

Annotations only give destructiveHint=true; the description carries real extra context: 'WRITE' frames the mutation, 'Nothing is sent to that person' rules out an email/notification side effect an agent might assume, and 'Not idempotent' warns that retries create duplicates. These are exactly the traits that alter invocation 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?

Front-loaded with the 'WRITE' marker, then four tight clauses with no filler: target, side-effect note, idempotency, endpoint. Every sentence earns its place and the most decision-relevant facts come 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 no-output-schema mutation tool, the description covers semantics, side effects, idempotency, and the endpoint well. It stops short of indicating the return payload (e.g. new contact id) or failure behavior for a bad client_id, which leaves a small 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?

With 75% schema coverage the schema already documents name, email, and client_id; the description adds the optionality framing '(name and e-mail, optional phone)' and implies client_id targets an existing client. This is a modest but real addition over 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?

States a precise verb+resource+target: 'adds a contact person ... to an existing client.' This is clearly distinct from siblings like superfaktura_create_client (creates the client) and superfaktura_list_contact_persons (reads them). The trailing endpoint hint reinforces the exact operation.

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?

'to an existing client' establishes the precondition that the parent client must already exist, which is the key routing context. It does not name an explicit alternative or when-not condition (e.g. vs create_client), but the use context 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 supply only destructiveHint=true, so the description carries most of the burden and does so well: it discloses the non-idempotent create semantics, the required-field minimum, the outward-effect scope ('nothing is sent to the client'), and the underlying endpoint POST /clients/create. These are traits an agent cannot infer from 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?

Three tight sentences; the WRITE marker and core action are front-loaded, and every clause carries a distinct, non-redundant fact (dupe risk, required field, no outbound send, 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 13-param create tool with no output schema and minimal annotations, this covers the mutation-risk and safety questions an agent needs answered. The remaining gap is the response shape (e.g. whether a client id is returned for follow-up calls), which the absence of an output schema makes slightly more relevant.

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 62% across 13 params, and the description only restates that 'name' is required, which is already in the schema's required list. It adds no format, constraint, or cross-reference detail for the other fields (e.g. country_id's list_countries link exists only in the schema). Baseline 3 for a partially documented schema with no compensating prose.

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 'WRITE: adds a new client to the SuperFaktura address book', giving an explicit verb (adds), resource (client), and destination (address book). The note that only the name is required and the POST endpoint pin it down unambiguously against siblings like superfaktura_get_client and superfaktura_add_contact_person.

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 names the exact alternative to consult ('check superfaktura_list_clients first') and explains the condition that motivates it (non-idempotency: two calls create two clients). It also sets expectations about side effects with 'Nothing is sent to the client'.

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

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

Annotations only supply destructiveHint=true, so the description carries most of the burden and delivers: created unpaid (no payment recorded), nothing sent, no attachments, and the non-idempotent warning that a second call records a second expense. This is exactly the behavioral detail an agent needs before writing, and it is consistent with destructiveHint.

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 'WRITE:' marker followed by terse, information-dense sentences; the endpoint reference closes it out. No filler, and each clause conveys a distinct constraint or effect.

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?

Given sparse annotations and no output schema, the description covers what an agent must know: write semantics, unpaid/unsent result, attachment limitation, idempotency behavior, and the endpoint. Nothing critical to invoking 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 parameter documentation is already handled and baseline would be 3. The description adds a modeling constraint beyond the schema: only a single total amount plus one VAT rate is accepted, i.e. no line-item breakdown, which affects how amount/vat should be populated.

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 ('records a received document (expense)') plus an example ('a supplier invoice or a bill'), which cleanly separates it from the sibling superfaktura_create_invoice (issued documents). The 'ONE total amount and VAT rate' phrasing also signals the modeling constraint up front.

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 clear context for when this applies (received supplier documents, created unpaid, no attachments sent), which is enough to route an agent correctly. It stops short of naming alternatives or exclusions explicitly (e.g. 'for issued invoices use create_invoice'), so it is strong but not 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 only supply destructiveHint=true, so the description carries most of the burden and delivers: nothing is sent via e-mail or post, nothing is marked paid, and no payment link or discount is generated. It further discloses quota cost (client_id lookup consumes 2 of the daily requests), non-idempotency, and the checksum-based recovery path — exactly the operational traits an agent needs before calling a mutating endpoint.

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

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

The 'WRITE:' prefix and the two negations (not sent, not paid) are front-loaded where an agent will see them first, and nearly every clause carries distinct information. It is a dense single paragraph with heavy parenthetical nesting, which costs some scanability.

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 26-parameter mutation with no output schema and only a destructiveHint annotation, the description covers the safety-critical behaviors (unsent, unpaid, non-idempotent, quota cost, recovery tool). It leaves the response content and the behavior when client_name matches an existing client slightly under-specified.

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 already 100%, so the baseline would be 3; the description earns a bump by explaining the client_id-vs-client_name decision rule, the item shape (name, unit price without VAT, VAT rate, quantity), and the recovery role of the checksum beyond its length limit. It does not explain the numbering/sequence or symbol fields, which the schema alone carries.

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 ('WRITE: creates ONE document in SuperFaktura') and immediately enumerates the exact document types it can produce (draft/estimate/order/proforma). It also draws a hard boundary ('A final regular invoice cannot be created here'), which lets an agent distinguish it from every other creative sibling 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 clear when-to-use context (unsent draft/estimate/order/proforma for user review) plus an explicit negative boundary against final invoices, and routes the agent to superfaktura_get_response_by_checksum for timeout recovery instead of retrying. It does not name a sibling for the excluded case (issuing a real invoice) or state prerequisites, so it stops just short of 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 only carry destructiveHint=true, so the description does heavy lifting: it flags the operation as a WRITE, discloses the duplicate-name rejection behavior (important for error handling), and names the endpoint POST /tags/add. It does not describe the response payload, but for a single-field create 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?

Two front-loaded sentences leading with the WRITE nature and purpose, plus a terse endpoint reference. No filler; every clause (scope, duplicate refusal, endpoint) 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?

A single-parameter create tool with no output schema and minimal annotations needs little else; the description covers operation type, scope, and the one notable failure mode. Return value details are omitted, which is acceptable given no output schema, though a hint about what the created tag identifier looks like would round it out.

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

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

Schema coverage is 100% and the sole parameter 'name' is documented as 'Tag name.' with length constraints, so the schema already carries parameter meaning. The description adds no format, casing, or character-set guidance beyond restating 'tag name', matching the baseline for fully-covered schemas.

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

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

Specific verb+resource: 'adds a new tag name', with scope clarified (usable on invoices, expenses and clients). An agent can immediately distinguish this from the read-only sibling superfaktura_list_tags 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 conveys context (creation of a tag applied across invoices/expenses/clients) and notes that duplicates are refused, which implicitly guides usage. However, it never states when to prefer this over alternatives or any prerequisites beyond the duplicate rule, so guidance remains implied rather than explicit.

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

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

The '(read only)' note merely restates the readOnlyHint=true annotation, so it earns no credit beyond structured data. The description does add value by naming the returned fields (currency, number of entries, current balance), which matters because no output schema exists, but it omits any behavior on invalid/missing ids or error conditions.

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

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

Two compact fragments that lead with what is returned and the HTTP route; nothing is padded. Minor redundancy in the parenthetical '(read only)', which duplicates the annotation, keeps it from a 5.

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

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

For a single-parameter read tool with no output schema, the description covers the operation, the identifying parameter's source, and the shape of the returned data. Only error/not-found behavior is unaddressed, which is a small gap given the tool's simplicity.

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

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

Schema coverage is 100% and the single parameter already documents its type, positivity constraint, and provenance ('from superfaktura_list_cash_registers'). The description adds no format or syntax 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 (get) and resource (one cash register) plus the payload fields returned (currency, entry count, balance), so the agent knows exactly what it retrieves. The word 'One' implicitly contrasts with the sibling superfaktura_list_cash_registers, but that sibling is never named, so differentiation is left to inference.

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

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

Usage is only implied: the schema note that the id comes 'from superfaktura_list_cash_registers' sketches a list-then-view workflow, and 'One ... register' hints at single-record retrieval. There is no explicit when-to-use/when-not statement and no named alternative, so an agent must infer the 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?

Annotation readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description adds the API endpoint and the shape of the returned payload, which is useful, but says nothing about auth requirements, not-found/error behavior, or whether results are cached/filtered.

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

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

Two compact fragments that front-load the returned data before the endpoint detail; no filler. It could drop the raw endpoint with no loss, but overall it is tight and well-ordered.

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

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

For a single-parameter read tool with annotations covering safety and no output schema, the description does the right thing by enumerating the returned fields. Error/not-found handling is the only meaningful omission.

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

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

Schema description coverage is 100% and the single client_id parameter is fully documented (including its type and that it comes from superfaktura_list_clients). The description adds no parameter meaning beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource ('Get a client') and enumerates the returned fields (address, tax ids, bank data, currency/due days/discount, statistics), which is more than a restatement of the title. The singular 'client' vs the sibling 'superfaktura_list_clients' implies single-fetch versus list, but the description never explicitly contrasts them, so sibling differentiation is left implicit.

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: fetching one client by id, where the id originates from the list tool (noted only in the schema, not the description). There is no explicit when-to-use, when-not-to-use, or alternative routing, though in a get/list family the context is reasonably 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?

readOnlyHint already declares this as a safe read, but the description adds genuinely new behavioral context: the fair-use quota (1000/day, 31000/month) and the fact that every tool call consumes one request. It stops short of explaining response shape or error behavior, 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?

Front-loaded with the resource, then the quota context, then the all_companies branch. Dense but every sentence carries information; the parenthetical quota detail is slightly verbose but earns its place by preventing accidental rate-limit exhaustion.

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 enumerating returned fields, and it covers the rate-limit behavior an agent needs to budget calls. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining the consequence of all_companies=true and that returned ids correspond to the login's company_id. That adds meaning beyond the schema's one-line definition.

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 (retrieves the company profile the API key operates in) and enumerates the returned fields (name, IČO, DIČ, IČ DPH, address, VAT flag, bank accounts) plus remaining quota. This clearly separates it from siblings like superfaktura_get_client or superfaktura_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?

"Good first call" gives explicit guidance on when to reach for it, and the all_companies branch tells the agent when to widen scope. It does not name a specific alternative tool or state exclusions, so it falls short of a full 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=true, so safety is covered. The description adds genuine value beyond that: it discloses the included payload (items, VAT rates, payments, supplier) and an important negative trait, 'Attachments are not returned', which an agent could not derive from 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?

Two tight sentences with the return contents front-loaded, followed by the exclusion and the raw endpoint. No filler; every clause 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 single-parameter read whose safety profile is covered by annotations, the definition says what comes back and what does not. It stops short of covering failure behavior (e.g., an unknown expense_id) but is otherwise self-sufficient.

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 a single well-documented parameter, so the schema already carries the semantics (integer id, exclusiveMinimum 0, sourced from list_expenses). The description adds no format or constraint detail beyond it, 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 clear operation (fetch a single expense) and enumerates the returned payload components: items, VAT rates, payments, supplier. The singular framing distinguishes it from superfaktura_list_expenses, though the description never names that sibling the way a 5 would.

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 per-id detail view versus list_expenses, but there is no explicit when-to-use statement or exclusion. The reference to superfaktura_list_expenses appears only in the schema's parameter description, not in the tool description itself.

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

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

readOnlyHint=true already establishes the safe-read profile, so the bar is lower, yet the description still adds genuinely useful negative disclosure: the public access token and payment links are NOT returned. It also names the underlying endpoint GET /invoices/view/{id}.json. It does not disclose auth requirements or error behavior for missing/unauthorized 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?

Two short sentences plus a bare endpoint reference carry a lot of information with no padding. The returned-content enumeration is front-loaded, and the exclusion note is placed where it is most useful.

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

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

With no output schema, the description carries the return-value burden and does so well by listing the component sections of the returned document. It stops short of covering error cases (invalid id, permissions) or whether embedded items/payments can be large, but it is otherwise sufficient for a one-parameter read tool.

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

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

Schema description coverage is 100% with a single required invoice_id, so the schema already carries the parameter burden. The description adds no format, range, or provenance detail for invoice_id beyond what the schema states, 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 clearly indicates retrieval of a single document and enumerates what it contains (header, client, items, VAT summary, payments, related documents), which distinguishes it from the sibling superfaktura_list_invoices. The verb 'get' is only implicit in the name rather than stated in the description text, 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?

There is no guidance on when to use this versus superfaktura_list_invoices or the other get_* siblings, and no mention of prerequisites such as needing an id obtained from the list endpoint. The only such hint ('the id of a superfaktura_list_invoices row') lives in the schema, not the description.

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

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

readOnlyHint=true already tells the agent this is a safe read, and the description adds genuinely new context: the checksum is retained for 3 months and the call exists to guarantee idempotency (avoid duplicate creation). It does not say what happens if the checksum is unknown or the window has expired, which is the remaining behavioral gap for an error-prone recovery path.

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 front-loaded sentence carrying trigger, action, rationale, and retention, followed by the endpoint path. Every clause earns its place and no sentence is wasted.

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

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

With one parameter, full schema coverage, no output schema, and a readOnly annotation, the description is nearly self-sufficient — it even signals that the return value is the original request's reply. Only the failure mode (checksum not found/expired) is left undefined.

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

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

Schema description coverage is 100% and the single parameter is fully documented as 'The checksum given to superfaktura_create_invoice.' The description reinforces the same meaning but adds no format or provenance 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+resource ('fetch the reply of the ORIGINAL request by the checksum') and explains the scope ('of a create', tied to superfaktura_create_invoice). It is unmistakable against siblings like superfaktura_get_invoice or superfaktura_list_invoices, which retrieve documents rather than a prior request's response.

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

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

Explicit trigger condition is given: 'If a superfaktura_create_invoice call timed out, fetch the reply of the ORIGINAL request ... so the document is not created twice.' This names the sibling it complements and the exact situation that selects it, leaving nothing to inference.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description adds useful context by naming the payload fields the agent will receive, but says nothing about lookup failure behavior when an id does not exist or about the API's rate/auth profile.

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

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

Two compact fragments covering purpose and endpoint, with the identifying information front-loaded and zero filler. It is slightly telegraphic, but nothing is wasted.

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

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

For a single-parameter read tool with no output schema, the description rounds out the picture by enumerating the returned fields, which the schema cannot convey. Only the error/not-found behavior is unaddressed, a minor gap given readOnlyHint covers safety.

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

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

Schema coverage is 100% and the single parameter is fully documented ('Stock item id (from superfaktura_list_stock_items)'), so the baseline of 3 applies. The description adds no format or constraint detail beyond what the schema already 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+resource ('One warehouse item') and enumerates the returned fields (SKU, price, VAT, purchase price, quantity), which distinguishes it from the sibling superfaktura_list_stock_items by being singular. Sibling differentiation is implied by 'One' rather than stated explicitly, so it stops short of a 5.

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

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

The description offers no when-to-use or when-not-to-use guidance and never names superfaktura_list_stock_items as the alternative for browsing. The only routing hint ('from superfaktura_list_stock_items') lives in the schema's parameter description, not in the tool description itself.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the upstream endpoint (GET /bank_accounts/index) and the field set, which is modest extra context, but says nothing about pagination, result size, or whether the list is scoped to the authenticated company.

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 plus the raw endpoint path — front-loaded with the resource and free of filler. The endpoint string is arguably redundant with the tool contract, but it is short and harmless.

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

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

With no output schema, the description usefully compensates by naming the fields returned. For a no-param read-only list tool this is close to complete; only pagination/ordering behavior is left unstated.

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

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

The tool takes no parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; the enumerated return fields are a small bonus that belongs more to output 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 resource (the company's bank accounts) and previews the returned fields (bank name, IBAN, SWIFT, default flag), which is enough for an agent to distinguish it from superfaktura_list_bank_moves. No explicit sibling contrast, but the resource noun is unambiguous.

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

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

There is no when-to-use or when-not-to-use guidance, but for a zero-parameter read of a single well-defined resource the usage is largely self-evident from the name and description. A sentence noting it returns only the company's own accounts (vs. moves/transactions) would have earned more.

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

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

Annotations declare readOnlyHint=true, so safety is covered, and the description adds useful behavior beyond that: default sort order (newest first), pagination via next_page passed as page, and the underlying GET endpoint. This is solid added context for a read 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?

A single dense sentence with a parenthetical return-field list, front-loaded with the resource and its scope. It is appropriately sized and wastes little, though the parenthetical is busy.

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

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

With no output schema, the description usefully enumerates the return fields, and it covers default ordering, filtering dimensions, and pagination. For a 10-parameter read tool it is reasonably complete, though it could tie filter categories more explicitly to their params.

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 80%, so the schema documents most parameters; the description only loosely maps its filter categories (date range, credit/debit, amount) back to those params. With the schema already doing the heavy lifting, this meets the baseline rather than adding meaning beyond it.

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

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

States a specific verb (List) and resource (imported bank account moves/transactions) and enumerates the returned fields, so an agent knows exactly what it fetches. It does not explicitly distinguish itself from siblings like list_bank_accounts or list_stock_movements, but the resource is specific enough to avoid confusion.

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 listing the available filters (date range, credit/debit, amount) and how to page, which tells the agent how to narrow results. It offers no explicit when-to-use guidance or named alternatives, leaving selection context to inference.

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

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

The description restates the read-only nature already covered by readOnlyHint=true, but adds value by disclosing the returned fields and the underlying GET /cash_registers/getDetails endpoint. It does not cover pagination, result ordering, or what happens when no registers exist, so it is adequate rather than rich.

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

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

A single tight sentence with the resource and payload front-loaded. The trailing endpoint reference is mild noise but consistent with this API-shaped tool family and does not bury the key 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 parameterless list tool with no output schema, the description supplies the essential payload fields an agent needs to interpret the result. Only pagination and result-volume behavior are unaddressed, a minor 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?

The tool takes zero parameters, so the schema imposes no semantic burden and the baseline is 4. The description cannot add parameter meaning because there are none to explain.

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 resource (company's cash registers) and the data returned (currency, entry count, current balance). It reads clearly as a collection-listing operation and is distinguishable from the singular superfaktura_get_cash_register sibling, though the verb 'list' is only implied by the name 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?

No explicit guidance on when to use this versus superfaktura_get_cash_register or any other sibling. The list-vs-get distinction is left entirely to inference from the tool names, and there is no mention of prerequisites or when results would be empty.

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

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

Annotations only declare readOnlyHint=true, so the description carries the rest, and it does add real context beyond that: the exact set of searchable fields, the pagination workflow ('pass next_page as page'), the response content ('contact data and totals'), and the underlying endpoint. It does not cover ordering/sorting behavior beyond the direction param, but the additions are meaningful 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 short, front-loaded sentences that lead with what is listed before drilling into search fields and pagination. The trailing 'GET /clients/index.json' is marginal filler since the schema already carries the parameters, but nothing is padded or buried.

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

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

For a read-only, zero-required-param list tool with a fully documented schema and no output schema, the description covers purpose, filter semantics, and the pagination loop an agent must follow. It stops short of describing result shape or default sort field, but the essential call-correctly information is present.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters (page, search, per_page, direction, created_period, modified_period) including their enums and defaults; baseline is 3. The description's enumeration of searchable fields adds a little precision over the schema's vaguer 'names, numbers, e-mails ...', but the pagination hint largely restates what the page parameter description already says.

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 address book (clients and suppliers)') and clarifies that the resource spans both clients and suppliers, which is useful scoping. It implicitly separates itself from the singular superfaktura_get_client and the create variants via the 'list' verb, but never names an alternative, so sibling differentiation is inferential rather than explicit.

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

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

The mention that 'search matches name, IČO, DIČ...' implies when to supply the search parameter, and the pagination note implies when to use page/next_page, giving usable implied guidance. However, there is no explicit when-to-use or when-not-to-use statement, and no reference to the single-record superfaktura_get_client alternative for looking up one client.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds the returned field set (name, e-mail, phone) and the underlying GET endpoint, but says nothing about pagination, empty results, or rate limits.

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

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

Two short, front-loaded sentences with no filler; the resource and its returned fields come first. The trailing endpoint reference is slightly redundant but harmless.

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 does the needed work by enumerating the returned fields. For a single-parameter read-only lookup this is nearly complete; only pagination/ordering behavior is unstated.

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

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

Schema description coverage is 100% for the single client_id parameter, so the schema already carries the semantics. The description only echoes client_id via the URL template and adds nothing beyond it.

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

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

States a specific resource and scope: contact persons stored for one client, with the returned fields named. It is clearly distinct from the sibling add_contact_person (write) and list_clients, though it relies on the title for the 'list' verb.

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

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

No explicit when-to-use guidance or alternatives are given; the only signal is the implicit 'for one client' scoping. An agent must infer that this is the read counterpart to add_contact_person.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds the GET endpoint (/countries/index/view_full:1) and the shape of returned fields, but discloses no auth needs, rate limits, or edge behavior; modest added value over 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 carries purpose, content and use case without padding. The trailing endpoint path is somewhat implementation-detail bloat but does not obscure the meaning.

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

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

With no output schema, the description carries the return-value burden and does describe the key fields (id, ISO code, EU flag). For a zero-parameter lookup tool this is nearly complete, lacking only explicit format/ordering notes.

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 the baseline is 4. The description's mention of country_id refers to a downstream consumer field, not a parameter here, so there is nothing further to document.

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 countries) and enumerates the payload (country ids with ISO code and EU flag), so the agent knows exactly what it retrieves. It is implicitly distinguishable from list siblings, though it never names an 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?

States the concrete use case ('for the country_id of clients'), giving the agent clear context for when to reach for it. It offers no explicit when-not or named alternatives, 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?

With readOnlyHint=true already covering the safety profile, the description adds useful behavioral context by disclosing the return shape (a tree with id, name, parent), which matters because there is no output schema. It does not mention pagination, caching, or authentication 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 a single, front-loaded sentence that efficiently covers purpose and return fields. The appended raw endpoint 'GET /expenses/expense_categories' is arguably extraneous for an AI agent but does not harm readability.

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

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

For a zero-parameter read-only tool with no output schema, the description supplies the essential return structure and links the data to expense category_id values. It omits when-to-use guidance relative to sibling tools, but is otherwise adequate 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?

The tool takes zero parameters, so the baseline of 4 applies. The description mentions 'category_id of expenses' but this is not an input parameter of this tool, so no additional parameter meaning is 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 identifies the resource (expense category tree) and its returned fields (id, name, parent), and links it to the category_id used by expenses. It is clear enough to distinguish from sibling list tools, though it lacks an explicit action verb such as 'list' or 'retrieve'.

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

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

There is no explicit guidance on when to use this tool versus alternatives like superfaktura_list_expenses. Usage is only implied by the mention of 'category_id of expenses', leaving the agent to infer the 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?

With readOnlyHint=true already covering the safety profile, the description still adds non-obvious behavior: an implicit server-side default date window, the 'all' override, and the fact that paging continues by feeding next_page into the page parameter. No rate limits or account/permission notes, but the defaults disclosure is genuinely useful.

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

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

Densely front-loaded: resource definition first, then status semantics, then the default-period caveat and paging rule, ending with the endpoint. The status enum restatement is mildly redundant with the schema, but nothing else is wasted.

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

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

For a 13-parameter, zero-required search tool with no output schema, the description covers payload shape, default-window behavior, and paging continuation. Remaining filter semantics are handled by the high-coverage schema, so 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 coverage is 85%, so most parameters are self-documenting and the baseline would be 3. The description goes beyond it by spelling out the next_page -> page paging contract and restating status semantics, though it adds nothing for amount_from/amount_to, client_id, category_id or direction.

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/search) and resource (received documents = expenses: received invoices, bills, internal documents) and enumerates the payload fields returned (amounts, VAT, supplier, payment status). The 'received' framing implicitly separates it from superfaktura_list_invoices (issued invoices) and its get/create 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?

Gives real operational context: without a date filter SuperFaktura applies its default period, and created_period='all' is the escape hatch, plus how to page. It stops short of naming alternatives (e.g., use superfaktura_get_expense for a single record), 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 only supply readOnlyHint=true, so the description carries the behavioral load and does it well: it warns that without a date filter only the CURRENT year is returned, points to created_period='all' as the escape hatch, and explains pagination via next_page. It could go further on result caps or ordering defaults, but the key trap an agent would otherwise fall into is disclosed.

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 purpose, then the two highest-risk behaviors (default year scope, pagination), then enum decoding, then the endpoint. It is dense and occasionally list-like ('VS ...'), but nearly every clause carries actionable information and nothing is padded.

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

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

With 16 optional parameters, no required fields and no output schema, the description supplies the scoping caveat, the pagination contract and the enum interpretations an agent needs to call it successfully. It does not describe return payload shape or default result ordering, but the response contents are at least summarized in the opening sentence.

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 a 3 is the baseline; the description goes beyond it by decoding enum semantics the schema only lists as strings (estimate = quote, cancel = credit note, reverse_order) and by explaining that 'several allowed' for type. It also clarifies search fields and the next_page-to-page pagination handoff, adding meaning not present in the raw property text.

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 issued documents) plus what each record carries (client, items, totals, payment status), which distinguishes it cleanly from superfaktura_get_invoice and the other list_* siblings. An agent knows immediately this is the paginated collection endpoint for invoices, not a single-document 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?

Gives real selection guidance: how the type parameter routes between ordinary invoices, proformas, quotes, credit notes, etc., how status narrows by payment state, and what search matches. It also names a sibling (superfaktura_list_clients) for obtaining client_id. It stops short of an explicit when-not-to-use statement (e.g., prefer get_invoice for a known number), so it lands at 4 rather than 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?

With readOnlyHint=true already declaring the safety profile, the description adds genuinely new context by detailing what the call returns (id, name, mask, next formatted number, default flag) and how the returned ids feed downstream document creation. It omits pagination or auth details, but for a parameterless read against annotated metadata 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?

A single, front-loaded sentence covering resource, returned fields, and downstream purpose with no padding. The trailing raw endpoint (GET /sequences/index.json) is implementation detail that adds little for an agent, slightly diluting an otherwise tight definition.

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

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

For a zero-parameter, read-only tool with no output schema, the description supplies what annotations and schema cannot: the shape of the returned sequence records and their role in document creation. Only minor gaps remain (no pagination/ordering note), which are unlikely to affect 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?

The tool takes zero parameters, so the baseline is 4. The description correctly implies no filtering or required inputs, and the schema coverage is 100% with an empty properties object — nothing additional is needed or missing.

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 precise resource — document numbering sequences per document type — and enumerates the returned fields (id, name, mask, next formatted number, default flag), which clearly separates it from sibling list tools like superfaktura_list_invoices or superfaktura_list_tags. The listing verb is carried only by the name/title rather than the description text, so it falls just short of a self-contained verb+resource statement.

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?

"Sequence ids are used when creating documents" implies the reason to call the tool (fetch ids before document creation), but it is phrased as a fact about the data rather than an explicit when-to-use instruction. No alternatives or exclusions are named, so an agent must infer the workflow on its own.

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

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

readOnlyHint=true already covers the safety profile, so the description's added value is pagination mechanics ("Paged: pass next_page as page") and the shape of returned records. That is genuine context beyond the annotations, though it omits any note on auth scoping or default 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?

Three dense sentences with no filler: resource and returned fields first, then search semantics, then paging, then the endpoint. Nothing needs to be re-read.

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 describing returns, and it does list the record fields plus the next_page pagination token. It stops short of describing the response envelope or paging limits, but an agent has enough to call and consume the tool 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 75%, so the baseline is 3. The description clarifies that the search term covers name/SKU/description, but price_from, price_to, direction, and in_stock_only receive no added meaning beyond their schema entries, and the sku clause merely restates the schema's "Search by SKU."

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 warehouse items") and enumerates the returned fields (name, SKU, unit, price, VAT, quantity in stock), which clearly separates it from the singular superfaktura_get_stock_item and from superfaktura_list_stock_movements. An agent can route to it without opening the schema.

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

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

It explains the two search entry points ("search matches name, SKU and description; sku matches the SKU") and hints at paging, so usage is implied. But it never states when to prefer this list tool over get_stock_item or list_stock_movements, and gives no exclusions or prerequisites.

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

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

readOnlyHint=true already covers the safety profile, so the description's added value is the disclosure that results are paged and what the log entries contain (quantity changes, notes, related invoice or expense). It stops short of describing ordering guarantees beyond the schema's direction enum or any 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?

Three terse clauses: the resource and its payload, the paging mechanic, and the backing endpoint. Zero filler and the identifying content 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?

With no output schema, the description carries the burden of hinting at return content and does so by naming entry types; paging is also addressed. It is complete enough for a four-parameter read tool, though a note on ordering of the log would round it out.

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

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

Schema description coverage is 100% and every parameter (page, per_page, direction, stock_item_id) is already documented in the schema, so the baseline applies. The description's pagination remark largely restates the schema's own 'Use next_page from the previous reply' text.

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 ('stock log of one item') and enumerates what the log contains (quantity changes, notes, related invoice or expense), which cleanly separates it from the sibling superfaktura_list_stock_items.

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

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

The description gives a concrete procedural hint for paging ('pass next_page as page'), which is real usage guidance, but it never states when to reach for this tool versus list_stock_items or the get_stock_item sibling, and offers no prerequisite or exclusion conditions.

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

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

readOnlyHint=true already tells the agent this is a safe, non-mutating read, so the bar is lower. The description adds that results carry id and name fields, but says nothing about ordering, pagination, or whether the list is account-scoped.

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 substantive content (what the tags are and where they apply) front-loaded before the endpoint string.

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 and no parameters, the description usefully compensates by declaring the returned shape (id and name). It is close to complete for a trivial list tool; only ordering/pagination behavior is unstated.

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

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

The tool takes zero parameters, so the baseline is 4; there is no parameter surface for the description to document or to omit.

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 the resource (tags) and states the payload returned (id and name) plus where tags apply (invoices, expenses, clients). It is clearly a read of tags, but it never explicitly contrasts itself with the sibling superfaktura_create_tag or other list_* tools, so sibling differentiation is left implicit.

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

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

There is no when-to-use statement, no prerequisites, and no mention of alternatives such as superfaktura_create_tag. Usage is only inferable from the resource name, which is the minimum implied context.

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