GoodLeads

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the bar is higher, but the description adds substantial behavioral context: only sellable records are billed or delivered, keyless callers see masked contacts, zero_reasons appear for impossible filters, and records appear the morning after state publication. It also discloses 422-versus-500 behavior, canonical vocabulary handling, and access-level differences, all 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?

Although long, the description is dense and efficiently structured with clear sections: core contract, canonical vocabulary, filter grammar, worked example, args, and returns. Every block earns its place by addressing a real decision an agent must make; there is no filler or restatement of schema fields.

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 12 parameters, 0% schema description coverage, and no actual schema descriptions, the description is exceptionally complete. It covers selection modes, summary contract fields, billing rules, filter operators by type, pseudo-fields, sorting semantics, response structure, access-level masking, freshness metadata, and error behavior. Nothing an agent needs to call this tool correctly appears 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 0%, so the description carries the full burden for 12 parameters. The Args section explains each parameter's semantics, including mutual exclusivity of list_id with state/states/filters, page_size caps by tier, sort field ordering rules, lane meanings, cap shape, and summary implication. It even documents edge cases like unknown field/direction returning a 422 and the total-order tiebreak on lead_ref ASC.

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: 'Browse leads — rows for a shape or a saved list, or (summary=True) its counts, facets and price.' It clearly distinguishes the row contract from the summary contract and signals that this is the lead-browsing entry point, not checkout or field discovery. It is far more than a restatement of the title and stands apart from siblings like find_lead_by_glid and create_checkout.

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 provides two alternative ways to select records ('a saved list' vs 'an inline shape'), when to use summary, and when to pass lane/cap. It names related tools where relevant: 'Use list_filterable_fields to discover the 77 fields' and 'To buy, hand the same list / shape, lane and cap to create_checkout.' It also gives exclusions and defaults, such as omitting both state and states for every live state.

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), so the description carries the full burden, and it does so richly. It discloses the critical behavior that no charge happens until a human completes checkout, that payment is via Stripe hosted page, that the file arrives about a minute after payment, and that after-payment enrichment may cause additional billing under a ceiling. It also explains the billing base ('sellable' not 'matching') and the 30-day replacement guarantee. This goes far beyond the annotation fields.

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 very long (over 800 words) and packs in a lot of detail. It is well-structured with clear paragraphs for pricing, delivery, and return fields, and it front-loads the primary purpose. However, its length may overwhelm an agent when parsing quickly, and some details (e.g., the exact sample-link URL) could be moved to an out-of-band reference. It is not concise, though it is efficient in that every sentence adds 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 everything an agent needs to invoke the tool correctly: how to define the list, what parameters to use, what the return structure is, edge cases like 409 conflicts and 30-day guarantees, and even a sample file link for preview. The output schema exists and the description enumerates the fields returned. No important behavioral or operational context 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 description maps most parameters to their meaning: list_id, filters+states, lane, cap, delivery, crm_connection_id, connector_crm_name. It even explains the cap format and the pricing rule. However, it does not explicitly explain the customer_email parameter, which appears in the schema but is absent from the description. Given schema coverage is 0%, the description compensates well for the other eight parameters but leaves one 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 opens with a specific verb and resource: 'Turn a quoted list into a payment link a person completes.' It clearly states the tool creates a one-time checkout link, and contrasts with a standing order on the same list. It also situates itself relative to quote_list by saying the list is quoted through the same summary path. This fully distinguishes it 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?

Explicit when-to-use guidance is given: 'this tool sells the one-time purchase' and how to set up standing orders later via the receipt. It explains two ways to pass the list (list_id or inline filters+states), how to pick a lane, and what happens if the price changes (409 with fresh quote). It also tells the agent how to handle the URL: 'Hand the URL to your human; do not represent the purchase as complete until they confirm payment.' This is actionable and complete.

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 only say readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description adds substantial behavioral detail: creating the link charges nobody, payment happens only on human completion, stale quotes return 409, billing base is `sellable` not `matching`, selected records are frozen, delivery fires automatically on payment, and invalid contact data is replaced within 30 days. This goes far beyond the annotations and gives an agent trustworthy expectations.

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 the critical no-charge caveat, then organized into clear sections for the two buyable paths, delivery, and return fields. It is verbose and repeats return-value details that the output schema likely already provides, but the structure keeps the extra length navigable. A tighter version could trim the return-field enumeration without loss.

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 10 optional parameters, no required fields, and sparse annotations, the description covers pricing rules, quote validity, 409 conflict behavior, delivery modes, billing basis, post-payment delivery timing, and replacement guarantees. The only notable gaps are customer_email and the `period` schema mismatch, but the overall context is sufficient for an agent to invoke the tool correctly and anticipate outcomes.

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 carries the burden of explaining parameters, and it largely succeeds: it maps product_id to shelf products, list_id and inline filters/states to list purchases, lane and cap to quote shaping, and delivery/crm_connection_id/connector_crm_name to delivery behavior. However, it omits customer_email entirely and references a `period` option that does not appear in the input schema, which creates minor ambiguity. Despite that, it compensates impressively for the sparse 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 sentence names an exact operation and resource: "Mint a hosted Stripe Checkout link — for a shelf product, or for a list you shaped." It also differentiates from the sibling checkout_list by explaining that the list path uses the same code and remains for compatibility. The two purchase modes are explicitly laid out, so an agent knows exactly what the tool offers.

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 clearly says when to prefer the dedicated journey: "For new work, prefer the dedicated buying journey: interpret_list → quote_list → checkout_list." It then states when to use this tool instead: shelf products, or list compatibility. This is explicit routing guidance with named alternatives, not merely implied context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description is fully consistent with these. It adds substantial behavioral detail: coverage deliberately does not affect the headline score, paid enrichment stages are reported but unscored, unmeasured stages are listed with reasons, and check results include browse_filters for surgical repair runs. This goes well 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?

