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

Annotations already cover readOnly, idempotent, openWorld, and non-destructive behavior. The description adds the useful behavioral detail that the tool returns 'one requested page' rather than all records, and that it supports filtering by IDs and timestamps. This goes beyond the structured annotations without contradicting them.

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, no filler. The first sentence states the core behavior and filters; the second sentence handles sibling differentiation. Every word 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?

The output schema covers return values, annotations cover safety traits, and the description supplies pagination and sibling routing. The remaining gaps are minor: exact timestamp filter semantics and default/combination behaviors are left to the schema or the agent to infer, but the tool is still actionable.

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 describes five of nine parameters in detail, and the description only groups filters generically as 'credit IDs and created or modified timestamps.' It adds some high-level meaning for the timestamp parameters, which lack schema descriptions, but does not clarify range semantics, exclusivity, or combination behavior. With 56% schema coverage, the description only partially compensates.

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 ('List') and resource ('vendor AP credits'), and immediately states pagination and filtering capabilities. It clearly differentiates itself from the two most similar siblings by naming accounting_ap_payments_list and accounting_payments_list and specifying what they handle instead.

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 explicitly states when to use this tool: 'Use this for credits on vendor accounts.' It also names the alternatives for AP disbursements and customer receipts, giving the agent clear routing logic with no need to infer.

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, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds behavioral context beyond the annotations by noting pagination ('one requested page') and the available filter dimensions (payment IDs, timestamps). This is useful and consistent, though it does not detail default page size or response shape—but those are partially covered by the schema and output 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 two sentences with no wasted words. The core purpose is front-loaded, and the alternative tool routing is efficiently packed into the second sentence. Every sentence 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?

For a read-only, paginated list tool with an output schema and detailed annotations, this description is complete enough. It states the resource type, pagination model, filterable fields, and sibling routing. An agent has everything needed to select and invoke the tool correctly without guessing.

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 56%, with five parameter descriptions present but four timestamp parameters undocumented. The description adds high-level meaning by saying the list is 'filterable by payment IDs and created or modified timestamps,' which partially compensates for the undocumented timestamp parameters. However, it does not explain the semantics of the four timestamp fields in detail or clarify sorting/pagination behavior beyond what the schema already states.

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 begins with a specific verb and resource: 'List one requested page of vendor AP payments.' It also names the exact filtering dimensions (payment IDs, created/modified timestamps), making the tool's purpose unambiguous. It even distinguishes the tool from sibling tools by explicitly contrasting accounting_ap_credits_list and accounting_payments_list, so an agent can discriminate purely from the description.

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 gives concrete usage guidance: use this for accounts-payable disbursements, and explicitly says to use accounting_ap_credits_list for vendor credits and accounting_payments_list for customer receipts. This is a clear when-to-use and when-not-to-use statement with named alternatives, which is exactly what an agent needs for routing.

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 annotations already declare the tool read-only and idempotent, so the description does not need to repeat those safe behaviors. The added note that it returns a single upstream record without pagination is genuine behavioral context that helps the agent understand response scope and avoid expecting pagination.

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 filler. The primary behavior is front-loaded, and the alternative-tool guidance is compactly appended. Every sentence carries meaningful 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?

This is a simple single-parameter get-by-ID operation with a full output schema and safety annotations. The description covers the core behavior, absence of pagination, and the relevant alternative for unknown IDs, leaving no material gap for correct invocation.

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 documents accountId as a required integer 'GL account ID', and coverage is 100%. The description adds value by clarifying that this is the ServiceTitan ID, which reinforces the external identifier semantics and connects the parameter to the tool's stated purpose.

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 ('Retrieve') with a clear resource ('a GL account by its ServiceTitan ID') and explicitly contrasts this tool with accounting_gl_accounts_list. The distinction between a direct fetch by ID and a search list is unambiguous, so an agent can tell them apart immediately.

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 states exactly when to use this tool—when the ServiceTitan ID is known—and explicitly names accounting_gl_accounts_list as the alternative when the ID is unknown. This gives the agent a clear decision rule with no inference required.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered structurally. The description adds that results are paged ('one requested page') and lists available filter dimensions, which is useful but doesn't disclose pagination behavior, defaults, or response envelope—though the output schema helps fill that 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?

Two sentences, front-loaded with the core purpose and filter summary, followed by sibling routing. No filler, and each phrase 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?

For a read-only list tool with a rich 18-parameter schema, output schema, and safety annotations, the description covers the essential context: what it lists, its filter scope, and the relevant sibling tools. It doesn't explain sort/includeTotal/date-filter details, but those are documented in the schema, so the description is nearly 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 78%, close to high, and most parameters carry detailed descriptions and enums. The description adds a helpful summary of the filter categories (IDs, names, numbers, types, subtypes, source, description, Intacct flags) but doesn't elaborate on page, pageSize, sort, or date-window semantics. The schema remains the primary source of parameter 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 opens with a specific verb and resource ('List one requested page of general-ledger accounts') and explicitly names sibling tools with different purposes: accounting_gl_accounts_get for a single known account and accounting_gl_account_types_list for account-type metadata. An agent can distinguish this tool from nearby siblings without opening the schema.

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?

It states when to use alternatives: use accounting_gl_accounts_get for one known account and accounting_gl_account_types_list to resolve account-type metadata. This gives an agent clear routing logic: for paged/filtered listing use this tool, for single-record lookup use the get variant.

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, idempotentHint, and destructiveHint false, so the safety profile is established. The description adds value beyond annotations by clarifying pagination behavior ('one requested page') and the catalog-like nature of the response, which helps set expectations for how to use the returned definitions.

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 filler. The core purpose and pagination behavior are front-loaded, and the sibling differentiation is placed second. Every word 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?

