Xero MCP Server

Official

by XeroAPI

Overview Schema Related Servers Score Discussions

TypeScript

Remote

Server Quality Checklist

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

Latest release: v1.0.0
Disambiguation4/5
Most tools have distinct purposes targeting specific resources and actions (e.g., create-invoice vs. update-invoice), but there is some overlap in list operations (e.g., list-contacts and list-contact-groups) that could cause minor confusion. The descriptions help clarify, but the sheer number of tools increases the risk of misselection.
Naming Consistency5/5
Tool names follow a consistent verb_noun pattern throughout (e.g., create-contact, list-invoices, update-timesheet-line), with no deviations in style or convention. This predictability makes it easy for agents to understand and navigate the toolset.
Tool Count2/5
With 51 tools, the count is excessive for a single server, making it heavy and potentially overwhelming for agents. While Xero is a comprehensive platform, this many tools suggests poor scoping and could lead to inefficiency in tool selection and usage.
Completeness5/5
The toolset provides complete CRUD/lifecycle coverage across multiple domains (e.g., invoices, contacts, payroll, reports), with no obvious gaps. It includes creation, listing, updating, and deletion operations where applicable, ensuring agents can handle end-to-end workflows without dead ends.
Average 3.2/5 across 51 of 51 tools scored. Lowest: 2.4/5.
See the Tool Scores section below for per-tool breakdowns.
- 2 of 33 community issues answered or closed in the last 6 months
- 1 commit in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
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.
This repository includes a glama.json configuration file.
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?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states 'Update an item' which implies a mutation operation, but it doesn't cover critical aspects like required permissions, whether updates are reversible, rate limits, error handling, or what the response looks like. This leaves significant gaps for a tool with 9 parameters and nested objects.
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 with just one sentence, 'Update an item in Xero.', which is front-loaded and wastes no words. While it may be too brief for completeness, it efficiently conveys the core purpose without unnecessary elaboration.
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 complexity (9 parameters, nested objects, no output schema, and 0% schema description coverage), the description is incomplete. It doesn't explain what an 'item' is in Xero's context, what fields can be updated, or the expected behavior. For a mutation tool with rich input structure, this minimal description is inadequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning none of the 9 parameters have descriptions in the schema. The tool description adds no information about parameters, such as what 'itemId', 'code', 'name', or nested objects like 'purchaseDetails' represent. This fails to compensate for the lack of schema documentation, making parameter understanding difficult.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update an item in Xero' clearly states the action (update) and resource (item in Xero), which is adequate. However, it doesn't differentiate from sibling tools like 'update-contact' or 'update-invoice' beyond the resource type, and it lacks specificity about what aspects of an item can be updated. This makes it vague but functional.
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. It doesn't mention prerequisites (e.g., needing an existing item), exclusions, or comparisons to related tools like 'create-item' or 'list-items'. Without such context, users must infer usage from the tool name alone.
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 full burden but only states that creation returns a deep link. It lacks critical behavioral details: whether this is a write operation (implied but not explicit), permission requirements, idempotency, error handling, or rate limits. The mention of displaying the link is a minor behavioral note but 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 appropriately concise with three sentences that are front-loaded (purpose first, then output details). No wasted words, though it could be more structured by separating purpose from behavioral notes.
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 mutation tool with no annotations, 0% schema coverage, and no output schema, the description is incomplete. It covers the basic purpose and output format but misses parameter semantics, usage context, error handling, and other behavioral traits needed for safe and effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate but provides no parameter information. It doesn't explain what 'contactId', 'lineItems', or 'reference' mean, their formats, or how they relate to credit note creation. This leaves all 3 parameters undocumented beyond the schema structure.
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 states the verb 'create' and resource 'credit note in Xero', making the purpose specific and understandable. It distinguishes from siblings like 'update-credit-note' by focusing on creation rather than modification, though it doesn't explicitly contrast with other creation tools like '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?
No guidance is provided on when to use this tool versus alternatives. The description mentions the output (a deep link) but doesn't explain prerequisites, scenarios for credit notes over other documents, or comparisons to siblings like 'create-invoice' or 'update-credit-note'.
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 mentions that a 'deep link' is returned and should be displayed, which adds some context about output behavior. However, it lacks critical details: it doesn't clarify if this is a mutation (implied by 'create'), what permissions are required, whether the quote is draft or final, error handling, or rate limits. The description is insufficient for a mutation tool with zero annotation coverage.
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 appropriately concise with two sentences that directly address the tool's action and output. It front-loads the core purpose ('Create a quote in Xero') and avoids unnecessary fluff. However, the second sentence about displaying the link could be integrated more tightly, and it lacks structural elements like bullet points for clarity.
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 complexity (7 parameters, no schema descriptions, no annotations, no output schema), the description is incomplete. It covers the basic action and output format but misses parameter explanations, usage context, error handling, and behavioral details like idempotency or side effects. For a mutation tool in a financial system, this leaves significant gaps for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate by explaining parameters, but it provides no information about any of the 7 parameters. It doesn't clarify what 'contactId', 'lineItems', or other fields represent, their formats, or how they relate to quote creation. The description fails to add meaning beyond the bare schema, leaving parameters undocumented.
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 states the action ('Create a quote in Xero') and resource ('quote'), making the purpose immediately understandable. It distinguishes from siblings like 'update-quote' by specifying creation rather than modification, though it doesn't explicitly contrast with other creation tools like 'create-invoice' or 'create-credit-note' beyond the resource type.
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. It doesn't mention prerequisites (e.g., needing a valid contactId), compare it to similar tools (e.g., 'create-invoice' for binding documents), or specify scenarios where a quote is appropriate over other financial documents. Usage is implied by the tool name alone.
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 must fully disclose behavioral traits. It mentions that a deep link is returned and should be displayed, which adds some context about output behavior. However, it lacks critical details: whether the update is idempotent, what permissions are required, if it's rate-limited, how partial updates are handled, or error responses. This leaves significant gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the core action ('Update a contact in Xero'). The additional sentences about the deep link are relevant but could be more tightly integrated. Overall, it avoids fluff and stays focused, though it could be slightly more structured.
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 complexity (7 parameters, nested objects, no output schema, no annotations), the description is incomplete. It covers the basic action and output format but misses parameter explanations, error handling, side effects, and differentiation from siblings. For a mutation tool with rich input schema, this leaves too much unspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate by explaining parameters. It provides no information about any of the 7 parameters (e.g., what 'contactId' refers to, how 'name' interacts with 'firstName'/'lastName', address structure). This leaves the agent reliant solely on the schema without semantic guidance, which is inadequate given the coverage gap.
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 states the action ('Update a contact in Xero') and specifies the resource ('contact'), making the purpose immediately understandable. However, it does not differentiate this tool from its sibling 'update-*' tools (e.g., update-bank-transaction, update-invoice) beyond the contact focus, which slightly limits clarity in a crowded toolset.
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 like 'create-contact' or 'list-contacts'. It mentions the output (a deep link) but does not specify prerequisites, error conditions, or contextual triggers for choosing this update operation over others.
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 states 'Create' which implies a write/mutation operation, but fails to describe permissions needed, whether the operation is idempotent, error handling, or what happens on success (e.g., returns the created item). For a mutation tool with zero annotation coverage, this is a significant 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, clear sentence with no wasted words. It's front-loaded with the core purpose, making it efficient and easy to parse, though this brevity contributes to gaps in other dimensions.
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 complexity (8 parameters with nested objects, no annotations, no output schema), the description is incomplete. It doesn't cover parameter meanings, behavioral traits, or output expectations, making it inadequate for a mutation tool in a system with many similar tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage and 8 parameters (including nested objects), the description provides no information about parameters. It doesn't explain what 'code', 'name', 'purchaseDetails', or other fields mean, their formats, or constraints, leaving the schema as the sole source of parameter documentation.
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 states the action ('Create') and resource ('item in Xero'), making the purpose immediately understandable. However, it doesn't distinguish this tool from sibling tools like 'create-contact' or 'create-invoice' beyond the resource type, missing explicit differentiation.
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. With many sibling tools for creating different resources in Xero (e.g., create-contact, create-invoice), the description lacks context on prerequisites, appropriate scenarios, or exclusions, leaving the agent to infer usage.
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 states 'Create' implies a write operation but fails to mention permissions, rate limits, idempotency, or what happens if options already exist. This leaves significant gaps for a mutation tool with no annotation coverage.
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 wasted words, making it highly concise and front-loaded. It efficiently communicates the core action without unnecessary elaboration.
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 mutation tool with 2 parameters, 0% schema coverage, no annotations, and no output schema, the description is inadequate. It lacks details on behavior, parameter meanings, error handling, and output, leaving the agent with insufficient context to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate by explaining parameters. It mentions 'tracking options for a tracking category' but does not clarify what 'trackingCategoryId' or 'optionNames' represent, their formats, or constraints like the 10-item max for 'optionNames'. This adds minimal value beyond the schema.
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 states the action ('Create tracking options') and the target resource ('for a tracking category in Xero'), making the purpose evident. However, it does not differentiate this tool from its sibling 'create-tracking-category' or 'update-tracking-options', which limits its score to 4 instead of 5.
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 like 'create-tracking-category' or 'update-tracking-options'. It lacks context about prerequisites, such as whether a tracking category must exist first, or any exclusions for usage.
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. While 'Updates' implies a mutation operation, it doesn't specify required permissions, whether changes are reversible, potential side effects, or what the response contains. For a mutation tool with zero annotation coverage, this leaves significant behavioral questions unanswered.
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, efficient sentence that gets straight to the point without unnecessary words. It's appropriately sized for a basic tool description and front-loads the essential information.
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 mutation tool with 3 parameters (0% schema coverage), no annotations, and no output schema, the description is insufficient. It doesn't explain what tracking categories are, what fields can be updated, what the 'status' enum means in practice, or what happens after the update. The context demands more comprehensive guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage for all 3 parameters, the description provides no information about what 'trackingCategoryId', 'name', or 'status' represent or how they should be used. The description doesn't compensate for this gap by explaining parameter purposes, formats, or constraints beyond what's visible in the enum for 'status'.
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 states the action ('Updates') and resource ('an existing tracking category in Xero'), making the purpose immediately understandable. However, it doesn't distinguish this tool from its sibling 'update-tracking-options', which could cause confusion about which tool to use for different tracking-related updates.
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. It doesn't mention prerequisites (e.g., needing an existing tracking category ID), compare it to 'create-tracking-category' or 'update-tracking-options', or specify appropriate contexts for updating tracking categories versus other entities.
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 states 'Updates' implying a mutation, but doesn't specify required permissions, whether changes are reversible, rate limits, or what the response looks like. This is inadequate for a mutation tool with zero annotation coverage.
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, efficient sentence with no wasted words. It's front-loaded with the core action and resource, making it easy to parse quickly, though it could benefit from additional context.
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 mutation tool with 2 parameters, 0% schema coverage, no annotations, and no output schema, the description is incomplete. It lacks details on behavior, parameters, return values, and usage context, making it insufficient for effective tool selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate by explaining parameters. It mentions 'tracking options' but doesn't detail what 'trackingCategoryId' or 'options' entail, their formats, or constraints like the 10-item max in the schema. This adds minimal value beyond the schema.
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 states the action ('Updates') and resource ('tracking options for a tracking category in Xero'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'update-tracking-category' or 'create-tracking-options', which handle related resources, so it falls short of a perfect score.
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. It doesn't mention prerequisites (e.g., needing an existing tracking category), exclusions, or comparisons to sibling tools like 'create-tracking-options' or 'update-tracking-category', leaving usage context unclear.
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. While 'Add' implies a write/mutation operation, it doesn't describe important behavioral aspects like required permissions, whether the operation is idempotent, error conditions, or what happens on success. For a mutation tool with zero annotation coverage, this is inadequate.
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, efficient sentence that clearly states the tool's purpose with zero wasted words. It's appropriately sized and front-loaded with the essential information.
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 mutation tool with no annotations and no output schema, the description is incomplete. It doesn't explain what happens after adding the line (e.g., returns the updated timesheet, returns success/failure), doesn't mention error handling, and provides insufficient behavioral context. Given the complexity of modifying payroll data, more guidance is needed.
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 both parameters (timesheetID and timesheetLine object with its sub-properties). The description adds no additional parameter semantics beyond what's in the schema, such as format examples or constraints. Baseline 3 is appropriate when schema does the heavy lifting.
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 states the action ('Add a new timesheet line') and target resource ('to an existing payroll timesheet in Xero'), providing specific verb+resource information. However, it doesn't explicitly differentiate from sibling tools like 'update-timesheet-line' or 'create-timesheet', which could cause confusion about when to use each.
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 minimal usage guidance, only indicating it's for adding to 'an existing payroll timesheet'. It doesn't specify when to use this tool versus alternatives like 'create-timesheet' (for new timesheets) or 'update-timesheet-line' (for modifying existing lines), nor does it 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?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool approves a timesheet, implying a mutation operation, but does not disclose critical traits like required permissions, whether the action is reversible, side effects (e.g., triggering payroll processing), or rate limits. This leaves significant gaps in understanding the tool's behavior.
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 wasted words, front-loading the key action and resource. It efficiently conveys the core purpose without unnecessary elaboration, making it easy for an agent to parse quickly.
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 complexity of a mutation tool (approving payroll timesheets) with no annotations and no output schema, the description is incomplete. It lacks details on behavioral traits, usage context, and expected outcomes, which are critical for an agent to invoke the tool correctly and safely in a real-world scenario.
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% description coverage, with the parameter 'timesheetID' fully documented. The description adds no additional semantic meaning beyond the schema, such as format examples or constraints (e.g., ID must be from Xero). With high schema coverage, the baseline score of 3 is appropriate, as the description does not compensate but also does not detract.
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 states the action ('Approve') and resource ('a payroll timesheet in Xero'), making the purpose specific and understandable. However, it does not explicitly differentiate from sibling tools like 'revert-timesheet' or 'update-timesheet-line', which would require mentioning what 'approve' entails (e.g., finalizing for payroll vs. editing).
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, such as 'revert-timesheet' or 'update-timesheet-line', nor does it mention prerequisites (e.g., the timesheet must be in a draft state). It lacks explicit context for usage, leaving the agent to infer based on the tool name alone.
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 of behavioral disclosure. It mentions that a deep link is returned and should be displayed to the user, which adds useful context about the output behavior. However, it doesn't disclose important behavioral traits like whether this is a write operation (implied but not stated), what permissions are required, whether there are rate limits, or what happens on failure.
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 appropriately concise with three sentences that each add value: the core function, what's returned, and how to handle the return value. There's no wasted language, and the information is front-loaded with the primary purpose stated first.
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 write operation with 6 parameters (4 required), no annotations, no output schema, and only 17% schema description coverage, the description is insufficient. It covers the basic purpose and return format but leaves critical gaps: no parameter guidance, no behavioral context about mutations, no error handling, and no differentiation from sibling tools. The agent would struggle to use this tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 17% (only the 'date' parameter has a description), so the description must compensate but fails to do so. The description mentions no parameters at all, leaving all 6 parameters (4 required) undocumented in terms of their purpose, format, or relationships. This creates significant gaps for an agent trying to invoke the tool correctly.
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 states the verb 'Create' and resource 'bank transaction in Xero', making the purpose unambiguous. It distinguishes from sibling tools like 'update-bank-transaction' by specifying creation rather than modification. However, it doesn't explicitly differentiate from other creation tools like 'create-invoice' or 'create-payment' beyond the resource type.
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. There's no mention of prerequisites, when this tool is appropriate versus other transaction methods, or any exclusions. The sibling list includes 'update-bank-transaction' and 'list-bank-transactions', but the description doesn't help an agent choose between them.
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 but only states it 'allows you to specify details' without disclosing behavioral traits. It doesn't mention whether this is a write operation (implied by 'create'), what permissions are needed, whether it's idempotent, what happens on failure, or any rate limits. For a creation tool with zero annotation coverage, this is inadequate.
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 appropriately concise with two sentences that directly address purpose and parameters. It's front-loaded with the main action and wastes no words, though it could be slightly more structured with bullet points for parameters.
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 creation tool with no annotations and no output schema, the description is incomplete. It doesn't explain what happens after creation (e.g., returns a timesheet ID), error conditions, or system behavior. Given the complexity of payroll timesheets and lack of structured metadata, more context is needed.
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 description mentions the parameters (employee ID, payroll calendar ID, dates, timesheet lines) but adds minimal semantic value beyond what's already in the schema, which has 100% coverage with clear descriptions. It doesn't explain relationships between parameters or provide usage examples, so it meets the baseline for high schema coverage.
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 states the action ('Create a new payroll timesheet') and resource ('in Xero'), providing specific context. It distinguishes from obvious siblings like 'get-timesheet' or 'delete-timesheet' by specifying creation, though it doesn't explicitly differentiate from all potential alternatives like 'update-timesheet' or 'revert-timesheet'.
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 like 'update-timesheet-line' or 'add-timesheet-line', nor does it mention prerequisites or constraints. It simply states what the tool does without contextual usage information.
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 states the tool creates a tracking category, implying a write operation, but does not cover aspects like required permissions, whether the operation is idempotent, rate limits, or what happens on success/failure. This leaves significant gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no wasted words, making it easy to parse. It is appropriately sized for the tool's apparent simplicity, though it could benefit from additional context.
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 mutation tool with no annotations, no output schema, and a parameter with 0% schema coverage, the description is incomplete. It does not explain the return value, error conditions, or behavioral nuances, leaving the agent with insufficient information to use the tool effectively.
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 description does not mention the 'name' parameter at all, and with 0% schema description coverage, the parameter is undocumented in both the schema and description. However, since there is only one parameter, the baseline is 4, but the lack of any parameter information in the description reduces it to 3, as it fails to compensate for the schema gap.
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 states the verb ('create') and resource ('tracking category in Xero'), making the purpose unambiguous. However, it does not differentiate from sibling tools like 'create-tracking-options' or 'update-tracking-category', which are related but distinct operations.
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 like 'update-tracking-category' or 'list-tracking-categories', nor does it mention prerequisites such as authentication or permissions. The description lacks context for distinguishing it from similar 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?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool deletes a timesheet, implying a destructive mutation, but fails to mention critical details like whether deletion is permanent, requires specific permissions, has side effects (e.g., on payroll data), or what the response looks like. This leaves significant gaps in understanding the tool's behavior.
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 that efficiently conveys the core action without unnecessary words. It is front-loaded with the key information, making it highly concise and well-structured for quick comprehension.
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 as a destructive mutation with no annotations and no output schema, the description is incomplete. It lacks details on behavioral traits, usage context, and output expectations, making it insufficient for safe and effective tool invocation by an AI agent.
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 the parameter 'timesheetID' fully documented in the schema. The description adds no additional meaning beyond the schema, such as format examples or constraints, so it meets the baseline for adequate but not enhanced parameter semantics.
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 states the action ('Delete') and resource ('an existing payroll timesheet in Xero'), making the purpose specific and understandable. However, it does not explicitly distinguish this tool from sibling tools like 'revert-timesheet' or 'update-timesheet-line', which might have overlapping or related functions, leaving some ambiguity in sibling differentiation.
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, such as 'revert-timesheet' or 'update-timesheet-line', nor does it mention prerequisites like permissions or conditions for deletion. It lacks explicit usage context or exclusions, offering minimal help for decision-making.
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. It states the tool lists data, implying a read-only operation, but does not disclose behavioral traits such as authentication requirements, rate limits, pagination, or error handling. For a tool with no annotations, this lack of detail is a significant gap.
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 concise and front-loaded, with two sentences that directly state the tool's purpose. There is no wasted text, but it could be slightly more structured to include usage hints or parameter context, preventing a perfect score.
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 no annotations, no output schema, and a tool with four parameters (one required), the description is incomplete. It lacks details on behavioral traits, return values, and usage context, making it inadequate for an agent to fully understand the tool's operation and limitations.
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 75%, with three of four parameters having descriptions in the schema. The description adds minimal value beyond the schema, mentioning 'for a certain contact' and 'up to a report date,' which aligns with 'contactId' and 'reportDate' but does not explain 'invoicesFromDate' or 'invoicesToDate.' Baseline 3 is appropriate given the high schema coverage.
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 states the tool's purpose: 'Lists the aged payables in Xero' and specifies 'for a certain contact up to a report date.' It uses specific verbs ('Lists') and resources ('aged payables in Xero'), but does not explicitly differentiate from its sibling 'list-aged-receivables-by-contact' or other list tools, preventing a perfect score.
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 minimal guidance: it mentions 'for a certain contact up to a report date,' which implies context but does not specify when to use this tool versus alternatives like 'list-invoices' or 'list-aged-receivables-by-contact.' No explicit when/when-not instructions or prerequisites are given, leaving usage unclear.
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 states the tool lists data, implying a read-only operation, but doesn't mention authentication requirements, rate limits, pagination, error handling, or the format of returned data. For a tool with no annotations and no output schema, this leaves significant behavioral gaps.
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 concise with two sentences that are front-loaded: the first states the core purpose, and the second adds scope. There's no wasted text, though it could be slightly more structured (e.g., separating purpose from parameters). It efficiently conveys key information 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?
Given no annotations, no output schema, and 4 parameters (with 75% schema coverage), the description is incomplete. It doesn't address behavioral aspects like data format, pagination, or error handling, nor does it provide usage guidance relative to siblings. For a tool with moderate complexity and limited structured data, this leaves the agent under-informed.
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 75%, with three of four parameters having descriptions in the schema. The description adds minimal value beyond the schema: it mentions 'for a certain contact' (implied by contactId) and 'up to a report date' (implied by reportDate). It doesn't explain the optional date filters (invoicesFromDate, invoicesToDate) or provide additional context, so it meets the baseline for high schema coverage.
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 states the tool's purpose: 'Lists the aged receivables in Xero' and specifies 'for a certain contact up to a report date.' This provides a specific verb ('Lists'), resource ('aged receivables'), and scope ('for a certain contact'). However, it doesn't explicitly differentiate from its sibling 'list-aged-payables-by-contact' or other list tools, preventing a perfect score.
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 minimal guidance: it mentions 'for a certain contact up to a report date,' which implies context but doesn't specify when to use this tool versus alternatives like 'list-invoices' or 'list-aged-payables-by-contact.' No explicit when-not-to-use or prerequisite information is included, leaving usage unclear.
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 but only states what is listed, not behavioral traits like pagination behavior (implied by schema), rate limits, authentication needs, or what data is returned. It mentions inclusion of Suppliers and Customers but lacks details on format, sorting, or default behavior.
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 two concise sentences with zero waste, front-loading the core purpose and efficiently specifying scope. Every word earns its place 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?
For a list tool with no annotations and no output schema, the description is incomplete. It lacks information on return format, pagination details (beyond schema hints), error handling, or how results are structured, leaving significant gaps for an AI agent.
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 fully documents the two parameters (page and searchTerm). The description adds no additional parameter semantics beyond what the schema provides, meeting the baseline for high coverage.
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 states the verb ('List') and resource ('all contacts in Xero'), specifying that it includes Suppliers and Customers. It distinguishes the scope but doesn't explicitly differentiate from sibling tools like 'list-contact-groups' or 'list-aged-payables-by-contact', which prevents a perfect score.
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 like 'list-contact-groups' or 'create-contact'. The description mentions inclusion of Suppliers and Customers but doesn't specify exclusions or prerequisites, leaving usage context implied at best.
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 reveals pagination behavior (10 items per page, need to ask for next page) and that it presents a 'complete overview' with details. However, it doesn't disclose important behavioral traits like whether this is a read-only operation, rate limits, authentication requirements, error conditions, or what happens when no journals exist. The description adds some context but leaves significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is verbose and contains implementation instructions ('Ask the user...') that don't belong in a tool description. It repeats information about parameters and pagination multiple times. While it attempts to be helpful, it lacks front-loading of essential information and includes procedural guidance that should be handled by the agent's prompting strategy rather than tool documentation.
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 3 parameters, no annotations, and no output schema, the description is incomplete. It doesn't explain what a 'manual journal' is in Xero context, what details are included in the response, error scenarios, or authentication requirements. The procedural instructions about asking users don't compensate for missing contextual information about the tool's behavior and output.
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 three parameters. The description adds marginal value by mentioning the date format ('YYYY-MM-DD' implied) and explaining that parameters are optional for filtering specific journals. However, it doesn't provide additional semantic context beyond what the schema descriptions already state about each parameter's purpose.
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 states the tool's purpose: 'List all manual journals from Xero' and 'retrieve a specific journal' with filtering capabilities. It distinguishes itself from sibling tools like 'create-manual-journal' and 'update-manual-journal' by focusing on retrieval rather than creation or modification. However, it doesn't explicitly differentiate from other list tools (e.g., 'list-invoices', 'list-contacts') beyond the resource type.
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 provides implied usage guidance by mentioning optional parameters for filtering and pagination, and suggests asking the user about scope before running. However, it lacks explicit when-to-use rules, prerequisites, or comparisons with alternatives. No guidance is given on when to use this versus other list tools or when manual journal listing is appropriate.
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 burden. It states it 'shows current leave balances' but doesn't disclose behavioral traits like whether it requires specific permissions, if data is real-time or cached, rate limits, error conditions, or pagination. For a read operation with no annotation coverage, this leaves significant gaps in understanding how the tool behaves.
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 two sentences, front-loaded with the core purpose and followed by clarifying details about leave types. It avoids redundancy and wastes no words, though it could be slightly more structured (e.g., bullet points for leave types).
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 read tool with one parameter and no output schema, the description covers the basic purpose and scope. However, without annotations or output schema, it lacks details on return format (e.g., structure of balances), error handling, and behavioral context. It's minimally viable but has clear gaps in 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 the single parameter 'employeeId' fully documented in the schema. The description doesn't add any parameter-specific details beyond what the schema provides (e.g., format examples, validation rules). Baseline 3 is appropriate when the schema handles parameter documentation effectively.
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 states the verb ('List') and resource ('leave balances for a specific employee in Xero'), with specific examples of leave types (annual, sick, other). It distinguishes from siblings like 'list-payroll-employee-leave' (which likely lists leave applications) and 'list-payroll-employee-leave-types' (which likely lists available leave types rather than balances). However, it doesn't explicitly contrast with these specific siblings.
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. It doesn't mention prerequisites (e.g., employee must exist), compare with similar tools (e.g., 'list-payroll-employee-leave' for leave applications), or specify use cases beyond the basic purpose. Usage is implied from the title but not explicitly stated.
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. While it indicates this is a read operation ('Lists'), it doesn't describe important behavioral aspects like authentication requirements, rate limits, pagination, error conditions, or what happens when parameters are omitted. The description mentions 'over a specified period' but doesn't clarify default behavior when dates aren't provided.
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 appropriately concise with two clear sentences. The first sentence states the core purpose, and the second provides valuable context about what the report contains. There's no wasted language, though it could be slightly more structured by explicitly mentioning the tool's read-only nature.
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 read-only reporting tool with 6 optional parameters and no output schema, the description is minimally adequate. It covers the basic purpose but lacks important context about output format, error handling, and parameter interactions. Without annotations or output schema, the agent has incomplete information about what to expect from this tool's behavior and results.
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?
With 100% schema description coverage, the baseline is 3. The description adds minimal value beyond the schema - it mentions 'over a specified period of time' which relates to fromDate/toDate parameters, but doesn't provide additional context about parameter interactions (e.g., how periods and timeframe work together) or business logic behind flags like standardLayout and paymentsOnly.
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 states the tool's purpose: 'Lists profit and loss report in Xero' with specific details about what it provides ('summary of revenue, expenses, and profit or loss over a specified period'). It distinguishes itself from other list tools by focusing on financial reporting rather than transactional data, though it doesn't explicitly differentiate from similar report tools like list-report-balance-sheet.
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. It doesn't mention when this report is appropriate versus other financial reports (like list-trial-balance or list-report-balance-sheet), nor does it specify any prerequisites or constraints for using this tool effectively.
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 but only states the basic action without disclosing behavioral traits. It doesn't mention whether this is a read-only operation, authentication needs, rate limits, or what the output looks like (e.g., format, pagination), which is inadequate for a tool with multiple parameters.
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, efficient sentence with zero wasted words. It's appropriately sized and front-loaded, clearly stating the tool's purpose without unnecessary elaboration.
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 complexity of a report tool with 7 parameters, no annotations, and no output schema, the description is incomplete. It lacks behavioral context, usage guidelines, and details on output format, leaving significant gaps for the agent to understand how to effectively use this 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?
The schema description coverage is 100%, so the schema fully documents all 7 parameters. The description adds no additional meaning beyond implying a report is generated, meeting the baseline of 3 where the schema does the heavy lifting.
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 states the action ('List') and resource ('Balance Sheet report from Xero'), making the purpose unambiguous. However, it doesn't differentiate from sibling tools like 'list-profit-and-loss' or 'list-trial-balance' beyond naming the specific report type, missing explicit sibling distinction.
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. The description lacks context about prerequisites, timing, or comparisons to other report tools (e.g., 'list-profit-and-loss'), leaving the agent without usage direction.
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 burden. It implies a state change ('revert to draft'), but doesn't disclose behavioral traits like whether this requires specific permissions, if it's reversible, what happens to associated data, or error conditions. For a mutation tool with zero annotation coverage, this is a significant 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, efficient sentence with zero waste. It's front-loaded with the core action and resource, making it easy to parse. 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?
For a mutation tool with no annotations and no output schema, the description is incomplete. It lacks information on behavioral implications (e.g., side effects, permissions), expected outcomes, or error handling. Given the complexity of reverting a timesheet, more context is needed for safe and 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 description coverage is 100%, with the single parameter 'timesheetID' fully documented in the schema. The description adds no additional parameter semantics beyond implying the ID is for a timesheet in Xero, which is already clear from context. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('revert') and resource ('payroll timesheet') with specific context ('to draft in Xero by its ID'). It distinguishes from obvious siblings like 'delete-timesheet' (destructive removal) and 'update-timesheet-line' (modification), but doesn't explicitly differentiate from all related tools like 'approve-timesheet' (opposite state change).
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 doesn't mention prerequisites (e.g., timesheet must be approved), exclusions, or compare with siblings like 'update-timesheet-line' for corrections. The description only states what it does, not when it's appropriate.
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 mentions that a deep link is returned and should be displayed, which is useful context about the output. However, it doesn't address critical behavioral aspects like whether this is a mutating operation (implied but not stated), permission requirements, error handling, or side effects (e.g., impact on accounting records).
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 appropriately concise with three sentences. The first sentence states the purpose, and the next two explain the return value and how to handle it. There's no unnecessary fluff, though it could be slightly more front-loaded with key behavioral information.
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 mutation tool with 6 parameters, low schema description coverage (17%), no annotations, and no output schema, the description is insufficient. It doesn't explain the update semantics (partial vs. full updates), doesn't warn about destructive changes (like line item removal), and provides minimal guidance on usage. The deep link information is helpful but doesn't compensate for the broader gaps.
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 low at 17%, with only the 'lineItems' parameter having a description. The tool description adds no parameter-specific information beyond what's in the schema. However, the schema itself is well-structured with clear properties, enums, and required fields, providing a baseline understanding despite the lack of descriptive text.
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 states the action ('Update a bank transaction in Xero') and resource ('bank transaction'), making the purpose immediately understandable. However, it doesn't differentiate this tool from sibling tools like 'update-contact' or 'update-invoice' beyond the resource type, nor does it specify what fields can be updated beyond the schema.
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. It doesn't mention prerequisites (e.g., needing an existing transaction ID), compare it to 'create-bank-transaction' or 'list-bank-transactions', or specify scenarios where updating is appropriate versus creating new transactions.
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 implies a mutation ('Update') but lacks details on permissions required, whether changes are reversible, error handling, or rate limits. This is a significant gap for a tool that modifies payroll data.
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, efficient sentence with zero wasted words. It front-loads the core purpose ('Update an existing timesheet line') and provides necessary context ('in a payroll timesheet in Xero') 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?
For a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't cover behavioral aspects like side effects, error conditions, or return values, which are critical for safe and effective use in a payroll context.
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 fully documents all parameters. The description adds no additional meaning beyond what's in the schema, such as explaining relationships between parameters or usage examples. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update'), target resource ('an existing timesheet line'), and context ('in a payroll timesheet in Xero'), making the purpose unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'update-timesheet' or 'add-timesheet-line', which would be needed for a perfect score.
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 like 'add-timesheet-line' or 'update-timesheet', nor does it mention prerequisites such as needing an existing timesheet line ID. It only states what the tool does, not when to apply it.
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 full burden. It discloses that a deep link is returned and should be displayed to the user, which adds useful behavioral context beyond the basic creation action. However, it doesn't cover critical aspects like authentication requirements, error handling, rate limits, or whether the operation is idempotent, leaving gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized with three sentences that are front-loaded: the first states the core action, and the following two explain the return value and its usage. There's minimal waste, though the third sentence could be integrated more tightly. Overall, it's efficient and structured.
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 the complexity (a mutation tool with no annotations and no output schema), the description is partially complete. It covers the action and return behavior but lacks details on parameters, error cases, and broader context like authentication. For a tool creating resources in an external system, more guidance on prerequisites and outcomes would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for undocumented parameters. It adds no information about the three parameters (name, email, phone), their semantics, formats, or constraints beyond what the schema provides (e.g., name is required, email has format). This leaves parameters largely unexplained, failing to address the coverage gap.
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 states the action ('Create a contact') and resource ('in Xero'), making the purpose immediately understandable. It distinguishes from sibling tools like 'list-contacts' and 'update-contact' by specifying creation rather than listing or updating. However, it doesn't explicitly differentiate from other creation tools (e.g., 'create-invoice'), though the resource type makes this distinction clear.
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. It doesn't mention prerequisites (e.g., required permissions), when not to use it (e.g., for updating existing contacts), or direct alternatives like 'update-contact' for modifications. The context is implied through the action and resource but lacks explicit usage instructions.
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 mentions the tool lists leave types but doesn't cover critical aspects like authentication requirements, rate limits, pagination, error handling, or what the output format looks like (e.g., JSON structure). This leaves significant gaps for an agent to use it effectively.
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 two sentences that efficiently convey the tool's function and scope without redundancy. It's front-loaded with the core purpose and adds clarifying detail in the second sentence. There's no wasted text, though it could be slightly more structured for readability.
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 lack of annotations and output schema, the description is incomplete. It doesn't explain what the return values include (e.g., fields like leave type IDs, names, accrual rules) or behavioral traits like response format, making it hard for an agent to interpret results. For a list tool with no structured output documentation, this is inadequate.
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 input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately doesn't discuss parameters, focusing instead on the tool's purpose. A baseline of 4 is applied since no parameters exist, and the description doesn't add unnecessary param details.
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 states the verb ('Lists') and resource ('all available leave types in Xero Payroll'), specifying the scope ('statutory and organization-specific leave types'). However, it doesn't explicitly differentiate from the sibling 'list-payroll-employee-leave-types', which appears to be a related but distinct tool for employee-specific leave types.
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 like 'list-payroll-employee-leave-types' or other payroll-related tools. The description only states what it does without context about prerequisites, timing, or comparisons to siblings.
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 burden. It states the tool retrieves data (implied read-only) and lists returned fields, but lacks critical behavioral details: pagination, rate limits, authentication requirements, error handling, or whether it returns all timesheets or requires date filtering. This is inadequate for a read operation with zero annotation coverage.
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?
Two sentences efficiently convey the purpose and returned data. The first sentence states the action, and the second elaborates on details. It is front-loaded with the core function, though minor improvements could include structuring the field list more clearly.
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 no annotations, no output schema, and a read operation with potential complexity (e.g., large datasets), the description is insufficient. It lacks information on response format, pagination, sorting, or error cases, leaving gaps for an AI agent to use the tool effectively.
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 input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately does not discuss parameters, earning a baseline score of 4 for not adding unnecessary information.
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 states the verb ('List') and resource ('all payroll timesheets in Xero'), and specifies the scope ('comprehensive timesheet details'). It distinguishes from sibling 'get-timesheet' (singular) by implying a bulk retrieval, but does not explicitly differentiate from other list tools like 'list-payroll-employees'.
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 prerequisites (e.g., authentication), filtering options, or compare it to siblings like 'get-timesheet' for single timesheet retrieval or 'list-payroll-employees' for related data.
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. It mentions that listing all groups is the default behavior and that specifying an ID retrieves details for a specific group, but it lacks critical behavioral details such as pagination, rate limits, authentication requirements, error handling, or what 'details' include beyond contacts. This is inadequate for a tool with potential complexity.
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 concise with two sentences: the first states the primary function, and the second explains the optional parameter. It's front-loaded with the main purpose and avoids unnecessary words, though it could be slightly more structured by separating use cases more clearly.
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 no annotations, no output schema, and a single parameter with high schema coverage, the description is incomplete. It fails to address behavioral aspects like response format, pagination, or error cases, and doesn't leverage context from sibling tools. For a list operation in a complex system like Xero, more guidance is needed to ensure proper usage.
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 the parameter 'contactGroupId' documented as 'Optional ID of the contact group to retrieve'. The description adds minimal value by reiterating the optionality and hinting at additional details like contacts, but it doesn't provide extra semantics beyond the schema, such as ID format or retrieval specifics. Baseline 3 is appropriate given high schema coverage.
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 states the tool's purpose: 'List all contact groups in Xero' specifies the verb ('List') and resource ('contact groups'), and it distinguishes this from other list operations by focusing on contact groups. However, it doesn't explicitly differentiate from sibling tools like 'list-contacts' beyond the resource type, missing a direct comparison.
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 by mentioning the optional parameter for retrieving a specific group, but it doesn't provide explicit guidance on when to use this tool versus alternatives like 'list-contacts' or other list tools. There's no mention of prerequisites, exclusions, or comparative contexts with siblings.
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. It mentions the tool lists items but doesn't disclose behavioral traits like pagination behavior (implied by the 'page' parameter), rate limits, authentication needs, or what the output looks like. For a list operation with zero annotation coverage, this leaves significant gaps in understanding how the tool behaves.
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 appropriately sized with two sentences that are front-loaded and efficient. The first sentence states the purpose, and the second adds usage context without unnecessary details, making it easy to parse.
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 complexity of a list operation with one parameter (page) and no annotations or output schema, the description is incomplete. It lacks details on pagination behavior, return format, error handling, or prerequisites, which are essential for effective tool use. The usage hint helps but doesn't compensate for these gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the undocumented parameter 'page'. However, the description adds no information about parameters—it doesn't mention pagination, explain what 'page' means, or provide any semantic context. This fails to address the coverage gap, leaving the parameter's purpose unclear.
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 states the verb ('Lists') and resource ('all items in Xero'), making the purpose specific and understandable. It distinguishes from siblings by focusing on items rather than other resources like contacts or invoices, though it doesn't explicitly contrast with similar list tools like list-accounts or list-contacts.
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 context for when to use this tool: 'to get the item codes and descriptions to be used when creating invoices in Xero.' This gives practical guidance, though it doesn't explicitly state when not to use it or name specific alternatives among the many sibling 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?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool lists categories and options, implying a read-only operation, but doesn't cover aspects like rate limits, authentication needs, error handling, or pagination. For a tool with no annotation coverage, this leaves significant gaps in understanding its behavior.
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, efficient sentence that directly states the tool's purpose without unnecessary words. It is front-loaded with the core action and resource, making it easy to parse. Every part of the sentence contributes meaning, earning 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?
Given the tool's low complexity (1 parameter, no output schema, no annotations), the description is minimally complete. It covers the basic purpose but lacks behavioral details and usage context. With no output schema, it doesn't explain return values, which is a gap, though the simplicity of the tool makes this less critical.
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% description coverage, with the single parameter 'includeArchived' well-documented in the schema. The description adds no additional parameter information beyond what the schema provides, which is acceptable given the high coverage. Baseline score of 3 reflects adequate but no extra value.
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 states the action ('List all tracking categories') and resource ('in Xero'), with additional detail about including 'associated tracking options'. It distinguishes itself from sibling tools like 'create-tracking-category' or 'update-tracking-category' by focusing on retrieval rather than creation or modification. However, it doesn't explicitly differentiate from other list tools (e.g., 'list-contacts'), though the resource specificity helps.
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 explicit guidance is provided on when to use this tool versus alternatives. While it's implied for retrieving tracking categories, there's no mention of prerequisites, related tools (like 'create-tracking-category' for setup), or scenarios where other tools might be more appropriate. The description lacks context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and adds valuable behavioral context: it discloses pagination behavior (10 items per page, requires calling again with next page number), user interaction requirements (ask about account filtering), and implies a read-only operation through 'List'. It doesn't mention rate limits, authentication needs, or error handling, but provides more than minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is verbose and poorly structured: it mixes tool functionality with user interaction instructions ('Ask the user...') and implementation details ('call this tool again...'). It's not front-loaded—the core purpose is buried among procedural steps. Multiple sentences could be condensed into clearer, more direct statements about the tool's behavior.
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 no annotations, 0% schema coverage, and no output schema, the description provides moderate completeness: it covers purpose, usage context, and pagination behavior. However, it lacks details on return values (what data fields are included), error conditions, or comprehensive parameter documentation. For a list tool with 2 parameters, this is adequate but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It mentions 'page' and 'bank account' parameters, explaining that 'page' is for pagination and 'bankAccountId' filters by account, which adds meaning beyond the bare schema. However, it doesn't explain parameter formats (e.g., what values 'page' accepts, what a valid 'bankAccountId' looks like), leaving significant gaps for 2 parameters with no schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool 'List all bank transactions in Xero' which provides a clear verb ('List') and resource ('bank transactions'), but it's vague about scope and doesn't distinguish from potential siblings like 'list-payments' or 'list-manual-journals' that might also involve financial transactions. It doesn't specify if this includes only cleared transactions, pending ones, or all types.
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 context on when to use it: 'Ask the user if they want to see bank transactions for a specific bank account, or to see all bank transactions before running.' This gives explicit guidance on user interaction and filtering options. However, it doesn't mention when NOT to use it or alternatives among sibling tools (e.g., vs. 'create-bank-transaction' or 'update-bank-transaction').
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. It mentions the tool lists 'all leave transactions including approved, pending, and processed time off,' which adds some behavioral context about scope. However, it lacks details on permissions, rate limits, pagination, or response format, leaving significant gaps for a read operation.
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 appropriately sized with two sentences that are front-loaded: the first states the purpose, and the second provides usage context. There's no wasted text, though it could be slightly more structured for clarity.
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 no annotations and no output schema, the description is incomplete. It covers the basic purpose and parameter usage but lacks behavioral details (e.g., response format, error handling) and doesn't leverage sibling context for differentiation. It's minimally viable but has clear gaps.
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 the 'employeeId' parameter. The description adds minimal value by restating 'Provide an employee ID to see their leave history,' which doesn't provide additional semantics beyond the schema. Baseline 3 is appropriate as the schema does the heavy lifting.
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 states the verb ('List') and resource ('leave records for a specific employee in Xero'), making the purpose explicit. It distinguishes from siblings like 'list-payroll-employee-leave-balances' by focusing on leave transactions rather than balances, though it doesn't explicitly name alternatives.
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 by specifying 'Provide an employee ID to see their leave history,' which suggests when to use it (for viewing leave records per employee). However, it lacks explicit guidance on when not to use it or alternatives (e.g., vs. 'list-payroll-employee-leave-balances'), leaving some ambiguity.
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 describes the output as a 'snapshot' but lacks critical details such as whether this is a read-only operation, if it requires authentication, any rate limits, pagination behavior, or error handling. For a tool with no annotation coverage, this leaves significant gaps in understanding its behavior.
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 concise with two sentences that are front-loaded with the core purpose. It avoids unnecessary words, but could be slightly improved by integrating usage context or behavioral details without sacrificing brevity.
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 no annotations and no output schema, the description is moderately complete for a simple listing tool with two optional parameters. It explains what the tool does but lacks details on output format, error cases, or operational constraints, which are important for full contextual 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%, so the schema fully documents the two parameters (date and paymentsOnly). The description does not add any meaning beyond what the schema provides, such as explaining the implications of the paymentsOnly flag or date formatting nuances. Baseline 3 is appropriate when the schema handles parameter documentation.
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 ('Lists trial balance') and resource ('in Xero'), with specific details about what it provides ('snapshot of the general ledger, showing debit and credit balances for each account'). It effectively distinguishes this tool from sibling tools like list-accounts or list-profit-and-loss by focusing on trial balance rather than other financial reports.
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. It does not mention any prerequisites, exclusions, or specific contexts for usage, nor does it compare it to similar tools like list-accounts or list-profit-and-loss, leaving the agent without direction on selection.
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 full burden. It discloses that a deep link is returned and should be displayed, which is useful behavioral context. However, it lacks details on permissions needed, error handling, whether the operation is idempotent, or any rate limits—significant gaps for a creation tool with no annotation coverage.
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 appropriately sized with three sentences, front-loading the core purpose. The second and third sentences about the deep link are relevant but could be more integrated. No wasted words, though slight redundancy in mentioning the link twice.
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 no annotations and no output schema, the description is incomplete for a creation tool with 5 parameters. It covers the purpose and return behavior but misses critical context like error cases, side effects, or prerequisites (e.g., needing valid contactId from list-contacts). The schema handles parameters well, but overall guidance is minimal.
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 80%, so the baseline is 3. The description adds no parameter-specific information beyond what the schema provides (e.g., it doesn't explain 'lineItems' or 'type' further). It mentions the deep link return, but this relates to output, not input parameters.
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 specific action ('Create an invoice in Xero') and resource ('invoice'), distinguishing it from sibling tools like 'create-contact' or 'create-quote'. It also mentions the return value (a deep link), which adds specificity beyond just the verb.
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 like 'update-invoice' or 'list-invoices'. It mentions the deep link should be displayed to the user, but this is a post-creation instruction, not usage context. No explicit when/when-not or alternative tools are referenced.
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 key behavioral traits: it's a creation tool (implying mutation), requires account codes from another source, and enforces accounting rules (balance and line count). However, it lacks details on permissions, error handling, or response format, leaving gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the main purpose and efficiently lists requirements in a single sentence. It avoids redundancy, but could be slightly more structured (e.g., separating prerequisites from rules). Overall, it's concise 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?
Given no annotations and no output schema, the description partially compensates by outlining creation logic and constraints. However, for a mutation tool with 7 parameters, it lacks details on authentication, side effects, or what happens post-creation (e.g., success response). It's adequate but has clear gaps in behavioral context.
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 thoroughly. The description adds minimal value beyond the schema by hinting at 'account codes' and 'basic accounting account types pairing', but it doesn't explain parameter interactions or provide additional semantics. Baseline 3 is appropriate given high schema coverage.
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 states the action ('Create a manual journal in Xero') and specifies the resource, but it doesn't explicitly differentiate from sibling tools like 'update-manual-journal' or 'list-manual-journals'. It provides additional context about retrieving account codes and journal line requirements, which helps clarify the purpose beyond just the verb.
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 by mentioning prerequisites ('Retrieve a list of account codes') and constraints ('must contain at least two individual journal lines', 'credit and debit balanced'), but it doesn't explicitly state when to use this tool versus alternatives like 'update-manual-journal' or provide clear exclusions. The guidance is helpful but not comprehensive.
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 burden. It states this is a list operation, implying read-only behavior, but doesn't disclose important behavioral traits: whether it requires authentication, rate limits, what specific details are returned (e.g., name, address, settings), or if it's scoped to the current authenticated organisation. The description is minimal and misses key operational context for a tool with zero annotation coverage.
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 perfectly concise: two short sentences that directly state what the tool does and its primary use case. Every word earns its place with no redundancy or fluff. It's front-loaded with the core purpose followed by usage context, making it easy to parse quickly.
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 the tool's simplicity (0 parameters, no annotations, no output schema), the description is minimally adequate. It covers the basic purpose but lacks depth: no output format details, no authentication requirements, and no behavioral nuances. For a read-only list tool in a financial system, more context about what 'organisation details' includes would be helpful, but the absence of an output schema means the description should ideally hint at return values.
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 0 parameters with 100% schema description coverage (empty schema). The description doesn't need to explain parameters, and it appropriately doesn't mention any. Since there are no parameters to document, the description's focus on the tool's purpose is sufficient, earning a baseline 4 for not introducing unnecessary parameter information.
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 states the tool's purpose: 'Lists the organisation details from Xero' specifies the verb (list) and resource (organisation details). It distinguishes from siblings by focusing on organisation-level information rather than transactional data like invoices or contacts. However, it doesn't explicitly contrast with other list tools that might also provide organisational context.
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 provides basic context: 'Use this tool to get information about the current Xero organisation' implies usage when organisation-level metadata is needed. However, it lacks explicit guidance on when to choose this over other list tools (e.g., list-accounts or list-contacts) or when organisation details are specifically required versus general system information. 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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It describes what information is returned (leave type name, schedule of accrual, entitlement) but doesn't mention critical behavioral aspects like whether this is a read-only operation, potential rate limits, authentication requirements, or error conditions. For a tool with zero annotation coverage, this leaves significant gaps in understanding how the tool behaves.
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 appropriately sized with two sentences that efficiently convey the tool's purpose and what information it returns. The first sentence states the core functionality, and the second adds valuable detail about the return content. There's no wasted text, though it could be slightly more structured for optimal front-loading.
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 the tool's moderate complexity (single parameter, read operation), no annotations, and no output schema, the description provides adequate but incomplete context. It explains what the tool does and what information it returns, but lacks details about behavioral aspects, error handling, and output format. For a tool with no structured metadata support, the description should do more to compensate.
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% description coverage, with the single parameter 'employeeId' clearly documented in the schema. The description doesn't add any additional parameter semantics beyond what's already in the schema. According to scoring rules, when schema_description_coverage is high (>80%), the baseline is 3 even with no param info in the description.
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 specific action ('List all leave types') and resource ('for a specific employee in Xero'), distinguishing it from sibling tools like 'list-payroll-leave-types' (which appears to be general) and 'list-payroll-employee-leave' (which likely shows actual leave taken rather than available types). The description provides precise differentiation through its focus on employee-specific available leave types with detailed information.
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 context by specifying 'for a specific employee,' but doesn't explicitly state when to use this tool versus alternatives like 'list-payroll-leave-types' or 'list-payroll-employee-leave.' It provides basic context (employee-specific) but lacks explicit guidance on exclusions or comparative use cases with sibling 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?
No annotations are provided, so the description carries full burden. It mentions the tool lists accounts but doesn't disclose behavioral traits like whether it's read-only, pagination, rate limits, authentication needs, or what the output format looks like. For a tool with zero annotation coverage, this leaves significant gaps in understanding its 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 two sentences, front-loaded with the core purpose and followed by a usage guideline. Every sentence adds value without waste, making it efficient and well-structured.
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 the tool's low complexity (0 parameters, no output schema, no annotations), the description is somewhat complete for basic understanding. However, it lacks details on output format, behavioral constraints, and broader usage beyond invoice creation, which could hinder an agent's ability to use it correctly in varied contexts.
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 input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description doesn't add param info, which is appropriate here. Baseline is 4 for zero parameters, as it avoids unnecessary detail.
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 states the verb 'Lists' and resource 'all accounts in Xero', making the purpose specific and understandable. It distinguishes from siblings by focusing on accounts rather than other entities like contacts or invoices, though it doesn't explicitly contrast with similar list tools (e.g., list-contacts).
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?
It provides clear context for when to use this tool: 'to get the account codes and names to be used when creating invoices in Xero'. This gives a practical application scenario, but it doesn't specify when not to use it or name alternatives among siblings (e.g., for other purposes beyond invoice creation).
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 of behavioral disclosure. It effectively describes the tool as a read operation ('List all leave periods') and specifies the required input ('employee ID'), but lacks details on permissions, rate limits, pagination, error handling, or what happens if optional dates are omitted. The description doesn't contradict any annotations since none exist.
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 appropriately sized with two sentences that are front-loaded with the core purpose. The first sentence comprehensively covers what the tool does, and the second provides essential usage instruction. There's no wasted text, though it could be slightly more structured for clarity.
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 the tool's moderate complexity (3 parameters, no output schema, no annotations), the description is adequate but has gaps. It clearly states the purpose and required input, but lacks details on behavioral aspects like permissions, error cases, or return format. Without annotations or output schema, more context on what the list includes (e.g., pagination, sample output) 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%, with all three parameters clearly documented in the input schema. The description adds minimal value beyond the schema by mentioning the employee ID requirement and implying date filtering, but doesn't provide additional context like format examples for dates or how date ranges affect results. This meets the baseline for 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 clearly states the specific action ('List all leave periods'), target resource ('for a specific employee in Xero'), and scope ('detailed time off periods including start and end dates, period status, payment dates, and leave types'). It distinguishes itself from sibling tools like 'list-payroll-employee-leave' by focusing specifically on leave periods rather than general leave information.
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 context by specifying 'Provide an employee ID to see their leave periods,' which indicates this tool is for viewing leave periods for individual employees. However, it doesn't explicitly state when to use this tool versus alternatives like 'list-payroll-employee-leave' or provide any exclusion criteria 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 mentions the action ('Lists') but does not describe traits like pagination, rate limits, authentication needs, or what the output looks like (e.g., format or fields). This leaves significant gaps for a tool with zero annotation coverage.
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 two sentences that are front-loaded and efficient, with no wasted words. Every sentence adds value: the first states the purpose, and the second provides usage guidance, making it appropriately sized and well-structured.
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 the tool's low complexity (0 parameters, no output schema, no annotations), the description is adequate but has gaps. It covers purpose and usage but lacks details on behavioral traits like output format or operational constraints, which are needed for full completeness in the absence of annotations.
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 input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description does not add parameter details, which is appropriate, and it compensates by providing usage context. Baseline is 4 for zero parameters, as the schema fully covers the lack of inputs.
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 states the verb ('Lists') and resource ('all tax rates in Xero'), making the purpose specific and understandable. However, it does not explicitly differentiate from sibling tools like 'list-accounts' or 'list-contacts', which follow similar patterns for other resources, so it misses full sibling distinction.
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?
It provides clear context on when to use this tool ('to get the tax rates to be used when creating invoices in Xero'), which is helpful for guiding usage. However, it does not specify when not to use it or name alternatives among siblings, such as other list tools for different resources, so it lacks explicit exclusions or comparisons.
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. It states the tool retrieves data (implied read-only) and lists return details, but lacks behavioral traits like authentication requirements, rate limits, error handling, or whether it's idempotent. For a read operation with zero annotation coverage, this is insufficient.
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 appropriately sized with two sentences: the first states the purpose clearly, and the second lists key return details. It is front-loaded and has zero wasted words, making it efficient for an AI agent.
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 no annotations and no output schema, the description provides basic purpose and return details but lacks completeness for a read tool. It doesn't cover behavioral aspects like permissions or errors, and while it hints at output structure, it doesn't fully compensate for the missing 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 description coverage is 100%, so the schema already documents the single parameter 'timesheetID' fully. The description adds no additional parameter semantics beyond what's in the schema (e.g., format examples or constraints), meeting the baseline for 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 clearly states the tool's purpose with specific verb ('Retrieve') and resource ('a single payroll timesheet from Xero by its ID'), and distinguishes it from sibling tools like 'list-timesheets' (which retrieves multiple) and 'create-timesheet' (which creates new). It also specifies the scope ('single' vs. list).
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 implies usage context by specifying 'by its ID' and listing details provided, which helps differentiate from 'list-timesheets' for bulk retrieval. However, it lacks explicit guidance on when to use alternatives like 'list-timesheets' or prerequisites (e.g., needing a valid ID).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/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 key behavioral traits: it's a read operation (implied by 'List'), includes pagination behavior (returns 10 quotes per page, requires re-call for next page), and requires user interaction for filtering. However, it doesn't mention rate limits, authentication needs, or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized (4 sentences) but not optimally structured. It front-loads the core purpose but mixes implementation instructions (user prompts) with tool behavior. Some sentences could be more streamlined, though all add value.
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 3 parameters with 0% schema coverage, no annotations, and no output schema, the description provides moderate context. It covers pagination behavior and user interaction needs but misses details on parameter usage (especially quoteNumber), return format, and error cases, leaving room for improvement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage for its 3 parameters (page, contactId, quoteNumber). The description only partially compensates: it mentions 'page number' and 'contact' in the context of pagination, but doesn't explain contactId's purpose for filtering or quoteNumber at all. This leaves significant gaps in parameter understanding.
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 states the action ('List all quotes') and resource ('in Xero'), providing a specific verb+resource combination. However, it doesn't differentiate from sibling tools like 'list-invoices' or 'list-credit-notes' beyond the resource type, missing explicit distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool: it instructs to ask the user about contact filtering before running and about pagination after running if 10 quotes are returned. It also specifies to call the tool again with page and contact parameters for pagination, offering clear usage context.
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 full burden. It discloses key behavioral traits: the tool only works on draft journals and should not modify unspecified parameters, which are important constraints. However, it lacks details on permissions, error handling, or mutation effects (e.g., whether updates are reversible), leaving gaps in behavioral 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 two sentences, front-loaded with the main purpose and followed by critical constraints. Every sentence earns its place by providing essential information without redundancy or fluff, making it highly efficient and well-structured.
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 the complexity (8 parameters, no annotations, no output schema), the description is adequate but incomplete. It covers key usage constraints but lacks details on return values, error cases, or broader context (e.g., how it fits with other Xero operations). For a mutation tool with no structured safety hints, more behavioral disclosure would be beneficial.
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 fully documents all parameters. The description does not add any additional meaning or syntax details beyond what the schema provides (e.g., it doesn't explain parameter interactions or provide examples). Thus, it meets the baseline but adds no extra value.
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 states the action ('Update a manual journal in Xero') and resource ('manual journal'), making the purpose explicit. However, it does not distinguish this tool from sibling tools like 'update-bank-transaction' or 'update-invoice', which also perform updates in Xero, so it lacks sibling differentiation.
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 context for when to use this tool ('Only works on draft manual journals') and includes a constraint ('Do not modify line items or parameters that have not been specified by the user'). However, it does not explicitly mention alternatives (e.g., 'create-manual-journal' for new journals or other update tools for different resources), so it falls short of full explicit 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?
With no annotations provided, the description carries the full burden. It discloses key behavioral traits: pagination behavior (10 items per page, requires re-calling with next page number), user interaction requirements (asking about contact filtering and pagination), and that contact filtering is optional. However, it doesn't cover aspects like rate limits, authentication needs, error handling, or what happens if no credit notes exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized (4 sentences) but could be more front-loaded. The first sentence states the purpose clearly, but the subsequent sentences mix usage instructions with behavioral details. Some redundancy exists (e.g., mentioning asking about contact filtering twice). It earns its place but could be structured better.
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 no annotations, 0% schema coverage, and no output schema, the description does a fair job. It covers purpose, usage, pagination behavior, and parameter semantics. However, it lacks details on return format, error conditions, authentication requirements, and doesn't fully compensate for the missing structured data. It's adequate but has clear gaps for a listing tool.
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?
Schema description coverage is 0%, so the description must compensate. It explains the semantics of both parameters: 'page' for pagination (with implied starting point and increment logic) and 'contactId' for filtering by contact. It clarifies that contactId is optional and should be persisted across pagination calls. This adds significant value beyond the bare schema.
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 states the tool's purpose: 'List credit notes in Xero.' It specifies the verb ('List') and resource ('credit notes'), but doesn't explicitly differentiate from sibling tools like 'list-invoices' or 'list-payments' beyond the resource type. The description is specific about what it does but lacks sibling comparison.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool: it instructs to ask the user about filtering by contact and pagination before/after running. It implies usage for listing credit notes with optional contact filtering and pagination, though it doesn't name specific alternatives among 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 of behavioral disclosure. It describes the tool as a retrieval operation ('retrieves comprehensive employee details') and mentions the response format ('complete overview'), but does not cover potential limitations like rate limits, authentication needs, or whether the data is real-time. It adds some context about handling large datasets, but could be more comprehensive for a tool with zero annotation coverage.
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 appropriately sized and front-loaded, starting with the core purpose ('List all payroll employees in Xero') followed by details on what is retrieved. The second sentence elaborates on the response, and the third provides user interaction guidance. While efficient, the third sentence could be more concise or integrated better, but overall it earns its place without significant waste.
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 the tool's complexity (a list operation with no parameters but potentially large output), no annotations, and no output schema, the description is moderately complete. It explains what data is retrieved and hints at handling large datasets, but lacks details on output format (e.g., pagination, structure) or error conditions. For a tool with no structured output documentation, more guidance on the response would improve completeness.
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 0 parameters with 100% schema description coverage, so the schema already documents this fully. The description appropriately does not discuss parameters, maintaining focus on the tool's purpose and output. This meets the baseline of 4 for tools with no parameters, as it avoids unnecessary parameter details.
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 specific verb ('List') and resource ('payroll employees in Xero'), and distinguishes this tool from siblings like 'list-payroll-employee-leave' or 'list-payroll-employee-leave-balances' by focusing on comprehensive employee details rather than leave-related data. It explicitly mentions retrieving 'comprehensive employee details' with specific examples of fields included.
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 retrieving a complete overview of all staff, but does not explicitly state when to use this tool versus alternatives like 'list-contacts' or 'list-payroll-leave-types'. It provides some context about handling many employees ('ask the user if they would like to see more detailed information'), but lacks clear exclusions or direct comparisons to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does well by disclosing key behavioral traits: it specifies the tool only works on draft credit notes, warns that missing line items will be removed, advises not to modify unspecified line items, and describes the return value (a deep link to view in Xero). However, it lacks details on permissions, rate limits, or error handling.
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 appropriately sized and front-loaded with key information (purpose and constraints). Sentences are efficient, but some redundancy exists (e.g., repeating line item warnings from the schema description), slightly reducing conciseness.
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 the complexity (a mutation tool with 5 parameters, no annotations, and no output schema), the description is moderately complete. It covers purpose, constraints, and return behavior but lacks details on parameter specifics beyond line items, error cases, or full output explanation, leaving room for improvement.
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 low at 20%, but the description adds some meaning by explaining the 'lineItems' parameter behavior (all must be provided, omissions cause removal). It doesn't cover other parameters like 'creditNoteId', 'reference', 'date', or 'contactId', so it partially compensates but leaves gaps, aligning with the baseline for moderate schema coverage.
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 states the action ('Update a credit note in Xero') and specifies the resource ('credit note'), making the purpose evident. However, it doesn't explicitly differentiate from sibling tools like 'create-credit-note' or other update tools, though the context of 'update' implies modification versus 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 context for when to use this tool: 'Only works on draft credit notes.' It also implies usage by specifying constraints like requiring all line items, but it doesn't explicitly mention when not to use it or name alternatives (e.g., using 'create-credit-note' for new ones).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does well by disclosing key behavioral traits: it specifies the invoice statuses included (Draft, Submitted, Paid), describes pagination behavior (10 invoices per page, requires page parameter), and explains how to handle subsequent calls. It doesn't mention rate limits, authentication needs, or error conditions, but provides substantial operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized but not optimally structured. The first two sentences establish purpose, but the remaining text mixes usage guidance with implementation details. While all content is valuable, it could be more front-loaded with core functionality before detailed procedural instructions. No wasted sentences, but organization could be improved.
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 no annotations and no output schema, the description provides good context for a listing tool. It covers purpose, scope, filtering options, and pagination behavior. Missing elements include return format details, error handling, and authentication requirements, but for a list operation with clear parameters, it's reasonably complete. The pagination guidance is particularly valuable.
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 only 33% (only 'invoiceNumbers' has a description), but the description compensates somewhat by explaining the purpose of contact and invoice number filtering in the usage guidance. However, it doesn't explain the 'page' parameter's semantics or format, nor does it clarify that 'contactIds' and 'invoiceNumbers' are arrays. The description adds value but doesn't fully compensate for the low schema coverage.
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 states the tool's purpose: 'List invoices in Xero' with specific scope details ('This includes Draft, Submitted, and Paid invoices'). It distinguishes from siblings like 'create-invoice' or 'update-invoice' by focusing on listing rather than creating/modifying. However, it doesn't explicitly differentiate from other list tools like 'list-credit-notes' or 'list-quotes' beyond the resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool: 'Ask the user if they want to see invoices for a specific contact, invoice number, or to see all invoices before running.' It also includes detailed pagination instructions ('Ask the user if they want the next page... If they want the next page, call this tool again...'). This gives clear context for usage decisions.
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 pagination behavior ('If many payments are returned, ask the user if they want to see the next page'), which is valuable. However, it doesn't mention authentication requirements, rate limits, error conditions, or what happens when no payments match filters.
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 appropriately sized with 4 sentences that each add value. It's front-loaded with the core purpose, followed by details about what's shown, filtering options, and behavioral guidance. No wasted words, though the pagination guidance could be slightly more concise.
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 5-parameter tool with no annotations and no output schema, the description provides good purpose and parameter guidance but lacks details about authentication, error handling, response format, and the 'page' parameter's semantics. It's adequate but has clear gaps given the tool's complexity.
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?
With 0% schema description coverage for 5 parameters, the description compensates well by explaining the filtering options ('filter payments by invoice number, invoice ID, payment ID, or invoice reference'). It maps clearly to 4 of the 5 parameters, though it doesn't mention the 'page' parameter explicitly. This provides substantial value beyond the bare 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 the verb ('List') and resource ('payments in Xero'), specifies what payments are shown ('payments made against invoices'), and distinguishes from siblings by focusing on payments rather than invoices, contacts, or other entities. It provides specific details about included data fields.
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 context for when to use this tool ('List payments in Xero') and includes explicit guidance about asking users for filtering preferences before running. However, it doesn't explicitly state when NOT to use it or name specific alternative tools for different scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does well by disclosing key behavioral traits: the payment amount constraints (positive, not exceeding remaining due), invoice prerequisites (AUTHORIZED status, not fully paid), and the return value (a deep link to Xero that should be displayed). It doesn't cover error handling or rate limits, but provides substantial operational context.
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 appropriately sized and front-loaded with the core purpose. Every sentence adds value: first states the action, second lists key parameters, third-fourth specify constraints, fifth-sixth describe prerequisites, and final sentences explain the return value. Some redundancy exists in stating invoice constraints twice, but overall 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?
For a mutation tool with no annotations and no output schema, the description does well by covering purpose, constraints, prerequisites, and return format. It could be more complete by explicitly stating this is a write operation (implied by 'create') and mentioning potential side effects on invoice status, but provides sufficient context for correct tool selection and invocation.
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 5 parameters thoroughly. The description adds minimal value beyond the schema by mentioning invoiceId, accountId, and amount as required parameters and reinforcing the amount constraints, but doesn't provide additional semantic context about date format interpretation or reference usage.
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 specific action ('create a payment'), target resource ('against an invoice in Xero'), and distinguishes it from siblings like 'create-invoice' or 'list-payments'. It goes beyond the tool name by specifying it's a transaction recording operation.
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 context about when to use this tool: for invoices that are 'status AUTHORIZED' and 'not fully paid'. However, it doesn't explicitly mention when NOT to use it or name specific alternative tools among the siblings, though the conditions imply alternatives aren't needed for this specific operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does well: it discloses that the tool mutates data (implied by 'Update'), specifies a precondition ('draft quotes'), warns about destructive behavior ('Any line items not provided will be removed'), and describes the return value ('a deep link to the quote in Xero is returned'). It lacks details on permissions or rate limits, but covers key behavioral traits effectively.
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 appropriately sized and front-loaded with the most important information (purpose and key constraint). Each sentence adds value, such as behavioral warnings and output details. Minor redundancy with the schema's lineItems description slightly reduces efficiency, but overall it's well-structured.
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 complexity (10 parameters, no annotations, no output schema), the description is quite complete: it covers purpose, constraints, critical parameter behavior, and output format. It lacks details on other parameters and error cases, but for a mutation tool with sparse structured data, it provides sufficient context for effective use.
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?
Schema description coverage is low (10%), but the description compensates by explaining the critical semantics of the 'lineItems' parameter: 'All line items must be provided. Any line items not provided will be removed.' This adds essential meaning beyond the schema's minimal descriptions. It does not cover other parameters, but the high value of this guidance justifies a strong 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 clearly states the verb ('Update') and resource ('a quote in Xero'), and distinguishes it from siblings by specifying 'Only works on draft quotes'—a crucial constraint not implied by the name alone. This makes the purpose specific and differentiated.
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 explicit context for when to use the tool ('Only works on draft quotes') and implies an alternative (e.g., not using it for non-draft quotes). However, it does not name specific sibling tools as alternatives (e.g., 'create-quote' for new quotes), which prevents a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and excels by disclosing key behavioral traits: it specifies the draft-only limitation, the destructive nature of line item updates (removal of unspecified items), and the return value (a deep link to view the invoice in Xero), which is crucial 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 appropriately sized and front-loaded with the core purpose and constraints, though it could be slightly more streamlined by avoiding minor repetition (e.g., the line item rules are stated in both the description and schema). Every sentence adds value, but there's room for tighter phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a mutation tool with no annotations or output schema, the description is highly complete: it covers purpose, usage constraints, behavioral details (including destructive effects and return value), and parameter implications, leaving no significant gaps for the agent.
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 thoroughly. The description adds minimal value beyond the schema by reiterating the line item behavior, but it doesn't provide additional syntax or format details, meeting the baseline for high 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 clearly states the specific action ('Update an invoice in Xero'), resource ('invoice'), and scope ('Only works on draft invoices'), distinguishing it from sibling tools like 'create-invoice' or 'list-invoices' by focusing on modification rather than creation or listing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use ('Only works on draft invoices') and provides clear behavioral guidance ('All line items must be provided. Any line items not provided will be removed. Including existing line items. Do not modify line items that have not been specified by the user'), which helps the agent understand critical constraints and avoid misuse.
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:

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

Score Badge

Copy to your README.md:

[![xero-mcp-server MCP server](https://glama.ai/mcp/servers/XeroAPI/xero-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/XeroAPI/xero-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/XeroAPI/xero-mcp-server'

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