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

With no annotations, the description carries the full burden of behavioral disclosure. It does not state that the operation is read-only, does not describe error behavior (e.g., what happens if the account is not found), and lacks any mention of authentication or rate limits.

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

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

The description is a single, front-loaded sentence with no filler words. It efficiently conveys the essential purpose.

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

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

The tool is simple with one parameter and no output schema, but the description's vagueness ('detailed information') does not fully compensate for the missing output schema. It lacks specifics about the return structure or error conditions, making it minimally complete.

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

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

Schema description coverage is 100%, with accountId described as 'The unique account ID (UUID)'. The description adds no additional meaning beyond the schema, so the baseline of 3 applies.

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

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

The description clearly states the action ('Get'), the resource ('account'), and the scope ('by its ID'). It implicitly distinguishes itself from xero_accounts_list by specifying a single account rather than a list.

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

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

The description implies usage when an account ID is known and detailed information is needed, but it does not explicitly mention alternatives like xero_accounts_list or provide criteria for when to use this tool over others.

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

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

With no annotations provided, the description carries full burden. It does not disclose behavioral traits such as read-only nature, pagination, sorting, or rate limits. 'List' implies read-only, but this is not explicit.

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

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

The description is a single sentence (12 words) that conveys the core functionality and optional filters. No wasted words.

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

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

Given no output schema, the description does not explain return format or behavior (e.g., all accounts vs partial). For a simple list tool with two optional params, it is minimally adequate but could mention default results or limits.

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

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

Schema description coverage is 100%, so the baseline is 3. The description paraphrases the filters ('Type' and 'Class') without adding new meaning beyond what the schema provides.

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

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

The description clearly states the action ('List'), the resource ('chart of accounts'), and the scope ('in Xero'). It also mentions optional filters, differentiating it from sibling tools like 'xero_accounts_get'.

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

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

No guidance on when to use this tool versus alternatives (e.g., xero_accounts_get). The description only states optional filtering without context on typical use cases or prerequisites.

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

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

With no annotations provided, the description carries the burden of disclosing behavior. It clearly states the tool is a no-op in flattened mode, which is a critical behavioral trait. It also adds context about tool availability. While it doesn't detail return values or behavior in non-flattened mode, the core side effect (no-op) is transparently disclosed, which is sufficient for this trivial tool.

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

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

The description is exceptionally concise: two short sentences that front-load the primary action and then provide necessary context. Every word earns its place, with no redundancy or fluff. It achieves maximum clarity in minimal space.

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

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

Given the tool's simplicity (no parameters, no output schema, no annotations), the description is nearly complete. It states the purpose, the no-op behavior in flattened mode, and the reason for that behavior. The only minor gap is not defining 'domain selection' or 'flattened mode', but these are contextual concepts likely understood from sibling tools and the environment. The description is adequate for an agent to decide whether to invoke this tool.

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

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

The tool has zero parameters, and the schema coverage is trivially 100% since there is nothing to document. Per baseline for 0-param tools, a score of 4 is appropriate. The description adds no parameter information because none is needed.

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

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

The description clearly states the tool's function: 'Return to domain selection' with a specific verb and resource, and explicitly notes it is a 'no-op in flattened mode'. This distinguishes it from data-oriented siblings like xero_contacts_list or xero_invoices_get. The purpose is unambiguous even for an agent unfamiliar with the system.

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

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

The description implies usage context by noting the tool is a no-op in flattened mode and that 'All tools are always available', suggesting that in the current environment one might not need to call it. However, it does not explicitly state when to use this tool versus alternatives like xero_navigate, nor provide exclusions beyond the flattened mode caveat. Usage guidance is present but only implied.

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

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

No annotations are provided, so the description must carry full transparency burden. It identifies the operation as creating a new contact, but does not disclose potential side effects, response behavior, or whether duplicate names cause errors.

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

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

Description is two short sentences, clear and to the point with no unnecessary words.

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

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

With 9 scalar parameters and no output schema, the description is minimal. It does not explain what the tool returns or how to verify the created contact, which is important for a create operation. However, the schema covers parameters well.

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

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

The input schema provides 100% coverage with descriptions for all parameters. The description only restates Name as required, which is already in the schema, adding no additional semantic meaning.

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

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

The description clearly states the tool creates a contact in Xero, using a specific verb and resource. It is distinct from sibling contact tools like list/get/search due to the 'create' action.

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

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

No guidance is provided on when to use this tool versus alternatives. It does not mention using list/search to find existing contacts or any exclusions. The only usage hint is implicit from the purpose.

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

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

