mark_invoice_paidMark a draft or sent invoice as paid (stamps paid_at). Cannot be applied to a void invoice. invoice_id is required.
| Name | Required | Description | Default |
|---|---|---|---|
| invoice_id | Yes |
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide only negative hints (readOnly=false, idempotent=false, etc.) which do little to describe behavior. The description adds the side effect 'stamps paid_at' and the constraint about void invoices. However, it does not mention what happens if the invoice is already paid, reversibility, or required permissions, leaving some behavioral gaps for a mutation tool.
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 short sentences, front-loaded with the main action, followed by a key exclusion and a note on the required parameter. Every sentence carries useful information, with no redundancy or unnecessary detail.
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?
The description gives the essential constraints (draft/sent, not void, requires invoice_id) and an output schema exists. However, it omits important edge cases like idempotency or behavior on already-paid invoices, and annotations do not fill this gap. For a simple tool it is mostly sufficient, but not fully complete for an agent to predict all outcomes.
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 0%, and the description only repeats 'invoice_id is required,' which is already in the schema's required array. It adds no semantic meaning about what invoice_id refers to or any format/constraints. The parameter name is self-explanatory, but the description fails to compensate for the lack of schema 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 clearly states the tool's function with a specific verb and resource: 'Mark a draft or sent invoice as paid (stamps paid_at).' This distinguishes it from sibling tools like update_invoice (general updates) and void_invoice (voiding), making the purpose immediately clear.
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 explicit usage context: it applies to 'draft or sent invoice' and notes a clear exclusion: 'Cannot be applied to a void invoice.' While it does not name alternative tools, the when/when-not conditions are stated. This is almost at the level of naming alternatives, but falls short of explicit sibling differentiation.
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.
Every tool targets a distinct resource and action, with detailed descriptions that clearly separate overlapping domains (e.g., consulting vs. marketing vs. outreach). Even within the same domain, tools like 'create_consulting_deliverable' and 'create_consulting_document_revision' are unambiguous due to their specific nouns.
All tools follow a consistent verb_noun snake_case pattern (e.g., 'create_invoice', 'get_deal', 'list_agents'). The few exceptions like 'locus_determine_from_scores' still adhere to the verb_noun structure and do not break the pattern.
With 124 tools, the server is massively over-scoped for typical MCP use. The tool count far exceeds the '50+ extreme mismatch' threshold, making it nearly impossible for an agent to efficiently navigate or select the right tool without extensive context. Even a large platform should consolidate or expose fewer tools.
The tool surface covers CRUD and lifecycle operations across at least 10 domains (sales, consulting, marketing, outreach, accounting, workflows, ticketing, API keys, feedback, platform metrics). Each domain appears to have no obvious gaps—e.g., invoicing includes create, update, send, mark paid, void; ticketing includes create, update, archive, dependencies, batch, scenarios, validation.