StackSwap

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

With no annotations, the description fully discloses behavior: accepts loosely-typed records, configurable threshold, and describes output. Covers all key behavioral traits.

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?

Concise single paragraph front-loads purpose. Could be slightly more structured but is efficient and clear.

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

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

Despite no output schema, the description thoroughly explains return metrics and risk callouts. Complete for a medium-complexity tool with two 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 covers all parameters (100% coverage). Description adds value by explaining loosely-typed nature, recognized fields, aliases, and default threshold, which go beyond 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 tool measures revenue concentration across accounts, listing specific metrics and return types. It distinguishes itself from sibling tools like analyze_win_loss by focusing on concentration metrics.

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 it operates only on the user's own book and provides example user queries. Does not explicitly mention when not to use or alternatives, but the context is 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?

With no annotations provided, the description carries full burden and excels: it discloses that win rates are computed per attribute value with sample size, values below minSample are suppressed, accepts loosely-typed records with outcome aliases, and returns ranked attributes with win rates and takeaway. No hidden behavior.

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

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

The description is a dense paragraph with front-loaded purpose. Every sentence adds critical information: behavior, defaults, usage scenarios. No fluff or repeated 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?

Given the tool has 3 parameters, no output schema, and no annotations, the description covers all essential aspects: purpose, parameter semantics, behavioral details (suppression, aliases), and expected return (ranked attributes with win rates). It is complete for an AI agent to use effectively.

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% but description adds value: explains default attributes ['source','type','owner'], default minSample=5, and that 'attributes' can be any field on deals. It also mentions outcome field aliases.

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 analyzes closed deals (won+lost) to surface predictive attributes. It uses specific verbs like 'analyze' and 'surface', and distinguishes from sibling tools like 'audit_pipeline_hygiene' or 'compute_nrr' which focus on different aspects.

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 scenarios: 'when user asks which sources/signals convert best', 'why are we winning/losing', or pastes closed deals. It also states 'Operates only on supplied deals' clarifying input constraint. It lacks explicit when-not-to-use guidance but is clear 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?

With no annotations, the description bears full burden. It explains the tool processes supplied deals and returns a score, but does not explicitly state it is read-only or side-effect-free. The phrase 'Operates only on supplied deals' implies no external mutations, yet more direct safety disclosure would be beneficial.

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 paragraph conveying dense information. It front-loads purpose and includes all key points, but could be more structured (e.g., using bullet points for flags). Every sentence is informative, yet slightly longer 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?

No output schema, but description outlines return elements: score, most common issues, worst offenders. It details flags and thresholds. However, it lacks precision on output format (e.g., exact structure of 'dirty deals'), which would help agents parse results. Still, it covers core inputs and logic well.

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

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

Schema coverage is 100%, and the description adds value by explaining 'loosely-typed deal records' and listing recognized fields with aliases (e.g., 'amount/value, stage/dealstage'). For config, it clarifies 'Optional tuning' and default threshold. This goes beyond the schema's property 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 starts with a specific action ('Audit') and resource ('user's OPEN DEALS'), and clearly states output: cleanliness score plus ranked dirty deals. It distinguishes from sibling tools like compute_pipeline_coverage by calling itself the 'data version of the pipeline-coverage-audit motion' and focusing on hygiene flags.

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: 'when the user asks is my pipeline clean, audit my deals, or pastes a deal list' and advises 'run it before trusting a forecast.' This provides clear context and appropriate triggers, though it omits a when-not clause.

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

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

With no annotations, the description fully covers behavior: computes weighted forecast, uses win% from deal or infers from stage, can be calibrated via config, returns band totals and slipping-deal flags. No hidden side effects are implied.

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

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

Description is detailed but well-structured and front-loaded with purpose. Every sentence adds value, though slightly verbose for the core function. Could be trimmed slightly.

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?

Covers all key aspects: bucket definitions, win% inference, calibration, quota gap, slipping flags, and return values. Missing only minor edge cases like empty deals list or error handling, but overall sufficient.

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%, but description adds meaning: explains deal record structure with aliases, config.periodDays as forecast period, config.stageProbabilities as win% overrides, and clarifies that deals are open. This goes beyond 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 it builds a weighted sales forecast from open deals, with explicit buckets (Commit, Best case, Pipeline, Longshot) and output fields. It distinguishes from sibling compute_pipeline_coverage by noting it generalizes from a single total to a full deal set.

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 when to use: when user asks about forecast, commit vs best case, or pastes deal list. Also clarifies it operates only on supplied deals (no CRM fetch), providing clear context and 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?

