Skip to main content
Glama

Server Details

Query and manage Mercoa AP/AR bill-pay: entities, invoices, transactions and payment methods.

Status
Healthy
Last Tested
Transport
Streamable HTTP
URL
Repository
m190/usefulapi-mcp
GitHub Stars
0

Glama MCP Gateway

Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.

MCP client
Glama
MCP server

Full call logging

Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.

Tool access control

Enable or disable individual tools per connector, so you decide what your agents can and cannot do.

Managed credentials

Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.

Usage analytics

See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.

100% free. Your data is private.
Tool DescriptionsA

Average 3.8/5 across 17 of 17 tools scored. Lowest: 3.2/5.

Server CoherenceA
Disambiguation5/5

Each tool targets a distinct resource (entity, invoice, transaction, payment method, organization) and action (create, find, get, list, update, add). There is no ambiguity between tools.

Naming Consistency5/5

All tools follow the consistent pattern 'mercoa_verb_noun' using snake_case. Verbs like create, find, get, list, update are used predictably.

Tool Count5/5

With 17 tools covering entities, invoices, transactions, payment methods, and organization, the count is well-scoped for a financial platform. Each tool justifies its existence.

Completeness4/5

The toolset covers core CRUD and query operations for the main resources. Minor gaps exist such as missing delete operations for entities and invoices, but the surface is largely complete for typical workflows.

Available Tools

17 tools
mercoa_add_invoice_commentAdd invoice commentA
Destructive
Inspect

WRITE — adds a comment to an invoice (visible in its activity log). POST /invoice/{invoiceId}/comment.

ParametersJSON Schema
NameRequiredDescriptionDefault
textYesComment text.
userIdNoID or foreign ID of the user creating the comment.
invoiceIdYesInvoice ID to comment on.
Behavior4/5

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

The description mentions the comment is 'visible in its activity log', adding behavioral context beyond the annotations (which only have destructiveHint: true). It also states 'WRITE', which is consistent with destructiveHint. This additional detail helps the agent understand the side effect.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is one sentence plus the endpoint, very concise. It front-loads the action. However, it could be slightly more structured (e.g., separate purpose from endpoint). No waste, but also minimal.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple write tool with no output schema, the description is adequate but lacks information on return behavior or error handling. The context of activity log is helpful. Given low complexity, it meets a minimum viable level.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with each parameter having a minimal description. The tool description does not add extra meaning beyond the schema. Baseline is 3, and no additional parameter context is provided.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it adds a comment to an invoice, with the verb 'adds' and resource 'comment to an invoice'. The title matches. This is distinct from sibling tools like mercoa_create_invoice or mercoa_update_invoice, which create or update invoices rather than adding comments.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description includes 'WRITE' indicating it's a mutation, but does not explicitly state when to use this tool versus alternatives. There is no guidance on prerequisites (e.g., invoice must exist) or when not to use it. The sibling list provides context but the description lacks explicit usage direction.

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

mercoa_create_entityCreate entityA
Destructive
Inspect

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
emailNoPrimary email for the entity.
isPayeeNoWhether this entity can receive payments (AR / vendor).
isPayorNoWhether this entity can pay invoices (AP).
profileNoNested profile object, e.g. { "business": { "legalBusinessName": "Acme Inc.", "email": "ap@acme.com", "businessType": "llc" } } or { "individual": { "name": {...}, "email": "..." } }.
foreignIdNoYour system's ID for this entity.
isCustomerNoWhether this entity has a direct relationship with your organization.
accountTypeNobusiness or individual.
Behavior4/5

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

The annotation 'destructiveHint: true' indicates mutation, and the description reinforces this with 'WRITE' and 'creates'. It adds behavioral context by detailing the resource type and key inputs, though it omits side effects or authentication requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single 20-word sentence that front-loads the purpose with 'WRITE — creates a real entity'. Every word earns its place, with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 7 parameters, nested objects, and no output schema, the description covers the core purpose but lacks details on constraints (e.g., foreignId uniqueness), parameter relationships, and the response format. The schema compensates partially.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides 100% coverage with descriptions for all 7 parameters. The description summarizes key groups ('role flags, accountType, profile') but does not add significant new meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'creates a real entity (customer/vendor/payor/payee) in Mercoa', specifying the action (create), resource (entity), and example roles. It distinguishes from sibling tools like 'mercoa_get_entity' by focusing on creation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear usage context by specifying required inputs: 'Supply role flags, accountType, and a nested `profile` object'. It does not explicitly mention when not to use this tool or alternatives, but the context is clear for a creation tool.

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

