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

Beyond the annotations, the description discloses the two traits an agent most needs: writes are local (nothing reaches SEF, consistent with openWorldHint=false) and an existing record with the same id is replaced rather than duplicated. It does not say whether omitted optional fields are wiped on replace, which is a real gap for a destructive-overwrite path, and 'replaces' sits in mild tension with idempotentHint=false and destructiveHint=false.

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 the replace behavior, with no filler. The preview/confirm reference and the SEF disclaimer each earn their place, though the flow is referenced rather than explained.

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

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

For a 14-parameter, nested-object mutation with no output schema and thin schema documentation, the description covers the safety and sequencing story but leaves field-level meaning and the replace-wipe behavior unaddressed. It is enough to start the preview/confirm dance correctly, not enough to fill the payload confidently.

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 29% across 14 parameters, including a nested address object, so the schema does little to explain fields like pib, mb, unitCode, sendToCir, or paymentDueDays. The description compensates for none of this — its only parameter-adjacent content is the implicit confirmCode step in the preview/confirm flow.

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 ('Adds a customer to the local profile') and adds crucial upsert semantics ('or replaces the one with the same id'). It also scopes the tool as local-only ('Nothing is sent to SEF'), which distinguishes it from the invoice-sending siblings, though it never names an explicit alternative.

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

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

The mention of 'Same preview → confirm flow as sef_setup_company' gives an agent a usable pattern reference and implies the two-step call sequence. However, there is no explicit statement of when to use this versus sef_list_customers, and no prerequisites or exclusions are given.

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

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

The annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the mutation profile is known. The description adds genuinely new behavioral context: the server-side status precondition and the user-approval gate that must precede the call. It does not say what happens after cancellation (whether the invoice record survives, whether the number is reusable) or what the required comment is used for, which matters for a destructive 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?

Three short sentences, no waste. The core action and its status gate come first, the alternative second, the approval prerequisite last where it is most likely to be obeyed.

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 two-parameter tool with no output schema, the description covers preconditions and the sibling alternative well, which is the hardest part. It is incomplete on the parameter side, especially the mandatory comment field, and says nothing about the result of a successful cancellation.

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 0% for both parameters, so the description carries the full burden and adds nothing: neither invoiceId nor the required 'comment' (3-1000 chars) is explained. An agent cannot tell from this text whether the comment is an audit reason shown to a user or an internal note, despite it being mandatory.

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 ('Cancels a sales invoice on SEF') and immediately scopes it by invoice status. It also names the sibling tool to use instead for other statuses, so an agent can distinguish it from sef_storno_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 when-to-use rule (status Draft, New or Sending error), an explicit when-not rule with the named alternative (Sent/Accepted/Rejected → sef_storno_invoice), and a hard prerequisite ('Only call after explicit user approval'). Nothing 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.

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuine value beyond them by stating "Makes no network calls" and by disclosing the returned content categories, which matters for an agent deciding whether this call is safe in an offline or sandboxed context.

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

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

Two short sentences with zero filler. The substantive content (what is shown) is front-loaded, and the safety reassurance follows as a compact qualifier.

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 the return value, and it does so at a summary level (environment, safety switches, profile summary). The shape of "safety switches" is left unspecified, which is a minor gap for an agent that may need to interpret the result, but the definition is otherwise sufficient for a zero-parameter diagnostic.

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 there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. The schema is empty and fully described, and no parameter semantics are 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 specific verb ("Shows") and enumerates the concrete content returned: environment mode (demo/prod), safety switches, and a profile summary. That is enough to distinguish it from the transactional siblings (sef_get_invoice, sef_send_invoice) and from sef_ping, though it never explicitly contrasts itself with sef_ping, the closest diagnostic sibling.

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

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

Usage is only implied: an agent can infer this is a pre-flight/diagnostic check to run before issuing invoices, but the description never says when to call it, nor when to prefer sef_ping instead. No prerequisites or exclusions are stated.

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

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

Annotations declare only the generic flags (readOnlyHint=false, destructiveHint=false, openWorldHint=false, idempotentHint=false); the description adds the important fact that the write is local-only and no network send occurs, plus that an approvalCode and totals come back. It does not address whether repeated drafting is safe, whether drafts expire, or what validation failures look like, but the core behavioral context is supplied.

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

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

Two sentences, front-loaded with the operation and immediately followed by the critical non-sending caveat and the workflow instruction. No filler or redundancy.

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

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

