XSDHub XML validation

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

Annotations already declare readOnly, idempotent, closed-world, non-destructive behavior, so the safety bar is low. The description usefully adds fallback behavior ('Returns a general guide when no exact match exists'), but says nothing about how ambiguous matches are resolved or what a general guide looks like.

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

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

Two tight sentences with no filler; the core action is front-loaded and the fallback behavior follows. Slightly terse given the open questions it leaves, but nothing is wasted.

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

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

With three optional parameters, no required fields, and no output schema, the definition should clarify at minimum what happens with empty input and how the standard parameter affects matching. The fallback sentence covers one edge case, but the parameter-interaction and no-input cases remain 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 description coverage is only 33%, so the description needs to compensate but does not. It never mentions code, message, or standard, nor how they combine (e.g., whether standard narrows the match, or what happens if all three are omitted since none are required).

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 ('Match an XML/XSD or invoice error code or message to a ... guide and explanation'), which is far more informative than the title alone. It does not explicitly distinguish itself from the sibling search_xsdhub_guides, but the matching/lookup framing makes its role reasonably clear.

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: call this when you have a validation error to interpret. There is no explicit statement of when to prefer this over search_xsdhub_guides or the validate_* tools, and no mention of prerequisites or ordering relative to validation.

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 fully covered without the description. The description adds a useful scope clarification (no account or billing data is exposed), but says nothing about whether authentication is required or how the capability data is presented.

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 enumeration of what can be read is front-loaded and the scope caveat follows. 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?

With no output schema, the description compensates by enumerating the returned categories (browser tools, file limits, privacy boundaries, test-mode status), which is exactly what an agent needs to judge relevance. For a zero-parameter read tool that is nearly complete, though it omits how to interpret or act on the returned limits.

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 meaning to convey and the baseline of 4 applies. Nothing in the description misleads about 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?

States a specific verb ("Read") and enumerates the resource contents: supported browser tools, file limits, privacy boundaries, and subscription test-mode status. An agent can tell this is a capabilities/introspection tool, distinct from action tools like validate_xml. It does not explicitly contrast itself with the nearest sibling, list_supported_standards, which overlaps on the "what is supported" theme.

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

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

"No account or billing access" sets a negative scope boundary but never says when to call this versus alternatives such as list_supported_standards. Usage is only implied — an agent must infer that it should call this to learn limits before attempting uploads or validation.

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, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description still adds real value by disclosing the return format (Markdown), the inclusion of a canonical source URL, and the restriction to public pages. It does not describe failure behavior for unknown slugs, which keeps 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?

Two sentences, front-loaded with the action and return artifact, followed by the input shape and examples. No redundant restatement of the title and nothing that could be cut 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?

For a one-parameter read tool with full annotations and no output schema, the description covers what is fetched, in what format, and what the input looks like. The remaining gap is edge behavior on missing or private slugs, which is modest for 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?

Schema coverage is 0% for the single 'slug' parameter, so the description must carry the meaning, and it does: it names the argument a public page slug and supplies concrete shape examples ('learn/xml-namespaces-explained', 'about', 'home'). That clarifies path-style formatting and the absence of leading slashes in a way the bare minLength/maxLength schema cannot.

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 gives a specific verb and resource ('Read one public XSDHub page as Markdown') plus the returned artifact (canonical source URL). 'One' versus the search_/list_ siblings hints at single-item retrieval, but it never names search_xsdhub_guides explicitly, so differentiation is left partly implicit.

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

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

Usage is implied rather than stated: the agent can infer this tool applies when it already has a page slug. There is no explicit 'use this instead of search_xsdhub_guides when you already know the slug' routing, and no exclusion for non-public pages.

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 state readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety and determinism are covered elsewhere. The description adds genuinely useful context that the list is fixed at six packages and includes scope and limitations rather than being open-ended. It stops short of saying how the result is shaped (structured records vs prose) or whether versions are grouped per package.

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, front-loaded with the verb and the headline content, with zero filler or restatement of the title. The trailing 'plus generic XML and supplied-XSD support' is dense but each clause still carries distinct 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 full annotation coverage, the description's main remaining job is previewing what comes back, which it does by naming packages, versions, scope, limitations and the two non-package cases. Only the shape of the returned data is left unstated, a minor gap for a simple fixed-list 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 and the schema is an empty closed object, so there is nothing to disambiguate; the baseline of 4 applies. Nothing in the description contradicts or misrepresents the no-argument signature.

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 gives a specific verb ('List') and a precisely scoped resource ('the six fixed invoice packages, versions, scope and limitations, plus generic XML and supplied-XSD support'). An agent can immediately tell this is a static inventory of supported standards. It does not, however, distinguish itself from the sibling get_xsdhub_capabilities, which plausibly overlaps.

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: because the tool enumerates supported packages, an agent can infer it should be called before choosing a validation path. There is no explicit when-to-use statement, no exclusion, and no pointer to get_xsdhub_capabilities as an alternative for capability questions.

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 genuinely new behavioral context beyond that: the result shape (source URLs and excerpts) and the explicit exclusion of validation/upload. It stops short of disclosing result ordering, rate limits, or what an empty result looks like.

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, zero filler. The core purpose and return format are front-loaded, and the exclusion clause follows as supporting scoping rather than as preamble.

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?

