Server Quality Checklist

Tool Scores

• cfdi_statusA
  4.2/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered by structured data. The description nonetheless adds real behavioral context beyond annotations: no credentials/CSD/PAC required, fail-soft contract returning available:false, one retry with a 10-second timeout, and the cross-tool output schema already carries return fields. Strong additive context, but the effort is largely replicated in the output schema it also enumerates.

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

  Conciseness4/5

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

  Well front-loaded (purpose first, then argument shapes, then return semantics, then failure behavior) and the bulleted status meanings are dense but useful. It is on the long side and the 'Returns: {...}' block restates the output schema, which is minor waste.

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

  Completeness5/5

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

  For a read-only external-service lookup with full annotations and an output schema, the description covers everything an agent needs: input shapes, preferred path, output field meanings, and the fail-soft edge case ('a failed lookup is a statement about the SAT, never about the invoice'). Nothing material is missing.

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

  Parameters3/5

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

  Schema coverage is 100%, so every parameter is already documented, and required-unless-xml relationships are stated in the schema itself. The description adds a genuinely useful formatting constraint ('six decimals, trailing zeros trimmed') and flags hand-typed totals as the common cause of a spurious 'No Encontrado', which is marginal added value over a fully documented schema. Baseline 3 is correct.

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

  Purpose5/5

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

  Specific verb+resource: 'Ask the SAT whether an invoice actually exists and is still live' via the public ConsultaCFDIService SOAP endpoint. It distinguishes itself from parse_cfdi by noting the derivation uses 'the same reader parse_cfdi uses', so an agent can tell the two apart 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.

  Usage Guidelines5/5

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

  Explicitly lays out both invocation shapes (four key fields OR the whole xml) and states which is preferred ('Deriving them from the XML is the more reliable route') with the reason. Gives a concrete example mapping a natural-language intent to the call.

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

• validate_nssA
  4.2/5.0
  Behavior4/5

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

  Annotations cover the safety profile (read-only, idempotent, non-destructive), but the description adds real behavioral context beyond them: spaces and dashes are normalized away before validation, and the two year fields are informational because IMSS-issued numbers can mismatch holder records — so only the check digit justifies rejection. That is the kind of edge-case semantics an agent could not infer from 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.

  Conciseness4/5

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

  Well front-loaded: purpose first, then field breakdown, then the rejection caveat, then args/returns/example. The explicit Returns block is partly redundant given a full output schema exists, but the overall structure is scannable and every other sentence earns its place.

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

  Completeness5/5

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

  For a single-parameter validator with an output schema, nothing material is missing: it covers input normalization, output shape, the informational-field caveat, and a concrete invocation example. An agent has everything needed to call it correctly.

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

  Parameters4/5

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

  Schema description coverage is 100%, so a 3 is the baseline, but the description exceeds it by disclosing normalization of spaces and dashes in `value` and confirming the default of `response_format` to markdown. These details add meaning beyond the schema's terse parameter docs.

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

  Purpose5/5

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

  States a specific verb and resource — validate an 11-digit NSS issued by the IMSS — and distinguishes itself from the sibling validators (validate_curp, validate_rfc, validate_clabe) by document type. It further explains the internal structure of the identifier, making the scope unambiguous.

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

  Usage Guidelines3/5

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

  Usage is implied by the document type being validated, and the description gives genuinely useful domain guidance that only the check digit can invalidate a number. However, it never states when to reach for this tool versus a sibling validator or when a caller would already have a normalized value, so routing guidance 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.

• generate_test_dataA
  4.4/5.0
  Behavior5/5

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

  Well beyond the readOnly/idempotent/non-destructive annotations, it discloses that records are synthetic, that CURPs or phone numbers can coincide with a real person by chance, and that values are not checked against SAT, RENAPO, IMSS or Banxico. It also guarantees internal coherence (RFC and CURP derived from the same name/sex/date/state, real Banxico bank code, NSS passing Luhn), which materially affects how an agent should trust the output.

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

  Conciseness4/5

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

  Front-loaded with the core purpose, then a rationale paragraph, Args, Returns and an example — a logical structure. The Args list duplicates a fully-covered schema and the Returns block restates an existing output schema, so a few sentences do not earn their place, but the disclaimers and example do.

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

  Completeness5/5

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

  For a generation tool with an output schema, zero required parameters and simple enums, the description is complete: it covers what is produced, per-kind composition, non-realism caveats and a worked example. Nothing an agent needs to call it correctly is missing.

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

  Parameters3/5

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

  Schema coverage is 100%, so the Args section largely restates what the schema already documents (kind, count bounds, format defaults). The description adds only marginal semantics — e.g. that a person record bundles RFC+CURP+CLABE+NSS — while the enum meanings remain schema-owned, so baseline 3 is appropriate.

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

  Purpose5/5

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

  The description pairs a specific verb (generate) with a precise resource (structurally valid Mexican identifiers) and immediately scopes it to fixtures, seeds and demos. It distinguishes itself from the validate_* siblings by stressing that output is generated, not looked up or verified against real registries.

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

  Usage Guidelines4/5

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

  It names the use cases (fixtures, database seeds, demos) and gives a clear negative condition — do not send the results to the SAT status service or a PAC. It does not explicitly route the agent to validate_rfc/validate_curp/validate_clabe for verification, so the alternative-selection guidance 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.