The description compensates for the absent output schema by naming the return (totals plus approvalCode) and clarifies the local-draft model, which is valuable for a 14-parameter mutation tool. However, with only 57% schema coverage and no annotations beyond generic hints, gaps remain around the undocumented optional fields, whether the stored draft must be retrieved with sef_get_draft, and any validity/auth constraints.

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 57%, so the schema itself documents several parameters (number, dueDate, customer, issueDate, deliveryDate, attachments, notes, unitCode). The description only gestures at 'the profile and the given lines' and does not clarify the many undocumented optional fields such as sendToCir, periodStart/periodEnd, orderNumber, or contractNumber. Baseline 3 is appropriate given partial schema coverage and minimal added meaning.

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

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

States a specific verb and resource ('Builds a UBL 2.1 invoice ... stores it as a draft and returns totals plus an approvalCode') and adds the decisive scope boundary 'Nothing is sent to SEF', which cleanly separates it from sef_send_invoice. An agent can identify the operation 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?

'Nothing is sent to SEF' plus 'Always show the result to the user before sending' establishes the draft-then-send workflow and implies sef_send_invoice is the follow-up step, which is clear usage context. It stops short of naming that sibling explicitly or stating when to prefer it over other paths (e.g., retrieving via sef_get_draft).

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 safety profile is fully covered elsewhere. The description adds only that a 'summary' is returned and that XML is opt-in, without disclosing what the summary contains or what happens for a missing/invalid draftId.

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

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

A single front-loaded sentence with no filler or redundant restatement of the title. It is efficient, though its brevity is the source of the completeness gaps noted elsewhere rather than a stylistic flaw.

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

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

For a two-parameter read tool with no output schema, the description is only minimally sufficient. It omits what fields the 'summary' includes, what the XML represents, and error behavior for an unknown draftId, which an agent would want before invoking it.

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 0%, so the description must carry the burden for both parameters. 'Optionally with the full XML' does explain the intent of includeXml, but draftId is left entirely undocumented and the description adds no format, ID-source, or default details for either parameter.

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: 'Returns a stored draft's summary,' with the optional XML payload named. It is distinguishable from the invoice siblings by the word 'draft,' but it never explicitly contrasts itself with sef_get_invoice or sef_list_invoice_ids, so it stops short of full sibling differentiation.

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 alternative is named. An agent cannot tell from the description whether to call this or sef_get_invoice, or under what circumstances a draft should be fetched rather than an invoice.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world behavior, so the safety profile is covered. The description adds that status is part of the result, but says nothing about what happens for an unknown invoiceId, what status values exist, or whether results are cached/eventually consistent — relevant given the openWorldHint.

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 with no filler; the verb, result, source system, and keying parameter all appear immediately.

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 with rich annotations and no output schema, the definition is minimal but workable. It leaves gaps on how to obtain the invoiceId and on failure semantics (not-found, auth/setup requirements given the sef_check_setup/sef_setup_company siblings), which an agent would need in practice.

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% for the single required parameter, so the description must carry the meaning. It does clarify that the id is the SEF-side invoiceId rather than an internal or draft id, which is genuinely useful, but adds no format, range, or sourcing (how to obtain a valid id) 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 a specific verb ('Returns') and resource ('a sales invoice and its status') scoped to SEF, which distinguishes it from siblings like sef_get_draft (local draft) and sef_list_invoice_ids (enumeration). It does not explicitly name a sibling to contrast with, but the resource is concrete enough to select on.

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

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

Usage is only implied: the agent must infer that this is the lookup to use after sending an invoice or when it already holds a SEF-side id. There is no stated when-not-to-use (e.g., versus sef_get_draft for unsent invoices) and no mention of where the invoiceId comes from, such as sef_list_invoice_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, idempotentHint, destructiveHint=false and a closed-world scope, so the safety profile is covered. The description adds one genuinely useful behavioral fact — that results come from the 'local profile' rather than a remote service — but says nothing about result size, ordering, or what happens when no customers exist.

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

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

A single front-loaded sentence with the verb and scope first and the returned fields in a compact parenthetical. Nothing is redundant or padded.

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

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

For a zero-parameter read-only list tool with full annotation coverage, the description supplies the essentials: source of data and returned fields, which partly substitutes for the absent output schema. Only minor gaps remain, such as whether an empty list or an error is returned when no customers are configured.

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 there is no parameter semantics to explain; baseline 4 applies. The parenthetical field list instead documents the shape of what comes back, which is a reasonable use of the space.

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 ('Lists') and resource ('customers') plus the scope ('defined in the local profile'), and the parenthetical enumerates the fields returned (id, name, PIB, defaults). This clearly separates it from the mutating sibling sef_add_customer, though it does not explicitly name any sibling it supersedes.

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 lookup to call before sef_draft_invoice or sef_add_customer, but the description never says when to use it or when another tool is preferable. No prerequisites or exclusions are given.

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

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

