Query and manage Mercoa AP/AR bill-pay: entities, invoices, transactions and payment methods.
The last two health checks of this connector failed. 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 17 tools
Each tool targets a distinct resource and action, with a clear split between find_* (search across collection), get_* (single record), and list_* (sub-resource enumeration). The read verbs find/get/list are nicely disambiguated by their descriptions, and write tools (create/update/add) are unambiguous.
All tools use a consistent mercoa_ prefix with a snake_case verb_noun pattern. There is minor variation in read verbs (find, get, list) but each maps to a coherent semantic, so it stays predictable.
17 tools is slightly heavy but reasonable for a payments/invoicing platform spanning entities, invoices, transactions, and payment methods. Every tool maps to a concrete endpoint without obvious redundancy.
Core read/create/update coverage exists for entities and invoices, but notable gaps remain: no entity update, no payment-method creation, and crucially no invoice approval or payment actions despite transaction and approval workflow being central to the domain.
WRITE — adds a comment to an invoice (visible in its activity log). POST /invoice/{invoiceId}/comment.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | Comment text. | |
| userId | No | ID or foreign ID of the user creating the comment. | |
| invoiceId | Yes | Invoice ID to comment on. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already carry destructiveHint=true, so the description doesn't need to re-declare risk. It adds useful context the annotations don't: the mutation is a write to the invoice activity log and the underlying call is POST /invoice/{invoiceId}/comment. It still omits who may comment, whether the comment is editable/deletable, and what the response contains.
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 compact sentence with the mutation marker front-loaded, then effect, then endpoint. No filler or redundancy.
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 comment-attach operation with no output schema, the essentials are present, but it does not say whether the created comment is returned, whether userId may be omitted (defaulting to the caller), or any rate/permission constraints. Adequate but with clear 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 all three parameters are documented in the schema; the description only restates invoiceId via the URL path template. It adds no meaning beyond the schema, 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 ("adds a comment to an invoice") and immediately distinguishes it as a mutation ("WRITE") from the read-heavy siblings like mercoa_get_invoice and mercoa_find_invoices. The parenthetical that the comment lands in the invoice's activity log further pins down what the tool actually produces.
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 "WRITE" marker and the note that the comment appears in the activity log imply when this is appropriate, but there is no explicit guidance on when to use it versus alternatives or any stated prerequisites (e.g., permissions, userId defaults). Usage is inferable rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE — creates a real entity (customer/vendor/payor/payee) in Mercoa. Supply role flags, accountType, and a nested profile object (business or individual details). POST /entity.
| Name | Required | Description | Default |
|---|---|---|---|
| No | Primary email for the entity. | ||
| isPayee | No | Whether this entity can receive payments (AR / vendor). | |
| isPayor | No | Whether this entity can pay invoices (AP). | |
| profile | No | Nested profile object, e.g. { "business": { "legalBusinessName": "Acme Inc.", "email": "ap@acme.com", "businessType": "llc" } } or { "individual": { "name": {...}, "email": "..." } }. | |
| foreignId | No | Your system's ID for this entity. | |
| isCustomer | No | Whether this entity has a direct relationship with your organization. | |
| accountType | No | business or individual. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations supply only destructiveHint=true, so the description does add value: it flags this as a persistent WRITE on a 'real' entity and names the endpoint POST /entity. However, it omits idempotency/repeat-call behavior, permission requirements, and the fact that the entity will be visible to real counterparties — material gaps for a create-with-side-effects 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 tightly packed sentences with the WRITE marker and the resource front-loaded, followed by the payload hint and endpoint. No filler or redundancy.
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 7 parameters, a nested profile object, and no output schema, the description should at least tell the agent what comes back (the new entity ID) for follow-up calls like mercoa_get_entity or mercoa_create_invoice, and mention that no fields are strictly required. It leaves those 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 the schema already documents all seven parameters, setting the baseline at 3. The description's mention of 'role flags, accountType, and a nested profile object' restates schema content rather than adding format rules or noting that email/foreignId are optional.
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 + resource ('creates a real entity') and enumerates the role variants (customer/vendor/payor/payee), which cleanly separates it from the read siblings (mercoa_find_entities, mercoa_get_entity) and from mercoa_create_invoice. An agent knows immediately this is the entity-creation tool.
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?
There is no explicit when-to-use guidance: it never says to search first with mercoa_find_entities to avoid duplicates, nor when to prefer this over creating an invoice with a new entity. Usage is only implied by the verb 'creates'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE — creates a real invoice/bill in Mercoa. Set status (DRAFT to stage, NEW to submit), amount, currency, payer/vendor, dates and line items. POST /invoice.
| Name | Required | Description | Default |
|---|---|---|---|
| amount | No | Total invoice amount. | |
| status | No | Invoice status, e.g. DRAFT, NEW, APPROVED, SCHEDULED. | |
| dueDate | No | Due date (ISO 8601). | |
| payerId | No | Payer entity ID (who owes). | |
| currency | No | Currency code, e.g. USD. | |
| metadata | No | Arbitrary key/value metadata. | |
| vendorId | No | Vendor entity ID (who is paid). | |
| lineItems | No | Line items array, e.g. [{ "amount": 100, "currency": "USD", "description": "Product A", "quantity": 1, "unitPrice": 100 }]. | |
| noteToSelf | No | Internal note. | |
| invoiceDate | No | Invoice date (ISO 8601). | |
| creatorUserId | No | User ID creating the invoice. | |
| deductionDate | No | Scheduled payment/deduction date (ISO 8601). | |
| invoiceNumber | No | Human-readable invoice number, e.g. INV-123. | |
| creatorEntityId | No | Entity ID on whose behalf the invoice is created. | |
| paymentSourceId | No | Payment method ID to pay from (payer's). | |
| paymentDestinationId | No | Payment method ID to pay to (vendor's). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only supply destructiveHint=true, and the description corroborates the mutation with 'WRITE — creates a real invoice/bill', adding that this is a live financial record rather than a draft-only action. It stops short of disclosing auth/permission requirements, idempotency, or what happens to a previously staged draft, so it adds modest value over the annotation.
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 WRITE marker and the core purpose, then parameter guidance, then the endpoint. Every clause carries information; nothing is redundant.
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 16-parameter mutation tool with no output schema and only a destructiveHint annotation, the description covers purpose and the status lifecycle but is silent on several field groups it exposes (paymentSourceId/paymentDestinationId, creatorUserId/creatorEntityId, invoiceNumber, metadata) and on required-vs-optional expectations (0 required params). Adequate but leaves gaps an agent may need to fill from the schema alone.
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 baseline is 3, but the description goes beyond the schema by explaining the semantic effect of the status values (DRAFT stages, NEW submits) — the schema merely lists DRAFT/NEW/APPROVED/SCHEDULED without behavioral meaning. It also signals the key field groups (amount, currency, payer/vendor, dates, line items).
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 ('creates a real invoice/bill in Mercoa') and names the endpoint ('POST /invoice'), which cleanly separates it from read-oriented siblings like mercoa_find_invoices and mercoa_get_invoice as well as from mercoa_update_invoice. An agent can identify the operation without opening the 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 status guidance ('DRAFT to stage, NEW to submit') tells the agent how and when the call takes effect, which is meaningfully actionable context. It does not, however, contrast this tool with alternatives such as mercoa_update_invoice or explain prerequisites (e.g. required entity/payer setup), so no explicit exclusions are offered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find/search entities (buyers, vendors, payors, payees). Use to look up counterparties by name/email/foreignId or list all. GET /entity.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max entities to return (1-100, default 10). | |
| search | No | Search by name, email, emailTo, entity ID, or foreign ID (partial matches). | |
| status | No | Entity status filter (e.g. verified, pending). | |
| isPayee | No | Filter entities marked as payees. | |
| isPayor | No | Filter entities marked as payors. | |
| foreignId | No | Your system's ID(s) for the entity. | |
| isCustomer | No | If true, only entities with a direct relationship to your organization. | |
| startingAfter | No | Entity ID cursor for pagination. | |
| paymentMethods | No | If true, include payment methods in the response. | |
| returnMetadata | No | Metadata key(s) to include in the response. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already tells the agent this is a safe, non-mutating read, and 'GET /entity' merely restates that. The description adds that matching is by name/email/foreignId, but says nothing about cursor-based pagination behavior, default page size effects, or result ordering — modest added value over what annotations and schema already convey.
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 tightly packed sentences: the capability and entity taxonomy come first, the usage guidance second, with zero filler. Nothing could be cut without losing routing or lookup 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 10-parameter, all-optional, read-only search tool with no output schema, the description gives enough to select and shape a call; the rich schema carries the filtering and pagination detail. Only the lack of any note on pagination/result-window expectations keeps it from a 5.
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 all 10 parameters are already self-documented with limits, defaults and examples. The description's mention of name/email/foreignId search fields overlaps with the 'search' and 'foreignId' schema descriptions rather than extending them, 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+resource ('Find/search entities') and enumerates the entity subtypes (buyers, vendors, payors, payees) plus the searchable fields, and names the HTTP endpoint. It is clearly distinguishable from create_entity and get_entity in intent, though it never explicitly contrasts itself with get_entity for single-ID retrieval, leaving full sibling disambiguation to inference.
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?
'Use to look up counterparties by name/email/foreignId or list all' gives explicit usage context and the two primary modes (search vs. list-all). There are no when-not conditions and the retrieval sibling (get_entity) is not named as an alternative, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find/search invoices (bills) across payers and vendors. Filter by status, entity, date, approver and more. GET /invoices (plural list endpoint).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max invoices to return (1-100, default 10). | |
| search | No | Search by vendor name, invoice number, check number, or amount. | |
| status | No | Invoice status filter (e.g. DRAFT, NEW, APPROVED, SCHEDULED, PAID). | |
| endDate | No | End date filter (ISO 8601). | |
| orderBy | No | Field to order by (e.g. CREATED_AT, AMOUNT, DUE_DATE). | |
| payerId | No | Filter by payer ID(s) or foreign ID(s). | |
| dateType | No | Date type to filter by (e.g. CREATED_AT, DUE_DATE). | |
| entityId | No | Filter by entity (payer or vendor) ID(s) or foreign ID(s). | |
| vendorId | No | Filter by vendor ID(s) or foreign ID(s). | |
| invoiceId | No | Filter by invoice ID(s) or foreign ID(s). | |
| startDate | No | Start date filter (ISO 8601). | |
| approverId | No | Filter by assigned approver user ID(s). | |
| paymentType | No | Filter by payment type (e.g. recurring). | |
| creatorUserId | No | Filter by the user ID(s) that created the invoice. | |
| entityGroupId | No | Filter by entity group ID. | |
| startingAfter | No | Invoice ID cursor for pagination. | |
| approverAction | No | Filter by approver action (use with approverId), e.g. APPROVE. | |
| orderDirection | No | asc or desc. | |
| invoiceTemplateId | No | Filter by invoice template ID(s). | |
| returnPayerMetadata | No | Include payer metadata in the response. | |
| returnPaymentTiming | No | Include payment timing in the response. | |
| returnVendorMetadata | No | Include vendor metadata in the response. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already tells the agent this is a non-mutating read, so the safety burden is lifted. The description adds only the underlying GET endpoint and a vague 'and more' on filters; it says nothing about pagination behavior, default limits, or that the returnPayerMetadata/returnVendorMetadata flags inflate the payload.
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 core purpose and no redundancy. The endpoint fragment is arguably skippable, but it does double as disambiguation against the singular get tool, so it mostly 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 22-parameter search tool with no output schema, the description is thin on return-shape and pagination expectations, though the 100% schema coverage carries the parameter burden. It is adequate for calling the tool but leaves the agent guessing about result volume and cursor semantics.
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 all 22 parameters are already documented with formats, defaults, and examples. The description's filter list merely echoes a subset of what the schema already provides and adds no syntax, precedence, or combination guidance.
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 (find/search) and resource (invoices), and parenthetically clarifies it is the plural list endpoint, which implicitly distinguishes it from the singular mercoa_get_invoice sibling. Scope ('across payers and vendors') and the supported filter families are named, though no sibling is called out by name.
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 listing filter dimensions (status, entity, date, approver), so an agent can infer it is the batch/discovery tool. However, it never states when to prefer this over mercoa_get_invoice for a single record, nor when to use it versus mercoa_find_transactions or the entity-scoped list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List/search payment transactions. Filter by entity, invoice, status, type and date. GET /transactions.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max transactions to return (1-100, default 10). | |
| search | No | Search by vendor name, invoice number, check number, or amount. | |
| status | No | Transaction status filter. | |
| endDate | No | CREATED_AT end date filter (ISO 8601). | |
| payerId | No | Filter by payer ID(s). | |
| entityId | No | Filter by entity ID(s) or foreign ID(s). | |
| vendorId | No | Filter by vendor ID(s). | |
| invoiceId | No | Filter by invoice ID(s) or foreign ID(s). | |
| startDate | No | CREATED_AT start date filter (ISO 8601). | |
| entityGroupId | No | Filter by entity group ID. | |
| startingAfter | No | Transaction ID cursor for pagination. | |
| transactionId | No | Filter by transaction ID(s). | |
| transactionType | No | Filter by transaction type. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, so safety is already covered and the description's main addition is the underlying endpoint (GET /transactions). It says nothing about pagination cursor behavior, result ordering, or the default result cap, which would be genuinely useful beyond the 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?
Three short clauses with the core purpose front-loaded and no filler. The trailing 'GET /transactions' is marginal value but not disruptive.
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 and thin annotations, the description covers the filter surface but omits anything about the shape of returned transactions or how paging composes. Adequate as a selector, incomplete as a call guide.
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% across all 13 parameters, so the schema already documents each filter's meaning and the 1-100 limit range. The description's partial restatement ('entity, invoice, status, type and date') adds no syntax or format detail beyond that, 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 ('List/search') and resource ('payment transactions') and enumerates the filterable dimensions, so an agent can distinguish it from mercoa_get_transaction (single lookup) without opening the schema. It stops short of naming sibling alternatives explicitly, keeping it at 4 rather than 5.
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 list ('entity, invoice, status, type and date') implies the tool is for scoped browsing rather than single-record fetch, which gives implied usage guidance. However, it never states when to prefer it over mercoa_find_invoices or mercoa_get_transaction, so the routing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single entity by ID (or foreign ID). GET /entity/{entityId}.
| Name | Required | Description | Default |
|---|---|---|---|
| entityId | Yes | Entity ID (e.g. ent_...) or foreign ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already tells the agent this is a safe read. The description adds the underlying REST route and the foreign-ID acceptance, but says nothing about missing-entity behavior, permissions/scope, or what fields come back. Moderate added value against an annotation that already covers the safety profile.
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 very short fragments that are front-loaded with the purpose; nothing is wasted. The trailing 'GET /entity/{entityId}' is arguably redundant for an MCP agent, 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 one-parameter, read-only lookup with 100% schema coverage and a readOnlyHint, the description covers what is needed to call it. The lack of an output schema means return shape is unstated, but for a get-by-ID tool that is a minor gap.
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% on the single 'entityId' parameter, including the 'ent_...' example and foreign-ID note, so the schema carries the burden. The description repeats the ID-or-foreign-ID point without adding new format or resolution semantics, matching the baseline 3.
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 ('Get a single entity') and emphasizes singularity, which implicitly separates it from the plural sibling 'find_entities'. It does not name that sibling or otherwise differentiate explicitly, so it falls short of a 5.
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 no guidance on when to use this over 'find_entities' or 'get_entity_events', nor any prerequisite such as needing a valid entity ID. Usage is only implied by the 'by ID' phrasing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the event/audit log for an entity. GET /entity/{entityId}/events.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max events to return (1-100). | |
| endDate | No | End date filter (ISO 8601). | |
| entityId | Yes | Entity ID or foreign ID. | |
| startDate | No | Start date filter (ISO 8601). | |
| startingAfter | No | Event ID cursor for pagination. |
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 useful framing that the result is an immutable event/audit log, but omits pagination behavior, cursor semantics, and result format – the schema documents the cursor but not how it behaves.
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, correctly front-loaded with the purpose before the endpoint reference. The 'GET /entity/{entityId}/events' fragment is largely redundant with the tool name and required entityId parameter, so it does not fully earn 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?
No output schema exists, so the description should ideally describe the return shape (list of event records) and pagination model. With 5 parameters, one required, and no output schema, the definition is minimally adequate but leaves the agent to guess what actually comes back.
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% (limit, startDate, endDate, entityId, startingAfter all documented inline), so the schema carries the parameter burden. The description adds nothing beyond the schema, which sets the baseline at 3.
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 ('Get') and resource ('event/audit log for an entity'), which is clearly distinguishable from mercoa_get_entity (entity data) and mercoa_get_invoice_events (invoice-scoped events). It does not explicitly name those siblings, but the scope is unambiguous.
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 no when-to-use guidance, no prerequisites, and no mention of alternatives such as mercoa_get_invoice_events. An agent must infer from the name alone that this is for retrieving an entity's audit trail.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get aggregate invoice metrics (totals/counts, grouped by currency) for an entity's payables/receivables — for AP/AR dashboards and aging. GET /entity/{entityId}/invoice-metrics.
| Name | Required | Description | Default |
|---|---|---|---|
| search | No | Search by vendor name, invoice number, check number, or amount. | |
| status | No | Invoice status filter (e.g. NEW, SCHEDULED, PAID). | |
| endDate | No | End date filter (ISO 8601). | |
| groupBy | No | Additional grouping (e.g. by status). | |
| payerId | No | Filter by payer ID(s). | |
| currency | No | Currency code(s) to filter on, e.g. USD. | |
| dateType | No | Date type to filter by (e.g. CREATED_AT, DUE_DATE). | |
| entityId | Yes | Entity ID or foreign ID. | |
| vendorId | No | Filter by vendor ID(s). | |
| invoiceId | No | Filter by invoice ID(s) or foreign ID(s). | |
| startDate | No | Start date filter (ISO 8601). | |
| approverId | No | Filter by assigned approver user ID(s). | |
| returnByDate | No | Group metrics by date, e.g. CREATION_DATE or DUE_DATE. | |
| excludePayables | No | Only return receivables (exclude payables). | |
| excludeReceivables | No | Only return payables (exclude receivables). | |
| returnByDateFrequency | No | Frequency for date grouping (e.g. DAILY, MONTHLY). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already covers the safety profile, and the description usefully adds that results are aggregated by currency and split across payables/receivables. It says nothing about pagination, result size, or how the currency grouping interacts with the groupBy/returnByDate parameters, so context beyond the annotation is thin.
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?
One compact sentence that front-loads the payload (aggregate metrics, grouping, entity scope) before the supporting context. The trailing 'GET /entity/{entityId}/invoice-metrics' restates what the name and required entityId already convey, which is minor redundancy.
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 aggregation tool with 16 well-documented parameters and no output schema, the description conveys the shape of the result (totals/counts grouped by currency, split by payables/receivables) adequately. It could say more about how date/grouping parameters reshape the aggregate, but nothing essential to calling it 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 description coverage is 100% across all 16 parameters, so the schema already carries the semantics for search, status, dateType, groupBy, returnByDate, excludePayables/Receivables, etc. The description adds only the currency grouping notion, which is baseline behavior 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?
States a specific verb (Get) plus a precisely scoped resource: aggregate invoice metrics with totals/counts grouped by currency for an entity's payables/receivables. The word 'aggregate' and the grouping qualifier cleanly separate it from sibling detail/list tools such as mercoa_find_invoices and mercoa_get_invoice.
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?
Gives an explicit use context ('for AP/AR dashboards and aging') that tells the agent when this aggregate tool is the right pick over invoice listing tools. It stops short of naming an alternative or stating when not to use it, so it does not reach the top band.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single invoice (bill) by ID. GET /invoice/{invoiceId}.
| Name | Required | Description | Default |
|---|---|---|---|
| invoiceId | Yes | Invoice ID (e.g. in_...) or foreign ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, which fully covers the safety profile for this call. The description adds nothing beyond the annotation and schema — no mention of error behavior for a missing ID, auth requirements, or what the response contains — so it earns little credit for 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?
Two short sentences, zero filler, with the core purpose front-loaded. Nothing could be cut without losing meaning.
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 one-parameter read tool with readOnlyHint, the definition is minimally sufficient — there is no output schema, but the description doesn't need to explain return values. It stops short of distinguishing behavior from the sibling read tools or covering lookup failure, leaving it adequate rather than 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 description coverage is 100% and the single parameter's format (in_... or foreign ID) is already documented in the schema. The description only echoes 'by ID' and adds no syntax or format 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 ('Get a single invoice (bill) by ID'), and the word 'single' implicitly distinguishes it from the list/search sibling mercoa_find_invoices. However, it never names a sibling explicitly, so the distinction is left to inference.
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: fetch one invoice when you already have its ID. There is no explicit guidance on when to prefer this over mercoa_find_invoices or mercoa_get_invoice_events, and no stated prerequisites or failure conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the event/audit log for an invoice (status changes, approvals, payments). GET /invoice/{invoiceId}/events.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max events to return (1-100). | |
| endDate | No | End date filter (ISO 8601). | |
| invoiceId | Yes | Invoice ID or foreign ID. | |
| startDate | No | Start date filter (ISO 8601). | |
| startingAfter | No | Event ID cursor for pagination. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already establishes this is a safe read. The description adds useful context about what the log contains and cites the HTTP endpoint, but says nothing about pagination behavior despite a startingAfter cursor, nor about ordering or result volume.
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 zero filler, front-loading the resource and its contents before the endpoint reference. Nothing is redundant.
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 list tool with full schema coverage and annotations covering safety, the description is nearly complete; no output schema is declared, so return-value detail is not required. Only the pagination/cursor behavior is left implicit.
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 all five parameters (invoiceId, limit, startDate, endDate, startingAfter) are already documented in the schema. The description adds no format or semantic detail beyond that, so the baseline of 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 ('Get') and resource ('event/audit log for an invoice'), and enumerates the content types (status changes, approvals, payments), so the agent knows exactly what comes back. The 'for an invoice' scoping cleanly separates it from the sibling mercoa_get_entity_events.
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 implied by describing the log contents, but there is no explicit when-to-use guidance and no named alternative (e.g., mercoa_get_invoice for the invoice itself). The agent can infer intent but must guess at routing versus siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the caller's Mercoa organization configuration (settings, payment methods enabled, etc.). GET /organization.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already tells the agent this is a safe, non-mutating read. The description adds that the configuration is the caller's (no identifier needed, auth context implied) and sketches the payload. It stops short of describing permissions required or the response shape.
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, purpose first, with the 'caller's' scoping qualifier front-loaded and zero filler. The trailing HTTP route is a minor but cheap anchor.
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?
There is no output schema, so the description carries some return-value burden; it partially discharges that by naming settings and enabled payment methods, but 'etc.' leaves the payload only roughly characterized. For a simple self-scoped getter with readOnly annotations, this is nearly sufficient.
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 tool takes zero parameters, so the baseline is 4. There is nothing for the description to disambiguate, and the schema is empty as expected.
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 (Get) plus resource (the caller's Mercoa organization configuration) and even names example contents (settings, payment methods enabled). It is naturally distinguishable from resource-specific siblings like mercoa_get_entity or mercoa_get_invoice, though it never explicitly contrasts itself with 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?
Usage is implied by the phrasing — an agent reads this when it needs the current organization's configuration — but there is no explicit when-to-use, when-not-to-use, or named alternative. For a zero-parameter self-scoped read this is acceptable, but nothing is spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single payment method for an entity. GET /entity/{entityId}/paymentMethod/{paymentMethodId}.
| Name | Required | Description | Default |
|---|---|---|---|
| entityId | Yes | Entity ID or foreign ID. | |
| paymentMethodId | Yes | Payment method ID (e.g. pm_...). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is covered. The description only reinforces this via the 'GET' path and adds no further behavioral context such as permission requirements, error behavior for unknown ids, or what the returned payment method exposes. With annotations carrying the burden, this is an adequate baseline.
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, zero filler, with the purpose front-loaded and the endpoint as supporting detail. Nothing is repeated or 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 two-parameter read operation with full schema coverage and readOnlyHint, the definition is sufficient to invoke correctly. It is not sufficient to fully set expectations on the response, since there is no output schema and the description never characterizes the returned payment method.
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%, with both parameters documented (entityId/foreign id, paymentMethodId e.g. pm_...). The path template '/entity/{entityId}/paymentMethod/{paymentMethodId}' maps parameters to their roles but adds no format or validation detail beyond the schema, so 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+resource ('Get a single payment method') and scopes it to an entity, so the agent knows it returns one record rather than a collection. However, it never names the sibling it is distinguished from (mercoa_list_entity_payment_methods), leaving the list-vs-single distinction for the agent to infer from 'a single'.
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 word 'single' implicitly signals this is for fetching one known payment method id rather than enumerating an entity's methods, which implies the alternative. But there is no explicit 'use this when you have a paymentMethodId; use list_entity_payment_methods otherwise' guidance, and no prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single payment transaction by ID. GET /transaction/{transactionId}.
| Name | Required | Description | Default |
|---|---|---|---|
| transactionId | Yes | Transaction ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already tells the agent this is a safe read, so the description only needs to add context. It contributes the REST route (GET /transaction/{transactionId}), which is mild value, but discloses nothing about the returned payload, missing-ID behavior, or auth scope.
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 purpose. The trailing REST endpoint restatement is mildly redundant with the purpose sentence but costs little.
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 getter with a covering annotation this is nearly sufficient, but with no output schema the description should say something about what a transaction object contains or how errors surface. As written it leaves the return value entirely unspecified.
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 the single transactionId parameter is already documented in the schema. The description restates the ID requirement but adds no format, prefix, or example beyond what the schema provides, making the 3 baseline 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+resource and scope ('Get a single payment transaction by ID'), which lets an agent distinguish it from the list-style sibling mercoa_find_transactions without opening either schema. It stops short of naming that sibling explicitly, so sibling differentiation is implied rather than stated.
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?
'by ID' implies the retrieval condition and contrasts implicitly with the find_* family, but there is no explicit when-to-use guidance, no exclusions, and no prerequisite or error-handling note for an unknown ID.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List an entity's payment methods (bank accounts, cards, check, etc.). GET /entity/{entityId}/paymentMethods.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Filter by payment method type (e.g. bankAccount, card, check). | |
| entityId | Yes | Entity ID or foreign ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the REST endpoint and the set of returned method types, which is mild but real context; it says nothing about pagination, ordering, or authorization requirements.
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, front-loaded sentences with no filler; the resource and its contents come first. The raw endpoint string is slightly redundant for an agent but costs little.
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 ideally would hint at the return shape or pagination behavior, and it does not. It is adequate for a simple read tool but leaves the agent guessing about response structure and volume.
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 both entityId and the optional type filter are already documented in the schema. The embedded path 'GET /entity/{entityId}/paymentMethods' confirms entityId is a path parameter but adds little beyond that. 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 (List) and resource (entity's payment methods), with concrete examples of what those methods are (bank accounts, cards, check). It does not, however, distinguish itself from the sibling mercoa_get_payment_method, which an agent could easily confuse with this one.
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 no when-to-use guidance, no exclusions, and never mentions the singular sibling get_payment_method that retrieves a single method. An agent must infer the list-vs-single distinction from the names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the users belonging to an entity (approvers, admins, etc.). GET /entity/{entityId}/users.
| Name | Required | Description | Default |
|---|---|---|---|
| entityId | Yes | Entity ID or foreign ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the underlying endpoint (GET /entity/{entityId}/users) and the nature of the returned users, but says nothing about pagination, ordering, or result size for a list 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 short sentences; the purpose is front-loaded and the endpoint reference is secondary. Nothing is wasted, though the endpoint restatement adds little for an agent that already knows the resource.
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, read-only list tool with annotations covering safety and no output schema to explain, the description is nearly sufficient. The one real gap is pagination/return-size behavior, which an agent calling a list endpoint would benefit from knowing.
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 single entityId parameter is documented as accepting an entity ID or foreign ID. The description only echoes the path variable, adding no syntax or format detail beyond the schema, so the baseline of 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 (List) and resource (users belonging to an entity), plus a parenthetical clarifying who these users are (approvers, admins). It is easy to distinguish from get_entity or list_entity_payment_methods, though it never names a sibling explicitly to sharpen the boundary.
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 'belonging to an entity' implies the context of use and the role hints suggest it's a roster lookup, but there is no explicit when-to-use guidance or comparison against alternatives like get_entity, which may also surface user information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE — updates an existing invoice/bill (all fields optional). Commonly used to advance status (e.g. DRAFT→NEW→SCHEDULED) or change amounts, dates, or payment methods. POST /invoice/{invoiceId}.
| Name | Required | Description | Default |
|---|---|---|---|
| amount | No | Total invoice amount. | |
| status | No | New invoice status, e.g. NEW, APPROVED, SCHEDULED. | |
| dueDate | No | Due date (ISO 8601). | |
| payerId | No | Payer entity ID. | |
| currency | No | Currency code, e.g. USD. | |
| metadata | No | Arbitrary key/value metadata. | |
| vendorId | No | Vendor entity ID. | |
| invoiceId | Yes | Invoice ID to update. | |
| lineItems | No | Replacement line items array. | |
| noteToSelf | No | Internal note. | |
| invoiceDate | No | Invoice date (ISO 8601). | |
| deductionDate | No | Scheduled payment/deduction date (ISO 8601). | |
| invoiceNumber | No | Human-readable invoice number. | |
| paymentSourceId | No | Payment method ID to pay from. | |
| paymentDestinationId | No | Payment method ID to pay to. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only carry destructiveHint=true, which already tells the agent this is a mutating operation; the description reinforces it with 'WRITE' and adds the endpoint POST /invoice/{invoiceId}. It also usefully clarifies 'all fields optional', implying a partial merge. It does not disclose what happens to omitted fields, whether status transitions are validated, or permission requirements — meaningful gaps for a 15-parameter 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 WRITE marker front-loaded and the endpoint appended, so the agent's eye lands on the operation type first. Slightly terse for a 15-parameter tool but no wasted 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?
With 15 parameters, one required, nested objects, and no output schema, the description is minimal but workable because the schema covers all fields at 100%. It could say more about merge semantics and status-transition rules given there are no enums to constrain status values.
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 every parameter is already documented in the schema; the baseline is 3. The description adds only the '(all fields optional)' note and example status values, which marginally overlaps the schema's own status description rather than extending it.
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 ('updates an existing invoice/bill') and frames it as a WRITE, which cleanly separates it from mercoa_get_invoice and mercoa_find_invoices. It does not explicitly name a sibling to route against or note that it differs from mercoa_create_invoice, so it stops short of a 5.
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?
'Commonly used to advance status (e.g. DRAFT→NEW→SCHEDULED) or change amounts, dates, or payment methods' gives a concrete primary scenario, which is stronger than nothing. However, there are no when-not conditions and no alternatives named (e.g. use create_invoice for new records), leaving the agent to infer selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query and manage Amberflo metering & billing: customers, meters, usage, plans, invoices, prepaid.
Manage Apollo invoices and customers with entity-scoped OAuth and optional read/write access.
Manage expenses, corporate cards, accounts payable, and accounting integrations
Sits between accounting and payment rails for reminders, Pay Now, autopay, portal, and book sync.
Add one secure layer between your agents and this server.
