GoodLeads

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

Beyond the readOnly/idempotent annotations, the description discloses billing rules, free-tier masking, 422 error behavior, freshness timing, zero_reasons, default exclusions, and sort order guarantees. It also warns that quote matching is never a price and that decision-maker filters should never be applied silently. 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 long, but it is organized into labeled sections and every block carries operational meaning. Some redundancy exists, such as repeating filing_kind examples and the same filter semantics in prose and grammar, but given the tool's complexity and zero schema coverage, the length is justified.

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 all 13 parameters, both row and summary return contracts, error semantics, pricing, privacy restrictions, provenance metadata, and domain-specific vocabularies. It is sufficient for an agent to call the tool correctly without any additional documentation.

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 0%, and the description fully compensates: every parameter is explained, including the shape of cap, lane values, sort field/direction syntax, page_size limits, and the filter grammar. It even defines named values like contact_relevance_tier and canonical entity_type values, which the loose schema cannot express.

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 opening line states the exact function: browse leads rows for a shape or saved list, or a summary with counts, facets, and price. It introduces the two mutually exclusive input modes and explicitly separates row retrieval from summary retrieval, making the tool's purpose 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 detailed when-to-use guidance: saved list vs inline shape, when to omit state filters, when summary is implied by lane/cap, and when to use include_existing vs default filing_kind. It also points to list_filterable_fields for field discovery and to create_checkout for the buying path, explicitly routing to sibling 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?

The description discloses that creating the link does not charge anyone, that payment only occurs when a human completes Stripe's hosted page, and that the file arrives about a minute after payment. It also explains post-payment enrichment, the ceiling charging model, replacement guarantees, and the traceability of records. These details go far beyond the sparse annotations (readOnlyHint=false, idempotent=false, destructive=false) and set accurate expectations for a state-changing commerce 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 over 800 words and repeats the same charging and delivery timing facts multiple times (e.g., 'Nothing is charged until a person completes checkout' appears in different wording throughout). It also includes a sample file URL and extensive pricing details that could be moved to linked documentation or the output schema. While front-loaded, many sentences do not earn their place, making it bloated rather than concise.

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 complex commerce tool with 11 parameters and no schema descriptions, this description covers every parameter, the full return field list, pricing rules, post-payment behavior, delivery options, and guarantees. It even provides a sample file URL and explains the difference from standing orders. No critical information is missing for an agent to call 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?

With 0% schema description coverage, the description fully compensates by explaining every parameter: lane's allowed values, cap's object shape and unit semantics, delivery modes and their effects, include_existing's filter behavior, offer_code and customer_email requirements, the live states list, and crm/connector parameters. It gives exact formats and example values, which is far more than the bare schema titles provide.

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 first sentence clearly states the tool converts a quoted list into a payment link the buyer completes, with the file delivered within a minute. This is a specific verb and resource, and it distinguishes the tool from quote_list, which only produces a quote. The purpose is unmistakable even without reading the rest of the long 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: pass a saved list_id or inline filters/states, specifies acceptable lane values, and explains the one-time purchase nature while noting that standing orders are set up from the paid order's receipt. It also warns about 409 responses when the quote is stale. However, it never names an alternative tool like create_checkout, so an agent must infer when to prefer this over a 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 are minimal (all false hints), so the description carries the full burden and exceeds it. It discloses that payment only happens on Stripe's hosted page, that billing base is `sellable` not `matching`, that a 409 is returned if the quote changed, that records are frozen at mint time, that delivery fires automatically, and even covers replacement/bounce policy. 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 dense and informative but noticeably long and somewhat repetitive: 'the same code as `checkout_list`' appears twice, and the return-field enumeration overlaps with the provided output schema. It is well-paragraphed and front-loaded, but it could be tightened without losing value.

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

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

For an 11-parameter tool with no schema description coverage, the description is remarkably complete. It covers pricing, quote validity, delivery timing, error behavior, standing orders, and edge cases like state omission. The output schema already exists, so the detailed return list is bonus context rather than a required gap.

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

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

