Billy MCP Server

Overview Schema Related Servers Score Discussions

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v1.0.0
Disambiguation5/5
Every tool targets a distinct resource and action, with clear separation between entities like contacts, invoices, products, payments, bills, and accounts. List/get/create/update operations are specific to their subject, and even similar tools like list_bills and list_invoices are distinguished by the vendor invoice descriptor.
Naming Consistency5/5
All tool names follow the consistent pattern 'billy_<verb>_<entity>' using snake_case throughout. The verbs (list, get, create, update) are uniform and predictable, making it easy to infer functionality from the name.
Tool Count5/5
With 15 tools, the server is at the upper boundary of the ideal range but remains well-scoped for an accounting/billing API. Each tool represents a meaningful operation across a coherent set of resources without redundancy.
Completeness4/5
The core accounting workflows are covered: contacts (CRUD minus delete), invoices (create/list/get), products (create/list/get), payments (create), and supporting lists for bills and accounts. Minor gaps like invoice updates or product updates exist, but agents can work around them or these may be deliberately omitted for compliance reasons.
Average 3.4/5 across 15 of 15 tools scored.
See the Tool Scores section below for per-tool breakdowns.
- 0 of 1 community issues answered or closed in the last 6 months
- 0 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only says 'create' without detailing side effects, default states, auto-generation behavior, or relationship requirements. This is insufficient for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no wasted words. It is front-loaded with the verb 'create' but lacks additional structure or detail; still, it is appropriately brief, similar to the TDQS 2.9 example.
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?
The tool has 8 parameters, no annotations, and no output schema. The description fails to mention return values, prerequisites, default behaviors, or other contextual information, making it incomplete for an agent to use correctly.
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 even with no parameter information in the tool description. The description itself adds no parameter meaning beyond what the schema already provides.
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 'Create a new invoice in Billy' clearly identifies the action (create) and the resource (invoice), distinguishing it from sibling tools like list/get/update. It is specific and unambiguous.
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, nor any prerequisites or exclusions. The description simply states the action without contextual advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only states 'List chart of accounts' with no mention of readonly behavior, pagination, or return format, leaving the agent without critical context.
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 concise sentence with no wasted words. It is front-loaded and directly states the purpose, making it easy to process.
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?
The tool is simple and the schema covers all parameters, but the description is minimal. It lacks context about pagination behavior, return value structure, or when to use, which would be helpful given no annotations and no output schema.
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 schema covers 100% of parameters with descriptions, so the baseline is 3. The description adds no semantic detail beyond the schema, but the schema already provides sufficient parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List chart of accounts' clearly states the verb and resource, identifying the tool as a listing operation for accounting accounts. It distinguishes from sibling tools implicitly through the resource name, but does not explicitly differentiate from other list tools.
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. It does not mention pagination, filtering, or any context for selection among sibling list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits such as return values, side effects, or authentication needs. It only says 'Create a new contact' and provides no insight into what happens after creation or any operational constraints.
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, clear sentence with no unnecessary words. It is appropriately concise for a simple create operation.
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?
For a tool with 12 parameters and no output schema, the description is insufficient. It fails to mention what is returned after creation, any required prerequisites, or how it relates to other contact operations. The schema is rich, but the descriptive context is too sparse.
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% with every parameter having a description. The tool description adds no extra parameter-level detail, so the baseline 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 the action ('Create') and the resource ('a new contact') within the Billy system. It distinguishes from sibling tools like billy_update_contact and billy_list_contacts by specifying 'create'.
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. There are no naming of alternative tools, exclusions, or usage context beyond the mere action of creating.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for disclosing behavioral details. However, it only states 'Create a new product' and does not mention side effects, permissions, idempotency, or error behavior, offering little transparency for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no superfluous words. It is efficiently front-loaded and earns its place as a clear, concise statement of the tool's purpose.
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 the tool's complexity (6 parameters) and lack of output schema or annotations, the description is inadequate. It does not explain return values, error conditions, or typical usage contexts, leaving significant gaps in the information an agent needs.
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 provides descriptions for all parameters (100% coverage), so the baseline is 3. The description adds no additional parameter context beyond the schema, so it neither enhances nor detracts from what is already available.
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 a specific verb 'Create' and clearly identifies the resource ('a new product') within the context of 'Billy'. This distinguishes it from sibling tools like create_contact and 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 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, no exclusions, and no prerequisites. It merely states the action without contextual cues or alternative suggestions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description is the only source of behavioral information. It only states the action 'Get organization details' with no mention of authentication requirements, rate limits, response structure, or any side effects. This is thin disclosure for an API call, even a read-only one.
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, concise sentence with no extraneous words. It is appropriately sized for a parameterless get operation, and the key information ('Get organization details') is 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?
The tool is simple (no parameters, no output schema) but the description still leaves gaps: it doesn't indicate what exactly is returned (e.g., full org object, summary) or any error conditions. Since no output schema exists, the description carries the burden of explaining the return value, which it does not fully do. Overall, adequate for a minimal tool but not complete.
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?
The tool has zero parameters, so the schema trivially covers them. The description adds no parameter information because none is needed. Baseline for zero parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's function—retrieving organization details from Billy. It is unambiguous and distinct from sibling tools that target other resources like contacts, invoices, or products, though it does not explicitly differentiate itself. The verb 'Get' is specific and appropriate.
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 compared to alternatives. It simply states what it does, with no mention of use cases, prerequisites, or why an agent would choose this over other Billy tools. This is a significant omission.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It only says 'Get', implying a read operation, but does not disclose behavior like error handling, return format, or whether related resources can be included. No context is added beyond the basic operation.
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, focused sentence that immediately conveys the tool's purpose with no wasted words.
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?
The tool is simple and the description is adequate for a basic get-by-id, but the lack of usage guidelines and behavioral transparency leaves gaps. For a read tool with no annotations, it could benefit from noting safety or typical use cases.
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 parameters are already well-documented. The description adds no further meaning to 'id' or 'include', but the schema suffices for a basic get operation.
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 a specific verb ('Get') and resource ('product') with a scope ('by ID'). It distinguishes this from sibling tools like billy_list_products, which retrieves multiple products.
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 billy_list_products for multiple products or billy_create_product for new products. There is no mention of constraints or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states that filtering and pagination are optional, but does not disclose defaults (e.g., page size), return format, or any side effects. This minimal information is insufficient for a tool with no structured safety 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 a single seven-word sentence that is front-loaded and free of redundancy. Every word earns its place, making it highly 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?
For a simple list tool with six optional parameters and no output schema, the description is adequate but incomplete. It does not explain the return value structure or provide usage context beyond the bare essentials. The high schema coverage partially compensates, but without annotations, the description could be richer.
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?
Input schema covers 100% of parameters with descriptions, so the baseline is 3. The tool description groups parameters into 'filtering' and 'pagination', but adds no substantive meaning beyond the schema. It is not misleading, just redundant.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('list') and resource ('products') with mention of optional filtering and pagination. It clearly indicates this is a list operation, distinguishing it from singular get_product and create_product by name, but does not explicitly contrast with those siblings.
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 the goal is to list products with optional filtering/pagination. However, it provides no explicit guidance on when to prefer this over billy_get_product or billy_create_product, nor any exclusions or alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It only states 'Create a payment to mark invoices as paid' but fails to mention that the tool also handles bills (cashSide credit), that it may update invoice/bill status, or what the response structure is. It does not disclose side effects, permissions, or reversibility, leaving significant uncertainty for a write operation.
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, concise sentence, immediately stating the action and purpose. It is front-loaded and contains no fluff or redundant information. Every word contributes to the meaning, making it an example of efficient writing.
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 the tool's complexity (7 parameters, 5 required, no output schema), the description is far too short to be complete. It does not explain the return value, side effects on invoices/bills, or the distinction between paying invoices versus bills. Critical usage context, such as the need for subjectReference formats or fee handling, is only in the schema, leaving the description insufficient for an agent to understand the full scope.
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%, with each parameter having its own description (e.g., cashSide explains debit vs credit, entryDate format). The description of the tool itself adds no parameter-specific semantics beyond implying the purpose of associations. Since the schema is comprehensive, the description provides minimal additional value, earning the baseline score.
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 'Create a payment to mark invoices as paid' uses a specific verb ('Create') and resource ('payment'), clearly identifying the tool's action. It distinguishes from sibling tools like list_bank_payments (read operation) and create_invoice (different resource). Though it only mentions invoices, the tool also handles bills via cashSide, but the core purpose is still clear.
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 for recording payments that mark invoices as paid, but provides no explicit guidance on when to use this versus alternatives. Sibling tools are mostly for different entities (contacts, invoices, products), and only billy_list_bank_payments overlaps slightly, but no alternatives or exclusions are stated. The schema hints at usage via required fields and the cashSide enum, but the description does not elaborate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden for behavioral disclosure. The description only restates the tool's basic action and does not mention return format, error behavior, permissions, or the impact of the 'include' parameter, leaving significant behavioral aspects undisclosed.
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, focused sentence that immediately conveys the tool's purpose. It is appropriately sized for the tool's simplicity and contains no filler.
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 is no output schema, the description should explain what the tool returns or any relevant behavioral context. It does neither, leaving the agent to guess about the response shape, error handling, or how 'include' affects the result. The description is minimal but insufficiently informative for a complete understanding.
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%: both 'id' and 'include' have descriptions, with 'include' providing an example. The description text adds no additional semantic value beyond what the schema already provides, so the 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 'Get a specific invoice by ID' uses a specific verb ('Get') and resource ('invoice') with a clear scope (by ID). This clearly distinguishes it from sibling tools like billy_list_invoices, which list invoices without an ID filter.
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 tool's purpose is straightforward and implies usage when a specific invoice ID is known. However, it does not explicitly state when to use this over alternatives (e.g., listing invoices) or mention any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'Update an existing contact' and fails to mention whether updates are partial or full, what response to expect, or any side effects. This is a significant transparency gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no unnecessary words. It is front-loaded with the verb and object, making it immediately clear what the tool does. Every word earns its place.
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 the high parameter count (11), no output schema, and no annotations, the description is insufficiently complete. It does not explain update semantics (e.g., partial vs. full update), whether the updated contact is returned, or any prerequisites. The agent would need to infer too much from the schema alone.
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% for all 11 parameters, each with a clear description. The tool description adds no parameter-specific information, so the schema carries the semantic weight. This matches the baseline of 3 given high schema coverage.
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 'Update an existing contact' clearly states the action (update) and resource (contact), distinguishing it from sibling tools like billy_create_contact and billy_get_contact. The verb is specific and the scope is clear.
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 for modifying an existing contact, but does not explicitly mention when to use this tool versus creating a new contact or when not to use it. No alternatives are named, leaving the guidance implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full behavioral burden. It only mentions 'List bank payments with optional filtering and pagination' but does not disclose response format, default pagination behavior, authentication needs, or any side effects. As a read-only list operation, this is a limited but notable gap.
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, front-loaded with 'List bank payments', and contains no superfluous words. It is appropriately sized for a simple list tool with well-documented schema.
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?
The tool has 6 optional parameters and no output schema. The description is minimal but sufficient to convey the basic purpose. However, it lacks context on return structure or any behavioral specifics that could be helpful given no annotations and no output schema.
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's 'optional filtering and pagination' adds only a high-level summary, not specific parameter meaning. The schema itself fully documents each parameter, so the description does not need to compensate.
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 uses the verb 'List' and specifies the resource 'bank payments', distinguishing it from sibling list tools like billy_list_invoices and billy_list_bills. 'Optional filtering and pagination' further clarifies scope.
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 for listing bank payments but does not explicitly state when to prefer this tool over alternatives (e.g., billy_list_invoices or billy_list_bills). There are no mention of exclusions or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It implies a read-only list operation and mentions filtering and pagination, but doesn't disclose pagination defaults, maximums, or sorting behavior beyond what the schema already states.
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 concise sentence that is front-loaded and contains no filler.
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 the tool has 7 parameters, no output schema, and no annotations, the description is too sparse. It doesn't mention the available filter fields, sorting, or return format, leaving the agent to discover these from the schema.
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% and each parameter has a clear description, so the description adds little beyond the schema. The phrase 'optional filtering and pagination' summarizes but doesn't add new meaning.
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 bills and clarifies that bills are vendor invoices, which distinguishes it from the sibling billy_list_invoices. The verb 'List' plus resource is specific and unambiguous.
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 says 'with optional filtering and pagination', which gives context on how to use it, but it doesn't explicitly say when to use this over billy_list_invoices or other list tools. No alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full transparency burden. It only says 'List', which implies a read-only operation, but it does not disclose default behavior, response format, pagination limits, or any side effects. The schema covers parameter details, leaving significant behavioral ambiguity.
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, front-loaded sentence with zero wasted words. It effectively communicates the tool's main purpose without redundancy.
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?
With 8 parameters, no annotations, and no output schema, the description is too sparse to be contextually complete. It fails to mention default behavior, how filters combine, what the response looks like, or any usage caveats. The description only scratches the surface for a tool of this 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 description coverage is 100%, so parameters are already well-documented. The description adds no additional meaning beyond what the schema provides, so the baseline 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 uses a specific verb ('List') and resource ('invoices'), and clearly indicates optional filtering and pagination. This distinguishes it from single-invoice retrieval (billy_get_invoice) and other list tools.
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 clearly states the core use case: listing invoices with optional filters and pagination. It does not explicitly name alternative tools or exclusions, but the context makes the tool's purpose evident among the siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the core behavior (listing) and adds that filtering and pagination are optional, which is helpful. However, it does not mention return format, default pagination behavior, sort defaults, or any side effects (though 'list' implies read-only). It adds some value beyond the name but remains minimal.
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, front-loaded with the action and resource, and contains zero wasted words. It efficiently communicates the core functionality without unnecessary elaboration.
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?
Given there is no output schema and no annotations, the description is short but covers the essential behavior. It does not describe return values, edge cases, or what happens with no filters, but for a simple list tool it is minimally viable. More detail about response shape or default behavior 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?
The input schema has 100% coverage, with descriptions for all six parameters. The description only recaps 'optional filtering and pagination' without adding new syntax or format details. Baseline of 3 is appropriate as the schema does the heavy lifting and the description adds no extra parameter-specific meaning.
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 states 'List contacts' with a specific verb and resource, clearly distinguishing it from 'billy_get_contact' (single contact retrieval). The addition of 'optional filtering and pagination' further scopes the behavior and differentiates it from other list tools like 'billy_list_invoices'.
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 through the tool name and the verb 'List', but it does not explicitly state when to choose this over 'billy_get_contact' or mention any exclusions. It provides clear context that it lists contacts with optional filtering/pagination, but lacks explicit alternatives or when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. 'Get' signals a read-only operation, but the description does not disclose error behavior, authentication requirements, or return format. It is minimal but not misleading.
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, concise and front-loaded with the verb 'Get'. Every word is necessary and there is no filler.
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 fully documented parameters, the description is adequate. The return value is implied by the tool name, but no output schema exists, so a brief mention of what is returned could have improved 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%, with both 'id' and 'include' already described. The description adds no additional parameter semantics, so it receives the baseline score of 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 the verb 'Get', the resource 'contact', and the scope 'by ID', which distinguishes it from list_contacts that retrieves multiple contacts. It is specific and unambiguous.
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 'by ID' phrasing implies this tool is used when you have a specific contact ID, but it does not explicitly mention alternatives or when not to use it. No reference to sibling tools like list_contacts or get_invoice, so guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![billy-mcp-server MCP server](https://glama.ai/mcp/servers/markhm/billy-mcp-server/badges/card.svg)](https://glama.ai/mcp/servers/markhm/billy-mcp-server)

Score Badge

Copy to your README.md:

[![billy-mcp-server MCP server](https://glama.ai/mcp/servers/markhm/billy-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/markhm/billy-mcp-server)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/markhm/billy-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server