The description indicates a read operation (get details) but doesn't mention side effects, permissions, or error handling. Since no annotations are provided, the description carries the full burden for transparency. It adequately describes the main behavior but lacks depth.

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

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

Two sentences, front-loaded with the core action and resulting data. Every word adds value with no redundancy or filler.

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

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

The description includes the return fields (addresses, phone numbers, email) which is helpful given no output schema. It is complete for a simple get operation, but could mention potential error responses or pagination if applicable. Still, it meets the needs for this single-param tool.

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

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

The schema covers the parameter fully with a description of the unique contact ID. The description adds no new semantics for the parameter; it only repeats 'by its ID'. Baseline score of 3 is appropriate given 100% schema coverage.

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

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

The description clearly states it gets contact details by ID and lists specific return fields like addresses, phone numbers, and email. Distinguishes from siblings such as xero_contacts_list (list all) and xero_contacts_search (filtered) by focusing on a single contact retrieval.

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

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

The description implies use when you have a specific contact ID and need full details. It doesn't explicitly compare to siblings, but the purpose is clear enough from context. A brief mention of when not to use (e.g., for searches or creation) would improve it.

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

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

Without annotations, the description must disclose behavioral traits. It mentions pagination and optional filtering, which implies a read-only, batch operation. However, it does not specify side effects, permissions, rate limits, or that it returns a list. The parameter descriptions in the schema confirm pagination limits (100 per page), so the description adds marginal 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.

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

Two concise sentences: first states the action and core feature (pagination), second covers optional filtering and return fields. No redundant or filler content.

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

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

Given no output schema, the description usefully specifies return fields. For a simple list tool with pagination and optional filter, it covers the essentials. However, the presence of sibling xero_contacts_search suggests that guidance on when to use list versus search would enhance completeness. Error handling and data freshness are not addressed.

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

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

Input schema has 100% coverage with clear parameter descriptions for 'page' and 'where'. The description adds value by stating that results include 'name, email, and addresses', which is not in the schema (no output schema). This extra context justifies a score above the baseline of 3.

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

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

The description uses specific verb 'List' and resource 'contacts in Xero', clearly indicating a paginated listing operation. It distinguishes from sibling tools like xero_contacts_get (single contact) and xero_contacts_search (likely full-text search) by mentioning pagination and optional where clause filtering.

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

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

The description says 'Optionally filter using a where clause', implying use cases for filtered or unfiltered lists. However, it does not contrast with sibling tools like xero_contacts_search, which might be more appropriate for complex queries. No explicit when-not-to-use guidance is provided.

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

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

The description discloses that it returns contacts matching a substring search, but lacks details on pagination, case sensitivity, maximum results, or response structure. Since no annotations exist, the description carries the full burden and provides basic but incomplete transparency.

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

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

The description is two sentences, front-loaded, and contains no extraneous information. Every word adds value.

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

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

For a simple search tool with one parameter and no output schema, the description covers the essential behavior. It could mention that multiple contacts may be returned or specify case sensitivity, but it is adequate for the complexity level.

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

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

The schema description coverage is 100% for the 'term' parameter, and the tool description adds no additional meaning beyond what the schema provides. The baseline is 3, as the description does not enrich parameter understanding.

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

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

The description clearly states the tool searches contacts by name and returns those whose name contains the search term. It distinguishes from sibling tools like xero_contacts_list (list all) and xero_contacts_get (get by ID) by specifying the search-by-name functionality.

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

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

The description implies usage for name-based searching but does not explicitly state when to use this tool versus xero_contacts_get (for exact ID lookup) or xero_contacts_list (for retrieving all contacts). No guidance on limitations or prerequisites is provided.

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

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

No annotations are provided, so the description must fully disclose behavior. It only states 'Create a new invoice,' implying mutation, but omits side effects (e.g., immediate persistence, status defaults, idempotency, error scenarios, or permissions). This is insufficient for a write operation.

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

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

The description is a single, direct sentence without extraneous information. It efficiently conveys the core action and mandatory requirements, earning full marks for conciseness.

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

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

With 7 parameters, 3 required, no output schema, and no annotations, the description is too minimal. It lacks information about return values, error handling, date formatting conventions, or typical usage flows, leaving the agent underinformed for a write tool.

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

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

The input schema has 100% description coverage, so the schema already details each parameter. The description only echoes the required fields without adding meaningful contextual insight beyond what's in the schema, resulting in a baseline score.

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

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