• parse_cfdiA
  4.4/5.0
  Behavior4/5

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

  Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the bar is lower, yet the description still adds real substance: code labeling, modulus-11 RFC validation, arithmetic checking with a stated tolerance, namespace-agnostic walking, and the explicit limits (no signature verification, no SAT contact). It stops short of describing pagination/size limits or failure modes on malformed XML, so not quite 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.

  Conciseness4/5

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

  Well front-loaded and organized with a numbered list, a negative-scope callout, and an example. However, the lengthy 'Returns' block largely re-enumerates a field list that already exists as an output schema, which is redundant padding.

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

  Completeness5/5

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

  For a two-parameter, fully-annotated tool with an output schema, the description covers purpose, scope limits, validation behavior, and routing to the sibling SAT-check tool. Nothing needed to invoke it correctly is missing.

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

  Parameters3/5

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

  Schema coverage is 100% and both parameters are fully documented in the schema, so baseline 3 applies. The Args section merely restates the schema definitions without adding format or edge-case detail beyond what is already structured.

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

  Purpose5/5

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

  Opens with a specific verb+resource ('Turn the XML of a Mexican electronic invoice (CFDI 4.0) into structured JSON') and enumerates exactly what is extracted (header, issuer, receiver, line items, taxes, timbre). An agent can immediately distinguish this parsing tool from cfdi_status 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.

  Usage Guidelines5/5

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

  Explicitly states when to use this versus the alternative: it does not ask the SAT, and 'Use cfdi_status for the SAT's own answer.' It also pre-empts a major misuse case by clarifying that a clean parse does not mean the document is valid or uncancelled.

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

• validate_clabeA
  4.4/5.0
  Behavior5/5

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

  Goes well beyond the annotations by disclosing the actual validation algorithm (3-7-1 weights reduced mod 10 before summing, and how the Luhn habit fails), the curated-subset policy that returns 'unknown' rather than inventing a bank, and the decision to report plaza verbatim rather than guess a city. These are meaningful behavioral traits the readOnly/idempotent annotations do not convey.

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

  Conciseness4/5

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

  Front-loaded with the core purpose and structure, then background on the algorithm and limitations, all under clear bold headers. The 'Returns' block largely restates the existing output schema, which is mild redundancy but the rest of the content earns its place.

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

  Completeness5/5

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

  With an output schema present, return values need not be re-explained, and the description otherwise covers normalization, algorithm correctness, and data-coverage caveats. An agent has everything needed to call and interpret it correctly.

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

  Parameters4/5

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

  Schema coverage is already 100%, so the baseline is 3, but the description adds value by noting that spaces and dashes are normalised away in 'value' and contrasting markdown vs json for response_format. This is incremental over the schema rather than contradictory.

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

  Purpose5/5

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

  States a precise verb (validate) and resource (18-digit CLABE, the account number for every SPEI transfer), then decomposes its structure. Sibling validators (validate_rfc, validate_curp, validate_nss) target different identifiers, and the description makes the CLABE domain unambiguous.

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

  Usage Guidelines3/5

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

  Usage is implied — you call it when you have a CLABE to check — and the example query demonstrates the invocation. However, there is no explicit when-to-use/when-not guidance nor any named alternative, leaving routing to inference given several sibling validators.

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