No annotations are provided, so the description carries the full burden. It discloses that parameters are fuzzy-matched against a catalog and enumerates return values (cost delta, readiness scores, etc.). However, it does not mention whether the tool is read-only, any side effects, authentication needs, or rate limits. For a data-returning tool, this is adequate but not thorough.

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

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

The description is two sentences, front-loaded with key outputs, then usage guidance. Every sentence earns its place; no unnecessary words.

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

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

With no output schema, the description adequately lists all returned fields (cost delta, AI-readiness, etc.). It does not cover error cases or tool-not-found scenarios, but for a high-level comparison tool this is sufficient for an agent to understand the tool's functionality.

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%, and the description adds value by explaining that the tool names are 'fuzzy-matched against catalog', which is not in the schema. This extra context helps the agent understand how input is processed.

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

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

The description clearly states it performs head-to-head comparison of two GTM tools, listing specific outputs (cost delta, AI-readiness, etc.) and providing example usage ('Salesforce vs HubSpot'). It effectively distinguishes from sibling tool compare_tools_n_way by focusing on two-specific-vendor comparisons.

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 ('when the user is choosing between two specific vendors') and gives concrete examples. While it does not explicitly mention when not to use it or name alternatives like compare_tools_n_way, the guidance is clear and sufficient for an AI agent.

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?

Describes the output markdown matrix and links, implying a read-only operation. No annotations provided, but the description adds sufficient behavioral context without contradictions.

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 plus an example, front-loaded with key information. No wasted words.

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

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

For a single-parameter tool with no output schema, the description fully explains the return structure and provides usage context, making it self-contained.

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 parameter is fully documented. The description adds example usage but no extra 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 clearly identifies the tool's purpose: side-by-side comparison of 2–6 GTM tools. It specifies the return format and distinguishes from the sibling 2-way compare tool.

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 use for category bake-offs and recommends the 2-way tool for pairs, providing 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?

With no annotations, the description carries full burden. It discloses that no data is fetched, it returns payback/verdict/retention caveat, and defaults grossMarginPct to 80 with a warning. It does not mention side effects or caching, but these are less critical for a computation 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 somewhat long but information-dense, front-loading the main purpose and then detailing parameters. It could be slightly more structured, but every sentence adds value for a tool with 7 parameters.

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

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

No output schema exists, so the description explains return values (payback months, verdict, retention caveat). Given the tool's complexity and parameter richness, the description covers essential aspects for an AI agent to use 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 coverage is 100%, but the description adds meaning beyond schema by explaining relationships (e.g., cac or salesAndMarketingSpend+newCustomers), conversion of annual to monthly, default behavior of grossMarginPct, and segment enum values. This adds significant value.

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 computes CAC payback period and judges it against benchmark bands. It specifies the verb 'compute' and resource 'CAC payback period', and distinguishes from siblings by noting it works on user-supplied numbers with no data fetch. The examples of user queries further clarify its purpose.

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 lists when to use the tool (e.g., when user asks about CAC payback) and clarifies it computes only on supplied figures. However, it does not mention when not to use it or direct to alternative tools, which would strengthen 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?

No annotations provided. Description discloses that computations are on supplied figures only, and outputs include a fragility flag when healthy NRR masks churn via expansion. This adds valuable behavioral context beyond just calculation.

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?

Three sentences, front-loaded with key outputs and purpose. Each sentence adds value without redundancy. Efficient and clear.

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

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

Without output schema or annotations, the description covers the tool's functionality, inputs, key outputs (NRR, GRR, verdict, fragility flag), and a critical behavioral nuance. Could slightly improve by detailing return format, but overall adequate.

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 baseline is 3. The description adds meaning by grouping parameters (startingARR required, others optional defaults to 0) and explaining the computation logic, enhancing agent understanding.

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

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

The description explicitly states it computes NRR and GRR from user-provided numbers, judges against StackSwap bands, and returns verdict and fragility flag. It clearly distinguishes from sibling tools by focusing on retention metrics.

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 use cases: 'when user asks 'what's my NRR / net retention', 'is my retention healthy', or pastes expansion/churn numbers.' It implies no data fetch, but does not explicitly state when not to use.

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

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

With no annotations, the description carries the full burden. It discloses that the tool only uses user-supplied numbers, does not fetch CRM data, and returns raw+weighted coverage, a verdict, and gap. It implies no side effects. A score of 4 reflects good transparency; it could be slightly improved by explicitly stating it is stateless and non-destructive.

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 concise at five sentences, each serving a purpose. It is front-loaded with the tool's core function, followed by parameter details, return info, and usage context. There is no fluff 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?

