Create an empty draft invoice for a company and return it with its id. The draft has no customer or line items yet and starts with the company's auto-included payment methods; nothing is sent. Next set the customer, line items, dates and currency with update-invoice-draft, then finalize it with submit-invoice. To copy an existing invoice into a new draft, use duplicate-invoice instead.
| Name | Required | Description | Default |
|---|---|---|---|
| companyId | Yes | Company ID |
Changes observed during successful MCP inspections.
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnly=false, destructive=false, openWorld=false), and the description adds genuine behavioral context beyond them: the draft is created empty, it inherits the company's auto-included payment methods, and 'nothing is sent' to the customer. It stops short of mentioning permission/auth requirements, which keeps it from a 5.
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 action and the return value, then the resulting state, then the workflow and alternative. No sentence is redundant; the closing routing sentence earns its place by preventing misuse of this tool for duplication.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but the description covers the return value (the draft with its id) and the full lifecycle for the object it creates. With one fully documented parameter and annotations covering the mutation profile, an agent has everything needed 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?
There is a single parameter with 100% schema coverage, so the schema already documents companyId (including the numeric pattern). The description's 'for a company' only implies the resource scope and adds no format or constraint detail, so the 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 and resource ('Create an empty draft invoice for a company') plus the return value ('return it with its id'). It draws a clear boundary against siblings by describing the draft's initial state (no customer, no line items) and explicitly naming update-invoice-draft, submit-invoice and duplicate-invoice as the follow-on 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?
Provides an explicit step-by-step workflow: create draft here, then set customer/items/dates/currency with update-invoice-draft, then finalize with submit-invoice. It also names the alternative path (duplicate-invoice) for copying an existing invoice, so an agent knows both when to use and when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