• sat_catalog_lookupA
  4.6/5.0
  Behavior5/5

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

  Annotations already declare the safe read-only, offline, idempotent profile, and the description reinforces it ('never touches the network'). It then adds genuinely valuable data-provenance caveats beyond the structured fields: the bank list is a curated Banxico subset, and CURP state keys deliberately do not match INEGI or ISO 3166-2:MX codes — exactly the kind of trap an agent needs warned about.

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

  Conciseness4/5

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

  Front-loads the core purpose, then uses a scannable bulleted list for the catalogues and a compact paragraph for query behavior. The catalogue glossary is long but each line earns its place; only the 'Two honesty notes carried in the output' framing is slightly padded.

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

  Completeness5/5

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

  For a bounded, offline lookup with a declared output schema, the description covers everything an agent needs: the enum of catalogues, query resolution rules, output format choice, provenance caveats, and a concrete example call. Nothing required to invoke it correctly is missing.

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

  Parameters4/5

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

  Schema coverage is 100%, so baseline is 3, but the description adds matching semantics the schema omits: leading zeros are ignored ('1' finds '01') and the fallback is case- and accent-insensitive substring over both code and label. The match_type output field ties these rules to observable behavior.

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

  Purpose5/5

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

  States a specific verb ('look up') and resource ('the code tables a CFDI is written in'), then enumerates all nine catalogues with a one-line gloss of each. This distinguishes it from siblings like validate_rfc or parse_cfdi, which validate or parse rather than resolve reference codes.

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

  Usage Guidelines4/5

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

  Clearly explains the two usage modes: no `query` returns the whole catalogue, a `query` does exact-then-substring matching, and it contrasts itself with 'downloading the SAT's spreadsheet' and 'never touches the network'. It stops short of explicitly naming when to reach for this over the validate_* siblings, so it is clear context rather than full alternatives guidance.

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

• validate_curpA
  4.6/5.0
  Behavior5/5

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

  Annotations already declare a safe, idempotent, closed-world read, so the description correctly focuses on behavior beyond that: input normalization (spaces, dashes, lowercase stripped), the base-37 modulus-10 check-digit algorithm, and the explicit limitation that it never contacts RENAPO to confirm registration.

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

  Conciseness4/5

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

  Front-loaded with the core purpose, then structured with bullets and an example. It is on the long side and the RENAPO-table trivia is dense, but every element (state keys, century marker, exclusion word X rule) aids correct interpretation, so little is wasted.

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

  Completeness5/5

  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 explained, yet the description still gives the decoded shape and an end-to-end example call. Nothing an agent needs to select or invoke this validator correctly is missing.

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

  Parameters4/5

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

  Schema coverage is 100%, so the baseline is 3, but the description adds real semantics the schema lacks — that the CURP value is normalised (spaces, dashes, case-insensitivity) before validation — plus a worked example input.

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

  Purpose5/5

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

  States a specific verb (validate) and resource (Mexican CURP, defined as the 18-character RENAPO population ID) plus the secondary decode behavior. An agent can distinguish this from validate_clabe, validate_nss and validate_rfc purely from the resource named.

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

  Usage Guidelines4/5

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

  Explains the context clearly, including the crucial 'structural validity is not registration' caveat and the cases (state keys, century marker) where a naive regex approach fails. It does not explicitly name a sibling or state when-not-to-use, so it falls 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.

• validate_rfcA
  4.6/5.0
  Behavior5/5

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

  Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial behavioral detail beyond them: modulus-11 check-digit verification, the two SAT generic special cases and why XAXX010101000 fails the arithmetic, input normalization, and the deliberate separation of is_generic from check_digit_satisfied. This is real disclosure an agent could not infer.

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

  Conciseness4/5

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

  Front-loaded with the core operation, then bulletted special cases, then args and returns — well organized and scannable. Slightly long: the aside about home-grown validators wrongly rejecting invoices is editorial rather than operational.

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

  Completeness5/5

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

  Output schema exists, yet the description still gives the return shape and the meanings of the two easily-confused flags. Combined with the scope caveat and normalization note, an agent has everything needed to call it correctly and interpret the result.

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

  Parameters4/5

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

  Schema coverage is 100%, so baseline is 3, but the description adds genuine meaning: spaces, dashes and lower case in `value` are normalised away, and the response_format default is restated with intent. The added normalization rule is not visible in the schema.

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

  Purpose5/5

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

  States a specific verb (validate) and resource (Mexican RFC / SAT taxpayer ID), and immediately disambiguates from sibling validators by naming the two RFC shapes (13-char persona física, 12-char persona moral). An agent can distinguish it from validate_curp/validate_clabe/validate_nss 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.

  Usage Guidelines4/5

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

  Explicitly frames the scope boundary — 'Structural validity is not registration. Only the SAT can say whether one is registered and active' — which tells the agent this tool answers well-formedness, not status. It does not explicitly name a sibling to use instead for registration checks, so it stops short of full routing guidance.

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