The description is long but earns its length given the tool's subtle coverage semantics and non-obvious behavior around paid vs free stages. It front-loads the core purpose, then organizes details into Args and Returns sections. It could be tightened with bullets, but every sentence carries meaningful operational information.

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

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

For a tool with only two parameters and an output schema, the description is complete. It explains the return shapes for single-state vs all-states calls, the _meta provenance block, per-check sample offenders, browse_filters usage, and the reasoning behind coverage not moving the score. An agent has everything needed to invoke the tool correctly and interpret its results.

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 carries the full burden. It fully documents both parameters: state is a two-letter code with the omit-to-get-all behavior, explicit performance implications, and default behavior (worst score first); sample_limit is given with its range (0–50) and default (8). This is excellent compensation for 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 description clearly identifies the tool's job: grading data quality for a state with a 0–100 score and per-dimension breakdown. It names the specific resource (records a buyer would receive) and the verb ('grades'), and provides the intended question it answers. However, it does not explicitly differentiate itself from siblings like browse_leads or list_filterable_fields, though the unique purpose is largely self-evident.

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 practical usage guidance: use it to answer 'how clean is the data we're selling in {state}?' and to track quality work. It also clearly instructs when to pass a state versus omit it, including performance tradeoffs (~800k records/40s vs seconds). It does not explicitly mention when not to use this tool or name alternative tools, but the context is clear enough for an agent to select it correctly.

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 real value beyond that: an explicit provenance guarantee — 'The surface never silently answers from local data' — and clarifies which database it reads (production or explicitly opted-in local). This explains the openWorldHint=false annotation usefully.

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 purpose, which is good. However, the middle section is rambling and grammatically awkward — 'Leads with what the buyer gets and how to act on it, then the mechanics:' — where 'Leads' is ambiguous (verb vs. noun) and the sentence structure is tangled. The description runs ~100 words and would benefit from tightening.

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 0-parameter meta tool with a rich annotation set and an output schema present, the description covers the essentials: what it does, when to use it, what it reads, and the built-in guarantees. It mentions 'the tools available' but doesn't enumerate them, relying on sibling context; this is a minor gap, not a blocker.

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 0 parameters, so per the rubric the baseline is 4. There is nothing the description could add about parameters, and the schema (no properties) makes this unambiguous. No penalty applies.

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

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

Front-loads a specific purpose — 'What GoodLeads is — call this to explain or vet us' — with a clear verb (explain/vet) and resource. Explicitly flags what it is NOT for ('to price a list, start with interpret_list'), distinguishing it from the same-named sibling. The meta-nature (describing the surface itself) is clearly separated from navigate/price/checkout 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?

Gives an explicit trigger ('call this to explain or vet us') and names an alternative for a specific scenario (interpret_list for pricing). It also tells the agent what the call will surface (database provenance, contract, available tools). It doesn't enumerate when-not-to-use cases against other siblings like explain_concept, but the core trigger and one key exclusion are 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 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses return shape, the `_meta` provenance block, freshness/source behaviors, and raises ValueError for malformed or unmatched IDs. This gives complete behavioral expectations.

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 structured with a lead sentence, use-case context, Args, and Returns. Every sentence adds operational value, and there is no redundant repetition of the schema or annotations.

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 one-parameter lookup with rich annotations and an output schema, the description is complete: it covers when to use it, how to format the parameter, what the response contains, and what errors can occur. 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 only provides the property name, but the description fully compensates by explaining the format (`GL-CO-00042`), case-insensitivity, and that it maps to the `lead_ref` field. This is exactly what an agent needs to construct a valid call.

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 operation ('One record in full, by its Lead ID') and immediately gives an example ID format. It clearly distinguishes this from listing/browsing tools by framing it as a targeted lookup when you already hold a Lead ID.

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 says 'Use this when you already hold a Lead ID' and explains what data you get. It does not name sibling tools or exclusions, but the intended context is clear enough to route an agent 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 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?

