Bills of sale for equipment, vehicles and stock: draft, finalize, print with signature lines.
Scored across 10 tools
Each tool has a distinct resource and action, and the two license tools are cleanly separated from the eight sale-lifecycle tools. The sale tools also separate reading (sale_get, sale_list), writing (sale_create, sale_update, sale_delete), freezing (sale_finalize), printing (sale_render), and aggregating (sale_summary) without confusing overlap.
All tools use a consistent snake_case domain_action convention: license_* and sale_*. There is no mixing of camelCase, vague verbs, or inconsistent ordering.
Ten tools is well-scoped for a bill-of-sale server: eight cover the full document lifecycle and two handle licensing. No tool appears redundant or missing at the count level.
The surface covers full CRUD plus finalize, render, summary, and licensing status, so core workflows are complete. A minor gap is the lack of search or filtering by buyer, seller, item, or date beyond the status filter, which agents can work around by listing and reading individual documents.
Turn Pro on for this connection with key, an MCPL1.. issued at checkout for this server or the bundle. Data under your token stays; a wrong or expired key changes nothing. license_status confirms it.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | License key from checkout, MCPL1.<payload>.<signature> |
Does 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 explicitly states that data under the token stays and that a wrong or expired key changes nothing, which is valuable non-destructive and failure-mode context for an activation mutation.
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 tight sentences front-load the action and key requirement, then add side-effect guarantees and a pointer to verification. No wasted words or repetition beyond the schema format.
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 activation tool with no output schema and no annotations, the description covers the action, key eligibility, non-destructive behavior, failure mode, and how to confirm success. It could add explicit return-value expectations, but license_status confirms it largely covers that 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?
The schema already fully documents the key parameter, so the baseline is 3. The description adds meaningful semantics by explaining the key must be issued at checkout for this server or bundle and that invalid keys are no-ops, going beyond the schema's simple format description.
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 uses a specific action, 'Turn Pro on for this connection,' with a clear resource (license/Pro status) and key format. It also distinguishes itself from the sibling license_status by focusing on activation rather than checking status.
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 clearly conveys when to use the tool: when activating Pro with a checkout-issued key for this server or bundle. It also references license_status as the follow-up confirmation step, though it stops short of explicitly saying 'use license_status instead to check current status.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report this endpoint's licence state for your token as JSON: the product, the tier free or pro, why it is not Pro, and the checkout URL. Call it to explain a free-tier refusal. No arguments, nothing changes.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does 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 explicitly states 'No arguments, nothing changes,' indicating a read-only, side-effect-free operation. It does not detail error handling or authentication requirements, which are minor omissions for a simple status check, but the core behavioral trait (no mutation) is clearly communicated.
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, tightly packed with all essential information. It is front-loaded with the primary action and output, then adds the use case and side-effect note. Every sentence earns its place with no redundancy or 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 tool with no input parameters and no output schema, the description fully covers what an agent needs: the return format (JSON with product, tier, reason, checkout URL), the trigger condition, and the lack of side effects. Nothing essential 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?
The tool has zero parameters, and the description confirms 'No arguments.' Per the scoring rules, 0 parameters earns a baseline of 4. The description adds no parameter-specific meaning because none exist, and it correctly reiterates the absence of arguments, aligning with the empty 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 verb and resource: 'Report this endpoint's licence state for your token as JSON'. It explicitly enumerates the returned fields (product, tier, reason, checkout URL), making the tool's purpose unambiguous. It also distinguishes itself from sibling tools like license_activate by focusing on status reporting rather than activation.
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 gives a clear trigger for use: 'Call it to explain a free-tier refusal.' This tells the agent when to invoke this tool. It does not explicitly discuss alternatives or exclusions, but the purpose is distinct enough from siblings that the guidance is adequate; it could be improved by noting it is the only read-only license info tool, though that is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record a sale and generate the bill of sale: who sold, who bought, what item (with VIN, serial or IMEI where it has one), the price in minor units and the date. Returns the BOS-YYYY-NNNN number of the draft. The draft can still be changed with sale_update; sale_finalize freezes it into the signing copy and sale_render prints it. Free tier: 10 drafts.
| Name | Required | Description | Default |
|---|---|---|---|
| vin | No | Vehicle Identification Number, 17 characters, for a vehicle sale | |
| date | No | The date of the sale, YYYY-MM-DD. Default today | |
| imei | No | IMEI, 15 digits, for a phone or tablet | |
| as_is | No | Include the as-is clause: sold with all faults, no warranties except any written here. Default true, the norm for second-hand sales; pass false to leave it out | |
| notes | No | Anything else the document should say, e.g. payment method or what is included in the sale | |
| serial | No | Serial number, for equipment and electronics | |
| currency | Yes | ISO code the price is in | |
| quantity | No | How many units this document covers. Default 1 | |
| warranty | No | A warranty the seller does give, in their own words, e.g. The seller warrants the engine for 30 days from the sale date | |
| condition | No | The condition at handover, e.g. used, good working order, or new, sealed | |
| buyer_name | Yes | Who is buying, e.g. Jane Kowalska or Northwind Sp. z o.o. | |
| buyer_email | No | The buyer's email | |
| buyer_phone | No | The buyer's phone number | |
| price_minor | Yes | The sale price in whole minor units (integer cents). 120000 is USD 1,200.00 | |
| seller_name | No | Who is selling. Defaults to the shared business profile's name when the profile has one | |
| duplicate_ok | No | Record it even though an identical sale to the same buyer exists, for a genuinely repeated sale. Default false | |
| seller_email | No | The seller's email | |
| seller_phone | No | The seller's phone number | |
| buyer_address | No | The buyer's postal address, one string | |
| item_category | No | What kind of item, e.g. vehicle, equipment, electronics, stock | |
| seller_address | No | The seller's postal address, one string | |
| identifier_other | No | Any other identifying number, e.g. a hull number or an asset tag | |
| item_description | Yes | What was sold, specific enough to identify it, e.g. 2019 Honda Civic 1.5 petrol, grey, or MacBook Pro 14-inch 2021 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses the return value (BOS-YYYY-NNNN), the mutable-draft state, and the free-tier quota, but says nothing about permissions, duplicate-detection errors (only the duplicate_ok param implies it), or what happens when the quota is exhausted.
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 sentences, front-loaded with the core action and output, then the sibling workflow, then the quota. No filler; every clause carries information an agent needs.
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 23-parameter creation tool with no annotations and no output schema, the description supplies the return identifier, the lifecycle context, and the quota. It stops just short of describing failure modes such as duplicate rejection, though the schema's duplicate_ok parameter partly covers that.
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% with 23 well-documented properties, so the schema already does the heavy lifting. The description recaps the required concepts (who sold, who bought, item with VIN/serial/IMEI, price in minor units, date) but adds no syntax or format detail 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 ('record a sale'), then immediately scopes it as generating the bill of sale draft. It is clearly distinguishable from the sibling lifecycle tools it names.
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 routes the agent through the workflow: the draft created here can be changed with sale_update, frozen by sale_finalize, printed by sale_render. It also flags the free-tier limit of 10 drafts, which is a concrete when-to-call constraint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a bill of sale by its BOS number. A draft goes outright. A finalized document needs confirm_finalized true, because it is the local copy of a record the buyer may hold. The BOS number is never reissued, so a gap in the series is the record that a document was deleted.
| Name | Required | Description | Default |
|---|---|---|---|
| sale | Yes | The bill of sale id, e.g. BOS-2026-0001 | |
| confirm_finalized | No | Required true to delete a finalized document. Default false |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses irreversibility, the gated path for finalized documents, and the non-reissuance of BOS numbers, so the agent understands the consequence of leaving a gap in the series. It omits permissions/auth requirements and any response behavior, but the substantive deletion semantics are covered.
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, front-loaded with the action and selector, then the conditional rule, then the lasting consequence. No filler or 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 an unannotated delete tool with no output schema, the description supplies the essential context: how to target the record, the confirmation gate, and irreversibility. Only auth/permission expectations and any error behavior are left unaddressed, which is a minor 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?
Schema coverage is 100%, so a baseline of 3 would be defensible, but the description adds real meaning beyond the schema: it explains why confirm_finalized exists (the local copy may correspond to a record the buyer holds) rather than merely restating that it must be true for finalized documents.
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 first sentence gives a specific verb (delete) and resource (bill of sale) with the key selector (BOS number), which cleanly separates it from siblings like sale_finalize, sale_get, or sale_update. An agent can route here without opening the 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 conditional branch that governs usage: drafts delete outright, finalized documents require confirm_finalized=true. It does not name alternative tools or explicitly state when not to delete, but the draft-vs-finalized rule is concrete operational guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Finalize a bill of sale so it is ready to sign: the document is frozen from this call on, sale_update refuses it, and every later render is the signing copy without the DRAFT watermark. Free tier: 5 finalized documents.
| Name | Required | Description | Default |
|---|---|---|---|
| sale | Yes | The bill of sale id, e.g. BOS-2026-0001 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does so well: it discloses an irreversible state change (frozen from this call on), the downstream effect on sale_update (refuses the document), the effect on rendering (signing copy, no DRAFT watermark), and a concrete quota (free tier: 5 finalized documents). That is exactly the mutation, side-effect, and limit information an agent needs before calling.
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?
One tight sentence with a colon that front-loads the outcome (ready to sign) before the consequences, plus a short quota sentence. Every clause earns its place: freeze, sale_update refusal, render change, and tier limit.
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 state-transition tool with no annotations and no output schema, the description covers the mutation, its irreversibility, downstream effects, and rate/quota limits. It could add whether the call is idempotent on an already-finalized document or the failure mode when the free-tier cap is hit, but nothing essential 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?
There is a single parameter (sale) with 100% schema description coverage, including a format example (BOS-2026-0001). Per the calibration baseline, the schema does the heavy lifting here and the description adds no additional parameter meaning, so a 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 (Finalize) and resource (bill of sale) and immediately characterizes the resulting state: ready to sign. It also distinguishes itself from siblings by noting sale_update will refuse the document afterward and sale_render will emit the signing copy, so an agent can tell it apart from those tools without opening their schemas.
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 makes the use context clear (once finalized the document is frozen and becomes the signing copy) and effectively rules out sale_update as a follow-up path. It stops short of an explicit when-to-use/when-not statement or naming an alternative for un-finalizing, but the implied usage is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one bill of sale in full by its BOS number: both parties, the item and its identifiers, price, terms, and whether it is still a draft or the finalized signing copy.
| Name | Required | Description | Default |
|---|---|---|---|
| sale | Yes | The bill of sale id, e.g. BOS-2026-0001 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the burden. It usefully discloses that the record can be a draft or the finalized signing copy (state awareness). However, it says nothing about read-only nature, permission/authentication requirements, or behavior for an unknown/archived id.
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 no filler. The key retrieval verb leads, followed by the identifier, then the returned fields. Nothing is wasted.
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-param read tool with no output schema, the description adequately telegraphs the returned fields and draft/finalized state. It is nearly complete but omits error/not-found behavior and access constraints, which would round it out.
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?
Only one parameter, and schema coverage is 100% with an example format (BOS-2026-0001). The description adds the semantic meaning of 'BOS number' and that it must be singular, but adds no format or validation detail beyond the schema. Baseline 3 fits.
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 (Read) and resource (one bill of sale), identified by BOS number, and enumerates the full field set returned. It clearly distinguishes itself from siblings like sale_list (which lists many) and sale_summary (which presumably condenses).
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 phrase 'in full' implies this is the verbose/single-record retrieval path, and naming the BOS number as the key implies how to call it. But there is no explicit when-to-use/when-not guidance or named alternative (e.g., 'use sale_summary for a condensed view'). Usable but not routing-grade.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every bill of sale, drafts and finalized, newest first: id, status, date, item, buyer, seller and price. Filter to drafts or finalized documents with status.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum rows, default 500 | |
| status | No | Which documents to list: all (default), draft, or final |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does add real behavioral context — default result set includes drafts and finalized, ordering is newest-first, and the returned columns are enumerated — but it says nothing about permissions, pagination beyond the schema's limit, or how large result sets are handled.
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 tight sentences, front-loaded with the core action and scope, with the filter behavior second. No filler or 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 list tool with no output schema, the description compensates well by enumerating the returned fields (id, status, date, item, buyer, seller, price). Only pagination/offset behavior and permission requirements are left 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?
Schema description coverage is 100%, so both parameters (limit, status) are already fully documented with an enum and default. The description restates the status filter behavior without adding syntax or semantics beyond the schema, so the baseline of 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 (List), resource (bills of sale), and scope (drafts and finalized, newest first), plus the returned fields. An agent can distinguish this from sale_get or sale_summary without opening 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?
The second sentence implies when the status filter is useful (to narrow to drafts or finalized), but there is no explicit when-to-use guidance relative to siblings like sale_get or sale_summary, and no exclusions stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render a bill of sale as a clean printable document: Markdown, a self-contained HTML file ready for print-to-PDF, or both, with signature lines for seller and buyer. Drafts render with a DRAFT watermark so a review copy cannot be signed by mistake. Every file comes back as a download link valid for one hour, and out_path is only the stem the files are named with. Free.
| Name | Required | Description | Default |
|---|---|---|---|
| sale | Yes | The bill of sale id, e.g. BOS-2026-0001 | |
| format | No | What to render: markdown, html, or both (default). The HTML is one self-contained file, no external assets | |
| out_path | No | Name for the downloaded files, e.g. civic-sale; with format both, .md and .html are appended to the stem. Default: the document id. Each file comes back as a download link valid for one hour | |
| overwrite | No | Replace an existing file at out_path. Default false: an occupied explicit path is refused, a derived one gets -2, -3, ... |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses the DRAFT watermark safety behavior, the one-hour download-link lifetime, the stem-only semantics of out_path, and that it is free. It omits any auth/permission requirements and doesn't say whether the sale must be finalized to render without a watermark.
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?
Purpose is front-loaded in the first clause, followed by the differentiators (watermark, link lifetime, out_path semantics). Dense but every sentence adds a distinct fact; the trailing one-word 'Free.' is terse but informative.
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 usefully explains the return value (a download link valid for one hour) and the naming behavior, and covers the draft/final watermark rule. Remaining gap is preconditioning: nothing states whether the sale must be finalized or what happens on an invalid id.
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 sale, format, out_path, and overwrite. The description restates the out_path-as-stem rule and format default rather than adding new syntax or edge-case meaning, 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?
States a specific verb (render) and resource (bill of sale) plus the exact artifacts produced: Markdown, self-contained HTML, or both. This is unmistakably distinct from the CRUD siblings (sale_get, sale_list, sale_update) 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?
Usage is implied rather than stated: the DRAFT-watermark rule hints that this is meant for review copies before finalization, and 'Free' hints at a cost-free alternative to other rendering paths. But it never says when to call this versus sale_get/sale_finalize or whether a sale must be finalized first.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Summarize the book: how many drafts and finalized documents, and the total sold value per currency, drafts separate from finalized. Currencies are never added together. Free.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose meaningful behavior: drafts are reported separately from finalized documents and currencies are never added together, which tells the agent exactly how the aggregation is scoped. It also flags that the call is free. It does not confirm read-only status or permission requirements, but for a no-parameter summary the key behavioral semantics are covered.
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 tight sentences, front-loaded with the core action and its outputs, with the two key aggregation rules attached immediately after. 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?
There is no output schema, so the description must convey the return shape and it does: counts by state and totals per currency. It leaves minor questions open (e.g., whether deleted or archived sales are counted, what 'sold value' includes relative to discounts), but is complete enough to call 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?
The tool takes zero parameters, so there is nothing for the description to clarify and the baseline of 4 applies. No hidden filtering inputs are implied.
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 (summarize) and resource (the sales book), then enumerates exactly what is computed: draft vs finalized document counts and total sold value per currency. This is clearly distinguishable from siblings like sale_list or sale_get, which retrieve records rather than aggregate 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 description never says when to prefer this over sale_list or sale_get, nor any precondition for calling it. 'Free' hints that it is a cheap call, but that is a cost note, not usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change anything on a bill of sale that is not finalized yet: price, buyer, seller, item details, identifiers, the as-is clause, warranty or notes. Pass an empty string to clear an optional field. A finalized document cannot be edited.
| Name | Required | Description | Default |
|---|---|---|---|
| vin | No | ||
| date | No | The date of the sale, YYYY-MM-DD | |
| imei | No | ||
| sale | Yes | The bill of sale id, e.g. BOS-2026-0001 | |
| as_is | No | ||
| notes | No | ||
| serial | No | ||
| currency | No | ||
| quantity | No | ||
| warranty | No | ||
| condition | No | ||
| buyer_name | No | Who is buying | |
| buyer_email | No | ||
| buyer_phone | No | ||
| price_minor | No | The sale price in whole minor units (integer cents) | |
| seller_name | No | Who is selling | |
| seller_email | No | ||
| seller_phone | No | ||
| buyer_address | No | ||
| item_category | No | ||
| seller_address | No | ||
| identifier_other | No | ||
| item_description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It usefully discloses mutation semantics, the finalized-document restriction, and the empty-string clearing behavior, but omits permissions, side effects, and return 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 tightly written sentences with no wasted words. The main action is front-loaded, followed by field examples, clearing semantics, and the finalized restriction.
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 23-parameter mutation tool with no annotations, low schema coverage, and no output schema, the description is incomplete. It omits auth requirements, whether unspecified fields are preserved, failure behavior beyond finalization, and any response context.
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 only 22%, so the description must compensate. It groups updatable fields and adds the important empty-string clearing rule, but many parameters and their formats remain unexplained 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 verb and resource ('Change anything on a bill of sale') and scopes it to non-finalized documents. This clearly distinguishes it from siblings like sale_create and sale_finalize, which handle creation and finalization.
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 a clear condition for use ('not finalized yet') and an explicit when-not ('A finalized document cannot be edited'). It does not name alternative tools, but the usage boundary is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
license_activatelicense_statussale_createsale_deletesale_finalizesale_getsale_listsale_rendersale_summarysale_updateE-signature & document automation: create, send, track and sign documents with payments. 38 tools.
Draft UK vehicle sales invoices from supplied deal facts, with totals and a private review link.
E-signatures for contracts and NDAs. Draft with AI, review, and send for signature.
Generate attorney-drafted NDAs, MSAs, DPAs, and more as PDF, ODT, or Markdown. No account required.
