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

Annotations already provide important behavioral hints (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false), so the bar is lower. The description adds some context by mentioning the return format ('Created invoice details including Id, DocNumber, and TotalAmt'), which helps the agent understand what to expect. However, it doesn't disclose other behavioral traits like authentication requirements, rate limits, or error conditions.

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 well-structured with clear sections (purpose, Args, Returns) and uses bullet points for readability. It's appropriately sized for a creation tool with 4 parameters. However, the 'Args' section could be more concise by integrating with the schema instead of duplicating information, and the purpose statement is somewhat basic.

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 complexity (a write operation with 4 parameters), the description is reasonably complete. It covers the purpose, parameters, and return values. With annotations providing safety hints and no output schema, the description's inclusion of return details is valuable. However, it lacks context about error handling, validation rules, or integration with sibling tools.

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

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

Schema description coverage is 100%, so the schema already fully documents all parameters. The description's 'Args' section essentially repeats what's in the schema without adding meaningful semantic context (e.g., explaining what a 'customer_id' represents beyond 'QuickBooks Customer ID' or providing examples of line item descriptions). The baseline of 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.

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 new invoice') and resource ('in QuickBooks Online'), distinguishing it from sibling tools like qbo_list_invoices (which lists invoices) and other list tools. It provides a precise verb+resource combination that leaves no ambiguity about the tool's function.

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 no guidance on when to use this tool versus alternatives. While it's clear this creates invoices, there's no mention of prerequisites (e.g., needing an existing customer), when not to use it, or how it differs from other invoice-related operations that might exist. The agent 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.

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

Annotations already cover key behavioral traits (read-only, open-world, idempotent, non-destructive), so the bar is lower. The description adds useful context by specifying what data is returned (Id, Name, AccountType, CurrentBalance) and the response format options, which goes beyond annotations. No contradictions with annotations exist.

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 efficiently structured with a clear purpose statement followed by bullet points for Args and Returns. Every sentence adds value without redundancy, making it easy to scan and understand quickly.

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 parameters, no output schema), annotations covering safety, and high schema coverage, the description is mostly complete. It specifies return fields, which compensates for the lack of output schema, but could improve by mentioning pagination or error handling for a more comprehensive view.

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

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

Schema description coverage is 100%, with both parameters well-documented in the schema (including enums, defaults, and descriptions). The description adds minimal value beyond the schema by listing the return fields, which doesn't directly relate to parameter semantics. Baseline 3 is appropriate given the comprehensive schema.

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 resource ('chart of accounts from QuickBooks Online'), making the purpose specific and unambiguous. It distinguishes this tool from siblings like qbo_list_customers or qbo_list_invoices by specifying it deals with accounts rather than other QuickBooks entities.

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 through the mention of filtering by account_type and output format options, but it doesn't explicitly state when to use this tool versus alternatives. No guidance is provided on prerequisites, timing, or comparisons with sibling tools like qbo_profit_loss_report for financial data.

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?

Annotations already provide strong hints (readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true), covering safety and idempotency. The description adds value by specifying the return format options ('markdown' or 'json') and listing the fields in the output (e.g., Id, VendorRef, TxnDate), which are not covered by annotations. It doesn't contradict annotations, as 'List' aligns with read-only behavior.

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 appropriately sized and structured with clear sections (Args, Returns), making it easy to scan. It avoids unnecessary verbosity, but the Args section could be more integrated into the main text rather than listed separately, slightly reducing efficiency. Overall, it's front-loaded with the core 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 complexity (5 parameters, no output schema), the description is reasonably complete. It covers the purpose, parameters (via schema), and return fields, though it lacks details on error handling or rate limits. With annotations providing safety context, it's sufficient for a list operation, but could benefit from more behavioral context like pagination limits or data freshness.

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 each parameter well-documented in the schema (e.g., limit, offset, status with enum values). The description adds minimal semantics beyond the schema, only briefly mentioning pagination and filtering in the Args section without new details. This meets the baseline of 3 since the schema carries the primary 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 action ('List') and resource ('bills/payables from QuickBooks Online'), making the purpose specific and unambiguous. It distinguishes this tool from siblings like qbo_list_invoices and qbo_list_vendors by focusing on bills/payables, which are distinct financial entities in accounting systems.

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 through the mention of filtering options (vendor_id, status) and pagination, suggesting it's for retrieving bill data. However, it lacks explicit guidance on when to use this tool versus alternatives like qbo_list_invoices or qbo_profit_loss_report, which might also involve financial data retrieval. No exclusions or prerequisites are 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true, covering safety and idempotency. The description adds useful context beyond this: it specifies the return format options (markdown/json) and details about pagination (limit/offset), which are not captured in annotations, enhancing 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 well-structured with clear sections (purpose, returns, args, returns details) and uses bullet points for readability. It is appropriately sized but could be slightly more concise by avoiding repetition of schema details. Most sentences earn their place by providing essential info.

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 complexity (list operation with filtering/pagination), annotations provide good safety coverage, and the description adds context like return format and data fields. However, without an output schema, the description partially compensates by listing return fields, though it could better explain response structure or error handling.

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

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

