jobber_get_invoiceJobber: One invoice with line items, payments recorded and balance. Returns line items, total, every payment already recorded and the remaining balance. A partly paid invoice shows each payment, so a reminder asks for the balance and not the total. Needs the user's Cotlet API key with access to this app.
| Name | Required | Description | Default |
|---|---|---|---|
| invoice_id | Yes | Invoice ID from list_invoices. |
Changes observed during successful MCP inspections.
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the safe read profile (readOnlyHint=true, destructiveHint=false), so the bar is lower. The description adds genuinely useful behavioral context: what the payload contains and the fact that a partly paid invoice enumerates each payment, plus the auth requirement (a Cotlet API key with access to this app).
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?
Front-loaded with the core purpose and appropriately short at three sentences. There is mild redundancy between the first sentence and the 'Returns line items, total...' restatement, but nothing is wasted outright.
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, so the description carries the return-value burden and does so reasonably, naming line items, total, payments and remaining balance. Combined with a single required parameter and full annotation coverage, the definition is complete enough, though it omits error/empty-invoice 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 coverage is 100% with a single documented parameter ('Invoice ID from list_invoices'), so the schema does the heavy lifting. The description adds no syntax or format detail for invoice_id beyond what the schema provides, making the baseline 3 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 and resource ('One invoice') and immediately scopes it against the list operation by emphasizing a single invoice with line items, payments and balance. An agent can distinguish this from the many sibling get_invoice tools and from jobber_list_invoices without opening a 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 'so a reminder asks for the balance and not the total' line implies a use case (reminder context) but never states when to use this tool versus jobber_list_invoices or when not to. Usage is left to inference rather than made explicit.
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.