Quipu MCP by usefulapi

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true; the description adds consistent context ('WRITE: it adds a record to the Quipu account') and a real dependency (tax id needed before invoicing). It does not disclose failure modes such as duplicate tax ids, validation errors, or what happens with optional fields left blank — meaningful gaps for an 11-param 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?

Three short, front-loaded sentences: what it does, that it is a write, and the key prerequisite. Nothing is redundant and the verb leads.

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 11-parameter create with no output schema, the description says nothing about which fields are required, how the enum for document_type is used, whether the returned id is needed for follow-up calls, or duplicate handling. It is far too thin for the tool's complexity.

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 18% — just tax_id and country_code are documented in the schema. The description mentions tax id semantically but leaves nine other parameters (document_type enum, bank_account_number, client_number, address fields) entirely unexplained, so it does not compensate for the low 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?

Specific verb + resource: 'Create a contact', with the useful scope qualifier '(client or supplier)'. This clearly separates it from quipu_list_contacts and quipu_update_contact, though it never names those siblings explicitly.

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 tax-id/invoicing note implies when the tool matters (set up a contact before billing them), but it never states when to use this versus quipu_update_contact for an existing contact, nor any exclusion or duplicate-handling guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations supply only destructiveHint=true and a title, so the description carries real weight here: it labels the operation as a WRITE, explains precisely what gets added ('a draft to Quipu'), and clarifies the non-obvious constraint that no issue date or number is sent. It doesn't cover permissions, idempotency, or what happens to the draft afterward.

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, front-loaded with the verb and resource, then the WRITE marker, then the draft-finalization caveat. No filler or repetition of 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 7-parameter mutation with no output schema, the description omits what a caller gets back (presumably the draft identifier needed to continue) and what preconditions exist on contact_id or numbering_series_id. The draft-vs-issued distinction is well covered, but the post-call picture is not.

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?

At 71% schema description coverage the schema already documents most fields, so the description's lack of per-parameter detail is acceptable. Its one contribution is negative-space information: it explains why there is no issue-date or invoice-number parameter. Several fields (tags, notes, payment_method) get no guidance in either place.

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 a specific verb and resource ('Create a DRAFT income invoice for a contact') and immediately clarifies the key qualifier, that the result is a draft rather than an issued invoice. This distinguishes it from quipu_get_invoice and quipu_list_invoices, which read invoices rather than create 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?

It implicitly establishes the use case (you want a draft that a human will finalize in the Quipu app) and explicitly bounds the tool's effect ('Quipu does not issue or register the invoice'). It stops short of naming an alternative tool or stating prerequisites, such as whether the contact must already exist.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The readOnlyHint annotation already declares this is a safe read operation. The description adds some behavioral context by disclosing that the contact's paid/unpaid income and expense totals are returned, but it does not cover error/not-found behavior or permissions.

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 with no wasted words. It communicates purpose and return content efficiently.

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 simple single-parameter read tool with no output schema, the description gives adequate context: it identifies the resource and summarizes the returned totals. Minor missing details such as not-found behavior are low risk here.

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 there is only one parameter, so the schema already explains contact_id. The description adds no syntax or format details beyond restating that lookup is by id, matching the baseline for fully covered 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 uses a specific verb ('Get'), resource ('contact'), and cardinality ('one ... by id'), and it also names the returned data ('totals of paid and unpaid incomes and expenses'). This clearly distinguishes it from sibling list/update/create contact 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?

The phrase 'by id' implies the tool is for retrieving a known contact, but the description never states when to use this versus quipu_list_contacts or quipu_update_contact. No explicit alternatives or exclusions are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The readOnlyHint annotation already covers the safety profile, and the description adds genuine value beyond it: it discloses that income invoices carry download_pdf_url and ephemeral_open_download_pdf_url and flags the latter as temporary. It stops short of describing error behavior or pagination-like concerns, but for a single-record get that's minor.

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 short sentences, front-loaded with the core operation and followed by the one non-obvious return detail. 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?

For a read-only single-record fetch with a fully described two-parameter schema and a clear readOnlyHint, the description covers what an agent needs plus a useful note on PDF link fields. The only gap is not-found/error behavior and the asymmetry for expense invoices.

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 both invoice_id and include are documented structurally, and the description adds nothing about the include parameter or id format. Baseline 3 applies when the schema does the heavy lifting.

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?