The description clearly states 'Create a new invoice in Xero' with specific verb and resource. It lists required elements (type, contact, line items) and distinguishes itself from sibling tools like xero_invoices_list (listing) and xero_invoices_update_status (update only).

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

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

The description mentions required parameters but does not provide explicit guidance on when to use this tool versus alternatives. It lacks context such as prerequisites (e.g., contact must exist) or exclusions (e.g., not for updating existing invoices).

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

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

With no annotations, the description carries the full burden. It transparently states what the tool returns ('full invoice details including line items, amounts, and payment status') and implies a read-only side-effect-free behavior via the verb 'Get'. It does not cover errors or auth, but for a simple lookup this is sufficient.

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

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

The description is a single sentence with a front-loaded verb and resource, followed by a concise statement of return value. Every word earns its place with no redundancy.

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

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

Given the tool's simplicity (one required parameter, no output schema), the description fully covers what the tool does and what information it returns. It is complete enough for an agent to select and invoke it correctly without additional context.

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

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

Schema coverage is 100% and the single parameter invoiceId is described in the schema. The description adds minimal semantic value by linking the ID to 'a specific invoice' and mentioning detailed output, but it does not go beyond the schema's existing meaning.

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

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

The description uses the specific verb 'Get' and clearly identifies the resource: 'a specific invoice by its ID'. It distinguishes this tool from sibling tools like xero_invoices_list (list all invoices) and xero_invoices_create/update_status by focusing on fetching detailed data for a single invoice.

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

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

The description provides clear context: use this tool when you have an invoice ID and need full details. It implies the contrast with listing or creating invoices, though it does not explicitly name alternative tools or exclusions. This meets the 'clear context, no exclusions' bar.

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

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

No annotations are provided, so the description bears the burden. It states listing with pagination but does not explicitly confirm read-only behavior, disclose any side effects, or mention rate limits. The word 'list' implies read-only, but transparency could be improved.

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

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

Two sentences with no extraneous words. Purpose and optional filters are front-loaded, making it efficient.

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

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

The tool has 3 optional parameters and no output schema. The description covers the main purpose and filters. It does not mention the return format (list of invoice objects), but this is typical for a listing tool. Minor gap.

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

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

Schema coverage is 100% with good parameter descriptions. The description adds slight value by clarifying ACCREC and ACCPAY meanings, but the schema already defines these. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'List', the resource 'invoices in Xero', and key features like pagination and optional filters (status and type). It distinguishes from siblings like xero_invoices_get (single invoice) and xero_invoices_create.

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

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

The description mentions optional filters but does not provide explicit guidance on when to use this tool versus alternatives like xero_invoices_get or xero_accounts_list. No when-not or prerequisite advice.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. It mentions the three possible statuses but does not disclose consequences (e.g., voiding is irreversible), permissions required, or side effects. This is a significant gap for a mutation tool.

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

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

The description is two short sentences with no unnecessary information. The key action is front-loaded, and every word contributes to understanding the tool's purpose.

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

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

Given the tool's low complexity (2 params, no output schema), the description covers the essentials of what it does. However, it lacks any mention of behavior beyond the status change, such as errors or reversibility, and does not address usage context relative to sibling tools. It is minimally viable but not thorough.

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

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

The input schema already provides descriptions for both parameters and an enum for Status, achieving 100% coverage. The description repeats the statuses but adds no extra meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool updates the status of an existing invoice, listing the specific actions (submit, authorise, void) which distinguishes it from other invoice tools like create or list. It is a specific verb+resource with clear scope.

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

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

The description implies when to use the tool (for existing invoices needing status changes) but does not explicitly mention alternatives or situations when not to use it. It lacks direct guidance on choosing this over other invoice tools, but the context is clear enough for a simple tool.

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

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

No annotations are provided, so the description carries the full burden. It discloses the tool's primary behavior (returns tool names and descriptions), clarifies it is non-prerequisite, and implies it is a read-only, informational tool. It does not describe detailed side effects or failure modes, but given the tool's simple, no-side-effect nature, the disclosure is adequate.

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

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

The description is two sentences with no fluff. The first sentence states the purpose, and the second clarifies usage context. All information is essential and front-loaded, making it highly concise and well-structured.

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

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

The tool is simple with one parameter, fully documented by the schema. The description states the output (tool names and descriptions) and clarifies the help/discovery nature. There is no output schema, but the return value is adequately described. For a discovery tool, this is complete.

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

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