Given the rich annotations, output schema, and mostly documented input schema, the description is sufficient for an agent to select and invoke the tool. It clearly states what the tool returns and when to use the sibling. It does not enumerate all optional date/sort filters, but those are already expressed in the input schema, so the omission is minor.

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 64%, so the schema documents most parameters but not all. The description reinforces the main filter dimensions (IDs, names, active) but does not add meaning for the undocumented parameters like createdBefore, modifiedBefore, createdOnOrAfter, and modifiedOnOrAfter. The parameter names are fairly conventional, but the description does not fully compensate for the coverage gap.

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 identifies the resource ('GL account-type definitions'), the operation ('List one requested page'), and the primary filters ('type IDs, names, and active state'). It also explicitly distinguishes itself from accounting_gl_accounts_list, so an agent can tell the difference between account types and actual ledger accounts without opening either schema.

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 gives direct usage guidance: use this tool as a catalog to resolve GL account types, and use accounting_gl_accounts_list for the actual ledger accounts. This explicitly routes the agent to the correct sibling based on intent, leaving little to inference.

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 mark this as readOnly, idempotent, and non-destructive. The description adds useful behavioral context beyond annotations by clarifying that only 'one requested page' is returned and that paging/total-count controls are available, preventing assumptions about automatic pagination or a full dump.

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 padding. The primary action and key behavior are front-loaded in the first sentence, and the sibling distinction is given concisely in the second.

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 read-only list operation with an output schema, the description gives the core purpose, the paging behavior, and a clear sibling alternative. It does not explicitly explain the date-filter semantics, but the schema field names and formats cover the essentials, making the description sufficient 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.

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

Schema coverage is 50%, with paging-related parameters described in the schema. The description reinforces the paging/total-count semantics but does not elaborate on the four date filter parameters (createdBefore, modifiedBefore, createdOnOrAfter, modifiedOnOrAfter). The parameter names and date-time format are reasonably self-explanatory, so the description provides modest added value without fully compensating for the undocumented parameters.

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 states a specific action ('List one requested page of invoice custom-field definitions') and a clear resource (custom-field definitions for invoices). It also distinguishes itself from accounting_invoices_list, which retrieves invoice records and their values, so an agent can tell them apart immediately.

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 explicitly says to use this tool to resolve invoice custom-field metadata and points to accounting_invoices_list as the alternative for invoice records. This gives the agent a clear when-to-use and when-not-to-use decision without ambiguity.

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 the read-only, idempotent, non-destructive profile, so the description only needs to add behavioral context beyond that. It does so by clarifying the response grain (invoice headers), the one-page nature of the call, and the range of filtering dimensions. It does not discuss pagination defaults or sorting behavior, but the schema and output schema cover those.

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 contain the essential purpose, scope, and routing guidance with no fluff. The key verb and resource are front-loaded, and the usage caveat is placed immediately after the main definition.

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 rich input schema, output schema, and annotations, this description provides enough context for an agent to select and invoke the tool correctly. It states what the tool returns at a high level, the main usage scenario, and the main alternative paths, while the schema handles the 32-parameter details.

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 88% and each parameter already has a meaningful description, so the baseline is 3. The description adds only a high-level grouping of filter categories without explaining any individual parameter format or relationship 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 states a specific verb ('List'), a clear resource ('customer invoice headers'), and a concrete scope ('one requested page'), then enumerates the filter dimensions. It also differentiates this tool from estimates and invoice-item tools, making its purpose distinguishable from a large sibling 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?

It explicitly says to use this tool for filtered invoice search and tells the agent to use estimates or invoice-item tools when the required grain differs. This gives clear when-to-use and when-not-to-use guidance, effectively routing the agent among alternatives without requiring it to inspect many siblings.

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, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context that the result contains detail rows with line-level account and amount information, but it does not disclose operational caveats such as pagination behavior or response shape, which are partly covered by the output 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 two sentences with no wasted words. The primary purpose is front-loaded, and the differentiation from the summary tool is stated efficiently in the second sentence.

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 full parameter schema coverage, an output schema, and strong annotations, the description is complete enough for an agent to select and invoke the tool correctly. It identifies the line-level scope and names the relevant sibling, so no critical contextual information is missing.

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%: id, page, pageSize, and includeTotal each have descriptive text. The tool description does not add parameter-level semantics beyond indicating line-level detail, 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 tool retrieves journal-entry detail rows, which is a specific verb plus resource. It also explicitly contrasts itself with accounting_journal_entries_get_summary, making the distinction between line-level detail and header-level totals 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 gives explicit guidance: use this tool for line-level account and amount detail, and use accounting_journal_entries_get_summary for header-level totals. This directly tells an agent when this tool is appropriate versus the closest sibling.

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, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the summary-vs-detail output distinction, but does not disclose additional behavioral context such as pagination behavior, rate limits, or response envelope details.

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 the core retrieve action and scope stated first and the sibling alternative stated second. Every sentence earns its place and there is no fluff.

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 output schema exists, annotations are rich, and the parameter schema is fully documented, the description is complete enough for an agent to select and call the tool correctly. It clearly scopes the result level and points to the details sibling for the alternative use case.

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 coverage is 100%, so the schema fully documents id, page, pageSize, and includeTotal. The description does not add much parameter-level detail; 'requested journal-entry IDs' pluralizes the singular id field but does not conflict with it.

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 ('Retrieve') and resource ('journal-entry summary rows'), and states it operates on journal-entry IDs. It also distinguishes this tool from accounting_journal_entries_get_details by framing it as the header-level summary counterpart.

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?

It gives explicit when-to-use guidance: use this for header-level accounting totals, and use accounting_journal_entries_get_details for line-level detail rows. This directly names the alternative and the condition that selects 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds useful behavioral context beyond annotations: results are paginated ('one requested page') and header-level rather than full entries. No contradictions with annotations.

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

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

Two sentences of roughly 50 words, with the core action front-loaded and the usage routing in the second sentence. Every clause earns its place — there is no fluff, tautology, or redundant restatement of the tool name.

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 30-parameter, zero-required listing tool with an output schema and safety annotations, the description covers purpose, pagination behavior, and the follow-up workflow. Return values are covered by the output schema and parameters by the schema (87% coverage), so the only minor gap is the absence of guidance on typical filter combinations — not essential for correct invocation.

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 87%, so the 30 parameters are already well documented in the schema. The description adds a high-level grouping of filter categories (IDs, numbers, sync status, posted dates, created/modified timestamps) that maps to schema fields, but it does not add syntax, constraints, or meaning beyond what the schema provides. 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 states a specific verb and resource ('List one requested page of journal-entry headers'), names the filter dimensions (IDs, numbers, sync status, posted dates, created/modified timestamps), and explicitly notes it returns headers only. This differentiates it from the get_summary and get_details siblings without needing to open their schemas.

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 explicitly states when to use this tool ('Use this to discover entry IDs') and routes to the two relevant alternatives with their selection conditions — accounting_journal_entries_get_summary for summary rows and accounting_journal_entries_get_details for line-level rows. An agent gets a clear decision path with no inference required.

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 the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the description doesn't need to restate that. It adds a little behavioral context by emphasizing paging and total-count controls, but it does not disclose anything beyond the schema and annotations, such as rate limits or response pagination 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?