"Get one invoice by id" states a specific verb and resource, and the word "one" implicitly contrasts with quipu_list_invoices. It's clear what the tool does, though it doesn't explicitly name the list sibling as the alternative.

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 only implied: retrieve a single invoice when you already hold an id. There's no statement about when to prefer quipu_list_invoices instead, nor prerequisites or what happens with an unknown id.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

readOnlyHint=true already tells the agent this is a safe read. Beyond that the description adds no behavioral context: no result ordering, no statement about whether filtering is conjunctive, no hint that page/page_size control pagination (that lives only in the schema).

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 short sentences with the core purpose front-loaded and no filler. The second sentence is a terse parameter list that could carry more value but wastes no words.

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 should say something about returned items, but it is silent on shape and pagination totals. For a five-parameter list tool with 40% schema coverage, the definition is minimally sufficient but leaves meaningful gaps.

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 40%, and the description names three of five parameters (kind, prefix, active) but gives no meaning for them — no allowed kind values, no indication of what prefix matches (code? name?), no definition of active vs archived. It partially compensates for the coverage gap but leaves the semantics thin.

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 ('List accounting categories') and disambiguates the domain term with '(chart of accounts groups)'. It does not explicitly contrast with the sibling quipu_list_accounting_subcategories, so an agent must infer the parent/child distinction.

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 only enumerates filter parameters rather than saying when to choose this tool over quipu_list_accounting_subcategories or quipu_list_book_entries. No exclusions, prerequisites, or conditions for use are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds the scoping nuance (all subcategories vs. those under one category), but says nothing about pagination behavior, result ordering, or what happens for an unknown category 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. It is efficient, though arguably under-specified rather than optimally concise.

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 simple read-only list tool with full schema coverage and no output schema, the description is minimally sufficient. It omits pagination existence and any differentiation from the sibling categories listing tool, which are the remaining gaps.

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 page, page_size, and accounting_category_id are fully documented in the schema itself. The description only restates the category filter in prose and adds no format or constraint 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 (List) and resource (accounting subcategories), plus the optional category filter. An agent can tell it apart from the sibling list_accounting_categories by resource name, though the description never explicitly contrasts the two.

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?

"Optionally for one accounting category" implies the filtering scenario, but there is no statement of when to use this vs. list_accounting_categories or any other listing tool, and no exclusions or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The readOnlyHint annotation already establishes that this is a safe non-mutating operation, lowering the disclosure bar. The description adds only that entries come back "in one list," and says nothing about pagination behavior (even though page/page_size exist), default ordering, or how the `include` expansion affects the payload — gaps that matter for a listing tool with no output schema.

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 short sentences, front-loaded with the core purpose; nothing is padded or buried. The second sentence is a lightly redundant enumeration of filters already named in the schema, which keeps it from a 5.

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 13-parameter listing tool with no output schema, the description covers the broad shape but leaves several parameters (sort, validation_status, include, with_detailed_amounts) entirely to the schema, and never mentions pagination semantics despite the tool returning a paged result set. Adequate, but there are clear gaps an agent must fill by reading the schema.

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 85%, so the schema itself documents nearly every parameter in useful detail (kind semantics, page/page_size defaults, payment_status behaviors). The description restates the filter categories at a coarser level and adds no syntax, formatting, or interaction rules beyond what the schema already provides, 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?

Names a specific verb and resource ("List all book entries") and clarifies the resource by parenthetical enumeration ("invoices, tickets and other accounting entries"). It is clear in isolation, but it never distinguishes itself from sibling tools like quipu_list_invoices, so an agent cannot tell from the description alone which list endpoint to pick.

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 enumerates available filter axes (type, kind, period, dates, payment status, contact), which implies how the tool is used for narrowed retrieval. However, there is no explicit when-to-use guidance, no statement of when NOT to use it (e.g. versus quipu_get_invoice or quipu_list_invoices), and no prerequisites or defaults called out.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

