Numeral MCP by usefulapi
Server Details
Calculate sales tax & VAT, record transactions and refunds, manage products and customers.
- Status
- Healthy
- Uptime
- 81.9% over 62 days
- Last Tested
- Transport
- Streamable HTTP · MCP 2025-06-18
- URL
- Repository
- m190/usefulapi-mcp
- GitHub Stars
- 0
TDQS
Scored across 11 tools
Each tool has a clearly distinct resource and action (calculate tax, create/get customer, create/get/list product, create/get transaction, create/list refunds, ping). The descriptions explicitly clarify boundaries, such as calculate_tax being stateless versus create_transaction writing a live record. No two tools overlap in a way that would cause misselection.
All tools use the numeral_ prefix and snake_case, with a consistent verb_noun pattern for almost every operation. The lone exception is numeral_ping, which lacks a noun but is a conventional health-check name, making this a minor deviation rather than a real inconsistency.
11 tools is well-scoped for a tax/compliance API covering products, customers, transactions, refunds, tax calculation, and health checking. Each tool clearly earns its place without redundancy or bloat.
The set covers key create, get, and list operations for products, but lacks update/delete for customers, products, and transactions, and has no list_customers or list_transactions. These gaps could hinder agents needing to manage or discover records beyond creation and single-record retrieval.
Available Tools
11 toolsnumeral_calculate_taxCalculate taxARead-onlyInspect
Calculate sales tax / VAT for an order — a STATELESS quote that persists nothing (record it later with numeral_create_transaction using the returned calculation id). Returns per-jurisdiction rates, total_tax_amount, and totals. Provide a customer address and one or more line items (each needs reference_product_id OR product_category). Amounts are in the currency's smallest unit (cents). Numeral: POST /tax/calculations.
| Name | Required | Description | Default |
|---|---|---|---|
| customer | Yes | Customer details — address is required. | |
| metadata | No | Arbitrary string key/value metadata. | |
| order_details | Yes | Order details. | |
| origin_address | No | The address a product ships from. Optional on 2024-09-01; required on API version 2025-05-12+. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so safety is covered; the description goes further by disclosing that the call is STATELESS and persists nothing, that a calculation id is returned for later recording, and what the response contains (per-jurisdiction rates, total_tax_amount, totals). It does not mention auth requirements, rate limits, or error behavior for international/unsupported jurisdictions.
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?
Four sentences, front-loaded with the core action and the statelessness constraint before the input requirements and unit convention. No filler, and the sibling pointer is appended where it is most useful rather than up front.
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 4-parameter nested-object tool with no output schema, the description covers the action, statelessness semantics, required inputs, unit convention, and a summary of the return payload. Nothing an agent needs in order 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?
Schema description coverage is 100% and nested objects are fully documented, so the schema carries the parameter burden. The description restates the alternative requirement (reference_product_id OR product_category) and the smallest-unit currency rule, both of which already appear verbatim in the schema, adding little beyond the baseline.
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+resource ('Calculate sales tax / VAT for an order') and immediately qualifies the scope as a stateless quote, which distinguishes it from the sibling write tools. It also names where persistence would happen instead (numeral_create_transaction), so an agent can route without reading any schema.
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?
Explicitly says when to use it (quoting tax) and when to use something else (recording the transaction, via numeral_create_transaction with the returned calculation id). It also states the minimum inputs needed to invoke it, so both the when and the how are covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
numeral_create_customerCreate customerCDestructiveInspect
CREATES a customer record — this WRITES to your Numeral customer list (used for order tracking and tax exemptions). Numeral: POST /tax/customers.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Customer name. | |
| Yes | Customer email (required). | ||
| is_tax_exempt | No | Whether this customer is tax exempt. | |
| reference_customer_id | No | Your own id for this customer (for reference-based lookups). |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The destructiveHint=true annotation already signals a state-mutating operation, and the description's "WRITES" mostly restates that. It adds the underlying REST endpoint (POST /tax/customers) but discloses nothing about auth requirements, duplicate handling, or reversibility, which would be the value-add over the annotation.
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 with the write semantics stated first and the endpoint last. The uppercase emphasis is slightly redundant given the name, but nothing is wasted or bloated.
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 four-parameter create with full schema coverage and no output schema, the description is adequate but thin: it omits what the response contains (e.g. a customer id for later get/refund calls) and how duplicate or tax-exempt edge cases behave.
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 four fields (name, email, is_tax_exempt, reference_customer_id) are already documented inline. The description adds no syntax, format (e.g. email validation) or usage nuance beyond the schema, 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+resource ("CREATES a customer record") and adds scope detail about what the customer list is used for (order tracking, tax exemptions). Siblings are all distinct resources, so no explicit differentiation is needed, but none is offered either.
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?
There is no when-to-use guidance: nothing about checking for existing customers first, whether the call is idempotent, or what to do on a duplicate email. The agent must infer all invocation context from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
numeral_create_productCreate productADestructiveInspect
CREATES (or upserts) a product with its tax category — this WRITES to your Numeral product catalog, which drives future tax calculations. Numeral: POST /tax/products.
| Name | Required | Description | Default |
|---|---|---|---|
| product_category | Yes | A tax category from Numeral's taxonomy, e.g. "GENERAL_MERCHANDISE", "SAAS_GENERAL". | |
| reference_product_id | Yes | Your product id (used to reference this product in calculations). | |
| reference_product_name | Yes | Human-readable product name. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, so the write nature is covered; the description still earns credit for disclosing the upsert semantics (existing product is updated rather than rejected) and the downstream consequence on future tax calculations. It stops short of saying which fields an upsert overwrites on an existing product.
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, front-loaded statements with the verb first and the blast radius second; caps emphasize the write. The trailing 'Numeral: POST /tax/products' endpoint reference adds little for an agent selecting the tool, keeping it just short of ideal.
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 3-parameter mutation with no output schema and minimal annotations, the description supplies the transferable facts an agent needs: it writes to the catalog, it upserts, and it affects downstream tax results. Missing only auth/permission prerequisites and what happens to fields omitted on upsert.
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 all three parameters are already documented in-schema with examples for the category taxonomy. The description only restates the tax category parameter and adds no format or constraint detail, so the schema does the heavy lifting and a 3 baseline 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?
States a specific verb and resource ('CREATES (or upserts) a product with its tax category') plus the concrete effect on the catalog that drives tax calculations. The upsert framing distinguishes it from the read siblings numeral_get_product and numeral_list_products without needing to 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 impact statement ('drives future tax calculations') implies the tool should be used to register products before calculations, but there is no explicit when-to-use rule, no exclusion ('use get_product to look up an existing id first'), and no alternatives named. 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.
numeral_create_refundCreate refundADestructiveInspect
RECORDS a refund against a transaction — this WRITES a live tax/compliance record (adjusts tax owed). Use type="full" to refund the whole transaction, or type="partial" with line_items (each keyed by reference_product_id) for a partial refund. Numeral: POST /tax/refunds.
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | "full" refunds the whole transaction; "partial" requires line_items. | |
| line_items | No | Required for type="partial": the line items to refund. | |
| transaction_id | Yes | The transaction id (tr_...) to refund. | |
| refund_processed_at | No | Unix timestamp (SECONDS) the refund was made. Defaults to now if omitted. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide destructiveHint=true; the description adds meaningful context beyond that — that the call writes a live tax/compliance record and adjusts tax owed, which tells the agent the effect is a real financial mutation, not just an 'add'. It omits permission requirements and irreversibility details.
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, no filler, with the write-behavior warning front-loaded before the mode-selection guidance and the endpoint reference trailing as an implementation note. 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 4-parameter mutation tool with no output schema and minimal annotations, the description covers the operation's nature, both modes, and the line-item structure requirement. Missing only peripheral details like auth requirements and how refund_processed_at defaults behave (though the schema notes the default).
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 four parameters are already documented in the schema. The description reinforces the critical dependency (type="partial" requires line_items keyed by reference_product_id) but adds no syntax or format detail beyond what the schema provides; baseline 3 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?
States a specific verb and resource ('RECORDS a refund against a transaction') and clarifies the operation's nature as a write ('this WRITES a live tax/compliance record'). It also names the sibling it is distinct from implicitly by scoping to creating rather than listing refunds (numeral_list_transaction_refunds exists).
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 explicit conditional guidance: use type="full" to refund the whole transaction, or type="partial" with line_items for a partial refund. It does not name sibling tools or state when *not* to create a refund, but the mode-selection condition is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
numeral_create_transactionCreate transactionADestructiveInspect
RECORDS a completed sale as a transaction — this WRITES a live tax/compliance record used for filings. Supply the calculation_id returned by numeral_calculate_tax and your reference_order_id. Numeral: POST /tax/transactions.
| Name | Required | Description | Default |
|---|---|---|---|
| metadata | No | Arbitrary string key/value metadata. | |
| calculation_id | Yes | The calculation id returned by numeral_calculate_tax. | |
| reference_order_id | Yes | Your order id for this sale (used for record keeping / dedupe). | |
| transaction_processed_at | No | Unix timestamp (SECONDS) the sale was processed. Defaults to now if omitted. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only supply destructiveHint=true, so the description carries most of the burden. It adds genuinely useful context: this WRITES a durable, filing-relevant compliance record rather than a transient one, and it names the source of the required input. It doesn't discuss idempotency/retry behavior or auth requirements, leaving that gap.
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: what it does, then the required input provenance, then the endpoint. Nothing is repeated or padded, and the emphasis on WRITES/RECORDS is placed where an agent will read it first.
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 4-parameter write tool with a nested object and no output schema, the description covers purpose, the prerequisite call, and the compliance significance. The one real gap is that it doesn't indicate what the call returns (e.g. a transaction id needed by numeral_get_transaction), which matters more given there is no output schema.
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 four parameters (including the nested metadata object and the SECONDS timestamp) are already documented in the schema. The description restates calculation_id and reference_order_id but adds no syntax or format detail beyond them, which is the baseline for a fully covered 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?
States a specific verb and resource ('RECORDS a completed sale as a transaction') and immediately characterizes the artifact as a live tax/compliance record, which distinguishes it from read-only siblings like numeral_get_transaction. Naming the underlying call (POST /tax/transactions) and its dependency on numeral_calculate_tax further separates it from numeral_calculate_tax and numeral_create_refund.
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?
Explicitly establishes the ordering dependency: the agent must first call numeral_calculate_tax and pass its calculation_id. It gives clear context for when this tool is appropriate (after a completed sale). It stops short of naming a when-not case or pointing to numeral_create_refund as the alternative for reversals, so it isn't a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
numeral_get_customerGet customerARead-onlyInspect
Get a customer by id. By default customer_id is the Numeral id (cus_...); set id_type to "reference" to look up by your own reference_customer_id. Returns name, email, and tax-exempt status. Numeral: GET /tax/customers/{customer_id}.
| Name | Required | Description | Default |
|---|---|---|---|
| id_type | No | Which id space `customer_id` is in (default: numeral). | |
| customer_id | Yes | The customer id — a Numeral id (cus_...) by default, or your reference id when id_type="reference". |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, so safety is already covered; the description still adds useful behavior: which fields come back (name, email, tax-exempt status) and the backing endpoint GET /tax/customers/{customer_id}. No mention of error behavior when an id is not found, which is the main residual gap for a lookup tool.
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 before the id-space nuance. Slightly redundant with the schema on the default-id statement and the trailing HTTP endpoint is marginal, but nothing is wasteful enough to hurt.
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 compensates by naming the returned fields. Input semantics for both id spaces are fully covered. Only omission is failure/not-found behavior, a minor gap for a simple read.
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 both parameters are already documented in the schema, including the enum for id_type and the cus_ prefix. The description restates the same default/override semantics rather than adding new syntax or constraints, so baseline 3 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?
States a specific verb and resource ('Get a customer by id') and immediately clarifies the dual lookup semantics, which no sibling (numeral_create_customer, numeral_get_product, etc.) shares. An agent can distinguish this from other get_* tools without opening a schema.
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?
Explains the default path (Numeral cus_ id) and the alternate condition that selects the other path (set id_type to "reference" to use your own reference_customer_id). Clear context for both modes, but no explicit when-not guidance or named alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
numeral_get_productGet productARead-onlyInspect
Get a single product by its reference_product_id (your id). Returns the product's name, product_category, and timestamps. Numeral: GET /tax/products/{reference_product_id}.
| Name | Required | Description | Default |
|---|---|---|---|
| reference_product_id | Yes | Your product id (the reference_product_id used when the product was created). |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already establishes this is a safe read, so the description's main added value is the explicit return shape (name, product_category, timestamps) and the upstream route mapping. It says nothing about not-found behavior, pagination/rate limits, or auth requirements, which are modest gaps for a simple lookup.
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, each earning its place: purpose and key parameter first, then return fields, then the underlying API route. Nothing is padded and the essential information is front-loaded.
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 compensates by enumerating the returned fields, and it maps to the REST endpoint. The only omission is error/not-found behavior, which is minor for a one-parameter read 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?
Schema description coverage is 100% and the single parameter is fully documented in the schema, so the baseline is 3. The description's '(your id)' phrasing and the parenthetical about it being the id used at creation add only marginal clarification 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?
States a specific verb and resource ('Get a single product') and scopes it to a lookup by reference_product_id, which inherently separates it from the sibling list_products. It also names the returned fields, so an agent knows exactly what this retrieval yields.
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: fetch one product when you already have the product id. It never contrasts with numeral_list_products (for enumerating/filtering products) or states prerequisites such as needing an id created earlier. Adequate but with clear gaps.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
numeral_get_transactionGet transactionARead-onlyInspect
Get a recorded transaction by its Numeral id (tr_...). Returns the transaction with its line items, currencies, and metadata. Numeral: GET /tax/transactions/{transaction_id}.
| Name | Required | Description | Default |
|---|---|---|---|
| transaction_id | Yes | The Numeral transaction id (tr_...). |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=true. The description earns extra credit by disclosing the return shape (line items, currencies, metadata), which is meaningful given there is no output schema, and by mapping to the underlying REST call GET /tax/transactions/{transaction_id}. It omits auth requirements, rate limits, and error 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?
Three short sentences, front-loaded with the operation and its identifier, then the return contents. The final REST-endpoint sentence is largely redundant with the tool name but serves as a useful API mapping and takes little space.
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 what is fetched and what comes back (line items, currencies, metadata). Nothing essential is missing for correct invocation, though not-found/error behavior is 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?
With a single parameter at 100% schema description coverage, the schema already documents transaction_id and its tr_... format. The description repeats the id format but adds no new semantics, 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 and resource ('Get a recorded transaction by its Numeral id'), which clearly separates it from numeral_create_transaction and numeral_list_transaction_refunds. It does not explicitly name or distinguish itself from any sibling, which keeps it just short of a 5.
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: the tool is for the case where you already hold a transaction id. There is no statement of when to prefer this over the list/refund siblings, no preconditions, and no exclusions, so it stays at the minimum viable level.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
numeral_list_productsList productsARead-onlyInspect
List your Numeral products (up to 50 per page), each with its reference id, name, and product_category. Use cursor (the last_product_id from a previous page) to paginate; has_more indicates more pages. Numeral: GET /tax/products.
| Name | Required | Description | Default |
|---|---|---|---|
| cursor | No | Pagination cursor — pass the last_product_id from the previous page. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint, so the description carries most of the burden and delivers: page size cap (50), the fields returned per item, the has_more flag, and the cursor's provenance. It stops short of noting rate limits or total-count behavior, but it is well beyond what the annotation provides.
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 clauses, front-loaded with what is listed and how many, followed by pagination mechanics and the endpoint reference. No filler sentences.
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 naming the returned fields (reference id, name, product_category) and the pagination contract (cursor, has_more). An agent has everything needed to call and iterate this tool correctly.
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 cursor parameter is fully documented in the schema, so baseline is 3. The description restates the cursor convention (last_product_id) and supplements it with the has_more indicator, but adds no new format or edge-case semantics.
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 ('List') and resource ('your Numeral products'), and adds scope details (up to 50 per page). It is clearly distinguishable from siblings like numeral_get_product (single fetch) and numeral_create_product (mutation).
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 explains how to paginate ('Use `cursor` ... to paginate'), which is genuine usage guidance, but it never states when to prefer this over numeral_get_product or when a single-product lookup is the better call. Usage is implied by context rather than explicitly routed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
numeral_list_transaction_refundsList transaction refundsARead-onlyInspect
List all refunds recorded against a transaction. Returns {refunds:[...]}. Numeral: GET /tax/transactions/{transaction_id}/refunds.
| Name | Required | Description | Default |
|---|---|---|---|
| transaction_id | Yes | The Numeral transaction id (tr_...). |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only supply readOnlyHint=true, so the description's disclosure of the return shape ({refunds:[...]}) is genuinely additive, especially since no output schema exists. It still says nothing about pagination, result limits, or error behavior for a list endpoint, which is the main remaining gap.
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 action and scope, then the return shape, then the endpoint. Nothing is padded or redundant.
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 read tool with no output schema, the description covers what it returns and where it maps in the API surface. The only missing element is list behavior such as pagination or ordering, which an agent may need for large refund sets.
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% and the single parameter is documented there with its tr_ prefix format. The description only echoes transaction_id in the path template, adding no syntax or constraint information beyond the schema — 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 and resource — 'List all refunds recorded against a transaction' — and the endpoint line confirms read semantics. It implicitly contrasts with the sibling numeral_create_refund, but never names it or any other sibling, so the differentiation is left to inference.
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?
There is no statement of when to use this versus alternatives, nor any prerequisite or exclusion. The only 'guidance' is the required transaction_id, which the schema already imposes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
numeral_pingPing (health check)ARead-onlyInspect
Health check — verifies the API key works and reports the environment (test/prod), api_version, and server timestamp. Numeral: GET /tax/ping.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, so safety is already covered. The description adds real context beyond that: it confirms the tool validates the API key (an auth-related check) and enumerates the environment/api_version/timestamp it reports.
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 leads with the purpose ('Health check') then the specifics, plus a compact REST endpoint note. 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?
No output schema exists, and the description compensates by naming the returned fields (environment, api_version, timestamp), which is exactly what an agent needs from a ping 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?
Zero parameters, so there is nothing to document and no schema gap to compensate for. Baseline 4 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+resource — a health check that verifies the API key and reports environment, api_version, and server timestamp. This is unambiguous and clearly distinct from all sibling tools, which are tax/customer/product/transaction operations.
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 by the nature of a ping (verify connectivity and credentials before other calls), but the description never explicitly says when to call it. With no overlapping sibling to disambiguate against, the vagueness is low-cost, keeping this at a minimum-viable 3.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
11 tool updates
- Changed
numeral_calculate_tax1 field changed- changed
Input schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
- Changed
numeral_create_customer1 field changed- changed
Input schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
- Changed
numeral_create_product1 field changed- changed
Input schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
- Changed
numeral_create_refund1 field changed- changed
Input schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
- Changed
numeral_create_transaction1 field changed- changed
Input schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
- Changed
numeral_get_customer1 field changed- changed
Input schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
- Changed
numeral_get_product1 field changed- changed
Input schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
- Changed
numeral_get_transaction1 field changed- changed
Input schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
- Changed
numeral_list_products1 field changed- changed
Input schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
- Changed
numeral_list_transaction_refunds1 field changed- changed
Input schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
- Changed
numeral_ping1 field changed- changed
Input schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
11 tool updates
- First observed
numeral_calculate_tax - First observed
numeral_create_customer - First observed
numeral_create_product - First observed
numeral_create_refund - First observed
numeral_create_transaction - First observed
numeral_get_customer - First observed
numeral_get_product - First observed
numeral_get_transaction - First observed
numeral_list_products - First observed
numeral_list_transaction_refunds - First observed
numeral_ping
Related MCP Connectors
Financial OS for small businesses: transactions, invoices, customers, time tracking and reports.
Bookkeeping for owner-operated businesses. Query transactions, invoices, and reports.
Real-time US and Canadian sales and use tax rates by address or geo coordinates.
Create invoices, quotes, receipts and credit notes with GST or VAT, as prefilled links or PDFs.
Related MCP Servers
- AlicenseAqualityAmaintenanceMerchant of record MCP server: create products, payment links, checkouts, subscriptions, invoices and discount codes, with VAT and sales tax handled in 135+ jurisdictions.43114 npm4Apache 2.0

AgentTax MCP Serverofficial
AlicenseAqualityDmaintenanceEnables MCP tool developers and AI agents to track payments, calculate sales tax liability, and ensure tax compliance across US jurisdictions.644 npmMIT
Subotiz MCPofficial
AlicenseNot gradedqualityCmaintenanceEnables AI agents to manage subscriptions, usage-based billing, payments, refunds, tax compliance, and invoicing to drive revenue growth.1MIT- AlicenseAqualityAmaintenanceTalk to your GnuCash books: a one-call financial dashboard (net worth, runway, budgets, what's overdue), and whole bank statements entered and reconciled in a single call from CSV, OFX, PDF, or even a screenshot or photo of the statement. Plus transactions, invoices, reports and multi-currency; local, SQLite/PostgreSQL/MySQL.8779MIT
Glama MCP Gateway
Add one secure layer between your agents and this server.