This is a simple two-parameter read tool with rich annotations, and the description covers purpose, return format, and scope, so it is broadly adequate. The notable gap is parameter guidance: with no output schema and 0% schema description coverage, the description is the only place query and limit semantics could appear, and they 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 0% – the schema exposes only constraints (query 2-160 chars, limit 1-10) with no semantics. The description never mentions 'query' or 'limit', so it fails to compensate for the coverage gap: an agent gets no hint about query syntax, matching behavior, or what the limit truncates.

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 ('Search XSDHub public XML and XSD guides') and immediately delimits scope by stating it does not validate or upload XML, which separates it from the validate_* siblings. It also says what comes back (source URLs and excerpts), so an agent knows this is a discovery tool, not a fetch or validation tool.

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

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

The negative guidance ('Does not validate or upload XML') implies the correct routing toward the validate_* tools and hints at a search-then-fetch flow with get_xsdhub_page, but no alternative is named and no when-to-use condition is stated explicitly. An agent can infer usage but must do the work itself.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new scope limits: KSeF is XSD-only, Factur-X validates XML only, and there is no authority or network acceptance check. It stops short of describing the result shape (errors vs warnings), which max_findings hints at but never explains.

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 core action and supported standards, with zero filler. The telegraphic phrasing ('RO or HR package') is dense but readable; no sentence is wasted.

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

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

With no output schema, the description carries the burden of explaining what comes back, yet it never says that findings, errors and warnings are returned or how max_findings and include_guides shape the response. For a validator whose whole value is its output, that is a meaningful gap despite otherwise good scope disclosure.

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; the schema already documents every parameter including the standard enum values and the 10 MiB XML limit. The description's 'KSeF is XSD-only; Factur-X checks XML only' largely restates the standard field's own schema text rather than adding new 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 ('Check') and resource ('invoice XML') and enumerates the six fixed rule packages it covers. The phrase 'fixed ... package' implicitly separates it from the sibling schema-driven tools validate_xml and validate_xml_against_xsd, though it 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?

The closing sentence 'No authority or network acceptance check' establishes a clear exclusion, and 'KSeF is XSD-only' scopes one standard. However, there is no explicit guidance on when to pick this over validate_xml or validate_xml_against_xsd, so the agent must infer the choice from the word 'fixed'.

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 read-only, idempotent, non-destructive behavior, so the bar is lower. The description adds genuinely new context: results are bounded, findings carry locations, and each call consumes one validation from a daily allowance — a quota constraint an agent cannot learn from annotations or schema.

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

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

Two tight sentences with zero filler, and the core purpose is front-loaded ahead of the quota caveat. Every clause carries information an agent needs.

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 discloses the return shape (bounded errors and warnings with locations) and the quota cost. It stops short of explaining how findings relate to explain_validation_error or what guide URLs appear when include_guides is set, 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 all three parameters are already documented in the schema. The description's 'bounded errors and warnings' loosely echoes max_findings but adds no syntax or format detail beyond what the schema provides, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Check XML well-formedness'), which is meaningfully distinct from the sibling validate_xml_against_xsd. It does not explicitly name that sibling, so the differentiation is inferable 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 well-formedness framing implies this is the syntax-only check to run before schema validation, but the description never says when to use it versus validate_xml_against_xsd or explain_validation_error. Usage is implied, not guided.

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, openWorldHint=false and destructiveHint=false, so safety is covered by structured data. The description adds two genuinely useful behavioral facts beyond that: no network resolution and that results are 'bounded findings' (truncation tied to max_findings). It stops short of saying what a finding looks like or whether validation halts at the first error.

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 core action, then input modes, then output framing. No sentence restates the title or repeats schema constraints unnecessarily.

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 seven-parameter, read-only validation tool with no output schema, the definition plus the rich schema cover the essentials: input modes, version support, no-network constraint, and bounded output. The main residual gap is return-value shape, which the 'bounded findings' phrase gestures at but does not specify.

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 71%, above the 50% threshold, so the schema already documents most parameters including mutual exclusivity of xsd and schemaFiles. The description reinforces the xsd-or-schemaFiles choice and frames schemaFiles as a 'local multi-file project with rootSchema', but adds no detail on xsdVersion behavior or the practical difference between 1.0 and 1.1 validation.

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

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

The description states a specific verb and resource ('Check XML against supplied XSD'), and the phrase 'supplied XSD 1.0 or 1.1' implicitly separates it from schema-less siblings such as validate_xml. It does not name validate_xml or validate_e_invoice explicitly, so an agent must infer the split, but the purpose itself is unambiguous.

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

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

The description conveys operating context ('one XSD or a local multi-file project with rootSchema; no network resolution'), which tells the agent that remote schema URLs are not an option. However, it never states when to pick this over validate_xml or explain_validation_error, so selection guidance 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.