The input schema already provides 100% coverage, including a detailed description for each enum value of the 'domain' parameter. The tool description adds minimal extra semantic context beyond saying it returns tools for the selected domain. Since the schema is thorough, the description does not need to compensate; the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Discover available Xero tools by domain' and specifies the output ('Returns tool names and descriptions for the selected domain'). The verb 'Discover' and resource 'available Xero tools by domain' are specific, and it distinguishes itself from sibling tools by being a help/discovery aid rather than a specific Xero operation.

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

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

The description provides clear context that this is a discovery tool, noting 'All tools are callable at any time — this is a help/discovery aid, not a prerequisite.' This tells the agent it is for exploring available tools and explicitly states it is not a required precursor to other calls. However, it does not explicitly state 'use this when you need to find a tool' but that is strongly implied by the first sentence.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the basic creation action but does not disclose side effects on the invoice, permission requirements, reversibility, or what the response contains. For a mutation tool, 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.

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

The description is two concise sentences that immediately state the action and its purpose, with no redundant or filler words. Every element earns its place.

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

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

With no annotations and no output schema, the description is too sparse for a creation tool. It fails to explain what happens after payment creation, whether the invoice status changes, or any error or edge-case behavior. The parameter schema is helpful but does not compensate for the lack of contextual information.

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

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

The schema provides descriptions for all five parameters (100% coverage), so the schema does the heavy lifting. The description adds no additional parameter semantics, but the baseline of 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.

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 payment in Xero') and its specific purpose ('Records a payment against an invoice'), distinguishing it from sibling tools that list or get payments. The verb 'Create' and resource 'payment' are explicit.

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

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

The phrase 'Records a payment against an invoice' implies the intended usage scenario (applying a payment to an invoice), but there is no explicit guidance on when to use this tool versus alternatives, nor any exclusions. Context is implied rather than stated.

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

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

Description indicates a read operation ('Get detailed information'), but with no annotations, it fails to disclose any behavioral traits such as auth requirements, rate limits, or side effects beyond the basic retrieval.

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

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

Single sentence of 12 words, efficient and front-loaded. No unnecessary information.

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

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

For a simple get-by-ID tool with one parameter and no output schema, the description sufficiently conveys the purpose and return value ('detailed information'). Completeness is adequate, though could specify example fields.

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

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

Schema description coverage is 100% (paymentId described as 'The unique payment ID (UUID)'), and description adds no additional parameter meaning beyond restating the schema. Baseline score of 3 applies.

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

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

Description clearly states 'Get detailed information about a specific payment by its ID.' Uses specific verb and resource, and distinguishes from sibling tools like xero_payments_list (list all) and xero_payments_create (create).

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

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

Implies usage for retrieving a single payment by ID, but provides no explicit guidance on when to use this over alternatives like listing all payments.

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

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

No annotations are present, so the description must disclose behavioral traits. It mentions pagination but relies on the schema for details. It does not mention read-only nature, rate limits, or any side effects. The minimal description adds little beyond the schema.

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

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

The description is one sentence, efficiently conveying the core action and optional filter. It is front-loaded and contains no unnecessary words.

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

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

Given the low complexity (2 parameters, no output schema, no nested objects), the description is adequate. It covers the main functionality (listing with pagination and filtering) but could be improved by noting the return type or that it's read-only. However, it is complete enough for a simple listing tool.

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

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

Schema coverage is 100% with detailed parameter descriptions for 'page' and 'Status'. The description merely echoes 'Optionally filter by status', which adds no new meaning. Baseline 3 is appropriate as schema carries the burden.

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

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

The description clearly states the verb 'List' and the resource 'payments in Xero', with optional filtering by status. It is specific and distinguishes from sibling tools that list different resources (e.g., xero_accounts_list, xero_invoices_list).

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

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

The description implies usage for listing payments with pagination and filtering, but does not explicitly state when to use this tool versus alternatives like xero_payments_get (single payment) or other list tools. No exclusions or contextual guidance provided.

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

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

No annotations are provided, and the description only says 'Get' which implies a read operation, but does not disclose potential limitations (e.g., data freshness, authorization needs, or if the report is computed on the fly). The behavioral traits are minimally transparent.

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

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

A single sentence conveys the essential information without redundancy. Every word is earned.

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

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

For a simple tool with one parameter and no output schema, the description is adequate but could be improved by hinting at the age categories (e.g., 30/60/90 days). It covers the basics but lacks some context.

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

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

Schema coverage is 100% and the single parameter 'date' is well-described in the schema (format, required). The description adds no additional semantic detail; the baseline of 3 is appropriate.

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

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