Annotations already declare readOnly, idempotent, open-world and non-destructive, so the safety profile is covered. The description adds real behavioral content the annotations cannot: the date range is interpreted against creation date for New/Draft/Mistake but against sending date for all other statuses, and this is version-gated to SEF 3.15.0. It does not say anything about result ordering, volume, or pagination, which keeps it from a 5.

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

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

Two sentences, both load-bearing: the first states the operation, the second carries the non-obvious date-field rule. Nothing is repeated from the schema or the annotations, and the key qualifier 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 three-parameter read-only lookup with full schema coverage and no output schema, the description covers what an agent needs to call it correctly, including the status-dependent date semantics that would otherwise cause silent wrong results. Minor omissions such as id format or result ordering are low-impact given there is no output schema to explain.

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 would be 3, but the description adds genuine meaning beyond the schema: it explains that the meaning of dateFrom/dateTo depends on the status value, a coupling the schema does not express. It does not clarify format expectations or whether the range is inclusive, leaving a small gap.

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 ("Lists SEF sales invoice ids") and constrains it to status plus date range, so the agent knows this is an id-only lookup rather than a full invoice fetch such as sef_get_invoice. It never names a sibling tool to contrast against, 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 status/date framing implies the use case (find invoice ids to feed into sef_get_invoice, sef_send_invoice, etc.), but the description never says that explicitly and gives no when-not guidance or alternative routing. The 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 readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds that the result is SEF's accepted-code set with sample values, but does not say whether the list is static or changes, or whether returned codes are localized or versioned.

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

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

