Moltline Merchant Maths

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and closed-world behavior. The description adds a clear error contract: invalid input returns an {"error": ...} object rather than raising a protocol error, and it notes that retrying after correction is safe.

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 core purpose is front-loaded, followed by a concise example, usage guidance, and error behavior. Despite covering several points, every sentence contributes useful information for correct invocation.

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?

The tool is simple, has an output schema, and the description still covers purpose, inverse relationship to a sibling, example input/output, usage exclusions, and error semantics. Nothing material is missing for an agent to call it 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 description coverage is 100%, so parameter definitions already carry the baseline. The description still adds value by showing the semantic relationship through a concrete example: net_target 100 with 2.9% and $0.30 fees returns charge 103.4, fee 3.4, net 100.0.

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 computation in concrete terms: compute gross charge from a target net after percentage and fixed fees. It also distinguishes itself explicitly as the inverse of processor_fees, so an agent can tell it apart from sibling calculation 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?

Gives explicit when-to-use guidance ('Use when the payout is the fixed requirement') and when-not-to-use guidance ('Not when the price is already set'), and names processor_fees as the inverse alternative.

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 readOnly/idempotent/closed-world annotations, the description discloses non-obvious behavior: it never raises a protocol error, instead returning {"error": "<what is wrong and how to fix it>"} with a concrete example message, and it states retry is always safe after correction. It also flags the PREMIUM licensing constraint, which annotations do not cover.

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 purpose and the exclusion are front-loaded, and the example output JSON earns its space by showing exactly how the two methods diverge. Slightly long overall—the full six-field sample response could be trimmed—but no sentence is 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 two-parameter read-only calculator with a full output schema, the description supplies everything an agent needs: purpose, routing rule, error contract, retry safety, and licensing caveat. Nothing required 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 coverage is 100%, so the baseline is 3; the description goes beyond it by supplying a worked input {"price": 200, "discounts_pct": [20, 10]} that concretely demonstrates that the array order is the application order. Validation bounds are left to the schema (exclusiveMinimum, minItems), which 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 opening line names a specific operation ('stack discounts') and a specific analytical distinction ('sequential vs additive comparison'). It explicitly rules out a sibling ('Not for a single discount inside an invoice (invoice_total)'), so an agent can route between this and invoice_total without opening either 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?

It states the trigger condition directly: 'Use when more than one discount applies and the order changes the answer,' and names the alternative tool for the excluded case. Both the when-to-use and the when-not-to-use are explicit, with the sibling named.

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 provides rich behavioral context far beyond the annotations. It explains the rounding logic ('Rounding remainders land on the final payment'), the specific licensing requirement, and the critical error handling format (returning a structured error object instead of raising a protocol exception).

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 definition is logically structured, flowing from the main purpose to an explicit example, and then concluding with technical constraints and error handling. Every sentence adds critical, non-redundant value.

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 that this is a calculation and scheduling tool, the definition is exceptionally complete. It covers the math, the business constraints (license), the operational safety (read-only/idempotent), and the specific error reporting structure.

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?

While the input schema provides 100% coverage, the description significantly enhances the semantics by providing a concrete, fully worked example of inputs and expected outputs, which helps an agent visualize the calculation.

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 immediately states the core function: 'Split a total into an installment schedule with optional deposit.' It distinguishes itself from sibling tools like invoice_total by focusing on the scheduled payment creation rather than just total calculation.

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 usage guidelines are perfectly clear, defining the correct use case ('one total is paid across scheduled dates') while providing a clear exclusion ('Not for partial-period adjustments (proration)').

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 cover read-only, idempotent, non-destructive, and closed-world behavior. The description adds important error behavior beyond annotations: malformed input returns an {"error": ...} object instead of a protocol error, and retry after correction is safe.

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 purpose is front-loaded and the usage and error guidance are easy to scan. The full input/output example is useful but somewhat verbose, especially since an output schema exists.

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 a computation tool with complete schema documentation, rich annotations, and an output schema, the description supplies the remaining operational context: usage boundaries, error contract, and retry safety.

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 schema already documents tax_pct, discount_pct, and the line_items shape including the 100-item cap. The description's input example is helpful but largely illustrates rather than adding new parameter semantics 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: totals an invoice and enumerates the exact components computed (per-line totals, subtotal, discount, tax, grand total). It clearly distinguishes itself from processor_fees and installment_plan by naming those siblings as out of scope.

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: several line items rolling up with discount and tax. It also names two alternatives and the conditions that select them, so an agent has direct routing 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?

Annotations already cover read-only, idempotent, and non-destructive behavior, and the description adds meaningful context beyond them: preset rates are editable and should be verified, the tool is free, it returns structured error objects rather than protocol errors, and retry is safe after correcting input.

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 front-loaded and structured around purpose, usage, example, and error behavior. It is slightly verbose in places, repeating read-only/idempotent behavior already covered by annotations, but the information remains useful.

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 fee-calculation tool with an output schema, the description provides everything an agent needs: purpose, when to use it, sibling alternative, example input/output, preset caveat, and error behavior.

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 baseline is 3. The description adds a concrete example input and clarifies that custom_pct and custom_fixed are for the custom processor option, which gives useful 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 states a specific action and resource: breaking down payment-processor fees into fee, net, and effective rate. It also explicitly distinguishes this tool from the sibling `charge_to_net` by stating that this is not the reverse calculation.

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 an explicit usage condition: use when the charge amount is known and the net payout is the question. It also names the alternative tool for the reverse case and explains safe retry after input errors.

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 declare readOnlyHint, idempotentHint, and destructiveHint=false, but the description adds substantial context beyond them: it states the tool never raises a protocol error, describes the error-return shape, and explains that retrying after correction is always safe. That is exactly the kind of behavioral detail an agent needs to handle failures and retries confidently.

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 compact and front-loaded: the core purpose comes first, followed by a compact worked example, usage routing, error contract, and retry safety. Every sentence carries information an agent needs, with 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?

The tool is a simple read-only calculation with an output schema already present, so the description does not need to explain return values in detail. It still covers the worked example, error behavior, usage boundaries, and idempotency, leaving nothing critical for an agent to infer before calling it.

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 every parameter. The description still adds value by walking through a concrete input/output example that maps amount_per_period, days_used, and days_in_period to the returned prorated_charge and prorated_refund. It does not explain refund_mode in the description, which keeps it from a 5.

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 opens with a specific verb and resource: 'Compute a prorated charge or refund for a partial billing period.' This is precise enough to distinguish the tool from siblings like installment_plan, which is explicitly named as the wrong tool for scheduled payments.

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 an explicit when-to-use condition ('a plan starts, ends, or changes mid-period') and an explicit when-not-to-use alternative ('Not for splitting a full amount into scheduled payments (installment_plan)'). The routing decision is fully specified.

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