Two short, purposeful sentences. The core behavior and scope are front-loaded, and the alternative-tool routing is stated without any 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?

With an output schema present, the return shape doesn't need to be explained. The description covers what the tool lists, its use case, its pagination/total-count aspect, and the correct sibling for transactions. It is complete enough, though it leaves sort and date-filter semantics entirely to the schema.

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 50%, covering page, sort, pageSize, and includeTotal; the description adds only a high-level nod to 'paging and total-count controls.' It does not compensate for the undocumented date-filter parameters or elaborate on how sort/filter options work, so the benefit beyond the schema is modest.

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 names a specific action and resource: 'List one requested page of payment custom-field definitions.' It also clearly differentiates itself from its closest sibling by pointing to accounting_payments_list for payment transactions and field values.

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?

It explicitly states when to use this tool: 'Use this to resolve payment field metadata.' It also names the alternative and the condition that selects it: 'use accounting_payments_list for customer payment transactions and their field values.'

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 readOnly, idempotent, openWorld, and non-destructive hints, so the bar is lower. The description adds the 'one requested page' pagination behavior and the customer-payment scope, but it does not disclose any additional behavioral details such as defaults, limits, or response semantics. There is no contradiction with 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 two sentences with no filler. The core action is front-loaded, and the second sentence adds valuable sibling differentiation. Every sentence 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?

For a 23-parameter list tool, the description gives enough orientation through pagination, filter categories, and sibling routing, while the output schema and annotations cover return values and safety. It does not explicitly mention bulk-export alternatives like export_payments, but 'one requested page' already signals this is a paginated list rather than an export.

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 83%, so the input schema already documents most parameters well. The description lists filter categories but does not add meaning beyond what the schema provides. The date-only parameters without descriptions, such as createdBefore and modifiedBefore, are not clarified further.

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 states a specific verb ('List'), a specific resource ('customer payment transactions'), and a scope ('one requested page'). It also explicitly distinguishes this tool from accounting_ap_payments_list by clarifying that AP list handles vendor disbursements.

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 names two sibling tools and tells the agent exactly when to use them instead: accounting_payment_types_list for payment-method definitions and accounting_ap_payments_list for vendor disbursements. This provides clear routing guidance beyond simple naming.

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, idempotentHint, openWorldHint, and destructiveHint. The description adds useful behavioral detail beyond that: the return is a single upstream record with no pagination, which is not captured in the annotations or input 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?

Two concise sentences with no filler: the first states the core action and scope, the second adds behavioral context and alternative routing. Every sentence 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?

For a simple single-ID lookup, the description, combined with the output schema and annotations, provides everything an agent needs to select and invoke the tool correctly. The no-pagination and single-record notes prevent false expectations about response shape.

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 documents paymentTermId with 100% coverage. The description adds meaning by identifying it as the ServiceTitan ID and makes the lookup key explicit, which helps the agent understand the identifier's origin and role.

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 states a specific verb ('Retrieve') and resource ('payment term by its ServiceTitan ID'). It clearly distinguishes itself from accounting_payment_terms_list by noting it returns the single upstream record without pagination.

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 explicitly routes agents to accounting_payment_terms_list when the ID is unknown. This establishes a clear when-to-use versus when-to-use-alternative boundary.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context about pagination ('one requested page') and filtering by IDs and timestamps, which goes beyond the raw 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?

Two sentences with no filler. The core purpose and paging behavior are front-loaded, and the alternative-tool guidance is packed into a single clear sentence.

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 read-only list tool with nine optional parameters and an output schema, the description covers the main decisions: what is returned, how paging works, and which sibling to use instead. It does not mention sort or includeTotal, but those are documented in the schema, so nothing critical is missing for correct invocation.

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 56%, and the description only mentions 'IDs and created or modified timestamps' at a group level. It does not explain the semantics of the individual timestamp filters or the constraints like max 50 IDs. The description adds some orientation, but most parameter meaning still comes from the 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 action ('List'), the resource ('invoice payment-term definitions'), and the key scoping behavior ('one requested page'). It also heads off confusion with siblings by naming accounting_payment_terms_get and accounting_invoices_list as distinct alternatives.

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 gives explicit routing guidance: use accounting_payment_terms_get for a single known term and accounting_invoices_list for invoice transactions. This tells an agent exactly when to choose this tool versus its closest alternatives.

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 annotations already declare the tool read-only, idempotent, and non-destructive, so the bar for behavioral disclosure is lower. The description adds meaningful context by stating it returns a single upstream record and has no pagination, which helps the agent understand the response shape without invoking the 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 a single, tightly constructed sentence with no filler. It front-loads the core behavior, then gives the pagination note and the alternative routing in an efficient second clause.

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 single-ID get tool, the description covers the essential behavior, the absence of pagination, and the routing to the list sibling when appropriate. An output schema exists, so return value details are already available, and the annotations cover the safety and idempotency profile.

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 documents the id parameter at 100% coverage. The description adds a small but useful clarification that this is the ServiceTitan ID, tying the parameter to the upstream system context. This goes slightly beyond the schema's 'Payment type ID'.

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 ('Retrieve'), the resource ('a payment type'), and the required identifier ('by its ServiceTitan ID'). It also distinguishes itself from the sibling accounting_payment_types_list by explicitly noting this returns a single record without pagination.

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 explicitly names the alternative tool (accounting_payment_types_list) and tells the agent when to use it: when the ID is unknown. This provides a clear decision rule for choosing between the get and list variants.

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 communicate the read-only, idempotent, non-destructive nature of the operation. The description adds some context by framing it as a paginated catalog of definitions rather than transactions, but it does not add substantial behavioral details beyond what annotations and the output schema already provide.

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 filler. The primary purpose is stated first, and the crucial sibling distinction is delivered efficiently in the second sentence.

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 combination of complete schema documentation, annotations, and output schema covers what an agent needs to call the tool correctly. The description's catalog/transactions distinction completes the contextual picture.

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 seven parameters. The description only lists the filter dimensions ('IDs, active state, and creation timestamps') without adding format, default, or constraint details, so it adds minimal value beyond the 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 specifies a clear verb and resource: 'List one requested page of customer payment-type definitions.' It explicitly contrasts with accounting_payments_list, which covers actual transactions, so an agent can distinguish this catalog tool from the closely named sibling.

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 when to use this tool ('Use this catalog to interpret or select payment methods') and explicitly directs the agent to accounting_payments_list when actual customer payment transactions are needed. This provides clear routing guidance among related tools.

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 read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral context: results are paginated by page, the data is definitional/catalog-like, and invoice transactions and tax totals are outside its scope. No contradiction with annotations exists.

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 filler. The main action is front-loaded, filter capabilities are summarized in one clause, and the essential scope exclusion is stated at the end. Every sentence contributes 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?

