Factusur

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

Annotations only cover safety and idempotency; the description adds the quota accounting semantics ('TOUT OU RIEN', nothing deducted on quota_exceeded), the error code, the batch_id resume path, the returned per-invoice state plus signed ZIP link, and a prompt-injection warning about untrusted invoice content. That is substantial disclosure beyond structured fields.

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

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

Purpose and hard limits are front-loaded, and the untrusted-content warning is correctly placed at the end where it is not buried mid-sentence. The parenthetical 'mêmes règles que le lot du site' is the one soft spot — it references an external context the agent cannot verify.

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 annotations and an output schema present, the description covers what the output schema cannot: quota accounting rules, partial-failure semantics and resume. Only the error-recovery path beyond quota_exceeded (e.g. partial validation failures) 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 coverage is 75%, so the schema already documents most parameters. The description still adds meaning to two of them: the 20-item cap and 'lot' grouping for sources, and the resume behavior behind batch_id. accept_terms and idempotency_key are left to the schema alone.

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: 'Convertit jusqu'à 20 factures en un lot', and immediately bounds the scope with the quota rule. An agent can distinguish this from the single-invoice sibling convert_to_facturx by the explicit 'lot' framing, though that sibling is never named.

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

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

It gives concrete operating conditions: all-or-nothing unlocking, quota limiting, spreadsheet splitting, and resume via { batch_id }. However, it never states when to prefer this over convert_to_facturx or create_upload_url, so the routing decision is left implicit.

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: quota is consumed per successful conversion exactly as on the site, an idempotency_key replay costs nothing, downloads are signed for 15 minutes single-use, and it warns that invoice content is untrusted third-party data that must not be followed as instructions. That is exactly the side-effect and security context the annotations can't express.

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 outcome and return values, then progressively narrower constraints. It is a single dense paragraph and could be broken into bullets, but almost every clause (quota, idempotency, needs_input, injection warning) carries real decision value.

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

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

For a 3-param tool with a deep nested schema and an output schema, the description covers the operational lifecycle (submit, resume, quota, downloads) without re-documenting return values. Omissions are minor: legal acceptance via accept_terms and the create_upload_url handoff are only partially surfaced.

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 67% schema coverage, the description usefully explains the four mutually exclusive `source` variants (base64 file, upload_id, structured invoice with no AI reading, or resuming a conversion_id) and the 3 Mo ceiling. It says nothing about accept_terms beyond the schema's own text, so it does not fully cover the remaining third.

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+standard: "Convertit UNE facture en PDF Factur-X (EN 16931)" and immediately enumerates the outputs (état, rapport de contrôle, quota restant, liens signés). The capitalized "UNE" distinguishes it from the batch_convert sibling without naming it.

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

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

Explicitly routes the agent: use create_upload_url for files over 3 Mo, use update_conversion when status is needs_input, and the payment link on quota_exceeded is human-only. It never says when to prefer batch_convert over this tool, so the sibling boundary is only implied by "UNE".

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 the non-read-only, non-idempotent profile; the description adds the traits that actually matter operationally: single-use URL, 10-minute expiry, minimum 3 MB, maximum 10 MB / 10 pages, and that the upload is performed out-of-band via HTTP PUT. Those constraints are not derivable from the annotations or schema.

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

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

Four sentences, front-loaded with what is created and its limits, then the mechanics, then the downstream handoff, then formats. No filler and no repetition of the tool name or title.

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

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

For a two-parameter tool with an output schema and annotations, the description covers everything an agent needs: how to obtain the URL, how to upload, size/format/expiry constraints, and what to do next. Return values are correctly left to the output schema.

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

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

Schema coverage is 100%, so the schema already documents both fields and the purpose enum, establishing a baseline of 3. The description goes further by tying the two enum values to concrete file-format rules (conversion vs. Factur-X verification), which gives the purpose parameter real decision meaning.

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

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