The description clearly states the tool gets an Aged Payables report and specifies the content ('outstanding supplier bills by age'). It distinguishes from sibling tools like xero_reports_aged_receivables and xero_reports_balance_sheet by naming the specific report type.

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

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

The description implies usage for viewing aged payables but does not explicitly state when to use or provide alternatives. Without guidance on when not to use or comparisons to sibling reports, an agent might lack context for selection.

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

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

No annotations provided, so the description carries full burden. It implies a read operation and specifies the report type, but lacks details on default behavior, response format, or auth needs.

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

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

One concise sentence that is front-loaded with the key action and resource, no extraneous text.

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

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

For a simple 1-param tool with no output schema, the description is adequate but could mention what the report contains (e.g., aging buckets) to be fully complete.

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

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

Schema coverage is 100% and the description does not add extra meaning beyond the schema's description of the date parameter.

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

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

The description clearly states the tool retrieves an Aged Receivables report with outstanding customer invoices by age, differentiating it from siblings like aged payables or balance sheet.

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

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

No guidance on when to use this tool versus alternatives (e.g., aged payables, balance sheet) or any prerequisites. The description is purely structural.

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

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

No annotations are provided, so the description must carry the burden of disclosing behavior. The description is minimal and does not mention safety, permissions, side effects, return format, or any limitations. It only describes the action without 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.

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

The description is a single concise sentence that is front-loaded with the main action and resource. There is no redundant information, making it efficient and clear.

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

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

For a simple tool with one fully-described parameter, the description is adequate but leaves gaps. It lacks details about the report contents, any caveats about historical dates, or how the date is used exactly. It also does not provide usage guidance among report siblings, making it minimally complete.

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

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

The input schema already covers the parameter fully with description and format. The description adds only 'as of a specific date,' which reinforces the date parameter but does not provide additional meaning beyond the schema. With 100% schema coverage, the baseline is 3, and no extra value is added.

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

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

The description clearly states the tool gets a Balance Sheet report, which is a specific resource and verb. It also mentions 'as of a specific date,' tying to the date parameter. This distinguishes it from sibling report tools like Profit and Loss or Aged Receivables.

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

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

There is no guidance on when to use this tool versus alternatives. The description only states what it does, with no context about choosing it over other report tools or any prerequisites. 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.

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

With no annotations, the description carries the burden of behavioral disclosure. The verb 'Get' implies a read-only operation, but no details are given about permissions, return format, or error handling. It is adequate but minimal, lacking explicit safety or side-effect information.

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

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

The description is a single, front-loaded sentence with no redundant words. It efficiently conveys the tool's purpose without unnecessary detail.

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

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

For a simple, self-descriptive report retrieval, the description is largely sufficient. However, since there is no output schema, the description does not clarify the structure or content of the returned report, making it slightly incomplete for a fully autonomous agent.

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

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

The input schema covers 100% of parameters with clear format descriptions (YYYY-MM-DD, required). The description's mention of 'date range' adds no additional semantic value beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the action (Get) and the resource (Profit and Loss report), making it distinct from sibling report tools like balance sheet and aged receivables. The verb and resource are specific and unambiguous.

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

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

The description implies when to use the tool (when a P&L report is needed) but provides no explicit guidance on selecting it over sibling report tools. There are no exclusions or alternative recommendations, relying on the tool name and context.

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

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

No annotations are present, so the description carries full responsibility for behavioral disclosure. The phrase 'Show credentials status and available domains' essentially restates the tool's purpose without adding details about side effects, safety, return format, or interpretation of 'credentials status.' This lack of extra context leaves the agent with minimal behavioral understanding.

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

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

The description is a single, concise sentence that immediately states the tool's function. It is front-loaded and contains no filler, making it highly efficient for an agent to parse.

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

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

Given the tool's simplicity (no parameters) and lack of output schema, the description is minimally viable but has gaps. It does not explain what 'credentials status' means, how the info is presented, or whether the operation is read-only. This incomplete context could lead to incorrect assumptions, but the simplicity of the tool partially compensates.

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

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

The tool has zero parameters, which warrants a baseline of 4. There is no parameter schema to elaborate on, so the description does not need to add parameter meaning. The baseline applies because no additional explanation is required.

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

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

The description uses a specific verb 'Show' and clearly identifies the resource ('credentials status and available domains'). This distinguishes the tool from sibling tools like xero_contacts_list or xero_invoices_list, which deal with specific data entities. The purpose is unambiguous.

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

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

No guidance is provided on when to use this tool versus alternatives. There is no mention of typical scenarios (e.g., checking authentication before other operations) or any explicit exclusions. The description simply states what it does without context.

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