Bills of sale for equipment, vehicles and stock: draft, finalize, print with signature lines.
Glama couldn't complete the latest health check. If this server requires authentication, missing or expired test credentials may be the cause. A test profile lets Glama authenticate for health checks and discover tools; it is separate from your personal connections.
If you are the author, claim ownership, then add or update a test profile under Admin → Test Profile.
Scored across 10 tools
Each tool targets a distinct action: license activation/status are clearly separated from the sale lifecycle tools, and sale_create/get/list/update/delete/finalize/render/summary each have unique responsibilities. There is no meaningful overlap or ambiguity between tools.
All tools follow a consistent resource_action snake_case pattern: license_* for licensing and sale_* for bill-of-sale operations. Verb choices are clear and uniform, making the set predictable for an agent.
Ten tools is well-scoped for a bill-of-sale server: two licensing support tools plus eight covering the full document lifecycle and reporting. Each tool earns its place without redundancy or bloat.
The surface covers the full lifecycle: create, read, update, delete, finalize, render, list, and summarize bills of sale, plus license activation and status. No obvious dead ends or missing core operations for the stated purpose.
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?
Annotations already indicate this is not read-only and not destructive, and the description adds useful behavioral detail: existing data under the token stays, and a wrong or expired key changes nothing. This goes beyond the annotation hints by explaining failure semantics and safety of the operation.
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 with no filler. It front-loads the core action, then gives the key format and safety guarantees, and closes with the verification tool. Every sentence contributes essential 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?
For a single-parameter activation tool with annotations covering the safety profile, the description is complete: it states what the tool does, what input is needed, what happens on failure, and how to confirm success. There is no missing critical information 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?
The schema already documents the key parameter and its format with 100% coverage. The description adds meaning by specifying that the key must be issued at checkout for this server or the bundle, which clarifies validity requirements not present in 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 uses a specific verb and resource: it 'turns Pro on' for the connection using a license key. It also distinguishes itself from the sibling license_status tool by saying license_status confirms the activation. This leaves no ambiguity about what the tool accomplishes.
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 provides clear context for use: the key must be an MCPL1.<payload>.<signature> issued at checkout for this server or the bundle. It does not explicitly list exclusions or alternative tools, but it does reference license_status as the confirmation path, giving the agent a sense of the workflow.
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?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds useful context beyond annotations by specifying the JSON response contents and stating 'nothing changes,' reinforcing the read-only nature of the call.
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 dense sentences cover output, purpose, usage context, and side-effect guarantee. Every sentence earns its place and the most important 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 sufficiently describes the return value. With no parameters, annotations covering safety, and a clear use case, nothing essential is missing for an agent to invoke 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?
There are zero parameters and the schema already fully documents that fact. The description explicitly says 'No arguments,' which is accurate and reinforces the schema without needing further elaboration.
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 begins with a specific verb ('Report') and a precise resource ('this endpoint's licence state for your token'), and enumerates the exact output fields: product, tier, reason, and checkout URL. This clearly distinguishes it from sibling tools like license_activate.
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 states when to call it: 'Call it to explain a free-tier refusal.' This is clear contextual guidance, though it does not name alternatives or explicitly state 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.
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?
Annotations only say the operation is not read-only, not idempotent, and not destructive. The description adds valuable behavioral context: it creates a mutable draft (not a final document), returns a generated identifier, can be blocked by duplicate detection (implied by duplicate_ok), and is subject to a free-tier limit. It does not explicitly mention side effects like persistence or confirmation requirements, but the draft lifecycle 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 compact, front-loaded with the primary action and outcome, and every clause earns its place: it covers the data captured, the return value, the draft lifecycle, sibling routing, and the free-tier limit in three sentences. No filler or repetition of schema details.
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 23 parameters, 100% schema coverage, and no output schema, the description covers the essential context: what the tool does, what it returns, how the result relates to sibling tools, and a quota hint. It could be slightly more complete by explaining what happens on duplicate or invalid input, or by noting that sales can be deleted, but the core context an agent needs to invoke it correctly is present.
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 description adds meaningful context beyond the schema by grouping fields conceptually (who sold, who bought, what item, price in minor units, date) and explaining the returned document number. It also clarifies that price_minor uses integer cents with an example. Most parameters are fully described in the schema, so the description does not need to repeat every field; the added context is useful without being redundant.
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 ('Record a sale') and immediately states the outcome ('generate the bill of sale'), listing the exact data fields involved and the returned artifact ('BOS-YYYY-NNNN number of the draft'). It distinguishes itself from sibling tools by naming sale_update, sale_finalize, and sale_render and clarifying the draft lifecycle, so an agent can tell it apart without inspecting 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?
The description explicitly defines when to use this tool: to record a sale and create a draft. It names the exact siblings for later operations—sale_update for changes, sale_finalize for freezing into the signing copy, sale_render for printing—and includes a free-tier constraint ('Free tier: 10 drafts'). It also highlights key options like duplicate_ok and as_is defaults, providing clear context and exclusions.
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?
Beyond the destructiveHint annotation, the description discloses important behavioral consequences: drafts are deleted outright, finalized deletions require explicit confirmation, and the BOS number is never reissued, leaving a gap in the series. This gives an agent practical knowledge about side effects and domain-level implications of the deletion.
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 focused sentences with no wasted words. The primary action is front-loaded, and the nuanced rules about finalized documents and BOS number reuse are concise yet complete. Every sentence contributes meaningful 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?
For a delete operation with only two parameters, complete schema descriptions, and a destructive annotation, the description covers the essential behavior and consequences. It explains the difference between deleting drafts and finalized documents, the confirmation flag, and the lasting series gap. No output schema is present, and none is needed for this action.
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 schema already documents both parameters. The description adds value by explaining the meaning of the BOS number in the deletion context and why confirm_finalized is required for finalized documents, including the local-copy rationale. This goes beyond the schema's basic field descriptions.
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: 'Delete a bill of sale by its BOS number.' This clearly distinguishes the tool from siblings like sale_create, sale_finalize, and sale_update. The rest of the description reinforces the destructive delete purpose without ambiguity.
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 clear context for when deletion applies and how finalized versus draft documents are handled. It explicitly states that a finalized document requires confirm_finalized=true and explains why this is necessary. It does not name alternative tools or state when not to use deletion, but the unique delete action makes those exclusions less critical.
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?
Annotations only indicate the operation is not read-only, not idempotent, and not destructive, so the description carries the burden of explaining side effects. It goes well beyond that: the document becomes frozen, sale_update refuses it, later renders omit the DRAFT watermark, and a free-tier limit of 5 applies. This is rich, useful behavioral disclosure.
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 with no filler. The first sentence front-loads the core purpose and the most important behavioral consequence, and the second efficiently adds the quota constraint. 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 one-parameter mutating tool with no output schema, the description covers the essential facts an agent needs: what finalize does, the irreversible freeze, downstream effects on update and render, and the quota. Nothing critical appears missing for correct invocation.
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 fully documents the only parameter, 'sale,' including its type, maximum length, and an example value. The description does not add parameter-specific detail beyond identifying the bill of sale, so baseline 3 is appropriate given the 100% schema coverage.
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 verb and resource: 'Finalize a bill of sale so it is ready to sign.' It also distinguishes itself from sibling tools by explaining that the document is frozen, sale_update refuses it afterward, and renders become the signing copy. There is no ambiguity about what operation is performed.
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 makes the usage context clear: it is the step that makes a bill of sale ready for signing, after which updates are refused and renders use the signing copy. It does not explicitly name alternative tools or state 'use when X, not Y,' but the lifecycle context is strong enough to guide correct selection.
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?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds meaningful behavioral detail by disclosing the returned content fields, including party names, item identifiers, price, terms, and draft/finalized status.
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 a single front-loaded sentence that leads with the action and key, then efficiently enumerates the returned content. Every clause earns its place, and there is no redundant phrasing.
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?
Despite having no output schema, the description compensates by clearly indicating the return contents. Combined with a single well-documented parameter and safety-bearing annotations, an agent has everything needed to invoke 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 description coverage is 100%, and the schema already documents the parameter as 'The bill of sale id, e.g. BOS-2026-0001'. The description adds the phrase 'by its BOS number', reinforcing the identifier semantics, but contributes little beyond what the schema already provides.
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 ('Read'), resource ('one bill of sale'), retrieval key ('BOS number'), and scope ('in full'). It enumerates exactly what content is included, which distinguishes it from sibling tools like sale_list, sale_summary, and sale_render.
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 clearly implies when to use this tool: when the full details of a single bill of sale are needed by its BOS number. It does not explicitly name alternatives or exclusion cases, but the 'in full' and 'one bill of sale' language gives clear context against the siblings.
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?
Annotations already establish read-only, idempotent, non-destructive behavior. The description adds useful behavioral detail beyond that: newest-first ordering, inclusion of both drafts and finalized documents, and the exact attributes returned. It does not mention pagination or the 500-row limit, but those are discoverable in the schema and minor for this simple read operation.
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 carry the full semantic load with no filler. The action and scope appear first, followed by the returned fields and filter capability.
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 low-complexity read-only list tool, the description plus schema covers required parameters, filtering, ordering, and return fields. The only minor gap is that the phrase 'every bill of sale' is not qualified by the 500-row limit, but the limit is specified in the schema and there is no pagination expected.
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 both parameters carry clear descriptions and enums. The tool description restates the status filter but adds no new meaning beyond the schema, matching the baseline for high-coverage schemas.
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 ('List every bill of sale'), adds scope (drafts and finalized), ordering (newest first), and the returned fields. This makes it easy to distinguish from the single-document sale_get and aggregate sale_summary 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?
The context for using the tool is clear: it is the list-all operation with an optional status filter, contrasted implicitly with sibling tools that create, delete, finalize, get, or summarize bills of sale. It does not explicitly name alternatives or say when not to use it, but the scope statement leaves little ambiguity.
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 annotations carrying no information beyond four false hints, the description supplies substantial behavioral context: DRAFT watermark on review copies, self-contained HTML, one-hour download-link validity, out_path being only a naming stem, and the cost being free. This goes well beyond the schema and 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 compact and front-loaded with purpose and formats. Each sentence conveys useful behavior, though the final "Free" and the repeated out_path stem detail add marginal value beyond the schema.
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 tool with no output schema and non-informative annotations, the description covers output form, delivery mechanism, naming semantics, and safety watermarking. It does not spell out response structure or error behavior, but the download-link statement gives enough context for correct invocation.
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 each parameter already has a detailed description, so the baseline is 3. The description mostly repeats what the schema says (download links, out_path stem behavior) rather than adding new parameter-level 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?
The description states a precise action and object: "Render a bill of sale as a clean printable document" with specific formats and signature lines. This clearly distinguishes it from the CRUD/status siblings like sale_get and sale_finalize by identifying it as the printing/rendering operation.
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 intended use case is implied (produce printable or print-to-PDF copies of a bill of sale, including watermark-protected drafts), but the description never explicitly says when to choose this over siblings such as sale_get or sale_summary. There is no exclusions/alternatives section.
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?
The annotations already establish read-only, idempotent, and non-destructive behavior. The description adds non-obvious behavior not covered by annotations: drafts are separated from finalized documents und currencies are never added together. The 'Free.' note also contributes context, though it is somewhat ambiguous.
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: it states the verb, the resource, and the exact output contents in one tight sentence. 'Free.' is terse and communicates an additional trait without wasting 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?
With no parameters and no output schema, the description carries the full burden of explaining what the tool returns—and it does: document counts by status, sold value per currency, and the rule that currencies are never summed. That is complete for a no-argument read-only 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 schema has zero parameters, so the description cannot add parameter-level meaning—it has nothing to clarify. The 0-parameter baseline of 4 applies, and no parameter information is missing.
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 names the resource ('the book') and enumerates exact outputs: counts of drafts and finalized documents, and total sold value per currency with drafts separate. This makes the tool clearly distinct from siblings like sale_get and sale_list, which operate on individual records.
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 aggregate-summary intent is unmistakable from the described outputs, so an agent can tell when to select this over per-sale tools. It does not explicitly name alternatives, but the distinction between summarization and individual-record access is contextually clear without exclusions.
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?
Beyond the annotations (which only indicate a mutable, non-idempotent write), the description explains editing semantics, including that empty strings clear optional fields and that finalized documents are immutable. It does not discuss authorization, response payload, or error behavior, but the key behavioral constraints are disclosed.
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 lead with the operation, then give the clearing convention, then state the immutable-state limitation. No filler or repetition.
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 broad update tool with 23 parameters and no output schema, the description covers what can be changed, the clearing convention, and the finalization gate. It omits auth/error/return details, but nothing essential for basic invocation 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?
With only 22% schema-description coverage, the description compensates by grouping parameters into meaningful categories (price, buyer, seller, item details, identifiers, as-is, warranty, notes) and adding the clearing rule for optional fields. It does not walk through every one of the 23 parameters, but the categories plus schema cover most practical needs.
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 clear verb and resource ('Change anything on a bill of sale') and states the lifecycle constraint ('not finalized yet'). It also enumerates the updatable field categories, which distinguishes it from sibling tools like sale_finalize and sale_create.
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 condition for use ('not finalized yet') and an explicit exclusion ('A finalized document cannot be edited'). It does not name alternative sibling tools, such as sale_finalize, so it falls just short of fully explicit routing.
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.
US legal documents matched to each state's law: leases, notices, NDAs, wills. PDF or Word.
Make documents in your brand from your data and send them for acceptance or signature.
Draft UK vehicle sales invoices from supplied deal facts, with totals and a private review link.
Add one secure layer between your agents and this server.