mercoa_create_invoiceCreate invoiceA
Destructive
Inspect

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
amountNoTotal invoice amount.
statusNoInvoice status, e.g. DRAFT, NEW, APPROVED, SCHEDULED.
dueDateNoDue date (ISO 8601).
payerIdNoPayer entity ID (who owes).
currencyNoCurrency code, e.g. USD.
metadataNoArbitrary key/value metadata.
vendorIdNoVendor entity ID (who is paid).
lineItemsNoLine items array, e.g. [{ "amount": 100, "currency": "USD", "description": "Product A", "quantity": 1, "unitPrice": 100 }].
noteToSelfNoInternal note.
invoiceDateNoInvoice date (ISO 8601).
creatorUserIdNoUser ID creating the invoice.
deductionDateNoScheduled payment/deduction date (ISO 8601).
invoiceNumberNoHuman-readable invoice number, e.g. INV-123.
creatorEntityIdNoEntity ID on whose behalf the invoice is created.
paymentSourceIdNoPayment method ID to pay from (payer's).
paymentDestinationIdNoPayment method ID to pay to (vendor's).
Behavior3/5

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

Annotations already declare destructiveHint=true, signaling a write operation. The description adds 'WRITE' and confirms creation, but does not disclose additional behaviors like required permissions, rate limits, or response details. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero waste. Front-loads the core action and key fields, then provides the endpoint. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

While the description covers the basic purpose, the tool has 16 parameters including nested line items and no output schema. The description does not address required vs optional fields, validation constraints, or what happens on success or failure. Schema descriptions fill some gaps, but more holistic guidance would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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 each parameter. The tool description summarizes key parameters (status, amount, currency, payer/vendor, dates, line items) but adds no new meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it creates a real invoice, lists key fields (status, amount, currency, payer/vendor, dates, line items), and distinguishes from sibling tools like mercoa_find_invoices (read) and mercoa_update_invoice (update). The status guidance (DRAFT to stage, NEW to submit) adds specificity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implied usage is clear (create new invoice), but no explicit when-not or alternatives. However, the status hints provide context for different creation scenarios (draft vs. submit).

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

mercoa_find_entitiesFind entitiesA
Read-only
Inspect

Find/search entities (buyers, vendors, payors, payees). Use to look up counterparties by name/email/foreignId or list all. GET /entity.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMax entities to return (1-100, default 10).
searchNoSearch by name, email, emailTo, entity ID, or foreign ID (partial matches).
statusNoEntity status filter (e.g. verified, pending).
isPayeeNoFilter entities marked as payees.
isPayorNoFilter entities marked as payors.
foreignIdNoYour system's ID(s) for the entity.
isCustomerNoIf true, only entities with a direct relationship to your organization.
startingAfterNoEntity ID cursor for pagination.
paymentMethodsNoIf true, include payment methods in the response.
returnMetadataNoMetadata key(s) to include in the response.
Behavior4/5

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

Annotations declare readOnlyHint=true, so no need to restate. Description adds context that it's a GET endpoint and can search by various fields. No contradictions. Could mention pagination behavior more explicitly, but adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences: first sets purpose, second gives usage guidance. No redundant words. Front-loaded and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 10 parameters and no output schema, the description covers the core use cases. It could mention that the response is a list of entities and hint at pagination via startingAfter, but the schema descriptions handle parameter details. Sufficient for a straightforward read-only search tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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 parameters. Description adds value by grouping searchable fields (name/email/foreignId) but doesn't significantly enhance understanding beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states verb (find/search) and resource (entities), and distinguishes by specifying counterparty types (buyers, vendors, payors, payees). Differentiates from sibling tools like create_entity or get_entity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly instructs to use for looking up counterparties by name/email/foreignId or listing all entities. However, it does not mention when to use get_entity instead (e.g., when you need a single entity by ID) or specify exclusions.

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

mercoa_find_invoicesFind invoicesA
Read-only
Inspect

Find/search invoices (bills) across payers and vendors. Filter by status, entity, date, approver and more. GET /invoices (plural list endpoint).

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMax invoices to return (1-100, default 10).
searchNoSearch by vendor name, invoice number, check number, or amount.
statusNoInvoice status filter (e.g. DRAFT, NEW, APPROVED, SCHEDULED, PAID).
endDateNoEnd date filter (ISO 8601).
orderByNoField to order by (e.g. CREATED_AT, AMOUNT, DUE_DATE).
payerIdNoFilter by payer ID(s) or foreign ID(s).
dateTypeNoDate type to filter by (e.g. CREATED_AT, DUE_DATE).
entityIdNoFilter by entity (payer or vendor) ID(s) or foreign ID(s).
vendorIdNoFilter by vendor ID(s) or foreign ID(s).
invoiceIdNoFilter by invoice ID(s) or foreign ID(s).
startDateNoStart date filter (ISO 8601).
approverIdNoFilter by assigned approver user ID(s).
paymentTypeNoFilter by payment type (e.g. recurring).
creatorUserIdNoFilter by the user ID(s) that created the invoice.
entityGroupIdNoFilter by entity group ID.
startingAfterNoInvoice ID cursor for pagination.
approverActionNoFilter by approver action (use with approverId), e.g. APPROVE.
orderDirectionNoasc or desc.
invoiceTemplateIdNoFilter by invoice template ID(s).
returnPayerMetadataNoInclude payer metadata in the response.
returnPaymentTimingNoInclude payment timing in the response.
returnVendorMetadataNoInclude vendor metadata in the response.
Behavior3/5

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

Annotations already provide readOnlyHint=true, so the description does not need to repeat it. It adds context about being a list endpoint, which implies pagination. However, it does not disclose rate limits, pagination behavior, or response structure beyond what annotations and schema provide. With annotations covering the safety profile, a score of 3 is appropriate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence plus a parenthetical about the endpoint. It is concise, front-loaded with the key purpose, and contains no unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 22 optional parameters, no output schema, and readOnlyHint annotation, the description adequately covers the tool's purpose and filter capabilities. It could be improved by mentioning pagination or the default return format, but it is still mostly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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 well-described in the schema. The description only lists filter types generically, adding no new meaning beyond the schema. Baseline is 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it finds/searches invoices (bills) across payers and vendors, lists several filter types, and explicitly mentions the endpoint 'GET /invoices (plural list endpoint)'. This distinguishes it from sibling tools like mercoa_get_invoice (singular) and mercoa_create_invoice.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use the tool (search/filter invoices) but does not explicitly state when not to use it or provide alternatives like mercoa_get_invoice for a single invoice. The endpoint hint gives some context, but clearer guidance would improve the score.

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

mercoa_find_transactionsFind transactionsA
Read-only
Inspect

List/search payment transactions. Filter by entity, invoice, status, type and date. GET /transactions.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMax transactions to return (1-100, default 10).
searchNoSearch by vendor name, invoice number, check number, or amount.
statusNoTransaction status filter.
endDateNoCREATED_AT end date filter (ISO 8601).
payerIdNoFilter by payer ID(s).
entityIdNoFilter by entity ID(s) or foreign ID(s).
vendorIdNoFilter by vendor ID(s).
invoiceIdNoFilter by invoice ID(s) or foreign ID(s).
startDateNoCREATED_AT start date filter (ISO 8601).
entityGroupIdNoFilter by entity group ID.
startingAfterNoTransaction ID cursor for pagination.
transactionIdNoFilter by transaction ID(s).
transactionTypeNoFilter by transaction type.
Behavior4/5

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

Annotations already declare readOnlyHint=true, covering the read-only safety profile. The description adds the endpoint (GET /transactions) and filter context, which aligns with the annotations. No additional behavioral traits beyond what annotations provide are needed, achieving a score of 4.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence plus the endpoint, highly concise. It front-loads the core purpose ('List/search payment transactions') and wastes no words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 13 parameters all described in the schema, no output schema, and readOnlyHint, the description is adequate. However, it could briefly mention pagination (startingAfter) or ordering, but not required for completeness given the schema coverage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description only lists generic filter categories ('entity, invoice, status, type and date') without adding meaning beyond what the schema already details for each parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists/searches payment transactions, mentions key filters (entity, invoice, status, type, date), and includes the endpoint. This distinguishes it from siblings like get_transaction (single transaction) and find_invoices (invoices vs transactions).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies search functionality but does not explicitly state when to use this tool over alternatives like get_transaction or find_invoices. No when-not or exclusion criteria are provided, limiting guidance for an AI agent.

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

mercoa_get_entityGet entityA
Read-only
Inspect

Get a single entity by ID (or foreign ID). GET /entity/{entityId}.

ParametersJSON Schema
NameRequiredDescriptionDefault
entityIdYesEntity ID (e.g. ent_...) or foreign ID.
Behavior3/5

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

Annotations already provide readOnlyHint=true. The description adds no further behavioral details (e.g., error handling, authorization) beyond restating the GET endpoint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One concise sentence with no waste, front-loaded with verb and resource. Includes useful HTTP method and path. Efficient for a simple tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple get-by-ID tool with 1 parameter, 100% schema coverage, and read-only annotations, the description is mostly complete. Lacks details on return value or error cases, but baseline expectations are met.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description covers 100% of the single parameter. The description adds no new information beyond what the schema already provides (e.g., path parameter, foreign ID). Baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses specific verb 'Get' and resource 'single entity by ID (or foreign ID)', clearly distinguishing from sibling 'mercoa_find_entities' which searches entities.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implicitly indicates use when you have an entity ID, but does not explicitly state when not to use (e.g., use find_entities for searching) or provide alternative guidance.

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

mercoa_get_entity_eventsGet entity eventsB
Read-only
Inspect

Get the event/audit log for an entity. GET /entity/{entityId}/events.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMax events to return (1-100).
endDateNoEnd date filter (ISO 8601).
entityIdYesEntity ID or foreign ID.
startDateNoStart date filter (ISO 8601).
startingAfterNoEvent ID cursor for pagination.
Behavior3/5

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

The description adds the HTTP method and confirms it's a read operation, but beyond that, there is no disclosure of behavioral traits such as pagination, ordering, or potential errors. The annotations already provide readOnlyHint, so the description's additional value is limited.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise (single sentence plus endpoint) with no wasted words. However, it lacks structured presentation (e.g., sections) that could improve scannability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given there are 5 parameters and no output schema, the description is too minimal. It does not explain pagination (startingAfter, limit), date filters, or the structure of the event log, leaving the agent with many unknowns.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents all parameters. The description does not provide extra meaning beyond the schema (e.g., usage tips or format details). Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (Get) and the resource (event/audit log for an entity). It also provides the HTTP endpoint, leaving no ambiguity about the tool's purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given on when to use this tool versus alternatives like mercoa_get_invoice_events. There is no mention of prerequisites, use cases, or exclusions.

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

mercoa_get_entity_invoice_metricsGet entity invoice metricsA
Read-only
Inspect

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
searchNoSearch by vendor name, invoice number, check number, or amount.
statusNoInvoice status filter (e.g. NEW, SCHEDULED, PAID).
endDateNoEnd date filter (ISO 8601).
groupByNoAdditional grouping (e.g. by status).
payerIdNoFilter by payer ID(s).
currencyNoCurrency code(s) to filter on, e.g. USD.
dateTypeNoDate type to filter by (e.g. CREATED_AT, DUE_DATE).
entityIdYesEntity ID or foreign ID.
vendorIdNoFilter by vendor ID(s).
invoiceIdNoFilter by invoice ID(s) or foreign ID(s).
startDateNoStart date filter (ISO 8601).
approverIdNoFilter by assigned approver user ID(s).
returnByDateNoGroup metrics by date, e.g. CREATION_DATE or DUE_DATE.
excludePayablesNoOnly return receivables (exclude payables).
excludeReceivablesNoOnly return payables (exclude receivables).
returnByDateFrequencyNoFrequency for date grouping (e.g. DAILY, MONTHLY).
Behavior4/5

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

Annotations already declare readOnlyHint=true, signaling a safe read operation. The description adds that the tool returns totals and counts grouped by currency, which provides behavioral context beyond annotations. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, informative sentence followed by the endpoint. It is front-loaded with the core purpose and has no wasted words. Highly concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 16 parameters and no output schema, the description adequately explains the return type (totals/counts grouped by currency) and use case. It could be more specific about the response structure, but it is generally complete for an agent to decide on using it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description mentions grouping by currency, but the input schema already details all parameters, including currency, groupBy, etc. The description does not add significant new meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it gets aggregate invoice metrics (totals/counts, grouped by currency) for an entity's payables/receivables, intended for AP/AR dashboards and aging. This distinguishes it from sibling tools like mercoa_get_invoice (single invoice) and mercoa_find_invoices (list of invoices), providing a specific verb+resource+scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description indicates usage for aggregate metrics and dashboards, implying it's for summary data. However, it does not explicitly state when not to use it or name alternatives. The context is clear but lacks explicit exclusions.

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

mercoa_get_invoiceGet invoiceA
Read-only
Inspect

Get a single invoice (bill) by ID. GET /invoice/{invoiceId}.

ParametersJSON Schema
NameRequiredDescriptionDefault
invoiceIdYesInvoice ID (e.g. in_...) or foreign ID.
Behavior3/5

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

Annotations already provide readOnlyHint=true, so the description does not need to restate safety. The description adds the HTTP method but no other behavioral traits (auth, rate limits, etc.). Minimal added value 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.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise: one sentence plus the HTTP path. Every word is necessary. Front-loaded with the key action and resource.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (get by ID with one parameter) and existing schema/annotations, the description is complete. No output schema exists, but the return value is implied as an invoice object. Could add more about expected response but not necessary for this low complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema fully documents the parameter. The description does not add any additional meaning beyond the schema's parameter description. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves a single invoice by ID, using 'Get' and includes the HTTP method and path. It differentiates from sibling tools like mercoa_find_invoices (search) and mercoa_update_invoice (mutation).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives. The context implicitly suggests using it when you have a specific invoice ID, but no when-not-to-use or alternative mentions.

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

mercoa_get_invoice_eventsGet invoice eventsA
Read-only
Inspect

Get the event/audit log for an invoice (status changes, approvals, payments). GET /invoice/{invoiceId}/events.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMax events to return (1-100).
endDateNoEnd date filter (ISO 8601).
invoiceIdYesInvoice ID or foreign ID.
startDateNoStart date filter (ISO 8601).
startingAfterNoEvent ID cursor for pagination.
Behavior3/5

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

The 'readOnlyHint' annotation already indicates this is a read operation. The description adds context about the content of the events (status changes, approvals, payments) but does not disclose other behavioral aspects like pagination, rate limits, or whether the data is ordered.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that states the purpose, includes an example endpoint, and is free of superfluous information. It is front-loaded and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

While the tool has a moderate number of parameters (5) and no output schema, the description is minimal. It does not explain the return format, pagination behavior, or default behavior of filters. Given the complexity, the description could include more context to aid effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so each parameter is documented in the schema. The description adds no additional information about the parameters; it relies entirely on the schema. Thus, the description provides no added value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly indicates the tool retrieves the event/audit log for an invoice, specifying the types of events (status changes, approvals, payments). It includes the HTTP method and endpoint, making the purpose unambiguous. The sibling list includes 'mercoa_get_entity_events', which targets entities, so the 'invoice' context effectively differentiates.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives, such as when to use 'mercoa_get_entity_events' or other audit log tools. There is no mention of prerequisites, context for use, or when not to use it.

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

mercoa_get_organizationGet organizationA
Read-only
Inspect

Get the caller's Mercoa organization configuration (settings, payment methods enabled, etc.). GET /organization.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Behavior4/5

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

Annotations already declare readOnlyHint=true, so the description is not burdened with basic safety. It adds value by specifying scope ('the caller's') and content ('settings, payment methods enabled'), which goes beyond the annotation. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence plus the endpoint. Every word is informative with no waste. Front-loaded with the key verb and resource. Ideal conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no parameters or output schema, so complexity is low. The description covers purpose and scope adequately. However, it could briefly mention that it returns the full organization object to avoid uncertainty, but not essential.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, so schema coverage is 100%. The description does not need to add parameter details. Baseline of 4 is appropriate as there is nothing missing.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the verb 'Get', resource 'organization configuration', and provides specific examples of what it returns ('settings, payment methods enabled'). The HTTP path further confirms the action. Distinguishes from sibling tools like 'get_entity' which target entities rather than the organization.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implies usage for retrieving the caller's own organization config, but provides no explicit guidance on when to use vs alternatives, nor any when-not-to-use conditions. Lacks exclusions or context that would help an agent decide between this and related tools like 'mercoa_get_entity'.

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

mercoa_get_payment_methodGet payment methodA
Read-only
Inspect

Get a single payment method for an entity. GET /entity/{entityId}/paymentMethod/{paymentMethodId}.

ParametersJSON Schema
NameRequiredDescriptionDefault
entityIdYesEntity ID or foreign ID.
paymentMethodIdYesPayment method ID (e.g. pm_...).
Behavior3/5

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

Annotations already declare readOnlyHint=true, so the agent knows it's a safe read. The description adds the endpoint but no additional behavioral context (e.g., error handling, authentication requirements, or data sensitivity). This is adequate but does not exceed what annotations already imply.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise: one sentence plus the endpoint path. No redundant information, front-loaded with the core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (two required string params, no output schema, readOnlyHint), the description is mostly complete. It could optionally mention the response format or that the entityId may be a foreign ID, but the schema already covers that. Minimal gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with clear parameter descriptions for entityId and paymentMethodId. The description adds no extra meaning 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.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Get') and resource ('a single payment method for an entity'), and provides the endpoint path. This distinguishes it from sibling tools like 'mercoa_list_entity_payment_methods' which lists multiple payment methods.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool vs alternatives (e.g., when to use list vs get by ID). The description simply states what it does without contextual usage advice.

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

mercoa_get_transactionGet transactionA
Read-only
Inspect

Get a single payment transaction by ID. GET /transaction/{transactionId}.

ParametersJSON Schema
NameRequiredDescriptionDefault
transactionIdYesTransaction ID.
Behavior3/5

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

The `readOnlyHint: true` annotation already indicates this is a read-only operation. The description adds the HTTP method (GET) and path, but does not disclose additional behavioral traits such as error handling, rate limits, or response format beyond 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.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: two short sentences, no filler, and front-loaded with the essential purpose. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple get-by-ID tool with one parameter and annotations covering safety, the description is minimally adequate. However, since there is no output schema, a brief note on the response shape (e.g., 'returns the transaction object') would improve completeness for agents.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a single parameter `transactionId` described as 'Transaction ID.' The description adds no extra meaning beyond the schema's description, so baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Get a single payment transaction by ID', specifying the action (get), resource (single transaction), and the required ID. This distinguishes it from sibling tools like `mercoa_find_transactions` which is for searching multiple transactions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when you have a transaction ID and need the single transaction details, but it does not explicitly state when to use this tool versus alternatives like `mercoa_find_transactions`. No when-not or alternative tool names are mentioned.

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

mercoa_list_entity_payment_methodsList entity payment methodsA
Read-only
Inspect

List an entity's payment methods (bank accounts, cards, check, etc.). GET /entity/{entityId}/paymentMethods.

ParametersJSON Schema
NameRequiredDescriptionDefault
typeNoFilter by payment method type (e.g. bankAccount, card, check).
entityIdYesEntity ID or foreign ID.
Behavior3/5

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

The annotation 'readOnlyHint: true' already indicates read-only behavior. The description adds no additional behavioral context such as permissions, rate limits, or side effects. It is consistent with annotations but does not provide further transparency beyond the schema and annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: one sentence plus the endpoint. Every part is functional with no wasted words. It is front-loaded with the core action and resource.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the description does not explain the return structure, pagination, or error handling. For a simple list endpoint, it is minimally adequate but could be more complete. Given the context, it lacks detail compared to richer sibling tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, with both parameters fully described in the input schema. The description adds minimal extra meaning, only providing example values for the 'type' parameter. It does not compensate beyond what the schema already offers.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'List an entity's payment methods' with examples of types, and provides the endpoint. It specifies the verb (List) and resource (entity's payment methods), distinguishing it from the sibling tool 'mercoa_get_payment_method' which retrieves a single method.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives. The description implies it is for listing all payment methods for an entity, but does not mention filtering, pagination, or conditions for use. It is adequate but lacks explicit when/when-not instructions.

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

mercoa_list_entity_usersList entity usersB
Read-only
Inspect

List the users belonging to an entity (approvers, admins, etc.). GET /entity/{entityId}/users.

ParametersJSON Schema
NameRequiredDescriptionDefault
entityIdYesEntity ID or foreign ID.
Behavior2/5

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

Annotations already set readOnlyHint=true, indicating a safe read operation. The description adds only the endpoint path, which is not behavioral. It does not disclose pagination, authentication needs, or error handling, providing minimal added transparency 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.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise—a single sentence plus endpoint path. Every word is necessary, but it could be slightly more structured (e.g., separate behavior from endpoint). Still, it is efficient and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list operation, the description adequately states the purpose and parameter. However, it lacks information about the return format (e.g., array of users) and any pagination details. Given no output schema, this gap reduces completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for the single parameter (entityId), with a brief description. The tool description adds no additional semantics, examples, or constraints beyond the schema. With high schema coverage, baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'List' and the resource 'users belonging to an entity', with examples of user roles (approvers, admins). It is specific and distinct from sibling tools that focus on invoices, payment methods, or entity creation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives, nor does it mention prerequisites or exclusion criteria. It only states what the tool does without contextual usage advice.

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

mercoa_update_invoiceUpdate invoiceA
Destructive
Inspect

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}.

