Create an accounts receivable credit memo with customer, date, reason code, and line items; optionally link it to a specific invoice.
Create a credit memo (AR) in KikoBooks. Requires customer ID, date, reason code, and at least one line item. Can be linked to a specific invoice.
| Name | Required | Description | Default |
|---|---|---|---|
| creditMemo | Yes |
Changes observed during successful MCP inspections.
v0.2.9Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only restates the schema's required fields and the optional invoice link; it does not say whether the memo is posted to AR/GL, whether it requires specific permissions, whether the operation is reversible, or what defaults apply to currency and accounts.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short, front-loaded sentences with no filler; purpose comes first, then requirements, then the optional linkage. The requirements sentence partly duplicates the schema's required array, which is the only mild redundancy.
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 mutation tool with a deeply nested payload (~15 line/header fields), no annotations, and no output schema, the description is too thin. It omits whether a result ID is returned, posting/approval behavior, error conditions on invalid customer or reason codes, and guidance on the optional header fields.
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?
Top-level schema coverage is 0% and the single 'creditMemo' object is undocumented in the schema, so the description must compensate. It names the required members (customer, date, reason code) and adds the real constraint that at least one line item is needed (not encoded as minItems in the schema), but it says nothing about the many optional fields (CurrencyCode default, GL overrides, customer/internal messages) or the nested line-item shape.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Create a credit memo (AR) in KikoBooks'), which cleanly separates it from the read-side siblings search_credit_memos and get_credit_memo. The AR qualifier pins the domain unambiguously.
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 closing line 'Can be linked to a specific invoice' implies one usage context, but there is no explicit when-to-use vs alternatives (e.g. void_bill, create_payment/refund) and no prerequisites or exclusions. Usage is only inferable from the note about invoice linking.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.