Given the output schema, annotations, and a 10-parameter input schema, the description provides adequate context: it states the resource type, pagination model, filter dimensions, and what the tool is not for. It could be slightly more complete by naming an alternative source for invoice transactions or tax totals, but nothing critical is missing for invoking 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?

Schema descriptions cover six parameters, but the four timestamp parameters lack descriptions, leaving 60% coverage. The description partially compensates by grouping them as 'created or modified timestamps' and clarifying they are filters. It does not describe every parameter, but the schema already handles the pagination and sorting details.

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 opens with a specific verb and resource: 'List one requested page of tax-zone definitions.' It further clarifies the tool's role as a catalog for resolving tax treatment identifiers and explicitly distinguishes it from invoice transactions or calculated tax totals, making its purpose unmistakable.

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 gives a clear positive use case ('Use this catalog to resolve tax treatment identifiers') and an explicit negative boundary ('does not return invoice transactions or calculated tax totals'). It does not name a specific sibling tool for those alternatives, but the exclusions still guide selection well.

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 annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds minimal behavioral context beyond the core retrieval action and the included fields, but does not disclose additional traits such as error behavior or response edge cases. With annotations covering the main behavioral concerns, a 3 is appropriate.

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

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

Two short sentences with no filler. The main retrieval behavior is front-loaded, and the alternative usage guidance is placed in the second sentence without 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?

This is a simple single-ID GET-style tool. The output schema is present, the annotations cover safety and idempotency, and the description explains what the tool returns and how to choose between this tool and the sibling list tool. Nothing important is missing for an agent to invoke it 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?

The schema already describes the only parameter ('id' as Booking provider tag ID) with 100% coverage, so the description does not need to add much. It reinforces that the ID identifies a single record to retrieve, but offers no new format, constraints, or usage details.

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 states a specific verb ('Retrieve'), a specific resource ('one booking-provider tag record by ID'), and the relevant fields (name and description). It also differentiates from the sibling list tool by explicitly naming crm_booking_provider_tags_list as the alternative for broader searches.

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 explicitly tells the agent when to use the alternative: use crm_booking_provider_tags_list to search by name, multiple IDs, or change dates. This makes the decision boundary between the get and list tools clear.

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, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds useful behavioral context beyond the annotations: it returns one page and supports searching by several filter dimensions. No contradiction exists between description and annotations.

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

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

Two sentences contain no filler and front-load the key search behavior and pagination note. The alternative tool is explicitly named rather than described vaguely.

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 output schema, annotations, and self-descriptive parameter names, the description is largely complete for selecting and invoking the tool. It covers primary search modes, pagination, and the main alternative. A minor gap is not stating whether filters can be combined or that no filters are required, but this is inferable from the optional schema 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 60%, with four date-range parameters lacking descriptions. The description helps by grouping filters into 'name, IDs, or created and modified ranges,' but it does not clarify the boundary semantics of createdBefore/createdOnOrAfter/modifiedBefore/modifiedOnOrAfter. Overall the parameter names and schema descriptions carry most of the meaning, with only moderate added value from the description.

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 states a specific verb and resource: 'Search booking-provider tag definitions' by name, IDs, or created/modified ranges. It also clearly differentiates the tool from crm_booking_provider_tags_get by noting that the get variant should be used when the tag ID is already known.

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 explicitly names the alternative tool and the condition for choosing it: use crm_booking_provider_tags_get when the tag ID is already known. The 'Returns one page' note also signals that pagination is needed for larger result sets.

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, idempotentHint, openWorldHint, and destructiveHint, covering the safety profile. The description adds pagination semantics ('one page', 'continue through results'), but it does not disclose other behavioral details such as default paging behavior or the effect of includeTotal beyond what the schema already states.

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

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

Two sentences with no filler: the first states the action and scope, the second gives the two essential pieces of invocation guidance. Information is front-loaded and every clause contributes.

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 read-only paginated list with a rich output schema and strong annotations, the description is nearly complete. The main gap is the lack of explicit distinction from the similar crm_bookings_provider_contacts_list sibling, which an agent might confuse 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%, so the schema already documents all four parameters. The description adds value by explaining that the booking ID is the required anchor and that page/pageSize drive result continuation, which clarifies their role beyond the raw schema descriptions.

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 'contacts attached to a tenant booking', making the core purpose plain. It does not explicitly contrast with the closely named sibling crm_bookings_provider_contacts_list, so it stops short of full sibling differentiation.

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 tells the agent to supply the booking ID and to use page/pageSize for pagination, which is actionable context. It does not explicitly discuss when to choose this tool over sibling contact-list tools, so exclusion guidance is missing.

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, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered by structured data. The description adds tenant-scoping context but discloses no additional behavioral traits such as error behavior, pagination, or special return conditions. With annotations present, this is adequate but not exceptional.

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 wasted words: the primary action and lookup key are front-loaded, followed by clear routing to alternatives. Every clause 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?

For a simple single-parameter read tool, the definition is complete: it states what the tool retrieves, by which key, when to use alternatives, and the annotations plus output schema handle safety and return structure. Nothing essential is missing.

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 the single parameter completely: 'id' is documented as an integer Booking ID, and schema description coverage is 100%. The description does not add further parameter-level detail, but none is necessary 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 uses a specific verb ('Retrieve') with a specific resource ('one tenant booking record') and the lookup key ('by booking ID'). It clearly differentiates from sibling tools by naming crm_bookings_list for search and the provider-scoped get for route-level access.

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?