With 0% schema coverage, the description must compensate and mostly does: it explains `list_id` vs inline `filters` + `states`, `lane` values, `cap` shapes, `delivery` modes, `product_id` deprecation, and CRM-related parameters. It leaves `offer_code` and `customer_email` undocumented, which is a small gap in an otherwise thorough parameter treatment.

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: 'Mint a hosted Stripe Checkout link for a list.' It immediately distinguishes itself by stating it is the 'older name' and 'the same code as `checkout_list`,' so an agent can clearly tell this tool apart from its sibling despite overlapping functionality.

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

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

The description explicitly lays out the recommended buying journey (`interpret_list` or `list_starters` → `quote_list` → `checkout_list`) and says this tool remains for compatibility. It also warns that `product_id` should not be used and names the alternative calls in the error path, 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 readOnly/idempotent safety, and the description goes well beyond them: cache-backed freshness semantics ('stale: true', 'status: computing'), the rule that paid stages are reported but unscored and do not move the headline score, unmeasured stages listed with reasons, and an explicit 'never call it again for a fresher one' instruction.

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?

Front-loaded with the core question and the dimension list, and the layout is scannable despite the length. It is verbose with bolding and long parentheticals, but nearly every clause conveys non-redundant semantics for a complex tool.

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?

Complete for a two-parameter read tool: covers input semantics, the caching/provenance behavior, the scoring rubric, and the fact that unscored coverage will not move the number. Nothing an agent needs in order to call and interpret it correctly 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 0%, so the description must carry the burden — and it does: `state` is specified as a two-letter code with omit-to-return-all (worst first), and `sample_limit` as a 0–50 range defaulting to 8. Both parameters are fully documented in prose.

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 verb and resource ('grades the records a buyer would receive') and enumerates the four dimensions it scores plus the fifth coverage dimension. An agent can distinguish it from browse_leads/quote_list siblings without opening any 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?