Given the tool's complexity (3 parameters with 100% schema coverage, no output schema), the description provides adequate completeness. It explains inputs, outputs (including raw/weighted coverage, verdict, gap), and the band used. It could detail the verdict logic slightly more, but it is sufficient for agent understanding.

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 provides 100% parameter coverage. The description adds value by explaining the distinction between openPipeline (raw only) and stages (weighted, the number that matters), and describes the return values. This additional context raises the score above the baseline of 3.

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

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

The description clearly identifies the tool's purpose: compute pipeline coverage from user-supplied numbers and judge against a band. It distinguishes from sibling tools by explicitly stating it does not fetch CRM data, differentiating it from tools that might pull data from external sources.

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 guidance: use when the user asks about pipeline coverage health or provides pipeline and quota numbers. It also clarifies when not to use by noting it only operates on user-supplied figures without fetching CRM data. It explains the two input modes (openPipeline for raw, stages for weighted) and recommends stages, giving clear context for agent decision-making.

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?

Describes output format (ranked matches with confidence levels and evidence snippets) and decision rule (ambiguous short tokens lose unless multi-mention or canonical-name). With no annotations, the description fully covers 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?

Two efficient sentences that cover purpose, input examples, output, and usage. Every phrase adds information without redundancy, and the purpose 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 one parameter and no output schema, the description fully compensates by detailing output structure, confidence levels, and linking to sibling tools. No gaps are apparent.

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 already explains the text parameter with limits. Description adds value by giving examples of acceptable text types (job posts, HTML, RFPs) and elaborating on the purpose, going beyond the schema's generic 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 clearly states it infers a GTM stack from freeform text, with concrete examples (careers page, job posting, etc.). It distinguishes from siblings by noting the output can be chained into scan_stack or find_overlaps.

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 when the user says 'I don't know what we use' or pastes a competitor's careers page to scout.' Also mentions conservative behavior on ambiguous tokens, providing clear usage context.

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

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

No annotations are provided, so the description carries full burden. It discloses that the tool returns a curated set of 104 hand-verified overlaps and savings, but does not state whether it is read-only, requires authentication, or has rate limits. The 'return' suggests no side effects, but this is implicit.

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

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

The description is two sentences, front-loaded with the core purpose, and contains no superfluous information. 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 tool has only one parameter, no output schema, and no annotations, the description adequately covers what the tool returns (redundant pairs with savings) and the input needed. It is complete for a simple lookup tool.

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

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