Explicit when-to-use guidance is provided: use this tool when the booking ID is known, use crm_bookings_list when the ID is unknown, and use the provider-scoped get when provider must be part of the route. This removes ambiguity for an agent choosing among similar tools.

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, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered. The description adds the real behavioral detail 'Returns one page', which is not visible in annotations and alerts the agent that results are paginated.

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 filler: the first states what the tool searches, the second states the pagination behavior and the key alternative. Every clause adds information an agent needs.

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 paginated search/list tool with rich annotations and an output schema, the description covers the core behavior and the main sibling decision (get vs list). It does not mention other potentially relevant alternatives such as export_bookings, but the schema and annotations fill enough context for correct invocation.

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 60%, with the four date-time parameters lacking descriptions; the description's 'created and modified ranges' fills in that gap by grouping them into meaningful filter dimensions. The schema already documents page/pageSize/sort/externalId/includeTotal, and the description's enumeration of search keys adds semantic grouping without repeating the 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 opens with a specific verb and resource: 'Search tenant bookings'. It then enumerates the precise search dimensions (IDs, external ID, created/modified ranges), and explicitly distinguishes itself from crm_bookings_get, so an agent can tell when to use which without opening the schema.

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?

It gives explicit routing guidance: 'use crm_bookings_get for a known booking ID', which is a clear when-not condition. The phrase 'Returns one page' also signals this is a paginated list operation rather than a bulk export, and the filter list defines the primary use case.

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 convey read-only, idempotent, non-destructive behavior. The description adds the key behavioral detail that it lists only one page at a time, and it emphasizes that both provider and booking IDs are required, which is important for correct invocation.

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 tight sentences: the first states the action and resource, the second states the prerequisite. No filler or repetition of schema details; every sentence 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?

For a simple paginated list with full schema coverage, a read-only annotation set, and an output schema, the description is complete. An agent has enough information to select and invoke the tool 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 description coverage is 100%, so the schema already documents all parameters including page, pageSize, and includeTotal. The description reinforces the two required identifiers but does not add new meaning beyond the schema, matching 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 a specific verb ('List'), a precise resource ('contacts for a booking within a specified booking provider'), and states the required scope. This clearly distinguishes it from the sibling crm_bookings_contacts_list, which lacks the provider qualifier.

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 gives clear context: use this when you need a page of contacts for a booking and you have both the booking provider and booking IDs. It does not explicitly name alternatives or state when not to use it, but the provider-scoped wording makes the intended context clear.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the scoping behavior of requiring both provider and booking IDs, but does not disclose not-found behavior or any other runtime details. This is adequate for a simple read-only getter, but not especially rich.

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 filler. The primary action and required identifiers come first, and the routing alternatives follow in a compact second sentence. Every sentence 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?

For a two-parameter, read-only getter with a rich annotation set and an output schema, the description is complete. It provides the key operation, identifies the required inputs, and points to the correct alternatives, so nothing essential is missing for correct invocation.

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 'id' and 'bookingProvider' already described as Booking ID and Booking provider ID. The description reinforces that both are needed ('using both provider and booking IDs') but does not add meaning beyond the schema, 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 uses a specific verb ('Retrieve'), names the exact resource ('one booking record from a specified booking provider'), and specifies the required identifiers (provider ID and booking ID). It clearly distinguishes itself from crm_bookings_get and the provider list route, so an agent can identify the intended 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 explicitly states when to use this tool versus alternatives: use crm_bookings_get for the tenant-wide ID route, and use the provider list when the booking ID is unknown. This gives clear routing guidance and removes ambiguity about which sibling to invoke.

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, idempotentHint, and non-destructive behavior. The description adds useful behavioral context beyond that: it returns only one page and is scoped to a single booking provider. No contradiction with annotations.

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

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