Annotations already declare `readOnlyHint=true`, `idempotentHint=true`, and `destructiveHint=false`, and the description adds substantial behavioral detail beyond that: it documents the enforced operator sets, masked fields and keyless-caller redaction, canonical-vocabulary behavior, null semantics for negative operators, and the guarantee that invalid (field, op) pairs return a 422 naming the row rather than a 500. This gives an agent a strong and accurate model of what the endpoint will and will not do.

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 front-loaded with the core purpose and a direct usage instruction before going into detailed reference material. Every major block maps to a section value, and the prose is dense rather than padded. It could be modestly trimmed without losing value, but for a contract-heavy reference tool the length is largely 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?

With no output schema, the description carries the full burden of explaining return shapes, and it does so thoroughly across all three sections. It also covers error semantics, masked-field constraints, canonical-vocabulary flags, and how the contract applies across browse, summary, export, checkout, and pipeline scoping. For a single-parameter introspection tool, 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?

The schema only defines `section` as a string with a default, giving no description of valid values. The description fully compensates by defining each section value (`fields`, `grammar`, `recipes`) and elaborating what each returns, including nested structures and field-level meaning. With 0% schema description coverage, this is exactly the parameter-level guidance 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?

The description clearly identifies the tool as the source of the filter contract from the schema endpoint, covering fields, grammar, or recipes. It explicitly ties usage to building `browse_leads` filters, which distinguishes it from sibling tools such as `browse_leads` and `list_live_states`. The verb 'list' is augmented with concrete resource and payload detail, so an agent can tell exactly what this tool returns.

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 instruction: 'Call this before building `browse_leads` filters you haven't used before.' It also explains that the same payload backs browse, summary, export, checkout, and pipeline scoping. It does not explicitly state when not to use it or name alternative lookup tools, but the usage context is clear enough for an agent to decide 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 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is known. The description adds substantial behavioral context: the meaning of `period` (monthly standing order vs one-time), that `stripe_price_id` is informational and never to be passed back, the graded pricing rule, and that only sellable records are billed. 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?

The description is longer than average but well-structured, moving from purpose to fields to pricing to alternatives. Every sentence carries information; there's no fluff. However, it could be more concise by separating the pricing rule into a supplementary sentence, yet as is it's efficient for the complexity it covers.

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 there is no output schema, the description fully covers the return fields (`product_id`, `name`, `description`, `state`, `lead_count`, `price_cents`, `period`, `stripe_price_id`) and explains their semantics. It also explains the pricing model, when to use alternatives, and how to buy. For a zero-parameter read-only list tool, 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?

There are zero parameters, so per the rubric the baseline is 4. The description doesn't need to document any input semantics because none exist; it focuses on output and usage, which 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 opens with a clear, specific statement: 'The pre-shaped shelf — ready-made business type × state lists.' It names the resource (shelf products), the verb (lists), and the structure (business type × state). It also differentiates from siblings by naming alternatives like list_starters and interpret_list, so an agent can tell them apart.

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 when to use this tool versus alternatives: 'For a shape of your own, or to see live graded counts and the exact price before buying, prefer the buying journey: list_starters ... or interpret_list → quote_list → checkout_list.' It also gives the purchase path: 'To buy a shelf product as-is, pass its product_id to create_checkout.' This leaves no ambiguity about 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?

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 declare read-only and idempotent; the description adds extensive behavioral context: quote_valid_until freshness, zero_reasons with nearest_alternative, forecast basis, ceiling_cents, and the rule that only sellable records are billed. It also warns 'Quote the server's numbers, never arithmetic of your own.' This goes far beyond the annotations and does not contradict 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?

The description is long but front-loaded with a one-line summary and then organized into billing, return fields, and args. There is some extra sales-oriented prose (e.g., 'The close is two questions...') that goes beyond operational necessity, making it slightly less concise than it could be, but the structure is well-sectioned and each part 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?

It covers inputs, outputs, pricing, freshness, error conditions (422 for keyless callers), and points to list_filterable_fields for filter syntax. It even provides a sample file URL to inspect the exact record shape. Given the tool's complexity and 0% schema coverage, nothing an agent needs 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?

Schema coverage is 0%, so the description fully compensates. The Args section explains each parameter: list_id mutual exclusivity, states default, filters contract, include_held default, lane allowed values, and cap structure. It also maps parameters to output behavior (e.g., 'quote present when lane or cap is given').

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 immediately states 'What this list costs before anyone pays: how many records name a person, and the price by grade.' This is a clear, specific verb (quote) plus resource (list) with a distinct scope. It also differentiates from checkout_list by saying 'to buy exactly what was quoted...', so an agent can tell quote from purchase.

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 when-to-use scenarios: pass a saved list or an inline shape, omit states for all live states, use lanes/ caps. It even names the alternative for the next step: 'hand the same list / shape, lane and cap to checkout_list.' It also includes a warning about billing discipline and what not to present, making usage boundaries clear.

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