Stackin

issue_invoice

Destructive

Issue a Brazilian fiscal document: NFS-e or NF-e.

This produces a legal fiscal document. Confirm the data with the user before calling when you inferred any field.

Every item needs a price: unit_price is what one unit costs and amount is the line's gross total. Send unit_price with quantity when the user quotes a price per unit, amount when they quote the line. Sending both asserts they agree and is refused if they do not.

document_type nfse is a service invoice: each item needs a description and a price, the recipient address is optional, and service_code (LC 116/2003 item.subitem) falls back to the company's fiscal profile when omitted.

document_type nfe is for goods, and the SEFAZ rejects a partial one: every item needs ncm and cfop, and recipient_address is required with street, number, neighborhood, city, state, zip_code and city_code all filled. Call validate_invoice_payload first when any of that was inferred rather than given.

Pass idempotency_key when a retry is possible: repeating the same key with the same payload replays the first answer instead of issuing a second document. Without one, a retry after a lost response issues again — another credit, another number burned, and undoing it means cancelling, which has a deadline. Nothing generates the key for you; use one per business event, not per call.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`items`	Yes
`number`	No
`series`	No
`tax_id`	Yes
`client_name`	Yes
`document_type`	Yes
`idempotency_key`	No
`recipient_address`	No

Output Schema

TableJSON Schema

Name	Required	Description
`id`	No	Local id. Use it for reissue and for submissions, and when a document was rejected and has no key.
`status`	No	issued, rejected or cancelled.
`protocol`	No	The authorization protocol, when granted.
`access_key`	No	The authorizer's key. Absent while the document is not authorized.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedSep 11, 2026

addedInput schema / $defs / IbsCbs

Added value: +{
+  "description": "The Reforma Tributária group for one item.",
+  "properties": {
+    "base": {
+      "anyOf": [
+        {
+          "exclusiveMinimum": 0,
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Base"
+    },
+    "classification": {
+      "pattern": "^\\d{6}$",
+      "title": "Classification",
+      "type": "string"
+    },
+    "cst": {
+      "pattern": "^\\d{3}$",
+      "title": "Cst",
+      "type": "string"
+    },
+    "rate_city": {
+      "minimum": 0,
+      "title": "Rate City",
+      "type": "number"
+    },
+    "rate_federal": {
+      "minimum": 0,
+      "title": "Rate Federal",
+      "type": "number"
+    },
+    "rate_state": {
+      "minimum": 0,
+      "title": "Rate State",
+      "type": "number"
+    }
+  },
+  "required": [
+    "cst",
+    "classification",
+    "rate_state",
+    "rate_city",
+    "rate_federal"
+  ],
+  "title": "IbsCbs",
+  "type": "object"
+}

addedInput schema / $defs / Product / properties / ibs_cbs

Added value: +{
+  "anyOf": [
+    {
+      "$ref": "#/$defs/IbsCbs"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

First observedSep 9, 2026

TDQS

A5/5.0

Behavior5/5

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

Despite the annotations (destructiveHint, non-idempotent), the description goes well beyond them: it discloses the legal nature of the document, the SEFAZ rejection of incomplete NF-e, the refusal when unit_price and amount conflict, and the full replay-vs-issue-again behavior of idempotency_key, including the need to cancel to undo. This is exactly the kind of behavioral context an agent needs and the schema cannot express.

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 each sentence earns its place: the purpose is front-loaded, then pricing semantics, then the two document type branches, then idempotency guidance. There's minimal fluff, and the paragraphs are grouped by responsibility, making it easy to scan. For a tool this complex, this level of detail is not almost at all.

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 complex nested schema and the existence of an output schema, the description covers the decision points an agent needs to invoke this tool correctly: which validation is required, what each document type demands, and what idempotency hazards exist. It also flags the user-confirmation step, which is a critical interaction requirement. No obvious gaps remain for safe invocation.

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 description coverage is 0%, so the description carries the full semantic load and does so thoroughly. It explains document_type's nfse vs nfe field requirements, the difference between unit_price and amount, when recipient_address becomes mandatory, and the business meaning of idempotency_key. Even though it does not narrate the obviously named tax_id, client_name, number, and series, it covers every ambiguity an agent is likely to face 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?

The first sentence states a specific verb and resource: 'Issue a Brazilian fiscal document: NFS-e or NF-e.' This clearly identifies the tool as the issuance action, distinct from siblings like reissue_invoice, cancel_invoice, and validate_invoice_payload. The two document_type variants are also exposed, so an agent immediately knows what the tool does.

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 gives explicit when-to-use guidance: confirm the user's data before calling when any field was inferred, call validate_invoice_payload first for partially inferred NF-e data, and pass idempotency_key whenever a retry might occur. It even describes the when-not-to case by warning that without a key, retries issue a duplicate document. This passes the bar of naming the alternative tool and the condition that selects it.

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

All Stackin tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.