A single front-loaded sentence with the resource stated first and examples that earn their place by showing the code format. Nothing is redundant.

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 reference lookup with no output schema and full annotation coverage, the description says enough to call it correctly. A brief note on how the returned codes link to invoice fields would make it 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 of 4 applies; there is nothing for the description to disambiguate beyond confirming the call requires no input.

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 ('Returns SEF's list of accepted unit codes') and reinforces it with concrete examples (H87 piece, HUR hour, MON month), so an agent knows exactly what it gets. It does not explicitly contrast itself with siblings like sef_draft_invoice, though the resource is distinctive enough to be unambiguous.

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

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

Usage is only implied: an agent can infer this is the lookup to call before supplying a unit code to an invoice tool. There is no explicit 'use when' statement, no note that this list is the authoritative source for valid codes, and no mention of alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered without the description. The description adds that the list is "official" and from SEF, which is modest but real context about authority and stability. It says nothing about whether the list is static or changes, or what a consumer should expect beyond codes.

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

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

A single front-loaded sentence with no filler; the resource and an illustrative code are stated immediately. 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 no parameters, no output schema, and rich annotations, the definition needs only to describe what comes back, and it does so only minimally — an agent cannot tell whether entries are bare code strings or objects with code plus description text. That return-shape gap is the main missing piece for a reference-lookup 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a 0-parameter tool applies. The mention of an example code format (PDV-RS-33) is a small bonus that hints at the value space, though not a parameter.

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?

"Returns SEF's official list of VAT exemption reason codes" gives a specific verb (returns) and a concrete resource, plus an example code format (PDV-RS-33) that makes the content unmistakable. It is clearly distinct from the invoice-writing siblings, but it does not explicitly distinguish itself from the similar reference-data sibling sef_list_unit_measures, leaving that differentiation to the name alone.

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

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

The description implies the use case — you fetch codes when you need an exemption reason for invoicing — but never states when to call this versus other tools, nor any prerequisite such as needing a configured company. Usage must be inferred entirely from the resource name.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is fully covered by structured data and 'harmless read-only' largely restates it. The description does add the behavioral purpose of credential/environment validation, but says nothing about what a failed check looks like, error surfacing, or whether it incurs meaningful API cost.

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

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

A single short sentence front-loads the mechanism and the purpose with no filler. The word 'harmless' is mildly redundant with readOnlyHint/destructiveHint=false, but it is a minor blemish rather than wasted space.

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

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

For a parameterless, side-effect-free smoke test with no output schema, the description covers what the tool does and why an agent would call it. The only remaining gap is what the call yields on success versus failure, which is a small omission for a tool of this 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?

The tool takes zero parameters and the schema is an empty object, so there is nothing to disambiguate. The baseline for a parameterless tool applies, and the description correctly avoids inventing inputs.

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 action (call a harmless read-only SEF endpoint) and an explicit goal (confirm the API key and environment work), which tells an agent this is a connectivity/credential smoke test. It does not distinguish the tool from the sibling sef_check_setup, which likely overlaps in intent, so it falls short of a 5.

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

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

Usage is implied clearly by the stated goal of verifying that the API key and environment work, so an agent can infer 'call this before other SEF operations.' However, it never says when not to use it or how it differs from sef_check_setup, leaving the main sibling ambiguity unresolved.

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, openWorld and idempotent; the description goes beyond them by explaining the idempotency semantics (alreadySent=true plus the earlier SEF response), the environment gate, and that server-side validation is skipped by default per SEF support. It leaves the success payload shape unstated, which keeps it below 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 action, then preconditions, then the flag rule, then the duplicate-send behavior — a sensible order. It restates the 'option is not in operation yet' caveat that also appears in the executeValidation schema description, which is mild redundancy.

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

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

With no output schema, the description carries return-value duty and does explain the alreadySent outcome. It is complete enough for a 3-parameter mutation, though it never says what a first-time successful upload returns (e.g., a submission identifier) for the agent to report or reuse.

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 33%: executeValidation is documented in the schema (including the default and the caveat), while draftId and approvalCode have no schema descriptions. The description adds only that approvalCode is 'the user approved' one and that draftId refers to an existing draft — useful but thin for the two required parameters.

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

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

States a concrete verb and resource — 'Uploads a previously drafted invoice to SEF' — which separates it from sef_draft_invoice (creates the draft) and sef_get_draft (reads it). It does not name a sibling explicitly, but the 'previously drafted' qualifier makes the pipeline position 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?

Gives an explicit precondition ('Only call after the user explicitly approved this exact draft'), a production precondition (SEF_MCP_ALLOW_PROD_WRITE=true), and a precise trigger for the optional flag ('only if the user explicitly asks for it'). An agent has no ambiguity about when this tool is appropriate.

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 this is a non-read-only, non-idempotent, closed-world mutation, and the description usefully adds that it operates on the local profile and 'Nothing is sent to SEF' — the single most important side-effect boundary. The two-phase preview/confirm flow also clarifies reversibility risk. It leaves open what happens to existing fields on update and whether the confirmCode expires.

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

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

Three short sentences, each earning its place: capability first, then the confirmation protocol, then the side-effect boundary. No repetition of schema or title content.

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 nested mutation with no output schema, the description supplies the critical operational facts — preview flow, local-only effect, confirmCode handling. Since the preview presumably conveys the return shape, the absence of output details is acceptable. Optional fields like numberPattern and paymentDueDays rely on schema text alone.

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

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

Schema description coverage is 77% and the nested defaultTax and bankAccount descriptions already carry format and default-rule detail in-schema. The description only adds meaning for confirmCode's role in the two-step flow, which the schema description also gestures at. Baseline 3 is right for high coverage where 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 names the specific action and resource: 'Creates or updates the seller (your company) in the local profile'. An agent can immediately tell this is the write-side counterpart to setup/checking tools. It stops short of naming a sibling such as sef_check_setup, so differentiation is implied by scope 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?

It gives a concrete call protocol: invoke without confirmCode to obtain a preview and code, show the preview to the user, then re-invoke with identical values plus the code only after confirmation. That is genuine when-and-how guidance. It does not, however, say when to prefer this over sef_check_setup or what to do if a profile already exists.

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, readOnlyHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is known. The description adds genuine value beyond that by disclosing an SEF-side state precondition and a human-approval gate. It does not disclose whether the storno is itself reversible, what SEF returns, or how failures on already-reversed invoices behave.

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 core action scoped first and the constraints immediately after. Nothing would be gained by shortening it.

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

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

The destructive, open-world mutation framing is adequately covered by annotations plus the approval gate, and no output schema means return values need not be explained. But with 0% schema coverage on three parameters and no contrast against sef_cancel_invoice, key call-shaping information 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 0% across three parameters, so the description carries the full burden and adds nothing: it never explains that invoiceId identifies the target, that comment is a mandatory human-visible reason, or that stornoNumber is an optional custom storno document number. An agent reading only the description cannot tell the difference between the required comment and optional stornoNumber.

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: 'Reverses (storno) a sales invoice on SEF', which is far more precise than the title alone and identifies the document type and system. It does not, however, distinguish this from the sibling sef_cancel_invoice, so an agent must guess which reversal path applies.

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 a clear applicability condition ('only for status Sent, Accepted or Rejected') and an explicit gating rule ('Only call after explicit user approval'), which is strong when-to-use guidance. It stops short of naming the alternative tool (sef_cancel_invoice) or explaining what to do when the invoice is in another status.

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