ParametersJSON Schema
NameRequiredDescriptionDefault
amountNoTotal invoice amount.
statusNoNew invoice status, e.g. NEW, APPROVED, SCHEDULED.
dueDateNoDue date (ISO 8601).
payerIdNoPayer entity ID.
currencyNoCurrency code, e.g. USD.
metadataNoArbitrary key/value metadata.
vendorIdNoVendor entity ID.
invoiceIdYesInvoice ID to update.
lineItemsNoReplacement line items array.
noteToSelfNoInternal note.
invoiceDateNoInvoice date (ISO 8601).
deductionDateNoScheduled payment/deduction date (ISO 8601).
invoiceNumberNoHuman-readable invoice number.
paymentSourceIdNoPayment method ID to pay from.
paymentDestinationIdNoPayment method ID to pay to.
Behavior3/5

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

Annotations already indicate destructiveHint=true. The description adds WRITE label and example status progression, which provides some behavioral context beyond annotations, but not extensive detail.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with prefix 'WRITE', followed by examples and endpoint. No redundant information, perfectly front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 15 parameters and nested objects, the description covers high-level purpose and typical usage. No output schema, but endpoint and common modifications are included.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description notes all fields are optional for partial updates, adding value beyond schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states it updates an existing invoice/bill, gives concrete examples like advancing status or changing amounts, and differentiates from create_invoice and get_invoice via context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides common use cases such as status advancement and field changes, and implies partial updates. It could explicitly mention alternatives, but the sibling list and context make it clear.

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

Discussions

No comments yet. Be the first to start the discussion!

Related MCP Servers

  • A
    license
    -
    quality
    B
    maintenance
    Exposes ~60 tools for the Merit Aktiva accounting API, covering sales/purchase invoices, payments, customers, vendors, items, general ledger, offers, reference data, and reports with both read and write operations.
    20
    MIT
  • A
    license
    -
    quality
    B
    maintenance
    Enables LLM agents to manage QuickBooks Online invoices, customers, and payments via typed tools with OAuth 2.1 authentication, rate limiting, and retries, plus read-only resources for company and receivables summaries.
    MIT
  • A
    license
    A
    quality
    A
    maintenance
    Enables interaction with the Centrapay payments API for testing NZ payment flows, including creating, managing, and settling payment requests through natural language.
    9
    13
    1
    MIT
  • A
    license
    -
    quality
    C
    maintenance
    Enables AI agents to read and write Cynco accounting data, including querying books, creating invoices, reconciling transactions, and generating financial reports.
    9
    1
    MIT

View all MCP Servers

Try in Browser

Your Connectors

Sign in to create a connector for this server.