Server Quality Checklist

Tool Scores

• mx__validate_cfdiA
  4.4/5.0
  Behavior5/5

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

  Annotations are absent, so the description carries the full burden and meets it thoroughly. It discloses the always-run root Comprobante check, the conditional TFD and Pagos validations with their trigger conditions, the XSD-only limitation, and the precise semantics of 'valid' (True only if every applicable schema passed). This depth goes far beyond what the annotations could have provided.

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

  Conciseness5/5

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

  The description is long but every section earns its place: purpose sentence, conditional validation logic, scope limitation, and a scannable bulleted return-dict breakdown. The core purpose is front-loaded, and the length is proportionate to the real complexity of three schemas and conditional validation paths.

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

  Completeness4/5

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

  An agent can invoke this correctly from the description alone: one fully documented parameter, explicit conditional behavior, documented return keys, and an existing output schema. The only real gap is that the description never positions itself against the adjacent sibling mx__verify_tfd, so an agent must infer which tool covers verification of the TFD seal.

  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 description coverage is 100% — the single 'xml' parameter is already documented as 'The CFDI 4.0 Comprobante XML to validate, as a string.' The description confirms this but adds no syntax, format, or encoding detail beyond the schema; the conditional behavior based on document contents is better credited under behavioral transparency.

  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+method: 'Validate a CFDI 4.0 document against the official SAT XSD schemas.' It further names the exact schemas (cfdv40.xsd, TimbreFiscalDigitalv11.xsd.xml, Pagos20.xsd.xml) and its structural-validation scope clearly differentiates it from the build/seal siblings and from mx__verify_tfd's verification role.

  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 states the negative space: business-rule checks from SAT's Matriz de errores are not run, and 'a document that passes this validator is structurally conformant but not guaranteed to pass PAC certification.' However, it never names a concrete alternative for those excluded cases, leaving the validate-vs-verify boundary with mx__verify_tfd implicit.

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

