numeral

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

Annotations indicate readOnlyHint=true, and the description reinforces the stateless nature with 'persists nothing'. It adds details about the API endpoint, amounts in smallest currency unit, and that the calculation is not saved, providing full transparency beyond annotations.

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 description is two sentences, front-loaded with the core function and stateless nature, then appending key details (return values, input requirements, currency unit, API endpoint). Every sentence earns its place with no wasted words.

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 no output schema, the description explains return values (per-jurisdiction rates, totals, calculation id). It covers the stateless workflow, required inputs, and parameter nuances (currency, address types, product identification). Highly complete for a tax calculation tool with nested objects.

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 baseline is 3. The description adds meaning: line items need reference_product_id OR product_category, address_type distinguishes shipping vs billing, origin_address required on newer API versions, and currency code constraints. This adds significant value beyond the schema definitions.

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 clearly states it calculates sales tax/VAT for an order, distinguishes itself as a stateless quote, and mentions key return fields like per-jurisdiction rates and total_tax_amount. It also contrasts with sibling numeral_create_transaction by indicating the calculation id should be recorded later.

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 states the tool is for stateless quoting and not for persisting data, guiding to use numeral_create_transaction with the returned calculation id for recording. Provides context on required inputs (customer address, line items) but does not explicitly state when not to use it, though the stateless nature is clear.

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

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

Annotations set destructiveHint=true, and description reinforces this by stating 'WRITES' and providing the endpoint. It adds context about purpose (order tracking, tax exemptions) without contradicting annotations.

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 sentences: first states action and side effect, second specifies the exact API endpoint. No wasted words, 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?

No output schema, but description explains what the tool does and its purpose. Missing return value description, but overall sufficient for a creation 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 covers all 4 parameters (100% coverage), and description does not elaborate further on parameter meaning or constraints. Baseline score 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?

Description uses specific verb 'CREATES' and specifies resource 'customer record', clearly distinguishing from siblings like numeral_calculate_tax or numeral_list_products.

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?

Description implies usage for order tracking and tax exemptions but provides no explicit guidance on when not to use or alternatives. Adequate but lacks precision.

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

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

The annotations already provide destructiveHint=true, so the description correctly reinforces that this tool modifies state. It adds valuable behavioral context beyond annotations: it specifies the upsert behavior (create or update) and the side effect that the change affects future tax calculations. This exceeds the baseline set by annotations.

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 description is extremely concise: two sentences that front-load the key verb and resource, then explain the broader impact. Every sentence adds unique value, with no redundancy or filler. The API endpoint reference is useful but not verbose.

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 the tool has 3 fully-described parameters, destructiveHint annotation, and no output schema, the description provides enough context about the action and side effects. However, it omits what the tool returns (e.g., the created product object), which is a gap for an agent needing to use the result.

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 input schema has 100% description coverage, with each parameter already documented. The description does not add additional parameter details beyond what the schema provides, so it meets but does not exceed the baseline of 3.

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 clearly states the tool creates or upserts a product with its tax category, specifying the resource ('product') and the action ('create/upsert'). It distinguishes from sibling tools by explicitly mentioning the product catalog and the API endpoint, making it clear this is for product creation, not for customers, transactions, or refunds.

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 description implies usage when you need to add or update a product for tax calculations, as it writes to the Numeral product catalog that drives future tax calculations. However, it offers no explicit 'when to use' vs 'when not to use' guidance, nor does it name alternatives like getting or listing products.

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

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

Beyond the destructiveHint annotation, the description explains it adjusts tax owed and creates a compliance record. It adds context about the write nature and tax implications.

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 description is three sentences, front-loaded with the main purpose, and every sentence adds value. No redundant information.

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, but description does not mention what the tool returns or error conditions. For a write tool with destructive hint, some mention of expected response or side effects would be beneficial.

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 baseline 3. The description echoes the schema's parameter info (type, line_items) but adds little new semantics beyond the effect on tax.

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 clearly states it records a refund against a transaction and writes a live tax/compliance record. It specifies the two modes (full/partial) and differentiates from siblings, which are all unrelated.

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?

Provides explicit guidance on using type='full' vs type='partial' with line_items. Does not mention when not to use or prerequisites, but given no sibling refund tool, this is sufficient.

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

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

Reinforces destructiveHint by noting it writes a live record used for filings. Does not disclose idempotency or permission requirements.

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 concise sentences front-loading purpose and key instructions, with API reference appended.

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?

Covers purpose, usage, and key parameters; lacks description of return value (since no output schema), but remains adequate for a write 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 coverage is 100%, and description highlights required parameters but adds no extra context for metadata or timestamp parameters.

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 clearly states the tool records a completed sale as a transaction for tax/compliance filings, distinguishing it from calculation and refund siblings.

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 states to supply calculation_id from numeral_calculate_tax and reference_order_id, indicating prerequisites. Lacks explicit when-not-to-use or alternative guidance.

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

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