Explicitly frames the use case ('how clean is the data we're selling in {state}?') and ties it to tracking data-quality work, and it names where browse_filters/the pipeline trigger come into play. It stops short of stating when NOT to use it versus a sibling, so it is clear context rather than full routing 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 mark the tool read-only, idempotent, and non-destructive; the description adds useful behavioral context by specifying that the surface reads production or an explicitly opted-in local database and that it 'never silently answers from local data.' This provenance guarantee goes beyond the annotation hints, though the promised 'contract' is left vague.

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 key purpose and alternatives are front-loaded, but the middle paragraph of use-case prose is longer than needed and the third paragraph opens with the grammatically unclear fragment 'Leads with what the buyer gets and how to act on it.' Useful content is present, but it is not tightly edited.

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 zero-parameter describe tool with an output schema, the description is quite complete: it covers what the response contains, the intended audience, database provenance, the contract, available tools, and the relevant sibling workflows. The only weakness is phrasing, not missing substance.

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

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

The tool takes zero parameters and schema coverage is 100%, so the schema has nothing to document. Per the baseline for parameterless tools, the description cannot add parameter meaning; it appropriately focuses on output and behavior instead.

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 opening clause states the tool returns what GoodLeads is, who buys it, and how records are built, and explicitly says to call it 'to explain or vet us.' It also distinguishes itself from pricing siblings by directing pricing workflows to interpret_list and quote_list, so an agent can tell scope apart from 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 gives an explicit when-to-use ('call this to explain or vet us') and an explicit alternative for a closely related task ('to price a list, start with interpret_list') plus a follow-up workflow ('read the free count from quote_list'). It also instructs agents not to disqualify an owner based on this description alone, clarifying when to leave the tool.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description goes further by revealing the output shapes (`carried`, `partially_carried`, `not_carried`), per-state zero semantics, and that ambiguous terms return a clarifying question instead of a guess. 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 front-loaded with the core purpose and uses examples and structured output shapes efficiently. The final paragraph repeats the 'don't conclude absence' idea from the opening line, adding mild redundancy, but overall every sentence contributes meaningful guidance.

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

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

With no output schema and only one bare parameter, the description fully compensates: it explains the possible return shapes, what they mean, how zeros should be interpreted, and when to call the tool. Nothing required to invoke it correctly 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 schema only says `term` is a required string with no description, so the description carries the burden. It defines the parameter as 'YOUR word for a concept' and provides several concrete examples, which is sufficient to explain what to pass, though the parameter itself is never explicitly named or formatted.

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: map a user's word for a concept to the surface's fields. It gives concrete examples ('vertical', 'direct dial', 'sole proprietor') and names the three answer shapes, making the tool's role unmistakable and distinct from sibling 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?

It explicitly says to call this tool whenever a term does not obviously match a field name, and gives a strong when-not directive: never conclude data is missing without calling it first. It does not compare against specific sibling tools, so the 'alternatives' part is implied rather than named.

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

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

With annotations already marking it read-only and idempotent, the description adds substantial behavior: case-insensitive ID matching, ValueError on malformed or unmatched IDs, free history with only the person masked, newest-first ordering, and a _meta provenance block. This goes well beyond the annotation safety profile and prepares the agent for error cases and output shape.

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

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

The description is front-loaded with the one-sentence purpose and usage condition, then organized into Args and Returns sections. Although the Returns section is detailed, every clause conveys a decision-relevant behavior (ordering, masking, errors, provenance), so no sentence feels wasted.

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 lookup tool with no parameter schema description, the description is complete: it covers ID format, input source, output contents, provenance, history, access/masking, and error behavior. An agent has everything needed to decide to call it and to interpret the result.

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 sole parameter `glid` has no description in the schema (0% coverage), so the description carries the full burden. It explains the parameter means the Lead ID, gives a concrete example (`GL-CO-00042`), maps it to the `lead_ref` field on every record, and notes case-insensitivity. This fully compensates for the schema 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 opening sentence names the exact operation and resource: 'One record in full, by its Lead ID' with format. The description then specifies precisely what is returned (business, contact, scores, attributes, provenance), which distinguishes this from list/browse siblings like browse_leads. This is a specific verb+resource, not a restatement of the title.

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 it: 'Use this when you already hold a Lead ID — from a file, a CRM, a receipt — and want everything we know about that business.' It gives clear context for choosing this over browsing/searching. It does not name sibling alternatives or state a when-not condition, so it stops short of a 5.

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 include readOnlyHint, idempotentHint, and destructiveHint false, so safety is covered. The description adds critical behavioral details that annotations don't: it never answers in prose, never asks a question back, never looks a person up, and never emits predicates on masked fields (with specific field names). It also states it always returns a shape, never a 500, and describes the `answer` structure for question/objection handling.

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 comprehensive but somewhat lengthycars, with 5 paragraphs. The most critical purpose and usage are front-loaded in the first paragraphcars, and the 'Next' step is at the end. However, some details like the `answer` structure could be condensed; the level of detail is justifiable given the complexity, but it borders on being verbose. Still, every sentence serves a purpose.

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

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

Given the tool's complexity and the rich output schema, the description is thorough: it explains the return shape fields, the `answer` sub-structure, and the `alternatives` with quotes. It also covers the behavioral constraints, examples, and next steps. The presence of an output schema reduces the need to describe return values in detail, but the description goes beyond, covering edge cases like questions and ambiguous asks.

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 0%, so the description must explain parameters. It does: `text` is described as the buyer's typed words with examples; `state` is described as an optional two-letter hint; `current` is described as the existing shape to merge into. This goes beyond the schema's bare property names, giving meaning and use context. Misses minor details like where `state` comes from, but enough for an agent to understand.

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

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

The description clearly states the tool's purpose: converting a buyer's natural language request into a structured list shape. It uses specific verbs ('interpret', 'convert', 'return') and names the resource ('the buyer's own words'). It distinguishes itself from siblings by explicitly naming next steps (quote_list, checkout_list) and contrasting with other tools like browse_leads and find_lead_by_glid.

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 when-to-use guidance: 'Start here' for list requests, with multiple concrete examples of what the buyer might type. It also explains when the tool handles questions/objections, and when the tool should be used for ambiguous asks with alternatives. It also names alternatives: 'Next: hand the shape to quote_list' implies use this before those, and mentions what it never does (never asks questions, never looks up a person), clarifying when not to use 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?

The description goes far beyond the readOnly/idempotent annotations, disclosing redaction behavior for keyless callers, enforced operator sets and pseudo-field overrides, null semantics for negated operators, and the concrete 422-vs-500 error contract. It also reveals the response structure, including canonical fields and raw_variant relationships. This is unusually rich behavioral disclosure.

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 long, but it is a grammar contract, so the length is justified and well-organized with bolded section labels. The front-loaded summary tells the agent what the tool is and when to call it before diving into the detailed argument spec. Every sentence adds necessary reference information rather than padding.

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 tool with no output schema, the description completely documents the return shapes, the grammar, the operator rows, pseudo-field overrides, sorting behavior, and error semantics. It also ties the tool to the recipe bank and UI behavior, leaving no obvious gap an agent would need to probe at runtime. This is fully adequate for safe 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 has only one optional parameter with 0% schema coverage, so the description carries the full burden. It defines the three allowed section values ('fields', 'grammar', 'recipes'), states the default, and explains in detail what payload each section returns. An agent can confidently choose a section without any ambiguity.

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 and resource: it lists the filterable fields, grammar, or recipes from the schema endpoint. It is immediately distinguishable from data tools like browse_leads and create_checkout, and even tells the agent to call it before building browse_leads filters. This is a precise, unambiguous definition.

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 when to use it: 'Call this before building browse_leads filters you haven't used before.' It also notes the same payload backs the Browse UI and that listed fields work across browse, summary, export, checkout, and pipeline scoping. It does not spell out explicit when-not-to-use scenarios, but the guidance is clear enough for model 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 indicate read-only, idempotent, non-destructive behavior. The description adds meaningful behavioral detail: data is read live from production, never cached, and the result is codes only with no counts. This goes beyond what annotations 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?

Every sentence earns its place: what it returns, when to call it, the exact output shape, and what to use instead for counts. The core message is front-loaded and there is no 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?

Despite having no output schema, the description gives the exact return format. It also tells the agent how to interpret the list and how to get count data elsewhere. Nothing needed for correct invocation 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 tool has zero parameters, so there is no parameter semantics to elaborate. The description compensates by documenting the return shape exactly, which is the only operational detail an agent needs.

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 exactly what the tool does: returns live state codes from production, never from cache. Differentiates from siblings by emphasizing it is the authoritative source for currently-live states and pointing to quote_list/browse_leads for counts.

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 when to call it — before promising a buyer a state — and gives a clear decision rule: a state not in the list is not live yet. It also names alternatives for count-related needs, so usage context is fully specified.

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?

Beyond the read-only/idempotent annotations, the description discloses live counts, absence of product_id, the pricing rule, one-time vs standing order billing, sellable-record billing, and record freezing when a link is minted. This is rich behavioral context that materially helps an agent understand what the tool and its outputs mean.

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

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

The description is front-loaded with the core definition and uses line breaks to structure topics, but it is long and somewhat repetitive, e.g. 'The shelf is the starter lists' restates the opening and the pricing/billing details could be trimmed. Most sentences earn their place, but the overall length is heavier than necessary.

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 the return shape, the meaning of each count, pricing, billing behavior, freezing, and the recommended preview path, so an agent can use the tool and its output effectively. The only notable gap is the unresolved relationship with list_starters, which prevents a perfect score.

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

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

The tool has zero parameters and the schema coverage is trivially 100%, so there is nothing to document. Per the baseline for no-parameter tools, a 4 is appropriate; the description even explains how the output's filters become parameters for quote_list and checkout_list.

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 as the shelf of ready-made business type × state lists with live counts, and states that it returns the same document as list_starters. However, it does not differentiate list_products from list_starters; it explicitly equates them, so an agent is left unsure which sibling to prefer.

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 useful downstream context: pass filters to quote_list for pricing, use checkout_list for payment, and preview with browse_leads. But it never says when to call list_products versus list_starters, and there is no explicit when-not or alternative-selection guidance for this tool itself.

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?

Beyond the annotations (readOnlyHint, idempotentHint), the description discloses additional behavioral traits: it returns a single document with a specific structure, the price is a floor not a flat price, and counts are cached server-side for a few hours from live inventory, explicitly avoiding stale marketing-page data. This adds significant transparency beyond the structured 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 front-loaded with the core purpose, then provides a compact yet detailed breakdown of the return format, field semantics, usage guidance, and caching behavior. Each sentence carries essential information; there is no fluff or redundancy. The structure is logical: what, return shape, field explanations, usage, and freshness.

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 tool with no input parameters and a rich output, the description is exceptionally complete. It covers the exact return structure, field meanings (including the nuance of price_from_cents), how to use it in a buyer journey, and even notes about data freshness. The presence of an output schema (mentioned in signals) is further complemented by the inline return example. Nothing an agent needs to call this correctly 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 tool has zero input parameters, so the baseline is 4. The description does not need to explain parameters, and it correctly focuses on the output structure. Since there are no parameters, the description cannot add value here, but it also does not miss anything.

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

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

The description clearly states the tool's purpose: it returns ready-made lists for every live state × business type, with live counts and a starting price. It differentiates itself from siblings by explicitly contrasting with quote_list (full price ladder) and interpret_list (narrowing). The verb 'list' and resource 'starters' are specific, and the scope is unambiguous.

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

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

The description provides explicit usage context: 'Show these to a buyer who has not said what they want yet, then narrow with interpret_list or your own filters and price the result with quote_list.' This tells the agent exactly when to use this tool and how it fits into a workflow, including an alternative (interpret_list for narrowing) and a follow-up (quote_list for pricing).

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 read-only, idempotent, and non-destructive; the description adds substantial behavioral context beyond that: quote_valid_until and next-morning refresh, forecast provenance and ceiling_cents, offer code ceiling behavior, zero_reasons semantics, and the 422 for keyless callers filtering on certain fields. 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?

The description is long, but it is organized with clear sections (billing discipline, lanes, cap, offer codes, Args, Returns) and front-loaded with the core purpose. Some prose is verbose — e.g., the repeated guidance and sales-style close — but the tool is genuinely complex enough to warrant most of the detail.

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

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

For a billing-aware quote tool with 8 parameters and a rich output contract, the description covers how quotes are computed, what is billable, how prices are calculated, lane/cap mechanics, offer code handling, a sample file, and the handoff to checkout_list. An agent has enough to call this correctly without needing the output 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 0%, so the description fully carries parameter meaning. The Args block explains every parameter: list_id's mutual exclusivity, states' live-state default, filters referencing list_filterable_fields, include_held and include_existing semantics, lane values, cap shape, and offer_code behavior. This goes well beyond the bare 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 first line — 'What this list costs before anyone pays' — names a specific verb and resource (quoting a list) and the description consistently explains it computes price by grade. It also separates itself from its sibling checkout_list by noting the next step is to 'hand the same list / shape, lane and cap to checkout_list' when actually buying.

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 quote_list vs checkout_list, how to pass a saved list vs an inline shape, when to include or omit states, how lanes and caps select the quote, and when to pass offer_code. It also warns to 'quote the server's numbers, never arithmetic of your own' and to relay zero_reasons instead of a silent $0.

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