The description is one compact sentence with no filler. It front-loads the core action and resource, then immediately states the key constraint ('requires the provider ID') and the pagination behavior.

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 output schema, annotations, and schema descriptions for most parameters, the description is adequately complete. It covers the essential provider scoping, filter categories, and one-page return behavior. It could have explicitly pointed to related booking-list tools, but this is a minor gap rather than a blocking one.

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 64%, so the description adds value by grouping parameters into meaningful filter categories: IDs, external ID, and created/modified date ranges. It also clarifies the role of the required bookingProvider parameter. Some parameters like page, sort, pageSize, and includeTotal are not explained in the description, but they already have schema descriptions.

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 ('Search'), identifies the resource ('one booking provider's bookings'), and lists search dimensions (IDs, external ID, created/modified ranges). This clearly distinguishes it from siblings like crm_bookings_list, which is not provider-scoped, and crm_bookings_provider_get, which fetches provider details rather than bookings.

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 states the key precondition: 'requires the provider ID.' It also communicates the intended filtering use cases. It does not explicitly name alternatives or say when not to use this tool, but the provider-scoped context is clear enough for an agent to choose it appropriately.

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, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds the parent-child relationship context and fallback routing, but it does not disclose additional behavioral traits such as error handling, 404 behavior, or permission requirements. This is adequate but not more than the annotations plus minimal description require.

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, both purposeful and front-loaded. The core operation is stated first, and the alternative routing is provided second without any filler or repetition.

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 read-only getter with full parameter documentation, annotations covering safety, and an output schema present, the description is complete. An agent has everything needed to select and 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?

Schema description coverage is 100%, so both parameters are already documented as 'Contact ID' and 'Contact method ID'. The description reinforces that contactId is the parent and contactMethodId is the specific method, but adds no new format, constraint, or semantic detail beyond the 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 states a specific verb ('Retrieve'), a specific resource ('one contact-method record'), and the two identifying keys required (parent contact UUID and contact-method UUID). It clearly distinguishes this getter from the sibling list tool by emphasizing single-record 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 explicitly tells the agent when to use this tool versus the alternative: use crm_contact_methods_list when the method ID is unknown. This is direct routing guidance that prevents incorrect tool 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is established. The description adds useful behavioral detail beyond annotations: the operation returns one page and requires a contactId, and it enumerates the filter categories. This goes beyond purely restating schema or annotation data.

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 with no filler. The purpose is front-loaded, followed by the key invocation constraint (requires contactId) and the pagination behavior. Every clause carries operational meaning.

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 12-parameter filtered list tool with an output schema and read-only annotations, the description covers the core decision factors: resource scope, filter types, required parameter, and return pagination. It does not detail sort behavior or named alternatives, but those gaps are relatively minor given the schema and sibling 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 67%, so the schema covers most parameters, but the description adds meaning by grouping the filter parameters into 'reference, type, value, or date filters' and explicitly clarifies that contactId is required and scopes the search to one contact. It also gives semantic context to otherwise bare date-time parameters.

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 states a specific action ('Search') and a clear resource boundary: one contact's phone, email, or other contact methods. It also lists the filter dimensions (reference, type, value, date) and explicitly notes the one-page return and required contactId, which distinguishes it from broader contact list and single-contact-get siblings.

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 'one contact's' combined with 'requires contactId' gives clear context for when to use this tool: when contact methods for a specific contact are needed. It does not explicitly name alternatives or exclusion criteria, but it provides enough directional context to avoid confusion with contact list/get siblings.

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 read-only, idempotent, and non-destructive behavior. The description adds useful behavior beyond those flags by clarifying the result is a single page and that filtering by related entity, type slug, type name, or creation time is supported. This helps the agent set expectations about pagination and scope.

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 efficient sentences with no filler; the core action and filters are front-loaded, and the alternative tool is mentioned at the end. Every sentence carries useful routing or scoping 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?

The description covers purpose, page semantics, optional filters, required contact context, and the inverse sibling tool. With output schema and full parameter descriptions available, nothing essential to correctly invoke this tool is missing.

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%, so the schema documents all 10 parameters. The description adds only a high-level grouping of filters (related entity, type slug, type name, creation time) rather than new format or syntax details, matching the baseline for fully covered schemas.

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 opens with a specific action ('List one page...') and names the exact resource ('contact-to-entity relationship records') plus the required context ('known contact UUID'). It also differentiates from the inverse sibling crm_contacts_by_relationship_list, so an agent can distinguish the tool without inspecting schemas.

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?

Explicitly states the primary use case: listing relationship records for a known contact UUID, with optional filters. It also names the alternative crm_contacts_by_relationship_list for the reverse lookup, giving clear when-to-use and when-not-to-use guidance.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations by stating that the tool 'returns one page' and by framing the search as scoped to a relationship ID, reinforcing the openWorldHint.

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 filler. The main operation and scoping are front-loaded, and the sibling alternative is placed second, giving the agent the core decision information immediately.

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 13 parameters, an output schema, and strong annotations, so the description does not need to explain return values or safety. It covers the essential usage context and points to the relevant sibling for relationship-link inspection, leaving only minor gaps such as how to obtain a valid relationshipId in the first place.

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 69%, so most parameters are already documented. The description groups filters into 'identity, archive, and date filters,' which adds some conceptual structure but no new per-parameter meaning beyond what the schema provides, especially for the undocumented date-time parameters.

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 states a specific verb ('Search'), resource ('contact records'), and required context ('known relationship ID'), and lists filter categories. It also explicitly distinguishes itself from crm_contact_relationships_list, so an agent can tell the two sibling tools apart without opening schemas.

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?

It clearly says to use this tool when searching contacts by relationship ID, and explicitly directs agents to crm_contact_relationships_list when the goal is to inspect links owned by one known contact. This is an explicit when/alternative distinction.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds minimal behavioral context beyond 'Retrieve' and the mention of stored identity fields, but it does not contradict or meaningfully extend 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?

Two concise sentences with no filler. The primary action is stated first, and the sibling differentiation is included in the second sentence 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?

This is a simple single-parameter read tool with full schema coverage, a robust annotation set, and an output schema. The description covers the essential usage distinction, and nothing critical is missing for an agent to invoke it 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?

Schema description coverage is 100%, with the single 'id' parameter clearly documented as a UUID. The description reinforces 'by UUID' but adds no new meaning beyond the schema, 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 states a specific action ('Retrieve'), a specific resource ('one CRM contact record by UUID'), and explicitly distinguishes itself from crm_contacts_list. This makes the tool's purpose unmistakable and clearly differentiated from its siblings.

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 explicitly names the alternative tool, crm_contacts_list, and specifies the search criteria that should trigger using it instead. This gives an agent clear when-to-use and when-not-to-use guidance.

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 read-only, non-destructive, idempotent, and open-world behavior, lowering the burden on the description. The description adds useful pagination behavior ('Returns one page') but does not disclose additional behaviors like default page size or how filters combine; these are partially covered by 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?

Two sentences with no filler: the first sentence lists searchable dimensions, the second gives the one-page behavior and the UUID routing hint. Every clause earns its place and the most decision-relevant information is 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 output schema, annotations, and self-describing parameter names, the description is nearly sufficient. It clearly communicates scope and the main alternative, though it does not differentiate among the many other CRM contact/list siblings like crm_contacts_by_relationship_list or crm_customers_contacts_list.

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 67%, so the description is not the primary source for parameter meaning. It helps by grouping filters into categories (name, title, reference ID, archive status, date ranges) and gives semantic context to the undocumented date-time parameters, but it does not map them to specific parameter names or describe pagination/sorting controls beyond what the schema already states.

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?

States a specific action ('Search CRM contacts') and enumerates the available filters: name, title, reference ID, archive status, and date ranges. The second sentence distinguishes it from crm_contacts_get, so an agent can immediately tell list/search behavior from single-record 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?

Explicitly tells the agent to use crm_contacts_get when a known UUID is available, which is a clear routing rule. 'Returns one page' also implies this is not a bulk-export tool, though other sibling contacts-list variants are not explicitly contrasted.

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, idempotentHint, and destructiveHint, covering the safety profile. The description adds meaningful behavioral context by specifying that only one page is returned and that results are scoped to a single customer, which is beyond what annotations or schema alone communicate. It does not contradict any annotation.

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 wasted words. The primary purpose is front-loaded, and the alternative tool reference is included succinctly in the second sentence. Every word 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?

For a simple paginated list endpoint, the description fully covers what an agent needs to know: the resource scope, pagination behavior, and the routing decision between this and the sibling tool. With an output schema present and annotations covering safety traits, nothing essential is missing.

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 all four parameters having clear descriptions (id, page, pageSize, includeTotal). The description's 'one page' phrase lightly reinforces pagination but adds no significant meaning beyond the schema. Per the baseline rule, a 3 is appropriate when the schema already documents parameters thoroughly.

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 states a specific verb ('List'), a specific resource ('contacts attached to a known customer'), and explicitly differentiates from the sibling tool 'crm_customers_contacts_modified_list'. It clearly indicates pagination with 'one page', making the tool's scope immediately understandable.

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 tells the agent when to use this tool: to list a page of contacts for a known customer. It also explicitly names the alternative for cross-customer incremental queries, giving a clear exclusion condition. This is direct, actionable guidance with no ambiguity.

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, idempotentHint, openWorldHint, and non-destructive behavior, so the description carries less safety burden. It adds useful behavioral context beyond annotations by stating the tool 'Returns one page' and that filtering is based on created or modified time ranges.

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 filler. The first sentence front-loads the purpose and filter scope, and the second handles pagination and sibling routing. Every clause 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?

For a read-only, paginated search tool with annotations, an output schema, and multiple sibling tools, the description is largely complete: it covers scope, time filters, pagination behavior, and the key alternative. The main gap is that it does not explicitly state whether customerIds is required or what happens when omitted, which matters given openWorldHint.

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 50%, with good descriptions for page, pageSize, customerIds, and includeTotal, but no descriptions for the four date parameters. The description provides the umbrella concept of 'created or modified time ranges' and 'specified customers', which helps map parameters to intent, but it does not detail per-parameter semantics like the difference between Before and OnOrAfter or combination constraints.

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 opens with a specific verb ('Search') and names the exact resource ('contact records'), with scope ('across specified customers') and key filters ('created or modified time ranges'). It also explicitly distinguishes the closest sibling, crm_customers_contacts_list, by stating that sibling is for all contacts of one known customer.

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 an explicit alternative and the condition that selects it: use crm_customers_contacts_list for all contacts of one known customer. This implies the current tool is for cross-customer, time-filtered contact searches, leaving minimal ambiguity about when to choose 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive behavior, so the safety profile is covered. The description adds value by stating pagination ('one page') and available date filters, but it does not disclose deeper behavioral details such as default ordering, total-count behavior, or any server-side limits. No contradiction with annotations.

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

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

Two concise sentences with no filler. The first sentence states the action, scope, and filters; the second clarifies the return type by excluding a common misunderstanding. Both sentences earn their 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?

For a read-only list tool with a rich output schema, annotations, and per-parameter schema descriptions for most fields, the description covers the essential selection context: what is listed, the filters, and what the response is not. Minor gaps remain around parameter nuances, but these are mostly available in the schema, so the description is adequately 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 50%, with the four date parameters lacking descriptions. The description partially compensates by mentioning 'created and modified date filters' and 'one page,' which maps to pagination and the date parameters. However, it does not explain sort semantics, inclusive/exclusive date behavior, or the meaning of includeTotal, leaving some burden unmet.

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 states a specific action ('List one page of custom-field type definitions') and a clear resource scope ('available to customers'). It also distinguishes the tool from customer-value retrieval by noting it returns metadata, not values. However, it does not explicitly differentiate from the many sibling custom-field-type list tools (e.g., locations, jobs, invoices), though the tool name partially covers this.

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: to list custom-field type definitions rather than a specific customer's field values. The clarification 'not values for one customer' is a useful exclusion, but there is no explicit guidance about alternatives or when one list variant should be preferred over another.

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, idempotentHint, and non-destructive behavior, so the description only needs to add extra context. The phrase 'including the customer data returned by ServiceTitan' informs the agent that the response contains the raw ServiceTitan customer payload, which is useful behavioral context beyond the annotations. It does not specify not-found behavior, but the simplicity of the tool and presence of an output schema reduce that 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?

Two tightly written sentences accomplish everything: the first states the exact purpose and scope, the second directs to the correct sibling for broader searches. There is no repetition or filler, and the key information is 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?

For a single-parameter read tool with full annotation coverage and an output schema, the description is complete. It explains the tool's scope, points to the alternative for search scenarios, and relies on structured metadata for safety and return-type information. An agent has enough information to invoke this tool correctly without further clarification.

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 fully documents the single 'id' parameter with 100% coverage, so the description need not repeat parameter details. The phrase 'by ID' adds no new semantic information beyond the schema. A baseline score of 3 is appropriate when the schema carries the parameter documentation 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 uses a specific verb ('Retrieve') and resource ('one customer record by ID'), clearly stating what the tool does. It also implicitly differentiates from crm_customers_list, which is framed as the search-by-attributes alternative, making the tool's unique role clear.

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 explicitly directs the agent to crm_customers_list for searching by name, address, phone, external data, activity, or date ranges, establishing exactly when to use the alternative. It implies that crm_customers_get is for direct ID-based lookup, providing clear selection criteria.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by noting pagination ('Returns one page') and the distinction from a direct get, but it does not disclose other behavior such as defaults or response structure, which is partly covered by the output 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?

Two short sentences, front-loaded with the tool's purpose and followed by direct routing guidance. Every clause earns its place; no filler or 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?

For a 24-parameter search tool with an output schema and strong annotations, the description gives enough orientation: it summarizes searchable dimensions, clarifies pagination, and points to the right sibling for known IDs. It does not mention sorting or defaults, but those are already specified in the input schema.

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 83%, so the schema already documents most parameters. The description adds a useful high-level grouping of filter categories, especially covering the otherwise undocumented date-range parameters as 'created and modified ranges,' but it does not deepen individual parameter semantics beyond the 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 states the specific verb 'Search customers' and enumerates the key search dimensions (IDs, name, address, phone, coordinates, external data, activity, created/modified ranges). It also distinguishes itself from crm_customers_get by noting this tool returns a page and should be used for search rather than known-ID lookup.

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 explicitly says 'Returns one page' and tells the agent to use crm_customers_get for a known ID, which is clear routing guidance. It does not mention bulk-export alternatives like export_customers, but the one-page statement plus sibling context is enough for most selection decisions.

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 establish read-only, idempotent, non-destructive behavior. The description adds operational context beyond that: results are paginated ('one page') and can be filtered by created/modified timestamps, plus the hard precondition of a customer ID. No contradictions with annotations.

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

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

Two short sentences with no filler. The core action and scope are front-loaded, followed by the optional filters and the prerequisite. Every clause contributes useful 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?

With an output schema present, return-value documentation is not needed. The description covers the essential calling context: pagination, timestamp filtering, and the required customer ID. Minor gaps such as default page size and exact filter parameter names are already present in the input schema, so nothing critical is missing.

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 only 50%, leaving the four timestamp parameters undocumented. The description partially compensates by explaining they filter by 'created or modified timestamps' and that the ID is required, but it does not elaborate on before/on-or-after semantics or pagination defaults beyond what the schema already names.

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 names a specific verb ('List'), a specific resource ('notes attached to a known customer'), and the key scoping detail ('one page', 'Requires the customer ID'). It clearly distinguishes this from other list tools by tying it to customer notes, even among many sibling note-list tools.

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 gives a clear prerequisite ('Requires the customer ID') and implies this is for fetching a paginated set of notes for a known customer, not a broad export or a different entity's notes. It does not explicitly name alternative tools for locations/leads/jobs notes, but the customer-specific wording makes the intended context reasonably clear.

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 the read-only, idempotent, and non-destructive profile, so the description has a lower burden. It adds value by stating what the response includes ('customer and lead details') and confirming this is a single-record fetch. It does not contradict 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?

Two sentences accomplish everything: the first states the tool's exact function, and the second routes to the appropriate alternative for search scenarios. There is no redundant or filler language.

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 single-parameter getter with rich annotations and an output schema, the description is complete. It specifies the resource, the selection mechanism, the included content, and the sibling tool to use for filtered searches.

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 'id' parameter is documented in the schema as 'Lead ID.' The description confirms the lookup key is the ID but does not add meaning beyond what the schema already 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 uses a specific verb ('Retrieve') with a clear resource ('one CRM lead record by ID') and explicitly scopes the payload to 'customer and lead details.' It also distinguishes itself from crm_leads_list by pointing out that the list tool handles search scenarios.

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 explicit routing guidance: use crm_leads_list when searching by customer, status, prospect state, location fields, or date ranges, implying this tool is for fetching by ID. This clearly separates the single-record getter from the search-oriented sibling.

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 read-only, idempotent, and non-destructive behavior, so the description only needs to add extra behavioral context. It adds 'Returns one page', which tells the agent about pagination behavior beyond the schema, and the phrase 'created and modified ranges' clarifies date filtering semantics. No contradiction with annotations.

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

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

Two sentences with no redundant words: the first states searchable dimensions, the second states pagination and the known-ID alternative. The most important usage information is 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?

For a filtered read-only list endpoint, the description covers the main decision points: what it searches, that it returns one page, and when to switch to crm_leads_get. The output schema and rich parameter schema cover return and filter details, so no critical information is missing for an agent to invoke it.

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 80%, so the schema already documents most parameters. The description adds value by grouping filters semantically (customer location, prospect state, created/modified ranges), which helps an agent map intent to the less-documented date-time and location parameters. It does not delve into each parameter, but the schema covers the remaining details.

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 states a specific action ('Search CRM leads'), enumerates the key filter dimensions (IDs, customer, status, prospect state, location, date ranges), and notes it returns one page, which separates it from crm_leads_get. This clearly identifies the resource and operation without relying on the tool name alone.

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?

It explicitly gives an alternative for a known ID ('use crm_leads_get') and indicates the list is page-based, which implies pagination for large result sets. However, it does not mention when a bulk export sibling (e.g., export_leads) would be more appropriate, so the guidance is useful but not exhaustive.

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 the operation read-only, idempotent, and non-destructive, so the description does not need to restate safety. It does add useful behavioral detail beyond annotations: the tool returns only 'one page' of notes and supports optional timestamp filtering. However, it does not describe ordering, pagination behavior beyond the page concept, or any response characteristics, though an output schema exists.

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 efficient sentence that front-loads the core action and resource, then adds the filtering capability and the required lead ID. There is no repetition of schema details or annotations, and every phrase 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?

For a paginated, read-only list tool with an output schema and a required lead ID, the description covers the essential operational facts: it returns one page, it can filter by timestamps, and the lead ID is required. It does not mention how to navigate all pages or what happens if the lead ID is invalid, but those are secondary given the schema and annotations.

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 50%, with page, pageSize, includeTotal, and id already described in the schema. The description adds high-level meaning for the four timestamp parameters by saying results are 'optionally filtered by created or modified timestamps,' but it does not clarify the distinctions between the before/after parameters or their boundary semantics.

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 starts with a specific verb and resource: 'List one page of notes attached to a known lead.' It clearly identifies both the entity type (lead) and the payload type (notes), and the 'one page' phrasing distinguishes it from tools that retrieve full note histories or lead records themselves. The requirement of a lead ID further pins down its 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 gives clear context for when to use the tool: when you already have a lead ID and need notes attached to that lead. It does not explicitly name alternatives such as crm_customers_notes_list or dispatch_jobs_notes_list, but the resource-specific wording makes the intended use obvious enough.

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 read-only, idempotent, open-world, and non-destructive behavior. The description adds value by disclosing pagination ('one page'), filtering by active state or creation time, and the location-scoped nature. It leaves slight ambiguity around behavior when locationIds is omitted, but does not contradict 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?

Two concise, information-dense sentences with no filler. The core behavior is front-loaded, and the second sentence provides a clear use case without 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 full output schema, 100% parameter schema coverage, and strong annotations, the description gives sufficient orientation for a paginated read-only list. The only notable gap is the behavior when locationIds is not supplied, which openWorldHint suggests is valid but the description does not clarify.

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%, so each parameter already has its own description. The description summarizes the main filter dimensions (location IDs, active state, creation time) but adds no deeper semantics beyond what the schema provides. 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?

States a specific action ('List'), a clear resource ('labor-type assignment records'), and the key scope ('for specified location IDs'), plus pagination and optional filters. It is clearly distinct from generic CRM list tools and identifies the domain without requiring the agent to open the schema.

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 explicitly states when to use the tool: 'Use this to determine which labor types apply across known service locations.' It provides clear context for the intended use, though it does not mention alternatives or exclusion cases.

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, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds 'one page' and 'known service location' context, but the pagination behavior is already implied by the page/pageSize schema and the description does not add further behavioral detail. With annotations covering the main traits, this is adequate but not rich.

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 short sentences with no filler. The primary behavior and scope are front-loaded in the first sentence, and the alternative tool is clearly separated in the second.

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