The annotation already declares readOnlyHint=true, and the description aligns by describing a read operation. The description adds behavioral context by specifying that the tool returns name, email, and tax-exempt status, and how id_type affects lookup behavior. No contradiction.

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 description is two sentences, front-loaded with the purpose, and no unnecessary words. Every sentence adds value: first for purpose and id_type, second for return content and endpoint.

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 the tool's simplicity (get by id, no output schema), the description is complete. It covers the operation, parameter variations, and return content. No missing critical information.

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% with clear descriptions for both parameters. The description adds the endpoint and return fields but does not provide additional parameter semantics beyond the schema. Baseline score of 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?

The description clearly states 'Get a customer by id' with specific verb and resource. It distinguishes between two id types (numeral vs reference) and mentions what is returned (name, email, tax-exempt status), setting it apart from sibling tools like numeral_calculate_tax or numeral_list_products.

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 description explicitly explains when to use each id_type parameter, providing clear context. However, it does not specify when not to use this tool or mention alternatives, which would be helpful but is not critical for a straightforward getter.

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

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

Annotations already provide readOnlyHint; the description adds the HTTP method and spec of returned fields, offering context beyond annotations without contradiction.

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 efficient sentences that front-load the core purpose and returns, with no waste.

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 simple 1-param tool with no output schema, the description fully covers what it does, what it returns, and the underlying API call.

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 parameter description in schema is clear; the tool description reinforces it by noting 'your id' and referencing creation time, adding clarity.

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 clearly states the verb 'Get', the resource 'single product', and the identifier 'reference_product_id (your id)', making it unambiguous and distinct from list tools.

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?

Implies use when you need a single product by its ID, but does not explicitly contrast with list_products or mention when not to use it.

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

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

Annotations already mark readOnlyHint=true, and the description confirms a read operation ('Get'). It adds useful context about what the response contains (line items, currencies, metadata), going beyond annotations.

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 description is concise with two sentences that front-load the core purpose and action, plus a reference to the API endpoint. No wasted words.

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 simple get tool with one param and no output schema, the description covers purpose, parameter format, and return content. Lacks exact output structure but is sufficient given the simplicity.

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% with a description for the only parameter. The description reiterates the id format (tr_...) and context, but does not add significant new meaning 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 clearly states the tool retrieves a recorded transaction by its Numeral id (tr_...), and distinguishes from sibling tools like numeral_create_transaction or numeral_list_products by focusing on retrieval of an existing resource.

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 description implicitly indicates that this tool is used when you have a transaction id and need details, but it does not explicitly state when to use it versus alternatives or when not to use it.

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

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

Annotations provide readOnlyHint, and description adds pagination limits (up to 50 per page), cursor usage, has_more flag, and the HTTP method/endpoint. No contradictions.

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 concise sentences, front-loaded with purpose and key details. No unnecessary words.

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?

Tool is simple, and description covers all needed context: pagination, fields returned, and API endpoint. No output schema needed, but description fills gap.

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?

Single parameter cursor is described in both schema and description. Description adds context (last_product_id) but schema already provides the same explanation. Schema coverage is 100%, 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?

Description clearly states verb 'List', resource 'Numeral products', and specifies fields returned (reference id, name, product_category). Distinguishes from sibling tools like numeral_create_product and numeral_get_product.

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?

Provides explicit pagination instructions using cursor and has_more. Does not explicitly state when not to use or list alternatives, but context is clear for paginated listing.

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

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

Annotations already indicate readOnlyHint=true, so the safe read nature is clear. The description adds that it returns {refunds:[...]} and the HTTP method (GET), providing additional transparency beyond annotations.

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 description is extremely concise with two short sentences. It front-loads the action and resource, and includes key details (return format, endpoint) without any fluff.

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 simple list tool with one parameter, the description covers purpose, return format, and endpoint. Though no output schema exists, the description specifies the output structure. No major gaps are apparent.

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 input schema already has 100% coverage with a description for the only parameter (transaction_id). The description adds no parameter meaning beyond the schema, so baseline score 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 clearly states the action (list refunds) and the resource (transaction), and includes the return format and HTTP endpoint. It is distinct from sibling tools like 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?

The description implies usage context (when you need refunds for a transaction) but does not explicitly state when not to use or mention alternatives like create_refund. Guidelines are implicit but not explicit.

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

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

The description adds value beyond annotations. Annotations declare readOnlyHint=true, but the description elaborates on the specific outputs (environment, api_version, server timestamp) and confirms it's a GET request, providing full transparency on 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 succinct sentences: one explaining the action and returns, the other specifying the endpoint. No extraneous words, 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 simple, zero-parameter health check with readOnly annotations, the description is complete. It covers the purpose, behavior, and output without needing an output schema. No gaps remain.

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 has zero parameters and 100% schema description coverage. With no parameters to describe, the baseline is 4. The description does not need to add parameter info, and it correctly omits any.

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 clearly states the tool's purpose: a health check that verifies the API key and reports environment, API version, and timestamp. It also includes the endpoint path. This distinguishes it from all sibling tools, which focus on tax, customer, product, refund, and 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?

The description implies usage as a basic connectivity test but does not explicitly state when to use it versus alternatives. No guidance on when not to use or exclusions is provided, though the purpose is self-evident.

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