Schema description coverage is 100%, so the schema fully documents all parameters. The description repeats parameter info (e.g., limit, offset, active_only, search, response_format) without adding significant meaning beyond what's in the schema, such as usage examples or edge cases. 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.

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 customers') and resource ('from QuickBooks Online'), distinguishing it from sibling tools like qbo_list_invoices or qbo_list_vendors. It explicitly mentions what data is returned, making the purpose unambiguous and distinct.

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 retrieving customer data but does not explicitly state when to use this tool versus alternatives like qbo_list_vendors or qbo_list_accounts. It provides no guidance on prerequisites, exclusions, or specific scenarios where this tool is preferred 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?

Annotations already cover key behavioral traits (read-only, open-world, idempotent, non-destructive), but the description adds valuable context beyond this: it specifies the return format options ('markdown' or 'json'), lists the fields in the response, and mentions pagination behavior via limit/offset. This enhances transparency without contradicting the annotations.

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

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

The description is well-structured and front-loaded with the core purpose, followed by organized sections for Args and Returns. Every sentence adds value: the first sets context, and the bullet points efficiently detail parameters and outputs without redundancy. It's appropriately sized for a tool with 7 parameters.

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 complexity (7 parameters, no output schema), the description is complete: it covers the purpose, all parameters with semantics, return format options, and response fields. With annotations providing safety and behavioral hints, and the description filling in usage and output details, there are no significant gaps for an AI agent to invoke the tool correctly.

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?

With 100% schema description coverage, the baseline is 3, but the description adds meaningful semantic context: it groups parameters (e.g., 'limit/offset: Pagination'), clarifies status enum values with descriptions like 'open', 'paid', or 'overdue', and explains the purpose of response_format. This goes beyond the schema's technical definitions, improving 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 specific action ('List invoices from QuickBooks Online') and resource ('invoices'), distinguishing it from sibling tools like qbo_create_invoice (which creates rather than lists) and qbo_list_customers/vendors (which list different resources). The verb 'List' is precise 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 provides clear context for usage through the 'with filtering options' phrase and the detailed parameter explanations, which help understand when to apply specific filters. However, it doesn't explicitly state when to use this tool versus alternatives like qbo_list_customers or qbo_profit_loss_report, 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.

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

Annotations already provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds value by specifying the return format options ('markdown' or 'json') and listing returned fields (Id, DisplayName, Email, Phone, Balance), which are not covered by annotations, enhancing 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 front-loaded with the core purpose in the first sentence, followed by structured 'Args' and 'Returns' sections. Every sentence adds value without redundancy, making it efficient and well-organized for quick comprehension.

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 annotations cover safety and idempotency, and the description adds return format and field details, it is complete for a read-only list tool. No output schema is present, but the description adequately explains returns, and the tool's complexity is low with clear parameters.

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 detailed parameter descriptions in the schema. The description adds minimal semantics beyond the schema, such as noting 'active_only' defaults to true and 'response_format' options, but does not significantly enhance understanding. 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.

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 'vendors/suppliers from QuickBooks Online', making the purpose specific. It distinguishes from siblings like qbo_list_customers and qbo_list_bills by specifying the vendor resource type, avoiding redundancy.

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 retrieving vendor lists, with context from sibling tools suggesting alternatives for other resources (e.g., qbo_list_customers for customers). However, it lacks explicit guidance on when to use this tool versus others or any exclusions, such as not using it for creating vendors.

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?

Annotations already cover safety (readOnlyHint=true, destructiveHint=false) and idempotency, but the description adds valuable context by specifying the return content structure (Income, Cost of Goods Sold, Expenses, Net Income) and output format options. It doesn't contradict annotations and enhances understanding of what the tool produces.

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 well-structured with clear sections (purpose, args, returns) and uses bullet points for readability. It's appropriately sized but includes some redundancy (e.g., restating parameter details already in schema). Every sentence adds value, though it could be more front-loaded.

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 moderate complexity, rich annotations, and full schema coverage, the description is mostly complete. It explains the report's components and output formats, compensating for the lack of output schema. However, it could better address usage context relative to sibling tools.

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?

With 100% schema description coverage, the schema fully documents all parameters. The description repeats parameter info in the 'Args' and 'Returns' sections but adds minimal extra meaning beyond what's in the schema (e.g., clarifying report components). 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.

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

The description clearly states the specific action ('Generate') and resource ('Profit & Loss (Income Statement) report'), distinguishing it from sibling tools like list operations or invoice creation. It precisely identifies the report type and its accounting context.

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 financial reporting within date ranges but provides no explicit guidance on when to use this versus alternatives like other reports or list tools. No exclusions or prerequisites are mentioned, leaving the agent to infer context from the tool name and parameters alone.

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