The description names a specific verb and resource ("Crée une URL de téléversement à usage unique") and immediately scopes it with lifetime and size limits. It is clearly differentiated from the sibling conversion tools by framing itself as the prerequisite upload step whose upload_id feeds convert_to_facturx, batch_convert or validate_facturx.

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 exactly what to do with the result (HTTP PUT with the given Content-Type, then pass upload_id to one of three named siblings) and gives per-purpose eligibility rules: PDF/JPG/PNG/XLSX/CSV for conversion, PDF only for validation. The exclusion "Aucune URL distante n'est acceptée" explicitly rules out an approach an agent might otherwise try.

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 read-only, idempotent, non-destructive behavior, but the description adds substantive traits: download links are freshly signed on each read, and no quota is consumed ("aucun décompte"). It also carries a prompt-injection warning that invoice text is untrusted third-party data, which is exactly the kind of safety context annotations cannot express.

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

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

Front-loaded with the core action and return highlights, followed by the untrusted-data caveat. The first sentence is dense but every clause contributes; 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?

An output schema exists, so return values need not be spelled out, yet the description still flags the most decision-relevant outputs (status, correction points, fresh links). With the injection warning and quota note, nothing an agent needs in order to call it safely 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 0%, so the description must compensate, and it does name both parameters and their referents (conversion vs batch). It still leaves open whether the two IDs are mutually exclusive or whether one is required, which the schema leaves unspecified too.

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: reads the state of a conversion or batch, and enumerates what it returns (status, control report, points to correct, download links). The single-vs-batch distinction is clear, but it never names the sibling it exists alongside (list_conversions, update_conversion), so differentiation is inferred 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?

Explains that the tool is keyed by either conversion_id (one conversion) or batch_id (a lot of the account), which gives an agent concrete selection context. It stops short of explicit when-not guidance or naming list_conversions as the route for discovering IDs.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the trailing "Lecture seule" is redundant rather than additive. The only extra behavioral fact is that the returned example uses fictitious data, which is useful but thin; with annotations carrying the safety profile, the lower bar is met at a 3.

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, no preamble, front-loaded with the primary return value (the schema) followed by the secondary artifacts and the read-only reassurance. Nothing could be removed without losing information.

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

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

With an output schema present, the description needn't detail field-level return values, and annotations cover safety, so the essentials are in place. The one gap is that the chaining mechanics are asserted rather than explained (whether the schema is passed to convert_to_facturx or merely consulted), leaving a small amount of inference.

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, which is the baseline-4 case, and the description correctly implies a parameterless call. The « invoice » token belongs to convert_to_facturx's parameter, not this tool's, so it adds chaining value rather than parameter semantics here.

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 concrete verb ("Renvoie") and enumerates exactly what comes back: the invoice JSON schema, a valid example with fictitious data, and Excel/CSV template links. It also names the sibling it pairs with (convert_to_facturx, source « invoice »), so an agent can tell it apart from the other get_*/validate_* tools without opening a schema.

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

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

Explicitly positions the tool as the input-side companion to convert_to_facturx and pins the required source value (« invoice »), which is genuine when-to-use guidance. It stops short of when-not-to-use (e.g. that it returns nothing conversion-specific and validate_facturx must run afterwards), so it is clear context rather than full routing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so 'Lecture seule' merely restates them. The description adds a list of returned data points, but with an output schema present that content is largely duplicated rather than adding behavioral context such as freshness or cost of the call.

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 enumerating the payload, followed by the read-only note; no filler. The comma-separated enumeration is dense but each item 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 zero-argument read tool with full annotation coverage and an output schema, the definition is sufficient to call it correctly. Only the absence of an explicit usage trigger keeps it from being complete.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing the description needs to compensate for. It also implies the scope is the authenticated user only, which is a useful semantic hint for a param-free tool.

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 concrete resource — the user's plan plus conversion consumption, quota renewal date, MCP safety limits and a recommended plan — which is clearly distinct from the conversion-specific siblings. It never explicitly says 'get' or names an alternative, but the enumerated payload makes the tool's identity 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 explicit when-to-use statement, no prerequisites and no named alternative. Usage is only implied (check quota/plan before spending conversions), and 'Lecture seule' is the sole operational signal.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely new behavioral context: entries are ordered newest-first and file attachments are purged per retention policy while a minimal history persists. That warning is valuable because it tells the agent older rows may be incomplete. It stops short of describing pagination mechanics.

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: what is listed and in what order first, the retention caveat second. Nothing is redundant, though the retention sentence could have been folded in more compactly.

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?

