xmlvalid

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

Annotations only declare readOnlyHint, so the description usefully adds that no API key is required, which parsers/ecosystems it recognizes, and that the answer includes an example. It does not discuss response format details or limits, but the disclosure goes beyond the annotation.

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, then supporting detail about parser families and the no-API-key note; every clause carries information. The ecosystem list is dense but earns its place by setting expectations about recognized error formats.

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 tool with no output schema, the description explains both the required input form and the shape of the answer (meaning, cause, fix, example), leaving nothing essential unspecified.

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 baseline is 3; the description adds real value by instructing the agent to include the stack trace prefix and paste the message verbatim rather than paraphrasing, which directly affects input quality.

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 ('Explain an XML parsing or schema validation error message') and enumerates the deliverable: meaning, cause, fix, plus an example. It is clearly distinguished from siblings like validate_xml (which produces errors) and explain_rule (which explains a rule).

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 input-side guidance ('paste the message as reported, stack trace prefix included') and names the parser ecosystems whose wording it understands, which tells the agent this is the right tool for any raw parser/validator output. It stops short of an explicit 'use X instead when...' routing statement against validate_xml or explain_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 only supply readOnlyHint, so the description carries the rest of the behavioral load; it contributes a genuinely useful fact in 'No API key needed' (an auth/access requirement) and describes the shape of the explanation returned. It still omits rate limits or whether the rule corpus can go stale, 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?

One sentence that front-loads the action and input, then a colon list of the value delivered, plus a short trailing availability note. No filler and nothing to trim.

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 reference lookup with a single required id and no output schema, the description must cover input format, returned content, and access requirements — it does all three. Nothing essential to calling 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?

With 100% schema coverage the baseline is 3, but the description adds real semantic breadth the schema lacks: a national CIUS rule is a valid id form and several naming families (BR-CO, BR-DE, PEPPOL-EN16931) are enumerated. It stops short of saying what happens for an unrecognized id.

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

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

States a specific verb and resource ('Explain an e-invoicing business rule by its id') and pins down the input space with concrete ids (BR-CO-15, PEPPOL-EN16931-R001, national CIUS rules), which separates it cleanly from explain_error. It also enumerates the returned content (message, level, rule sets, failure reason, remedy), so an agent knows exactly what it gets.

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

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

The description implies usage ('why invoices fail it and how to fix them') but never states when to choose this over explain_error or the other siblings, nor any preconditions beyond the API-key note. Guidance is inferable but not 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 cover the safety profile via readOnlyHint=true, so the description's burden is lower. It still adds a meaningful behavioral trait not in the annotations: results are retained for only 24 hours, which tells the agent the call can fail or return nothing after expiry.

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 with no waste; the purpose and the originating condition are front-loaded, with the retention caveat trailing appropriately.

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-param read tool with no output schema, this is nearly complete: it explains origin, status values, and retention. It could say more about what the 'result' contains once the validation finishes, but nothing critical is missing.

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

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

Schema coverage is 100% and the single param is already documented as 'The id validate_xml returned.' The description reinforces up front that the id comes from validate_xml, but adds no format or syntax detail beyond the schema, so the baseline 3 applies.

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

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

The description names the specific resource (a validation), what it returns (status and result), and ties it directly to the sibling tool validate_xml and the exact condition that produces a follow-up need. An agent can distinguish it from validate_xml or explain_error 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 the precise trigger for use: a validation that was still 'queued' or 'running' when validate_xml returned. This is strong contextual guidance, though it does not explicitly state when-not to use it (e.g., after the 24-hour window has expired).

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

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

With readOnlyHint already declared, the description still adds real behavioral context: 'No API key needed' (auth requirement) and a summary of the return payload (slug, version, business rules checked). It does not mention pagination or result-count limits for a no-required-parameter listing search.

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: what is searched, what is returned and where it flows, and the auth note. No filler, and the resource scope 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 one-optional-parameter search with no output schema, the description covers purpose, searchable fields, return contents and auth. The only gap is result-set behavior (how many results, any limits), which an agent might want before calling it repeatedly.

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

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

Schema coverage is 100% and the schema already gives query examples, but the description adds meaning by enumerating the fields the query matches against (name, namespace, root element, area) and noting that omitting the query lists the first schemas — neither of which the schema states.

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

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

States a specific verb (search) plus the exact resource (xmlvalid's catalog of official XML schemas) and enumerates the standards covered, so an agent immediately knows the scope. It also distinguishes itself from siblings by naming validate_xml as the consumer of its output.

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 line 'Returns each schema's slug to pass to validate_xml' tells the agent this is the discovery step before validation, giving clear usage context. It does not state explicit when-not conditions or contrast with explain_error/explain_rule, so it stops short of a 5.

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

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

Annotations only declare openWorldHint, so the description carries the burden and does so well: it discloses quota cost ('one API validation of the key's monthly quota'), the URL-fetch behavior, the pending/poll flow, and the rules_version_mismatch failure mode. It also describes the return shape (valid, errors, warnings with line/column/message/rule/help_url).

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 layered detail afterward, with no filler sentences. It is somewhat dense, packing format lists, quota notes and return values into a few long sentences, but each element is useful.

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

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

With 6 optional parameters, no output schema, and minimal annotations, the description supplies what's missing: inputs, schema selection, quota, async behavior and result structure. Nothing an agent needs to invoke it correctly is absent.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value by showing concrete schema formats ('@orders-v3', 'auto') and explaining that rules_version pins Schematron releases and fails with rules_version_mismatch. It restates the xml/url choice already documented in the schema, which caps it below 5.

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 ('Validate an XML document') and immediately enumerates the checked layers: well-formedness, XSD/DTD/RelaxNG, and Schematron business rules for named e-invoice profiles. This is distinguishable from siblings like get_validation or search_schemas without consulting their 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?

Explains the input alternatives (xml text vs public http(s) url), the schema options (catalog slug, saved '@orders-v3', or 'auto'), and the consequence of omitting schema (well-formedness only). The wait parameter also names get_validation as the polling alternative for pending results.

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