Docs for Fiscalisto's Mexican e-invoicing API (CFDI 4.0): search, operations, SDK code, errors.
Scored across 9 tools
Most tools have clearly distinct purposes: listing/searching docs, retrieving pages, describing operations/objects, explaining errors, and making test API calls. The only mild overlap is between describe_operation and describe_object when the operation response object can be expanded, and between search_docs/list_pages/get_page, but descriptions make the intended granularity reasonably clear.
All tool names use consistent snake_case with a verb_noun-style pattern: call_api, describe_object, describe_operation, explain_error, get_page, get_started, list_operations, list_pages, search_docs. get_started is slightly idiomatic but still fits the overall predictable convention.
Nine tools is well-scoped for an API documentation server. Each tool maps to a meaningful documentation or testing workflow, and there are no redundant or filler tools.
The surface covers the full documentation lifecycle: onboarding, page discovery, page retrieval, operation listing and detail, object schema lookup, error explanation, and live test calls. It includes both high-level guidance and low-level reference, with no obvious dead ends for an agent integrating the API.
Hace una solicitud real a la API en modo de pruebas con la llave fk_test_ de la persona (nunca una fk_live_) y devuelve el código, el Request-Id y el JSON de la respuesta. Para probar un cuerpo antes de escribir el código. Timbra con el emisor de pruebas del SAT, sin costo.
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | El cuerpo JSON, para POST. | |
| path | Yes | La ruta con su consulta, por ejemplo /v1/invoices?limit=3. | |
| method | Yes | ||
| api_key | Yes | La llave de pruebas (fk_test_…) de la persona, de Desarrolladores › Llaves. Pídasela; no la invente. | |
| idempotency_key | No | Idempotency-Key del POST (por omisión una nueva): repetirla con lo mismo contesta lo de la primera vez. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the sparse annotations: it discloses that the request is real but executed against sandbox keys, that the response includes status code and Request-Id, that stamping uses the SAT test issuer, and that there is no cost. This also resolves the destructiveHint=false question by making explicit that nothing production-side is touched.
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, front-loaded sentences with essentially no filler; the sandbox-key constraint and the no-cost stamping note each carry real information. Slightly more compact phrasing could still be achieved.
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?
No output schema exists, and the description covers the return shape (code, Request-Id, JSON), the credential requirement, and the sandbox semantics. Rate limits and pagination behavior for the proxied endpoint are the only notable omissions.
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 80% schema description coverage, the schema already explains path, body, api_key and idempotency_key. The description reinforces what body is for (trying a payload) but adds no format or constraint 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?
States a specific verb (makes a real API request) plus scope (test mode, fk_test_ keys only) and the return payload (status code, Request-Id, JSON). It implicitly separates itself from the doc-oriented siblings by making clear this actually executes a call, though it never names an alternative 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?
"Para probar un cuerpo antes de escribir el código" gives a concrete use case, and "nunca una fk_live_" plus the instruction to ask the person for their key set hard boundaries. It stops short of naming when to prefer describe_operation or explain_error instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Los campos de un objeto que contesta la API (Invoice, Customer, Event, Error…), con su tipo y significado, y un ejemplo. Sin nombre, la lista de objetos.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | El objeto, por ejemplo Invoice. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false). The description adds real value by disclosing the return content (fields with type, meaning, and example) and the no-name listing behavior, which matters because there is no output schema. It stops short of describing error or empty-result behavior.
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: the first front-loads what is returned, the second adds the no-name case. Nothing repeats the name or title, and the ellipsis in the object examples stays readable.
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-only tool with no output schema, the description covers what is returned and how to discover object names, which is enough to invoke it correctly. It is only slightly short on distinguishing object names from the 'Error' case handled by explain_error.
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 parameter's description already says 'El objeto, por ejemplo Invoice.' The description adds the consequence of omitting it (returns the object list), which enriches meaning slightly, but overall the schema carries the load.
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 (describe) and resource (object returned by the API), and enumerates the payload: fields, type, meaning, and an example. This is clearly distinct from describe_operation or list_operations, though it never names those siblings explicitly to draw the contrast.
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 clause 'Sin nombre, la lista de objetos' gives a conditional usage mode (call with no name to discover valid objects), which is genuinely helpful. However, it offers no guidance on when to prefer this over describe_operation or explain_error, so the agent must infer the boundary itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Todo sobre una operación: parámetros, cada campo del cuerpo (tipo, si es obligatorio, límites), ejemplos, el código con el SDK del lenguaje que elija y qué objeto contesta (sus campos con describe_object, o aquí con full).
| Name | Required | Description | Default |
|---|---|---|---|
| full | No | true: también la tabla de cada campo de la respuesta (larga). Por omisión solo su nombre y un ejemplo. | |
| language | No | El SDK del ejemplo de código. Por omisión ts. | |
| operation | Yes | El operationId (createInvoice), el método del SDK (invoices.create), el método y la ruta («POST /v1/invoices», «GET /v1/invoices/inv_123») o en palabras («create invoice», «cancelar factura»). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint and openWorldHint annotations already establish that this is a safe metadata lookup. The description adds useful behavioral detail: it emits SDK code for a chosen language and full=true produces a long response-field table, while the default only shows the name and an example.
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?
It is a single front-loaded sentence that immediately frames the tool as an operation-detail lookup. The parentheticals make it dense, but every listed item contributes to understanding what the tool returns.
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 appropriately enumerates the main returned artifacts: parameters, body fields, examples, SDK code, and response object information. It is nearly complete for a read-only documentation tool, with only minor gaps such as no explicit statement that it does not execute the operation.
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 the schema already documents operation, language, and full in detail. The description reinforces that language selects the SDK example and full expands the response table, but it does not add syntax or constraints beyond the schema.
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 specifies that this tool returns everything about an operation: parameters, body field metadata (type, requiredness, limits), examples, SDK code, and the response object. It also distinguishes response-object detail from the sibling describe_object by noting that response fields can be retrieved there or here with full.
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 mostly implied by the enumeration of returned content. The only explicit alternative routing is for response-object fields via describe_object or full, with no broader guidance on when to use this versus list_operations, call_api, or search_docs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Qué significa un código de error de la API (el error.code de la respuesta, por ejemplo issuer_required) y cómo resolverlo.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | El error.code de la respuesta. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds that it also explains how to fix the error (not just the meaning), but does not describe the shape of the answer or whether it includes docs links.
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 that names the input, gives an example, and states the outcome. No filler.
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-only lookup with no output schema, the description covers what the tool takes and what kind of answer to expect (meaning plus resolution). Return details are left implicit, but nothing needed to call it 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%, so the baseline is 3; the description earns a bump by clarifying the parameter's source (the error.code of the response) and giving a concrete example value, issuer_required, which shows the expected format.
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-like intent (explain what an error code means) and the resource (API error.code), plus the resolution angle. It is clearly distinct from siblings like call_api or search_docs, though it doesn't explicitly name 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 example '(el error.code de la respuesta)' implies it is used after receiving an API error, but there is no explicit 'use when' or 'use instead of search_docs' guidance. 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.
El texto completo (Markdown) de una página de la documentación, por su ruta, por ejemplo /docs/api/facturas o /docs/api/referencia/facturas/create-invoice.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | La ruta de la página. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context by revealing the return format (complete Markdown text), which matters because there is no output schema; it does not mention error behavior for missing paths or any size/truncation limits.
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 with the return value front-loaded and the examples inline; nothing is redundant and nothing needed is omitted.
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 no output schema, the description covers the input format and return type adequately. Only edge cases (invalid or missing path, non-existent page) are left 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 coverage is 100% and the single parameter is documented, so the baseline is 3. The description goes beyond the schema's vague 'La ruta de la página' by giving two concrete route examples, clarifying the expected path shape.
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 (retrieves the full Markdown text of a documentation page, keyed by route), which lets an agent distinguish it from list_pages or search_docs. The sibling differentiation is only implicit, since no alternative tool is named.
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 requirement of a path hints that you must first discover routes via list_pages or search_docs, but the description never says when to use this versus those siblings or what to do when the path is unknown.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start here when asked to add Fiscalisto or Mexican invoicing (CFDI 4.0) to an app. Empiece aquí: cómo integrar la API en una app de principio a fin (llave, SDK de su lenguaje, timbrar con Idempotency-Key, datos del cliente, errores del SAT, webhooks firmados, cancelar, probar sin costo y pasar a producción), en una página.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint and openWorldHint annotations already establish that this is a safe, closed-world read. The description adds useful behavioral context by saying the guide is contained in one page and enumerating the integration stages covered, including Idempotency-Key, SAT errors, signed webhooks, cancellation, and production rollout.
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?
The first sentence front-loads the primary use case, and the second sentence compactly lists the covered topics. The bilingual repetition is slightly redundant but useful for a Spanish-facing API and does not obscure the main instruction.
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?
Given zero parameters, no output schema, and annotations covering read-only/closed-world behavior, the description gives enough context for an agent to select this tool as the onboarding path. It could be stronger if it explicitly said what page or artifact is returned, but the core selection signal is 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?
The tool takes zero parameters, so there are no parameter semantics to document. Per the baseline for parameterless tools, a 4 is 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?
The description identifies a concrete starting-point guide for adding Fiscalisto / CFDI 4.0 invoicing to an app and summarizes the integration topics it covers. It is clearer than the generic name get_started, though it does not explicitly frame the tool as returning a documentation page.
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 clear usage condition: start here when asked to add Fiscalisto or Mexican invoicing to an app. It does not state when not to use it or name sibling alternatives such as search_docs or get_page.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Las operaciones de la API (operationId, método, ruta y qué hace), por sección. Úsela para encontrar la ruta correcta antes de describe_operation.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | Solo las de esta sección, por ejemplo «Facturas», «Webhooks» o en inglés «Invoices». |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful return-content detail (operationId, method, route, description) in the absence of an output schema, but says nothing about result volume, pagination, or whether the listing is exhaustive.
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 clauses with the resource description front-loaded and the usage hint second; nothing is wasted. It is arguably terse for a tool whose output shape matters, but every clause earns its place.
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-optional-parameter read-only listing with no output schema, the description covers what the tool returns and when to reach for it. Only the lack of any statement about result size or completeness keeps it from a 5.
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 tag parameter already carries examples ('Facturas', 'Webhooks', 'Invoices'). The description's 'por sección' merely restates the parameter's purpose without adding format or matching rules, so 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 states a specific verb and resource (list API operations) and enumerates what each entry contains (operationId, method, route, behavior), which is more than a restatement of the name. It also positions itself relative to describe_operation, though it does not distinguish itself from other read siblings like list_pages or search_docs.
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?
'Úsela para encontrar la ruta correcta antes de describe_operation' gives an explicit usage context and names the follow-up tool, forming a clear workflow. There are no explicit when-not conditions, but the intended sequencing is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Todas las páginas de la documentación: guías y referencia, con su ruta y de qué tratan.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), so the description's job is to add context, and it does: it discloses that each returned entry includes a route and a topical summary. With no output schema, that return-shape disclosure is genuinely useful; it stops short of saying whether the result is paginated or exhaustive.
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 that states the resource, its scope, and the fields returned. There is no filler and nothing is buried.
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 listing with no output schema, the description covers what the agent needs: the corpus, the entry types, and the per-entry fields. Only pagination or result-size behavior is left unstated.
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, which is the baseline-4 case. The description correctly makes no parameter claims and frames the tool as a full listing rather than a filtered query.
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 resource (all documentation pages) and scopes it to the two page types, guías and referencia, stating that each entry carries its route and topic. That distinguishes it from get_page and search_docs, though it never names those siblings explicitly.
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 enumerative framing implies the browse-the-catalog use case, but the description never says when to pick this over search_docs or get_page, nor gives any prerequisite or exclusion. 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.
Busca en la documentación de la API de facturación de Fiscalisto (guías y referencia) y devuelve las páginas que más coinciden. Entiende español e inglés («cancelar factura», «verify webhook signature»). Úsela antes de escribir código contra la API.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Palabras a buscar, en español o inglés, por ejemplo «cancelar factura motivo 02» o «create invoice». |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful behavior beyond that: bilingual ES/EN matching and that results are ranked pages from guides and reference, consistent with openWorldHint=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 with zero waste: purpose and return scope front-loaded, then bilingual capability, then the usage cue. Every sentence earns its place.
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 search tool with annotations covering safety and no output schema, the description is nearly sufficient. It could note result ranking or pagination, but nothing needed 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.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter with 100% schema description coverage, so the schema already documents the query format and bilingual examples. The description adds nothing about parameter semantics 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: searches the Fiscalisto billing API documentation (guides and reference) and returns the best-matching pages. This clearly separates it from page-fetching siblings like get_page or list_pages, though it never names those siblings explicitly.
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 usage condition: 'Úsela antes de escribir código contra la API.' It does not state exclusions or name alternatives (e.g., use get_page when you already know the page), 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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
call_apidescribe_objectdescribe_operationexplain_errorget_pageget_startedlist_operationslist_pagessearch_docsIssue, sign and manage Mexican CFDI 4.0 e-invoices, complements and credit notes.
Mexican invoicing (CFDI 4.0) and SAT taxes: search, draft and stamp invoices, IVA/ISR, 32-D.
Mexico CFDI 4.0 invoices for AI agents - issue, query, cancel facturas via Facturapi.
Brazilian e-invoicing (NF-e, NFC-e, NFS-e): issue, cancel and query fiscal documents, plus AP/AR.
Add one secure layer between your agents and this server.