An output schema and annotations exist, so return shape and safety need no explanation here. However, for a paginated list tool the description omits how to page (limit + before cursor) and that limit caps at 50, leaving the agent to reverse-engineer the loop from the schema alone.

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

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

Only 'before' is described in the schema (as the cursor from the previous page's next_before); 'limit' has no description anywhere and the description never mentions either parameter. With 50% schema coverage, the description should compensate but contributes nothing about paging or page size.

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 ('Liste les conversions du compte'), plus the ordering (plus récente à la plus ancienne) and the visible fields (n° de facture, initiales, statut, conformité). It implicitly separates itself from get_conversion (single) and the conversion-creation siblings, but never names them.

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?

Listing history makes the use case inferable, but there is no explicit 'use this when' or a mention of get_conversion for single-record lookup, nor any note about when the retention-truncated history is insufficient. Usage is implied rather than stated.

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

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

Annotations already declare readOnly=false, idempotent=true, destructive=false, so the safety profile is partly covered; the description adds what the annotations cannot: totals are recalculated after the edit, null clears a field, and certain field edits spawn a new conversion rather than mutating in place. The prompt-injection warning that invoice content is third-party UNTRUSTED data is substantive behavioral context for a write 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?

The core action, the path syntax and the follow-up call are front-loaded before the caveats, and each sentence carries a distinct operational fact. The final security sentence is long, but it encodes a genuine risk instruction rather than 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 3-parameter mutation tool with a nested free-form object and a known side effect, the description covers action, preconditions, follow-up, recomputation and injection risk; an output schema exists, so return values need not be described. Only authorization/permission requirements go unmentioned.

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

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

Schema description coverage is only 33%, and the description compensates for the weakest parameter: "changes" is a free-form path→value map in the schema, and the description supplies the path syntax with concrete examples ("buyer.siren", "invoice.issueDate", "lines.0.quantity") plus the null-to-clear semantics. It does not explain version/optimistic locking in prose, but that parameter is already self-documented in the schema.

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

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

The description uses a specific verb and resource: it corrects fields ("Corrige des champs") of a conversion in a defined state ("au statut needs_input"). It names the sibling it hands off to ("convert_to_facturx") and the exact continuation payload, so an agent can distinguish it from batch_convert or validate_facturx without opening any schema.

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

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

It states the precondition (status needs_input or à régénérer), the required follow-up call with its exact argument shape, and an explicit do-not ("Ne décompte rien : relancez ensuite convert_to_facturx…"). It also gives the side-effect condition: editing a facture number, total TTC or client SIREN on an already-unlocked invoice creates a new conversion — a routing fact an agent could not infer.

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 readOnly/idempotent/destructive annotations: no conversion is consumed, the uploaded file is deleted as soon as the report is produced, and the size limit and the fallback to create_upload_url are spelled out. It also discloses the epistemic limits of the output (technical checks only, not a certification or tax attestation) and flags invoice content as untrusted third-party data — unusually rich disclosure for a read operation.

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

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

Front-loaded with the purpose and the list of checks, then the cost/cleanup behavior, then accepted sources, then caveats. Every sentence carries information, though the prompt-injection warning is wordy relative to the rest.

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-source-parameter tool with rich annotations and an output schema, the description covers invocation paths, limits, side effects, cost impact, and report interpretation caveats. Nothing an agent needs in order to call it or interpret the result 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?

Though reported schema coverage is 0%, the description compensates by naming both source modes, the 3 MB decoded ceiling, and that upload_id comes from create_upload_url with purpose « validate », which is the key semantic link between sibling tools. It stops short of describing the report fields, but the output schema covers 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?

States a specific verb and resource ('Vérifie un PDF Factur-X existant') and enumerates the concrete checks performed (PDF/A-3, embedded XML, XSD, EN 16931 schematron, French rules, PDF/XML consistency). The word 'existant' plus 'Ne décompte AUCUNE conversion' cleanly separates it from the sibling convert_to_facturx, which produces rather than verifies files.

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 prescribes the two accepted input paths (base64 PDF up to 3 MB, or an upload_id obtained from create_upload_url with purpose « validate »), which is exactly the routing an agent needs. It does not explicitly state when to prefer this over siblings like convert_to_facturx, though 'existant' implies it.

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