Oblio MCP by usefulapi

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

With destructiveHint=true and idempotentHint=false already declared, the description still adds real value: the cancelled invoice remains in the series but becomes void, the external SPV side-effect must be checked separately, and the call is not retried. It doesn't say whether the cancellation can be undone via oblio_restore_document, which is the main remaining gap.

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 capitalised verb and scope, then behavioural consequences, requirements and endpoint in four tight sentences with no filler. The endpoint path is marginally 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?

For a destructive, open-world mutation with no output schema, the description covers the resulting state, the confirmation gate, and the external SPV consequence — enough for an agent to act safely. Failure behaviour and reversibility (restore availability) are the only unstated pieces.

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 cif, series_name, number and confirm all documented in the schema (including the confirm-after-approval rule). The description only restates the confirm:true requirement and the type values, adding little beyond structured data, 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 (CANCEL) plus the exact resource set (invoice, proforma, notice) and even the underlying endpoint. An agent can distinguish this from siblings like oblio_restore_document or oblio_get_document without opening any schema.

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

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

Gives clear context: confirm:true plus explicit user approval is required, and if the document already reached e-Factura/SPV the agent should check the SPV side. It does not name the inverse alternative (oblio_restore_document) or state when not to cancel, so it stops short of a full when/when-not routing rule.

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 destructiveHint=true and idempotentHint=false, but the description adds real context: what actually changes (the invoice's paid status), that the change 'is not reversible from the API', and that a confirm:true gate plus explicit user approval of the amount is required. It does not cover failure behavior or permission requirements, so it stops short of a 5.

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

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

Three short sentences, front-loaded with the action and its effect, followed by prerequisites and the endpoint. Nothing is padding and no sentence merely restates the tool name.

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

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

For a destructive, non-idempotent mutation with a nested collect object and no output schema, the description covers effect, irreversibility, and the confirmation requirement. It leaves some gaps (permission/auth needs, what a failed or partial collection returns), but nothing that would cause an agent to invoke it incorrectly.

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 80%, so the baseline is 3. The description reiterates the confirm:true gate and parenthetically lists payment channels (receipt, bank order, card) that map to the collect.type enum, but it adds no syntax, defaults, or constraints beyond what the schema already documents.

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?

It names a specific verb and resource ('Record that an issued invoice was paid') and even pins the endpoint (PUT /api/docs/invoice/collect). That is clearly distinct from sibling actions like oblio_issue_invoice, oblio_cancel_document, and oblio_restore_document, so an agent can select 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 states hard preconditions for use: 'Needs confirm: true and the user's approval of the amount' and 'Not retried'. That is clear context for when to call it, but it never names an alternative or a when-not condition (e.g., partial vs. full collection, or how it differs from cancel/restore), so routing is 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?

Annotations already mark this destructive/non-idempotent, and the description adds real context the annotations cannot convey: the number is consumed immediately, there is no draft state, no e-mail is sent, and the response shape (series, number, PDF link) is described. The retry caveat is exactly the operational detail an agent needs for a non-idempotent write.

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 critical distinction (proforma vs fiscal invoice) first, then behaviour, then prerequisites, then return, then failure handling. Six short clauses, each carrying unique information; nothing is padding.

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 16-parameter, nested-object write tool with no output schema, the description covers purpose, prerequisites, side effects, return content and error recovery. The only unaddressed element is the optional idempotency_key, which the 94%-covered schema documents on its own.

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 94%, so the schema carries the parameter burden and the baseline is 3. The description adds no per-parameter meaning beyond steering the agent to the VAT-rate and series lookup tools, which is useful routing but not parameter documentation.

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 ("Create a PROFORMA") with an immediate disambiguation from the sibling it is not ("not a fiscal invoice"). The "preferred first step" framing tells an agent where this sits relative to oblio_issue_invoice 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?

Explicit prerequisites are named with the exact sibling tools to call first (oblio_list_vat_rates, oblio_list_series, plus client/lines checks), and retry behaviour is stated: "Not retried: if the reply is an error, look in Oblio before repeating." This is when-to-use, what-to-prepare, and when-not-to-retry in one compact block.

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 cover the mutation/destructive/openWorld profile, and the description adds genuinely new behavioral detail: account data will be POSTed to the URL, the receiver must complete a base64 X-Oblio-Request-Id handshake with a 200, and confirmation is mandatory. It stops short of describing success response or what happens on repeated subscriptions, but it earns credit for going well beyond the annotation set.

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: purpose, security/behavioral requirements, and the confirm gate, with the HTTP route appended for grounding. Everything is front-loaded and 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 destructive, non-idempotent, open-world mutation with no output schema, the description supplies the safety preconditions, receiver contract, and confirmation requirement an agent needs. Minor gaps remain around return value and duplicate-subscription behavior, though the idempotentHint=false annotation partially covers the latter.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic grouping to the topic enum by naming the event families (stock, drafts, updates, cancellations, collections) and reinforces the user-confirmation gate on confirm. The cif and endpoint parameters are left to the schema.

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

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

States a specific verb (subscribe/create) and resource (an HTTPS endpoint receiving Oblio events), and enumerates the event families covered (stock changes, draft/update/cancel of documents, collections). An agent can immediately distinguish this from oblio_list_webhooks and oblio_delete_webhook without opening schemas.

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 preconditions: the endpoint must be user-named and user-controlled, must return 200 with the base64 of X-Oblio-Request-Id, and the call requires confirm: true. It does not, however, name alternatives such as listing existing webhooks first or deleting duplicates, so the routing guidance is partial.

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 destructiveHint=true and idempotentHint=false, so safety is covered. The description adds two behavioral facts not in the annotations: that a second, user-confirmed call (confirm=true) is required and the underlying DELETE endpoint. It doesn't spell out irreversibility explicitly, but the annotations plus this context are solid.

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, front-loaded with the action and id source, followed by the confirmation requirement and endpoint. No filler sentences; every fragment earns its place.

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

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

For a two-parameter destructive DELETE with full schema annotations and no meaningful return payload, this is essentially complete. A sentence on irreversibility or failure modes would round it out, but nothing required to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so both parameters (id and confirm) are already documented in the schema, including the confirmation protocol. The description restates both without adding format or edge-case detail, 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 ("Delete a webhook subscription") and names the sibling tool that produces the required id (oblio_list_webhooks), which separates it cleanly from oblio_create_webhook and oblio_list_webhooks.

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 preconditions: obtain the id from oblio_list_webhooks and set confirm to true only after user confirmation. It stops short of stating when NOT to delete or what alternatives exist (e.g. disabling a subscription), so it is not 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?

readOnlyHint=true already tells the agent this is a safe read. The description adds useful return-content context (type, series, number, PDF link, collections for invoices), which partly compensates for the missing output schema, but says nothing about auth, error behavior, or what a missing document returns.

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

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

Two tight sentences, front-loaded with what the tool returns and the keying scheme. The trailing raw endpoint 'GET /api/docs/<type>' is marginally useful but is the only slightly extraneous element.

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 steps in to summarize the returned fields (type, series, number, PDF link, collections). Combined with 100% schema coverage and a readOnly annotation, an agent has enough to invoke it correctly, though usage routing remains thin.

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

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

Schema coverage is 100%, so every parameter is already documented with examples and formats. The description merely echoes type/series/number without adding format, syntax, or edge-case detail beyond the schema, making the baseline 3 correct.

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

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

States a specific verb-and-resource: retrieves ONE invoice, proforma or notice identified by series and number. The singular framing implicitly contrasts with the list-oriented siblings (oblio_list_invoices), but no sibling is named 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 says how the document is keyed but never states when to use this tool versus oblio_list_invoices or the create/cancel/restore siblings. No prerequisites or exclusions are given; the only routing hints (oblio_list_companies, oblio_list_series) live 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?

Annotations already flag destructive=true and idempotent=false, but the description adds substantial context beyond them: no draft state, no post-issue editing, irreversible number consumption, cancellation-only recovery, optional ANAF e-Factura/SPV transmission, and no client e-mail. These are exactly the consequences an agent needs before firing an irreversible fiscal write.

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?

It is a dense single paragraph, but it is front-loaded with the action and irreversibility, followed by prerequisites and behavioral caveats in a sensible order. Nearly every sentence earns its place, with only mild redundancy between the narrative and the schema's own notes.

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 22-parameter, nested, irreversible write with no output schema, the description covers the critical safety context (confirmation, idempotency, irreversibility, retry handling, e-mail behavior) that the schema cannot express. It does not describe what a successful response contains or how errors are surfaced, but the essentials for correct invocation are 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 22 parameters in depth. The description restates a few high-signal ones (confirm, idempotency_key, reference_document, collect, delivery_date) but adds no syntax, format, or constraint detail beyond what the schema carries. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description opens with a specific verb and resource ("ISSUE a real INVOICE") and immediately characterizes it as a legal fiscal document that consumes the next number in the series. It implicitly distinguishes itself from sibling document tools (proforma creation via reference_document, cancellation, separate collection) so an agent knows this is the finalizing step, not a draft.

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 concrete prerequisites (confirm:true, idempotency_key, explicit user approval) and a clear safety rule (not retried; inspect Oblio before repeating), plus that no e-mail is sent. It implies the cancellation path and the optional collect step, but it never names the sibling tools (oblio_cancel_document, oblio_collect_invoice) as the alternatives for those flows, so it falls short of a full when-to-use/when-not matrix.

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 genuinely new behavioral context: the 250-per-page cap and the next_offset paging contract, plus the underlying endpoint. It does not describe the response shape, but that is a minor gap 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?

Two short sentences with the resource stated first and pagination second; the endpoint is tagged on at the end. No filler.

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

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

For a read-only, fully-schematized list tool this covers the essentials: what is returned (clients of a company), how to filter, and how to page. Only the absence of any hint about the sibling list tool keeps it from a 5.

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

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

Schema description coverage is 100%, so every parameter (cif, name, offset, client_cif) is already documented in the schema, including the next_offset paging hint. The description adds only a paraphrase of that same information, 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 (clients of a company) and the filtering options, and the title confirms the list/search action. It does not explicitly distinguish itself from the adjacent oblio_list_companies sibling, 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?

Usage is implied rather than stated: filter by name or client CIF when searching, page with next_offset. There is no explicit when-to-use-vs-alternative guidance and no mention of the oblio_list_companies companion tool.

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

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

The readOnlyHint annotation already establishes the safe-read profile. The description adds valuable context beyond that — the returned fields, the GET endpoint, and its role as a prerequisite for other tools — but it does not mention authentication or pagination 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?

Three compact elements — resource with fields, first-call guidance, and endpoint — with no wasted words. The most useful information is front-loaded.

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

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

For a no-parameter, read-only list tool with no output schema, the description supplies what the agent needs: the resource, returned fields, endpoint, and its dependency role. Nothing essential is missing.

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

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

The tool takes no parameters, so parameter semantics are not applicable. Per the rubric, zero parameters gives a baseline of 4.

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 the resource — companies linked to the connected Oblio account — and names the returned fields (CIF, name, access level). It clearly identifies what the tool retrieves, though it lacks an explicit action verb and does not explicitly contrast itself with 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?

It gives strong usage context: 'Good first call: every other tool needs a CIF from here.' This tells the agent exactly when to invoke it and why, but no when-not-to-use condition is provided.

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

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

Annotations only declare readOnlyHint=true, so the safety profile is already covered. The description adds genuinely useful behavior beyond that: results are newest-first by default, pagination is driven by next_offset, and products/collections/e-Factura status are opt-in payload expansions that change response weight. It omits any note on rate limits or result-count caps, 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 sentences, front-loaded with the resource and filter scope, then defaults, then the pagination contract. The parenthetical filter list is dense but each clause corresponds to real parameters. The trailing endpoint URL is marginal but cheap.

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

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

For an 18-parameter paginated list tool with no output schema, the description covers the two things an agent most needs: how ordering defaults and how to page using next_offset from the previous reply. It doesn't state the response envelope or total-count behavior, which matters when there is no output schema, but overall it is sufficient 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 coverage is already 89% and the schema documents the toggles precisely (draft = only drafts vs only issued). The description still adds value by grouping the 18 parameters into filter families and mapping the optional flags (with_products, with_collects, with_einvoice_status) to what they actually enrich in the reply. Slightly above the baseline-3 case for high coverage.

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 resource (invoices), scopes it to a company, and enumerates the filter families (series, number, dates, client, draft/canceled/collected). An agent can distinguish it from oblio_list_clients/oblio_list_products and from oblio_get_document (single document) by resource alone. It stops short of explicitly contrasting with those siblings, so a 4 rather than 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 operational guidance for pagination ('Pass next_offset as offset for the next page') and the default ordering, which is real usage help. However, there is no explicit when-to-use statement or exclusion — nothing tells the agent to prefer oblio_get_document for a single invoice or when a filter combination is pointless. Usage is implied by the resource name 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=true, and the description only restates the HTTP verb via 'GET /api/nomenclature/languages', which adds little. It does usefully disclose the return shape (code, name), which the missing output schema would otherwise leave unknown.

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 tight sentence plus a short endpoint reference; the resource scope and return fields are front-loaded. The raw endpoint path is slightly redundant with the name/annotations but remains 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 simple read-only nomenclature lookup with full schema coverage, the description covers what the tool returns (code, name pair) and what it represents, compensating for the absent output schema. Only explicit usage guidance is missing.

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

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

Schema description coverage is 100% and the single cif parameter is fully documented there, including its source (oblio_list_companies) and format. The description adds no parameter-level 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: 'foreign languages a company can issue documents in', plus the returned fields (code, name). It is clearly distinguishable from sibling list tools such as oblio_list_vat_rates or oblio_list_series, 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?

The phrasing 'languages a company can issue documents in' implies the use case (selecting a language when issuing a document), but there is no explicit when-to-use statement, no prerequisites, and no mention of alternatives. Usage is inferable 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=true, so the safety profile is covered. The description adds genuine behavioral context beyond that: the stock-enabled precondition (a gating condition the agent must know) and the fact that returned managements carry a work point and type. It does not mention pagination, but for a simple nomenclature list 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 compact sentence with the resource and precondition front-loaded, followed by the endpoint for orientation. No filler, though the endpoint reference is marginally redundant for an agent choosing a tool.

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

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

No output schema exists, and the description compensates by naming the returned fields (work point and type) and the stock-enabled precondition. Together with a fully documented single parameter and a readOnly annotation, an agent has enough to call this correctly; only return-shape details like count or ordering are absent.

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

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

Schema description coverage is 100% for the single required 'cif' parameter, and the schema already explains where CIF comes from (oblio_list_companies) with a format example. The description adds nothing about the parameter, so the baseline 3 for high schema coverage is correct.

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

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

States a specific verb+resource: listing stock managements (gestiuni) for a company, and includes the local Romanian term plus the underlying endpoint GET /api/nomenclature/management. It is clearly distinguishable from all siblings, which cover documents, clients, invoices, webhooks and other nomenclatures, though it does not explicitly name a sibling it differs from.

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 one real precondition — 'works only when stock is enabled' — which tells the agent when the tool is applicable. However, it offers no guidance on alternatives or what to do when stock is disabled, and there is no explicit when-to-use framing beyond that gate.

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-only profile, and the description adds genuinely useful behavior beyond it: page size (250), the next_offset-as-offset paging convention, and the set of fields returned. That is real added context for a list endpoint, though it stops short of describing sort/filter interaction.

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

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

Two compact sentences plus the endpoint reference; the resource and its attributes are front-loaded with no filler. The first sentence is only lightly fragmentary but still earns its space by summarizing return fields.

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

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

For a read-only list tool with full schema coverage and no output schema, the definition covers the resource, the attributes returned, and pagination. It does not explain sorting or how filters combine, but nothing critical 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 description coverage is 100%, so all seven parameters are already documented in structured fields. The description's pagination note ('Up to 250 per page: pass next_offset as offset') largely repeats what the offset schema text already states, so it adds little beyond the schema 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?

The description names a specific resource (products and services of a company) and enumerates the returned fields (unit, price, VAT, stock quantities), which clearly distinguishes it from siblings like oblio_list_clients or oblio_list_invoices. It lacks an explicit action verb (list/search) in the body text, relying on the title for that, so it falls just short of the top tier.

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

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

There is no when-to-use or when-not-to-use guidance and no explicit mention of alternatives. The only routing hints ('see oblio_list_management', 'from oblio_list_companies') live in the schema, not the description, so an agent gets no narrative steering here.

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

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

readOnlyHint=true already covers the safety profile, so the bar is lower; the description still adds value by disclosing the returned object's shape (type, name, start, next number, default) and the underlying endpoint. It does not mention pagination, auth requirements, or rate limits, keeping it short of a 5.

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

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

Very compact: the resource and its fields are front-loaded, followed by a terse usage tip and the GET path. No filler, though the parenthetical field list is dense and 'Use the name as series_name' is slightly cryptic out of context.

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-only lookup with annotations covering safety and no output schema, the description compensates by listing the returned fields. Missing only minor details such as what 'default' and 'next number' signify or whether the result is paginated.

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 cif parameter is already explained (format plus example RO37311090 and its source from oblio_list_companies). The description adds nothing about the 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?

The description names a specific resource ('Document series of a company') and enumerates the fields it carries (type Factura/Proforma/Aviz, name, start, next number, default), so an agent knows exactly what it retrieves. No sibling lists series, so there is no real ambiguity, though the description doesn't explicitly differentiate itself from 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?

Usage is only implied: you call it to inspect a company's series definition. It gives one actionable workflow hint ('Use the name as series_name'), but no explicit when-to-use, prerequisites, or alternatives for other lookups.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description contributes the return field set and the underlying GET path, which is useful, but says nothing about pagination, result size, or whether an unknown CIF errors or returns empty.

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 compact sentence with the resource and return fields front-loaded, followed by the endpoint. No filler, though the trailing HTTP path is marginal value for an agent that only needs the tool contract.

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 parenthetical field list is the only disclosure of return shape and it is included. For a trivial one-parameter read tool this is close to sufficient; only error/empty behavior is unaddressed.

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%: the single cif parameter is fully documented in the schema, including a pointer to oblio_list_companies and a concrete example. The description adds nothing about the 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?

Names a specific resource (VAT rates) and enumerates the salient returned fields (name, percent, default), so the agent knows exactly what comes back. It doesn't explicitly contrast with a sibling, but the resource is unambiguous within the oblio_list_* family.

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

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

"use the name and percent on document lines" gives implied usage context — you fetch these to populate document lines — but there is no statement of when to call this versus another lookup, nor any prerequisite or exclusion beyond the CIF requirement.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the HTTP endpoint (GET /api/webhooks) and, more usefully, the shape of what comes back (id, CIF, topic, endpoint), which matters since no output schema exists. Pagination and ordering behavior are still unstated.

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 with no filler, and the resource scope is front-loaded before the endpoint reference. The phrasing is telegraphic rather than fully formed prose, but nothing needs to be cut.

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 list tool with no output schema, the description supplies the essentials: what is returned, at what scope, and via which endpoint. Only pagination/result-size behavior is missing, which is minor at this complexity.

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 per the rubric. The description correctly implies no inputs are required; there is nothing to document beyond that.

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 the specific resource ('webhook subscriptions of the account') and even enumerates the returned fields (id, CIF, topic, endpoint), which cleanly separates it from create_webhook and delete_webhook in the sibling list. The listing verb is only implied by the title rather than stated in the description, which keeps it 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?

The scope ('of the account') implies the usage context, and no filtering or prerequisites exist for a zero-parameter list. However, there is no explicit when-to-use statement or mention of alternatives, so 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 destructive=true, idempotent=false and readOnly=false. The description adds real value beyond them by disclosing the human-approval gate, the mandatory confirm flag, and that the call is not retried (reinforcing non-idempotency). It stops short of explaining exactly what state change occurs or what the response contains.

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 the purpose and followed by the critical precondition and a compact endpoint reference. No filler, and the safety-critical requirement is not 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 destructive fiscal operation with no output schema, the definition covers the key prerequisites (cancelled state, confirm, user approval) and the endpoint. It omits what the restored document looks like afterward and any dependent effects, a minor gap given annotations already flag destructiveness.

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 five parameters including the confirm semantics. The description's 'Needs confirm: true' restates schema content rather than adding new parameter meaning; baseline 3 is appropriate when the schema carries the load.

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 ('Restore') and resource (CANCELLED invoice, proforma or notice), including the required precondition that the document be cancelled. An agent can distinguish this from oblio_cancel_document, its inverse sibling, without opening any schema.

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

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

Gives clear conditions for invocation: the document must be cancelled, confirm must be true, and the user must have approved. It does not explicitly name the alternative (oblio_cancel_document) or state when not to use it, which keeps it short of a 5.

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

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

Goes well beyond the annotations: it discloses irreversibility (an accepted document cannot be withdrawn), that the operation is not retried, the confirmation requirement, and the meaning of each return code (-1/0/1/2). The annotations only flag destructive/non-idempotent; the description explains the practical consequences.

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?

Dense but zero-waste: purpose, irreversibility warning, prerequisite, retry guidance, and return codes are all front-loaded in four short sentences. Every clause 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 compensates by explaining the return payload (text, sent, and the code values). Combined with the endpoint and safety caveats, an agent has everything needed to call and interpret this 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 100%, so cif, number, series_name and confirm are already fully documented in the schema. The description restates the confirm requirement but adds no syntax or format 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 (SEND) and resource (issued invoice to ANAF e-Factura/SPV), plus the underlying endpoint POST /api/docs/einvoice. It is clearly distinguishable from siblings like oblio_issue_invoice or oblio_cancel_document.

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

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

Explicitly states the precondition (confirm: true plus the user's approval), the when-not-to-retry rule, and names the alternative oblio_list_invoices with with_einvoice_status for checking status before repeating. Nothing about routing is left to inference.

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