• mx__verify_tfdA
  4.5/5.0
  Behavior5/5

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

  With no annotations, the description fully carries the burden of behavioral disclosure. It exposes the always-returned attributes, the XSLT-based cadena original computation, the exact cryptographic algorithm (SHA-256 + RSA-PKCS#1v1.5), and the important null-vs-false semantics for `sello_sat_verified`.

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

  Conciseness5/5

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

  The description is dense but well-structured: core purpose first, then the optional verification mode, then a bulleted return dict. There is no filler; every sentence provides operational or semantic detail needed to invoke the tool correctly.

  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?

  Even though an output schema exists, the description usefully covers runtime behavior, the verification algorithm, the optional certificate path, and the null semantics. An agent can correctly decide whether to call this tool and know what to expect in return.

  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?

  The input schema already documents both parameters with 100% coverage, so the baseline is 3. The description reinforces the optional certificate behavior and adds the 'same algorithm as the emisor's own Sello' detail, but it does not add substantial new parameter meaning beyond what the schema already states.

  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 opens with a precise verb and object: 'Parse a Timbre Fiscal Digital 1.1 stamp and, optionally, verify SelloSAT.' This clearly identifies the resource (TFD 1.1) and the tool's distinguishing verification behavior, setting it apart from the CFDI build/validate/seal sibling tools even without naming them.

  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 provides clear conditional usage guidance: supply `pac_certificado_der_b64` to verify SelloSAT, or omit it to parse fields and compute the cadena original without verification. It also clarifies that a null `sello_sat_verified` means verification was not attempted, not that it failed. It stops short of explicitly naming alternatives or exclusions.

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

• mx__build_pagoA
  4.7/5.0
  Behavior5/5

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

  With no annotations provided, the description carries the full behavioral burde. It discloses that the output is unsealed, omits Sello/NoCertificadao/Certificado, forces buyer.uso_cfdi to CP01 'regardless of what the caller passes,' and returns a dict with an xml key. It also explains that the tool mirrors mx__build_cfdi and that sealing must happen afterward.

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

  Conciseness5/5

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

  The description is dense but every sentence earns its place: scope, fixed-value behavior, sealing expectations, and return shape. It is front-loaded with the purpose and organized so that technical details follow naturally, without repetition or fluff.

  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?

  Given the tool's complexity, the descriptions fully covers what an agent needs: input responsibilities, forced schema values, output structure, the unsealed state, and the next step to use mx__seal_cfdi. The output schema signal also relieves the description from needing to enumerate every return field beyond the xml key.

  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. The description adds value beyond the schema by explaining that comprobante_data fields like SubTotal/Moneda are fixed or derived, that buyer.uso_cfdi is forced to CP01, and that pagos_data drives the Pagos20 complement. This helps the agent understand why certain fields must not be supplied.

  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 opens with a specific verb and resource: 'Build a well-formed, unsealed Complemento de Pagos 2.0 CFDI.' It immediately distinguishes itself from mx__build_cfdi by scoping to a Pagos-type comprobante and mentions the Pagos20 complement and fixed Concepto wrapper.

  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?

  The description makes the intended context clear through the phrase 'Pagos-type Comprobante' and refers to mx__build_cfdi and mx__seal_cfdi as related steps. However, it does not explicitly state 'use this instead of mx__build_cfdi for Pagos' or list when-not-to-use conditions, so it falls short of the highest explicitness bar.

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

• mx__get_supported_scopeA
  4.7/5.0
  Behavior5/5

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

  With no annotations, the description carries full disclosure duty and excels: it states the tool returns scope information, lists exact supported CFDI versions and complementos, names the implemented operations, and explicitly calls out what is not implemented ('PAC submission transport and later-phase complementos are not'). This gives a transparent view of behavior and limitations.

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

  Conciseness5/5

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

  The description is front-loaded with the purpose, then layers supporting details: scope source, implemented operations, excluded features, and return value. Every sentence adds useful context and none is redundant with the schema or annotations.

  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 zero-parameter introspection tool with an output schema, this description is complete. It tells the agent exactly what scope information is returned, what is covered, what is not covered, and where the authoritative context lives, so there is no ambiguity about calling 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?

  The tool accepts zero parameters, so the baseline is 4. The description adds useful meaning by explaining that the returned ScopeInfo describes current scope, which is about as much parameter semantics as an empty schema needs.

  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 opens with a specific verb and resource: 'Return the CFDI document types, complementos, and sealing modes this package supports.' It clearly identifies this as an introspection capability and distinguishes it from the operational siblings by describing what it reports.

  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 explicitly tells callers when to use it: 'for callers to check before assuming a document type or complemento is supported.' It also names the sibling tools and notes which are implemented versus not, but it does not explicitly say when not to use it or directly route to an alternative tool, so it stops short of full when/ when-not guidance.

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

• mx__seal_cfdiA
  4.9/5.0
  Behavior5/5

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

  With no annotations, the description carries the full burden, and it does extensively: it explains that local sealing uses an actual SAT XSLT transform, that out-of-scope complementos are stubbed to no-op templates, that key material is only accepted as file paths and never plaintext, that PAC mode returns the XML unchanged, and that the tool does not submit to any PAC. It also explicitly warns that no_certificado is not derived from certificate bytes. This is a highly transparent behavioral disclosure.

  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?

  The description is organized with clear paragraphs per mode and a concise return-value summary. It is longer than minimal, but every section adds necessary operational detail: mode behavior, XSLT internals, security constraints, and return shape. Minor deduction because the implementation detail about spec files and SelloDigitalSigner's docstring could arguably be condensed, but it earns its place for transparency.

  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?

  Given the tool's overall complexity (6 params, two modes, file-path dependencies, security considerations) and the fact that no annotations are present, the description covers all essential calling context: mode selection, required parameters per mode, security convention, return format, and what the tool does not do. The presence of an output schema further confirms the return dict, and the description already enumerates its keys. Nothing critical is missing.

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

  Parameters5/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 substantial value beyond the schema. It explains the relationship between key_path/cert_path/key_password/no_certificado and sealing_mode, clarifies the security convention for key material, documents the no_certificado derivation caveat, and maps the sealing_mode enum values to their concrete behavior. This is auxesis rather than mere repetition.

  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 opens with a specific verb ('Seal'), a precise resource ('a CFDI 4.0 Comprobante'), and an explicit scope qualifier ('PAC-agnostic'). It clearly distinguishes the two modes of operation. It also differentiates the tool from siblings by stating that it does not submit to any PAC, which is a key distinguishing trait among the cfdi-related tools.

  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?

  The description explicitly explains when each sealing_mode should be used: 'local' computes the cadena original and signature, 'pac' returns the XML unchanged for PACs that seal on the emisor's behalf. It also states what this tool does not do ('does not submit to any PAC') and where to find the PAC-agnostic design context (package README). This is strong guidance for selecting the right mode and avoiding misuse.

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

• mx__build_cfdiA
  5/5.0
  Behavior5/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It honestly states that the output is unsealed, omits Sello/NoCertificado/Certificado, and that validation on the output should report exactly those three missing attributes. It also documents RFC validation behavior as a validation error rather than a generated document.

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

  Conciseness5/5

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

  The description is dense but every sentence earns its place. It is front-loaded with the core purpose, then adds exclusions, validation behavior, workflow, and return shape without unnecessary filler. Code formatting and structured bullets improve scannability.

  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 complex nested-object tool with no annotations, the description is remarkably complete. It covers model validation, RFC validation behavior, sealed vs unsealed output, expected downstream validation results, and the return dict including the total computation formula. An agent can select and invoke this tool correctly with confidence.

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

  Parameters5/5

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

  The input schema only describes comprobante_data as an object matching a schema, but the description adds substantial meaning: full field list reference, seller/buyer as MXEmisor/MXReceptor, lines as CFDIConcepto, and RFC validation via TaxIdentifier.validate_mx_rfc. This is critical because the schema uses additionalProperties: true and does not enumerate fields.

  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 states a specific verb ('Build'), a specific resource ('CFDI 4.0 Comprobante XML'), and a clear scope ('Ingreso or Egreso'). It also distinguishes itself from the sibling mx__build_pago by explicitly excluding Pago documents, making tool selection unambiguous.

  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?

  The description explicitly says when not to use this tool ('For tipo_de_comprobante="P" (Pago), use mx__build_pago instead'), and it names the follow-up tool mx__seal_cfdi for sealing. It also explains what mx__validate_cfdi should report, giving clear workflow guidance.

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