readOnlyHint=true already covers the safety profile, so the bar is lower. The description adds that results can be filtered by contact kind/nationality, but says nothing about pagination behavior, default ordering, or result shape beyond what the schema provides.

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 compact sentences with zero waste; the core purpose is front-loaded before the filter capabilities. Every clause 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 an 8-parameter, all-optional read tool with no output schema, the description covers purpose and filtering adequately and annotations cover safety. Minor gaps remain around sort-field values and pagination semantics, but nothing critical 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?

Schema coverage is 88%, so the schema already documents nearly every parameter including enums, ranges and defaults. The description only restates the filter fields at a high level and adds no format or interaction details, making 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 ('List contacts') and clarifies the domain object ('clients and suppliers') of the Quipu account. An agent can distinguish it from quipu_get_contact and quipu_create_contact by the list/read scope, though it never explicitly names a sibling.

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 filter sentence implies how to narrow results (kind, tax id, country, email, free text), which gives implicit usage guidance. However, it never says when to use this versus quipu_get_contact for a single record, nor when to combine filters.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

readOnlyHint=true already declares the safety profile. The sentence 'Totals and PDF links are in the attributes' adds useful output context beyond annotations, but nothing is said about ordering, result caps, or default pagination 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?

Two short sentences, front-loaded with the resource and followed by filter scope and a return-value note. No filler, though the filter list is a bare inventory rather than a prioritized lead.

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 12 optional parameters and no output schema, the note about totals and PDF links partially compensates. However, 'validation_status' is undocumented in both schema and description, and there is no guidance on how period, operation_date, and operation_date_from/to interact.

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 92%, so the schema (including enum meanings for kind and payment_status) already does the heavy lifting. The description merely names filter dimensions already present in the schema and adds no syntax, precedence, or combination rules.

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 ('List invoices') plus the scope distinction 'issued and received', which clarifies the tool returns both income and expense invoices. Sibling tools contain no other invoice-listing endpoint, so differentiation is implicit rather than required.

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 implies usage by enumerating filter dimensions, but never states when to use this versus quipu_get_invoice for a single record, nor that filters are combinable. No exclusions or preconditions are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

readOnlyHint=true already covers the safety profile, so the description only needs to add context. It adds the downstream workflow use (series id for draft invoices) but says nothing about what a series record contains or how filtering behaves. Adequate but thin beyond 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?

Two short sentences, front-loaded with the resource and followed by the actionable usage note. 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 simple read-only list tool with no output schema, the description covers purpose and workflow but leaves return shape and two parameter semantics unexplained. It is minimally sufficient rather than fully complete.

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 60%: 'prefix' and 'applicable_to' have no schema descriptions. The description mentions '(prefixes)' but never explains whether prefix filtering is exact or partial, and never clarifies applicable_to, so it fails to compensate for the coverage gap.

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 ('List invoice numbering series (prefixes)') and parenthetically clarifies what a series is. It is clearly distinguishable from the other list_* siblings by resource, though it doesn't explicitly contrast 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?

Provides clear workflow context: 'Use a series id when you create a draft invoice,' which links this read to quipu_create_draft_invoice. It gives no exclusions or alternative-tool guidance, but the intended usage point is unambiguous.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare idempotentHint=true, so the description must carry most of the burden. 'WRITE: it changes the record' usefully discloses mutation and the partial-update merge behavior is a valuable non-obvious trait. Beyond that, nothing is said about reversibility, permission needs, or error behavior for a 12-field 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 with the mutation warning front-loaded and no filler. Appropriately sized for the sparse information it actually conveys.

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 12 parameters at 8% schema coverage, no output schema, and minimal annotations, an agent lacks the field-level meaning needed to populate optional fields confidently. The description should at least explain what the commonly used fields accept, which it does not.

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 only 8%, so only contact_id has any documentation ('Quipu resource id (integer)'), and even that omits that it is required. The description says nothing about any of the 11 optional fields, the document_type enum, or country_code's 2-character constraint, leaving most parameters semantically thin.

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 ('Update fields of one contact'), which clearly separates it from quipu_create_contact and quipu_get_contact. It does not explicitly name siblings, but the write/read/create distinction is inferable from the verb.

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 clause 'only the fields you send change' implicitly tells the agent this is a partial update, which is useful usage context. However, there is no explicit guidance on when to use this vs. create_contact, no prerequisites (e.g., contact must exist), and no mention of what happens on invalid IDs.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.