The schema already describes the 'tools' parameter with 100% coverage. The tool description adds no additional semantic detail beyond rephrasing the schema description. 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 verb ('return') and the resource ('redundant pairs') with specific scope ('in a user's stack') and additional context (curated set of 104 overlaps, savings). It distinguishes well from siblings like compare_tools or suggest_swaps.

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

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

The description implies usage when a user has a stack of tool names, but does not explicitly state when to use this tool versus alternatives like compare_tools or suggest_swaps. No exclusions or when-not-to-use guidance are provided.

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

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

No annotations are provided, so the description carries the full burden. It describes the output (penetration %, whitespace score, ranked accounts, unsold products), input types (loosely-typed accounts, full sellable set), and constraints (operates only on user's own book). It could mention error handling or missing fields, but overall transparency is strong.

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 dense paragraph but every sentence adds essential information. It is front-loaded with the core purpose. Slightly more structure (e.g., separating input/output snippets) could improve readability, but it remains efficient and clear.

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

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

Given no output schema, the description fully explains return values (penetration, ranked accounts, unsold products). Input parameters are well described, usage context is provided, and sibling differentiation is included. The tool is simple (2 parameters, no nested objects), so the description is complete for its complexity.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value beyond the schema by noting that accounts are 'loose records' with field aliases (products/skus, arr/mrr, health/healthScore, name/company) and that catalogProducts is the 'full sellable product set.' This enriches understanding of how to use the 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 clearly states the tool's purpose: 'Map product whitespace across the user's existing ACCOUNTS against a product catalog'. It specifies the verb (map), resource (whitespace), and scope (user's accounts vs catalog). It also distinguishes from the sibling tool score_expansion_opportunities by contrasting outputs (penetration map vs propensity-weighted 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?

Explicit usage guidance is provided: 'Use when the user asks "where is our whitespace", "which products are under-penetrated", or pastes accounts plus a catalog.' It also notes when not to use ('never a prospecting list') and provides an alternative tool ('for a propensity-weighted, dollar-valued go-after list use score_expansion_opportunities').

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

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

With no annotations, the description carries the burden. It discloses the return format (10-20 questions with 'why it matters' and 'watch for'), authorship, and parameter effects, but omits limitations, data source, or potential errors.

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

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

The description is a single, well-structured paragraph that front-loads the core functionality and then details parameters and use cases. Slightly verbose with repeated 'optional' but overall efficient.

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

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

Despite lacking an output schema, the description sufficiently explains the return structure and authorship. Missing details on edge cases or pagination, but adequate for a simple retrieval tool.

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

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

Schema coverage is 100%, but the description adds significant value by explaining vendor-specific gotchas, category slugs with examples (e.g., Apollo, Salesforce), and the default behavior when parameters are omitted.

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 explicitly states the tool returns 10-20 buyer questions with rationale and red flags, clearly distinguishing it from siblings like compare_tools or get_vendor_fact_sheet by focusing on procurement due diligence.

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 use cases: evaluating a vendor, prepping for a sales call, or building a procurement checklist. Does not mention when not to use or alternatives, but the context is 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?

Discloses output content (leaders, runner-ups, cost, AI-readiness, swap-registry, partner links) and known buckets, but does not mention sorting order, pagination, or any access constraints. With no annotations, this is good but not exhaustive.

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?

Three efficient sentences front-loading purpose, contents, and usage examples with no redundancy.

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

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

Despite no output schema, the description enumerates output fields (cost, AI-readiness, etc.) and lists known buckets, making the tool fully understandable for an agent.

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

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

Schema coverage is 100% with descriptions. Description adds value by noting category accepts free-text needs like 'zapier alternative', enriching schema 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?

Clearly states it returns a 'full map of one GTM category' listing leaders, runner-ups, and candidates, distinguishing it from sibling `recommend_partner` which gives a single best pick.

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 when the user wants to see the full landscape for a category' with examples, and contrasts with `recommend_partner` as strictly more comprehensive.

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

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

With no annotations, the description fully discloses expected behavior: returns canonical URL, category, last-modified date, full markdown body, sections, and related-tools footer. Also notes content provenance (operator team) and usage guidance (cite URL). No contradictions.

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?

Packed with information in two sentences, though the first sentence is somewhat long. Could be slightly shorter without losing clarity, but effectively concise overall.

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 lacking an output schema, the description fully details what the tool returns (canonical URL, category, last-modified date, full markdown body). With a single parameter and clear usage context, no further information is needed.

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%, but description adds significant value by explaining the 'slug' parameter's origin (from 'search_content') and providing concrete examples ('modern-gtm-architecture'). This enriches the schema definition.

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

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

The description uses specific verbs ('Fetch') and identifies the resource ('full body of a StackSwap knowledge base article as markdown'), clearly distinguishing from sibling tools like 'search_content' which returns slugs.

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 the tool: after 'search_content' returns a slug or when pointed at a specific article. Provides clear context but does not list all alternatives among the 18 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?

No annotations exist, so description carries full burden. It fully discloses the output content (leverage points, alternatives, discount, script, timing, trap callouts) and how parameters affect behavior (monthlySpend computes savings, contractEndsIn triggers adjustments). No hidden side effects implied.

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 purpose and components. Some redundancy in listing examples, but overall it's fairly concise given the amount of detail. Could be slightly trimmed 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?

For a tool with 3 params and no output schema, the description thoroughly explains output contents and parameter effects. It provides enough context for an agent to use effectively.

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% (3 params with descriptions), baseline 3. Description adds significant semantics: explains that monthlySpend is used to compute target savings and contractEndsIn triggers compressed-timeline adjustments, going beyond the schema's basic field 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 it returns a renewal-negotiation playbook for a specific vendor, listing specific components (leverage points, discount ask, etc.). It distinguishes from siblings by specifying usage context ('renewal, price increase'). Highly specific verb+resource.

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 ('mentions a renewal, a price increase, or 'we're up for renewal''). Does not provide when-not-to-use or alternatives, but the positive guidance is 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?

No annotations are provided, so the description carries full burden. It discloses the tool returns expert-authored content, but lacks details on data freshness, access permissions, or whether the output is static. For a read-only informational tool, it covers key aspects but misses some behavioral context.

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

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

The description is well-structured with front-loaded purpose, list of metrics, usage syntax, author credibility, and use cases. While slightly lengthy, each 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?

Given no output schema, the description partially explains return values (healthy range, nuance, etc.) but omits output format (e.g., JSON vs text). For a simple tool with one optional param, it is mostly complete but lacks final clarity on output structure.

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% for the single parameter. The description adds value by providing examples and explaining behavior when omitted, enhancing the schema's meaning.

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

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

The description clearly states the tool returns an operator-authored read on a RevOps metric, covering specific details like healthy range, nuance, mistakes, and bad readings. It lists the exact metrics covered, differentiating it from sibling computational tools like compute_cac_payback.

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 use cases are provided: when user asks 'is X a good number' or needs a calibrated benchmark. Guidance on passing metric slug/name or omitting for menu is clear. However, no explicit when-not-to-use or alternative tools are mentioned.

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

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

With no annotations, the description bears full burden. It describes the tool as returning static content (playbook) without side effects, and clarifies it's operator-authored rather than generic. This sufficiently discloses behavior.

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

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

The description is front-loaded with the core function and includes useful detail about covered playbooks. It could be trimmed slightly but remains efficient and informative.

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 one optional parameter and no output schema, the description fully explains what is returned (problem, steps, pitfalls, artifact), how to use it, and its source. It leaves no critical questions unanswered.

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

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

Schema coverage is 100% with a detailed description. The tool description adds value by listing the specific playbook topics covered (e.g., TOI measurement, win-rate analysis), enriching understanding 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 clearly states the tool returns a step-by-step playbook for specific RevOps motions, listing covered topics and distinguishing it as operator-authored. The purpose is concrete 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?

The description explicitly says when to use it ('when the user wants to RUN a RevOps motion') and provides example queries. It also explains how to choose between passing a playbook slug or omitting it. While it doesn't name sibling alternatives, the guidance is 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?

No annotations provided; description implicitly indicates read-only behavior by listing returned data fields. However, it does not explicitly state that the tool is non-destructive or has no side effects. For a retrieval tool, this is adequate but could be more transparent.

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

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

Description is a single, dense sentence that efficiently conveys all key information. It is front-loaded with the tool's output and use case. Slightly less concise due to the list of fields, but 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 no output schema, the description sufficiently explains the return value by listing fields. For a single-parameter tool with no complex behavior, the description is complete. It could mention handling of missing tools, but not necessary.

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

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

Schema coverage is 100% with a clear description for the parameter 'name'. The description adds no further semantics beyond the schema, so 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?

Description explicitly names the tool's purpose (Full StackSwap profile) and lists specific data fields (cost, AI-readiness score, category, overlaps, etc.). It clearly differentiates from sibling 'search_tools' by stating depth beyond name+cost.

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?

Provides clear when-to-use guidance ('use when the user wants depth on one tool') and contrasts with sibling 'search_tools'. Could be slightly improved by adding explicit when-not-to-use, but the existing usage guidance is strong.

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

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

No annotations provided, so description fully carries the burden. It specifies what the fact sheet includes (pricing tiers, integration scores, AI disclosures, etc.), provenance labeling, freshness window, and not-found behavior. Comprehensive and clear.

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

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

Description is well-structured and informative, listing components and behavior. Slightly long but each sentence contributes value. Front-loaded with main 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 low complexity (one string param, no output schema), the description adequately explains return format, behavior on not-found, and provenance. No gaps identified.

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

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

Schema coverage is 100% with a clear description of the single parameter. Description adds value by mentioning fuzzy-matching against the catalog, which goes beyond the schema. Overall, adds meaningful context.

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

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

The description clearly states it returns a full vendor fact sheet and distinguishes itself from sibling `get_tool_details` by noting it provides strictly more detail. Verb 'return' with resource 'vendor fact sheet' is specific.

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 when an agent or buyer needs the structured machine-readable view of a tool — strictly more detail than `get_tool_details`', providing clear context for when to use this tool over a sibling. Lacks explicit when-not but is strong overall.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool normalizes field aliases, infers win% from stage, and accepts optional quota and config overrides. It does not specify the output format, but given no output schema, this is a minor gap.

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

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

The description is a single paragraph that front-loads the main action. It is slightly dense but every sentence adds value, and there is no wasted text. It could benefit from better structure (e.g., bullet points) but is not overly verbose.

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 complexity of 3 parameters (one required, with nested objects) and no output schema, the description covers purpose, usage, parameter details, and behavioral constraints. It is complete enough for an agent to correctly decide when to use this tool and how 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 100%, so baseline is 3. The description adds significant value beyond the schema by explaining field aliases for deals, the purpose of quota (weighted coverage), and how config.stageProbabilities overrides the stage-to-win% map.

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 ranks open deals by expected value with a velocity penalty and buckets them into Work now/Soon/Watch, with reasons and risk flags. It explicitly distinguishes from siblings by being the only prioritization tool among many pipeline analysis 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 provides explicit usage cues: 'Use when the user asks which deals should my reps work first, prioritize my pipeline, or pastes a deal list.' It also clarifies that the tool only operates on supplied deals and does not return new prospects, 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?

With no annotations, the description fully covers behavioral traits: risk blending (customer health, recency, seat adoption), exposure formula, acceptance of loose types with alias normalization, and output details (ranked list with risk drivers, ARR, suggested play). It also specifies scope ('user's own book'). No contradictions.

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

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

The description is well-structured with a clear purpose sentence upfront, followed by risk explanation, parameter details, and output summary. It is relatively concise given the complexity, though the sentence about aliases is a list that could be slightly condensed. Overall, 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?

Given the tool's complexity (risk calculation, multiple fields, aliases, optional window) and no output schema, the description covers all necessary aspects: what it does, how it works, input format, output structure, and usage scope. It also addresses edge cases like windowDays only applying when renewal dates are supplied. Complete.

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

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

The input schema has 100% coverage, but the description adds significant value beyond the schema. For 'accounts', it lists recognized fields and aliases (arr/mrr/contractValue, etc.). For 'windowDays', it explains the default (120) and condition ('applies only when renewal dates are supplied'). This clarifies usage beyond structural definitions.

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: 'Rank the user's existing ACCOUNTS by renewal risk x ARR'. It uses a specific verb ('rank') and resource ('accounts'), and provides a clear distinction from siblings by noting it operates only on the user's own book, not a prospecting list. This makes the purpose 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 provides explicit trigger phrases ('when the user asks 'which renewals are at risk'', 'where is my ARR exposed') and clarifies that it operates only on existing accounts. However, it does not explicitly state when not to use this tool vs. siblings, though the context is implied. This is nearly thorough but misses explicit exclusions.

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

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

No annotations provided, so the description carries full burden. It discloses that the tool returns recommendations with sign-up URL and positioning. No side effects or permissions are mentioned, but for a read-only recommendation tool, this is adequate.

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

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

The description is two sentences, front-loaded with the core purpose, and contains no extraneous 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 fully addresses the tool's functionality given its simple input/output. No output schema exists, but the description explains what is returned.

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 a clear description of the 'category' parameter. The description adds context by explaining the output format, which goes 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 clearly states the tool's purpose: given a need, return recommended affiliate partner(s) with sign-up URL and positioning. It distinguishes itself from siblings like 'recommend_stack' by specifying 'affiliate partner' rather than a stack of 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 implies usage when a user has a need for an affiliate partner recommendation (e.g., 'outbound', 'CRM', 'automation'). It does not explicitly mention when not to use or provide alternatives, but the context is clear given the 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?

No annotations provided, so description carries full burden. It describes outputs but does not explicitly state side effects or permissions. For a recommendation tool, the absence of destructive behavior is implied but not confirmed. Adequate but not exhaustive.

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 well-structured sentences: first describes output, second gives usage context and sibling differentiation. No fluff, 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?

Covers purpose, output, usage, and parameter hints. Lacks output schema, but description sufficiently describes return type. No mention of rate limits or auth, but acceptable for a low-risk recommendation tool. Mostly complete given the tool's complexity.

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%, but description adds value by explaining budget overage behavior (flags, no auto-swap) and industry parameter flexibility (common slugs, aliases, fallback). TeamSize parameter is adequately described in schema. Adds meaningful nuance beyond 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?

Description clearly states the tool returns a curated tool list with cost and readiness scores for a given industry. It explicitly distinguishes from sibling tools scan_stack and recommend_partner, providing a specific verb-resource pairing.

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 use case: 'greenfield what stack should I buy? queries' and contrasts with scan_stack (audits existing stack) and recommend_partner (single category). Provides clear when-to-use and 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?

With no annotations, the description carries full burden. It discloses what the tool returns (spend, recoverable, gaps, opportunities, audit link) and implies a read-only preview. It does not mention side effects or permissions, but the 'preview' label and explicit outputs provide sufficient transparency.

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

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

The description is three sentences long, front-loaded with the action, and each sentence adds value: action, outputs, and link. No unnecessary words 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?

Given no output schema, the description lists all expected return components (spend, optimized, recoverable, gaps, opportunities, link). It is functional but does not detail the format (e.g., numbers vs strings) or error handling. Adequate for a preview tool.

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

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

Schema coverage is 100%, so the description adds little beyond what's already in the schema. It mentions 'tools + team size + industry' but does not provide examples or clarify format. Baseline of 3 is appropriate as description complements but does not significantly enhance understanding.

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

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

The description states a specific verb ('Run a preview StackScan') and resource ('a list of tools + team size + industry'), clearly distinguishing it from sibling tools like compare_tools or detect_stack_from_text. It explicitly lists the outputs: current spend, optimized spend, recoverable, gaps, and opportunities.

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

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

The description implies usage for initial stack assessment but does not explicitly state when to use this tool vs alternatives (e.g., for a full audit vs. compare_tools). No when-not-to-use or alternative suggestions are provided.

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

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

Given no annotations, the description carries full burden. It reveals that the tool only scores owned accounts, normalizes aliases, falls back to Intent-only if ICP missing, and returns a ranked list with sub-scores. Missing some edge cases but overall transparent.

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

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

The description is well-structured, front-loading the purpose and composition. Each sentence adds necessary context without redundancy. No wasted words.

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

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

For a complex tool with multiple layers, nested config, loose input, and no output schema, the description comprehensively covers behavior, input shape, scoring logic, and output format. No gaps for the agent to infer.

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 baseline is 3. The description adds value by explaining how `config.icp` drives scoring, that `idealStack` activates Stack Fit, and that accounts are loosely-typed with alias recognition. This goes beyond 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 tool scores and ranks the user's OWN accounts using a composite fit score (0-100) blending ICP Match, Intent, and optional Stack Fit. It explicitly distinguishes from net-new account tools, saying 'does NOT return net-new accounts to buy'.

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 scenarios: 'Use when the user asks 'which of my accounts best fit our ICP', 'rank my book by fit', or pastes accounts plus an ICP definition.' It also explains fallback behavior (Intent only if no ICP) and when Stack Fit activates (if idealStack supplied).

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

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

No annotations provided, so description carries full burden. It explains the blending of propensity components, the return format with specific levers, and the loosley-typed input handling. Minor gap: no mention of data freshness or accuracy limitations.

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?

Multiple sentences but front-loaded with core purpose. Every sentence adds value, though could be slightly more concise. Overall well-structured and easy to parse.

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

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

Covers parameters, usage, behavior, and return format. No output schema, but description includes example lever strings. Lacks explanation of error handling or defaults, but given complexity it is fairly complete.

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

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

Schema coverage is 100%, and description adds significant meaning: explains how each config parameter contributes (e.g., 'pass config.catalogProducts to compute cross-sell gaps') and documents field aliases for accounts.

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 ranks accounts by expansion opportunity with a specific verb 'Rank' and resource 'accounts'. It distinguishes it from siblings like 'find_whitespace' by focusing on existing accounts and expansion levers.

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 lists when to use: 'when the user asks where is my expansion revenue, which customers should we upsell'. Also clarifies scope: 'Operates only on the user's own book — never a prospecting list'.

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

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

No annotations are provided, so the description must cover behavioral traits. It states it performs a read operation (full-text search returning ranked articles) and notes the knowledge base size (~50). However, it lacks details on pagination, ordering, or any limitations, which would improve transparency.

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

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

The description is concise (4 sentences), front-loads the core purpose, and efficiently includes usage guidance, example queries, and a follow-up instruction. No unnecessary words.

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

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

Given the tool has 3 parameters, no output schema, and no annotations, the description sufficiently covers what the tool does, what it returns, when to use it, and how to proceed for full article access. It leaves no major gaps for agent decision-making.

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 baseline is 3. The description provides context about the knowledge base content and usage examples but does not add significant parameter information beyond what the schema already provides (e.g., query is free-text, limit defaults to 10).

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 performs full-text search over a specific knowledge base (~50 articles) and lists return fields (title, slug, etc.). It distinguishes itself from sibling tools like get_kb_article by noting that slug should be passed there for full body.

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 'Use when the user asks a GTM strategy/architecture/methodology question that's been written about' and provides concrete examples. It also directs to pass slug to get_kb_article for full body, but does not mention alternatives like search_tools for broader searches.

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

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

No annotations provided, so the description carries full burden. It discloses search behavior (substring, case-insensitive), return fields (cost, partner link), and the 'list top tools' fallback. No contradictions.

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. Purpose is front-loaded, and essential details are concisely provided.

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

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

Given no output schema, the description adequately explains return format (monthly cost, partner link). Complexity is low with two parameters, and coverage is complete.

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

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

Schema coverage is 100%, baseline 3. The description adds meaning beyond schema: explains substring matching, case-insensitivity, and the behavior when query is omitted. This enhances usability.

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 action: search a catalog of ~400 GTM tools by name, returning monthly cost and partner sign-up link. It distinguishes itself from sibling tools like search_content by focusing on tool names and costs.

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 explains when to use (search by name) and implicit behavior (omit query to list top tools), but does not explicitly mention when not to use or alternatives among 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?

No annotations present, so description bears full burden. It describes inputs (loose records with field aliases), grouping behavior, computed metrics, and the limitation to user's own book. No side effects or destructive actions are implied, and the description is comprehensive for a read-only analysis 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 informative but slightly verbose. It front-loads the core action and then details parameters and use cases. Every sentence adds value, but it could be tightened by removing redundancy (e.g., 'loosely-typed' and 'normalized' are similar).

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 no output schema, the description explains return values (per-group count, ARR, share, average ARR, plus NRR/GRR with retention inputs). It covers input requirements and constraints (only own book). Complete for the tool's complexity and context.

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

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

Schema coverage is 100% and includes descriptions for both parameters. The description adds value by specifying defaults (groupBy default 'segment'), field aliases, and optional retention inputs. It goes beyond schema repetition.

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 segments accounts and shows revenue concentration, growth, and leaks, with specific metrics (account count, ARR, etc.). It distinguishes from sibling tools by mentioning NRR/GRR segmentation, which overlaps with compute_nrr but specifies the context.

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

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

Explicitly says 'Operates only on the user's own book' and provides example queries like 'which segments drive revenue'. It implies when not to use (e.g., not for other users' data) but does not explicitly list exclusions. Could be stronger with a 'when not to use' statement.

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?

Since no annotations are provided, the description carries full burden. It clearly states that submissions do not immediately mutate the catalog, queue for admin review, and propagate only after merge. Also mentions two-way data flow and returns a correction ID.

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

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

The description is a single, front-loaded paragraph with three sentences that cover purpose, behavior, and return value without unnecessary 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 no output schema, the description adequately explains the return value (correction ID + reassurance) and the workflow. All parameters are described, and the overall process is clear.

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 baseline is 3. The description adds value by noting 'fuzzy-matched against catalog' for tool parameter and 'strong signal for fast approval' for source_url, enhancing the schema's meaning.

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

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

The description clearly states it submits a correction to the StackSwap catalog, listing specific fields like pricing, feature list, etc. It distinguishes from sibling tools (which are mostly reads or comparisons) by being a write 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?

Explicitly says when to use: when the user notices stale price, inaccurate feature list, etc. Mentions the submission process is queued for review, but doesn't explicitly describe 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?

With no annotations provided, the description takes full responsibility for behavioral disclosure. It accurately conveys the tool's behavior: it returns recommendations with cost savings and reasoning, and it may return nothing if no replacement exists ('when one exists'). This is sufficient for a straightforward recommendation tool, though more detail on response structure (e.g., is it a single best match per tool?) would improve transparency.

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

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

The description is two sentences long, with the first sentence stating the core action and outputs, and the second providing an example bias. No extraneous information is included; 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 simplicity (one parameter, no output schema, no annotations), the description covers the essential function: what it does, what it returns, and its bias. It does not detail edge cases (e.g., multiple replacements per tool) or output format, but for typical use, it is adequate. Compared to the calibration example of a filtered-list tool, it is similarly complete.

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

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

The input schema covers the single parameter 'tools' with 100% description coverage. The tool description adds meaning by explaining that each tool in the array is evaluated individually, aligning with the return of per-tool recommendations. This adds value beyond the schema, which only states 'Tool names to evaluate for AI-native replacements.' The connection between input and output is clarified.

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 explicitly states that the tool returns AI-native replacement recommendations with annual savings and reasoning for each tool supplied. It clarifies the skew toward legacy-to-modern swaps with concrete examples (Outreach → Smartlead, ZoomInfo → Apollo), making the purpose specific and distinct from sibling tools like compare_tools or get_tool_details.

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

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

The description implies usage for evaluating tools for replacements but does not explicitly contrast with alternatives or state when not to use. Sibling tools like compare_tools or find_overlaps might serve different needs, but no guidance is provided on selecting between them. The 'skews toward legacy → modern swaps' phrase offers some context, but lacks explicit when-to-use/when-not-to-use instructions.

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