StackSwap

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

With no annotations provided, the description carries the full burden. It enumerates the returned fields (cost delta, AI-readiness, headless-readiness, overlap status, swap-registry signal, recommended pick) and explains headless-readiness as 'MCP/API callability'. It does not mention side effects, auth, or rate limits, but for a read-only comparison tool the output disclosure 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 concise at two sentences. It front-loads the central purpose in the first sentence, lists the outputs efficiently, and the second sentence delivers usage guidance with examples. 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 simple schema (two strings), no output schema, and no annotations, the description covers the essential context: what it does, what it returns, and when to use it. It could go deeper on interpreting output values (e.g., cost delta format), but it is reasonably complete for an agent to invoke 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% with both parameters described as 'First/Second tool name (fuzzy-matched against catalog)'. The description adds examples and the phrase 'specific vendors' but does not provide additional parameter-level detail beyond the schema, so it meets the baseline without significantly enhancing 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 'Head-to-head comparison of two GTM tools' with a specific verb and resource. It distinguishes itself from the sibling tool compare_tools_n_way by explicitly focusing on two specific vendors and providing examples like 'Salesforce vs HubSpot' and 'Outreach vs Smartlead'.

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

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

The description provides an explicit 'Use when' statement with clear scenarios (choosing between two specific vendors) and concrete examples. It does not explicitly mention when not to use it or name alternatives like compare_tools_n_way, but the context is clear enough for an agent to select 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?

No annotations are provided, but the description details the output format (markdown matrix with specific columns, partner sign-up links) and the 'one shot' behavior, which conveys a read-only comparison operation. However, it doesn't disclose edge-case handling (e.g., unknown tools) or whether external calls are made, so it's not fully 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 dense sentences front-load the purpose and output, immediately followed by usage guidance and an alternative. Every sentence earns its place with no filler or repetition of schema details.

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 specifies the return value (markdown matrix with six categories and partner links), the tool count range, and the differentiation from the 2-way variant, making it complete for an agent to invoke correctly.

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

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

The schema already describes the 'tools' parameter at 100% coverage, so baseline is 3. The description adds concrete usage examples ('Apollo vs ZoomInfo vs Cognism vs Clay') and specifies the 2–6 range, which aligns with the schema's min/max constraints, providing useful context 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 opens with a specific verb and resource ('Side-by-side comparison of 2–6 GTM tools'), and explicitly differentiates from the sibling tool compare_tools by noting the 2-way alternative for head-to-head pairs. It also lists the concrete output contents, leaving no ambiguity about what the tool does.

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

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

It states 'Use for category bake-offs' and gives an explicit alternative: 'Prefer the 2-way compare_tools for clean head-to-head pairs.' This tells the agent exactly when to choose this tool over a sibling.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It describes the input-to-output transformation but does not state whether the tool is read-only, whether it requires specific permissions or connections, or any side effects. The lack of safety or operational context is a significant gap, especially for a tool that synthesizes evidence.

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 sentence that efficiently conveys the core purpose without wasted words. It front-loads the action and lists the key output components, making it 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?

Given the tool's complexity (7 parameters, no schema descriptions, no annotations, no output schema), the description is insufficient. It does not explain the meanings of most parameters, provide usage scenarios, or detail the output structure, making it difficult for an agent to invoke the tool correctly and fully.

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 has 0% description coverage, so the description must compensate for all 7 parameters. It only references 'user answers' (answers) and 'connected-system evidence' (connectedEvidence), leaving goal, stage, motion, systems, and constraints unexplained. The required 'systems' parameter is not mentioned at all, which is critical for correct invocation.

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 function: transforming user answers and connected-system evidence into KEEP, SWAP, and BUILD recommendations with confidence, alternatives, and next prompts. It uses a specific verb and resource, and the output description distinguishes it from simpler tools by emphasizing explainability and next prompts, though it does not explicitly contrast with sibling tools like recommend_stack 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 when to use the tool (when user answers and connected-system evidence are available and final recommendations are needed) but provides no explicit guidance on when not to use it or when to prefer alternative sibling tools. There is no mention of prerequisites or exclusions.

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

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

No annotations are provided, so the description carries the full burden. It discloses return format (ranked matches with confidence levels, evidence snippets, ready-to-use array) and reveals conservative behavior on ambiguous short tokens, adding useful context beyond the schema. It could mention no-match behavior or limits, but overall it covers key 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?

Three sentences with zero redundancy. Each sentence earns its place: function, output, usage, and behavioral nuance. The description is dense but well-organized, front-loading the core verb and resource, then adding targeted details.

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

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

For a simple single-parameter tool with no output schema, the description is remarkably complete. It covers input examples, output structure, usage scenarios, and behavioral caveats, making the tool's purpose and behavior fully understandable without additional structured data.

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 covers 100% of the single parameter's meaning (a text string). The description adds value by exemplifying valid inputs ('job post to raw HTML') and reinforcing the freeform nature, which goes beyond the schema's dry type 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 specifies a clear verb and resource: 'Infer a GTM stack from a freeform text blob.' It also lists concrete examples (careers page, job posting, HTML) and distinguishes from siblings by noting the output can chain into scan_stack or find_overlaps, making the tool's unique role obvious.

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 explicit when-to-use guidance: 'Use when the user says I don't know what we use or pastes a competitor's careers page to scout.' It also implicitly excludes alternatives by describing what the tool does not do (e.g., not a scanner like scan_stack) and suggests integration with other 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?

With no annotations provided, the description carries the full burden. It discloses the curated nature (104 hand-verified overlaps) and the output (redundant pairs with savings), which implies a read-only lookup. It does not mention edge cases or side effects, but 'return' strongly implies non-mutating behavior, and the curated count adds meaningful 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 a single, information-dense sentence that immediately conveys input, output, and key characteristics. Every phrase earns its place 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?

The description covers input, output, and a unique data attribute (hand-verified overlaps), which is sufficient for a simple one-parameter lookup. It does not explicitly address the no-overlap case or validate tool name matching, but this is a minor gap given the tool's simplicity.

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% for the single 'tools' parameter, with a clear description in the schema. The tool description only repeats 'list of tool names' without adding extra semantic detail, so it does not elevate beyond the schema baseline.

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 redundant pairs for a set of tools, with explicit mention of the curated 104 hand-verified overlaps and savings. This distinguishes it from siblings like compare_tools or suggest_swaps by focusing on curated redundancy detection within a stack.

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

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

The description provides clear context: use when you have a list of tool names in a stack and want to identify known redundant pairs. However, it does not explicitly state when not to use or name alternatives, though the sibling list offers potential 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 provided, the description carries the full burden of behavioral disclosure. While it indicates the output is a 'copy-ready one-shot prompt,' it does not mention whether the operation is read-only, what side effects (if any) occur, or what the generated prompt will look like. The description does not explicitly contradict any annotations, but it provides minimal 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 a single, concise sentence that is front-loaded with the main purpose. Every word contributes to understanding the tool's function, with no filler or redundant 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 four parameters, no output schema, and no annotations, the description is too brief. It fails to clarify the purpose of the optional parameters or the expected result, leaving the agent with insufficient information to invoke the tool confidently across different use cases.

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 must compensate by explaining the parameters. It only implicitly clarifies that 'recommendation' is the input recommendation, but leaves 'output', 'target', and 'systems' unexplained. This is insufficient for an agent to know how to populate the optional 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 uses a specific verb ('generate') and clearly identifies the resource ('a copy-ready one-shot build or migration prompt') and its source ('a StackSwap KEEP, SWAP, or BUILD recommendation'). This clearly distinguishes it from sibling tools like generate_data_layer_blueprint or suggest_swaps, which focus on different outputs.

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 the tool is used when you have a StackSwap KEEP, SWAP, or BUILD recommendation and need a copy-ready prompt, but it does not explicitly state when to use this tool versus alternatives or provide any exclusions. The usage context is clear but not fully articulated.

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 carry the full burden. It only says 'generate' without disclosing what the output is, whether it is read-only, if any side effects exist, or what format the blueprint takes. The phrase 'case-specific' hints at analysis but is not informative enough for an agent to understand 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 single, front-loaded sentence that clearly leads with the action and object, followed by the trigger condition. Every word contributes to the purpose, making it appropriately concise.

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

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

The tool has 4 parameters, no output schema, and no annotations. The description lacks essential context such as what a 'data-layer blueprint' contains, what inputs are needed, and how the result is presented. This is insufficient for an agent to use the tool correctly.

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

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

Schema description coverage is 0% for all 4 parameters, and the description does not compensate. It mentions 'systems' in the trigger condition but says nothing about 'entities', 'primarySourceOfTruth', or the 'problem' parameter. The agent gets no additional meaning beyond the parameter names.

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

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

The description clearly states the action ('Generate') and the object ('case-specific GTM data-layer blueprint'), and specifies the trigger conditions ('when systems mirror state, drift, or lack explicit ownership'). This distinguishes it from sibling tools like compare_tools or find_overlaps, which are about comparison or discovery.

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

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

The description gives a clear when-to-use condition ('when systems mirror state, drift, or lack explicit ownership'), but does not mention when not to use it or name alternatives. This stops short of full guidance but provides usable 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 the full burden. It discloses output structure ('why it matters' and 'watch for' red flags), authorship/credibility (StackSwap operator team, Nick French with 10+ yrs experience), and the layering behavior when both params are passed. Slightly missing details on output length variance/edge cases, but solid for an unannotated 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?

Three sentences, front-loaded with the action and output format. The authorship/credibility sentence is somewhat tangential to execution but does add trust context for an agent deciding whether to surface this tool. Efficient without waste.

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

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

For a read-only informational tool with no output schema and both params fully documented, the description is nearly complete. It covers what's returned, the two param dimensions, when to use, and credibility. Minor gap: no mention of error behavior when an unknown vendor/category slug is passed, but this is a low-complexity look-up 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 both vendor and category params are already documented with descriptions. The description adds marginal value by explaining the interaction/layering behavior and defaulting rule beyond what schema conveys — but the core semantics are already in the schema, so baseline 3 is appropriate.

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

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

Clear specific verb+resource: 'Return 10-20 questions a B2B GTM buyer should ask a vendor before signing.' Distinct from siblings — it produces a due-diligence question set, clearly different from compare_tools, get_tool_details, or search_content. The vendor/category dual behavior is explicitly stated.

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 explicit when-to-use: 'Use when the user is evaluating a vendor, prepping for a sales call, or building a procurement checklist.' Also explains parameter interaction (vendor-only, category-only, or both for layered diligence) and notes the category defaulting behavior. Strong 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 the transparency burden. It discloses the output scope ('every catalogued tool') and included attributes ('cost, AI-readiness, swap-registry status, and partner sign-up links'). However, it does not explicitly state the operation is read-only (though 'Returns' implies it), and it does not clarify that the 'limit' parameter can cap the 'full map.' Minor gaps, so 4 rather than 5.

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 and well-structured. It opens with the core purpose, then usage, then a compact list of known buckets. Every sentence delivers useful information without waste, and the bucket list is a practical reference rather than padding.

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

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

Despite no output schema or annotations, the description sufficiently explains the return value ('leaders, runner-ups, and skip/replace candidates' with specific fields) and the intended use case. It also covers the category parameter via the bucket list and notes the limit parameter's effect through schema. For a two-parameter read tool, this 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 description coverage is 100%, so baseline is 3. The description adds value by enumerating 'Known buckets' for the category parameter, which goes beyond the schema's generic example. It does not add syntax for 'limit,' but the schema already handles that, so this extra guidance justifies a 4.

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 function: 'Full map of one GTM category — leaders, runner-ups, and skip/replace candidates.' It also distinguishes from siblings by noting it is 'strictly more comprehensive than recommend_partner' and returns 'every catalogued tool,' which differentiates it from single-pick recommendations.

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 guidance is provided: 'Use when the user wants to see the full landscape for a category' with concrete examples. The alternative is named directly ('recommend_partner (single best pick)'), and the word 'strictly more comprehensive' implies when not to use this tool in favor of the sibling.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does so by specifying the exact return payload: 'canonical URL + category + last-modified date + full markdown body (sections + related-tools footer).' It also notes the content source and asks to cite the URL, which adds context about data provenance and usage expectations. It lacks explicit read-only hints, but the fetch semantics are 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?

The description is three sentences, each earning its place: the first states the core action, the second gives usage context, and the third details the return value and citation requirement. It is front-loaded and free of fluff, making it easy for an agent to parse quickly.

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

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

For a single-parameter fetch tool with no output schema and no annotations, the description is robustly complete. It covers the input source, the return structure, and the provenance of the content. It does not address error cases (e.g., unknown slug), but this is a minor gap given the simplicity of the operation.

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

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

The input schema already has 100% coverage with a detailed description of the slug parameter. The tool description reinforces this by explaining the slug comes from search_content and provides examples. This adds workflow context beyond the schema alone, making the parameter meaning clearer and more actionable.

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 function: 'Fetch the full body of a StackSwap knowledge base article as markdown.' This is a specific verb-resource pair that distinguishes it from sibling tools like search_content (which returns slugs) and get_tool_details (which likely returns tool metadata). The mention of 'full body' and markdown further clarifies its unique role.

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 guidance on when to use the tool: 'Use after search_content returns a slug, or when an agent has been pointed at a specific article.' This gives clear context and sequencing, though it does not explicitly mention alternatives or when *not* to use it. It does imply that other tools are for preliminary searches, which is sufficient.

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 behavioral burden. It discloses the tool is read-only knowledge retrieval (returns strategic content) with no side effects implied. It adds origin context ('Authored from operator experience across major B2B SaaS renewals') which helps the agent gauge credibility and scope. It clearly states monthlySpend affects computed savings and contractEndsIn alters timing guidance. This is transparent about behavioral outcomes.

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 compact paragraph that front-loads the core deliverable before enumerating elements. It packs substantial information into a single, readable block. It could be slightly tightened (some enumeration could be trimmed), but every sentence carries functional value. The use-case trigger sentence is well placed at the end for retrieval matching.

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

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

The tool has no output schema, but its purpose is to return advisory content whose exact shape is inherently flexible. The description enumerates seven content categories the response will cover, which gives the agent a strong expectation of return content without field-level schema. For a lightly-parameterized (3 params, 1 required) advisory tool with strong param coverage and clear trigger conditions, the description is adequately complete.

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

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

Schema description coverage is 100%, so all three params are documented in the schema. The description adds meaning beyond that: it explains monthlySpend's purpose ('compute target savings against the suggested discount ask') and contractEndsIn's conditional effect ('days or weeks triggers compressed-timeline guidance'). It also clarifies vendor accepts name or slug formats. The description substantively enhances parameter understanding beyond schema text.

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+resource ('Return StackSwap's renewal-negotiation playbook for a specific vendor') and enumerates the specific deliverables (leverage points, price anchors, discount ask, walkaway script, timing, contract traps). It distinguishes itself from sibling tools like get_vendor_fact_sheet and get_buyer_questions by focusing specifically on renewal negotiation. It doesn't uniquely differentiate from all siblings but the purpose is clear and 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?

The description gives explicit usage context: 'Use when the user mentions a renewal, a price increase, or 'we're up for renewal' conversations.' This directly tells the agent when to invoke it. It also explains what optional parameters do ('contractEndsIn flags compressed-timeline adjustments'). It doesn't explicitly name what sibling to use instead for non-renewal vendor questions, but the when-to-use guidance is strong and the deliverable scope is clearly bounded.

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 the profile's contents, including the precedence rule 'vendor fact sheet wins when fresh', and the fuzzy-matching behavior via the schema. It doesn't discuss error cases or rate limits, but for a read-oriented profile tool, the behavioral detail is solid.

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 main purpose and a rich list of returned fields. Every word adds value, and the usage guidance is woven in efficiently.

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

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

Given the tool's low complexity (one parameter, no output schema, no annotations), the description is remarkably complete. It specifies the fields, the cost calculation nuance, the usage context, and the alternative tool, leaving no major gaps 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?

Schema description coverage is 100% for the single 'name' parameter, which already explains fuzzy-matching. The description adds no extra semantics beyond reiterating that it's for a single tool, so it meets the baseline without exceeding it.

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

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

The description clearly states the tool's function: returning a full StackSwap profile for a single tool, listing specific fields like cost, AI-readiness score, category, overlaps, swap-registry status, and partner link. It also distinguishes itself from search_tools by noting it provides more depth, making its purpose unambiguous.

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

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

The description explicitly says 'Use when the user wants depth on one tool' and contrasts with search_tools' name + cost, giving clear context for when to choose this tool. It does not enumerate other alternatives or exclusions, but the provided guidance is sufficient for a single-parameter tool.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly describes the conditional return ('when one exists'), the not-found response, provenance labeling, and 90-day freshness computation. It doesn't explicitly state any side effects, but the read-only nature is strongly implied and no contradictions exist.

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

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

The description is four sentences, each earning its place: purpose, content list, data provenance/freshness, and usage guidance with fallback. It's front-loaded with the main action, avoids fluff, and remains compact despite covering many details.

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 a simple one-parameter input schema and no output schema, the description fully compensates by enumerating the fact sheet's contents (pricing, integrations, AI, affiliate terms, conflicts), provenance, freshness window, and the not-found path. It also names the underlying schema (GTM Decision Schema v1.0.0), giving a complete picture for an agent to invoke 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%, as the single parameter `tool` already fully explains accepted values and fuzzy matching. The description adds no additional parameter-level detail, so the baseline of 3 applies without needing compensation.

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-resource pair ('Return the full vendor fact sheet') and clearly scopes it with 'when one exists.' It explicitly distinguishes itself from the sibling tool `get_tool_details` by stating it provides 'strictly more detail,' making the purpose unmistakable.

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

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

The description provides an explicit usage context: 'Use when an agent or buyer needs the structured machine-readable view of a tool.' It contrasts with `get_tool_details` to guide selection, though it doesn't enumerate other excluded scenarios. The fallback behavior (not-found + submission pointer) also clarifies what happens when the tool isn't applicable.

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

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

The description discloses a useful limitation: 'The server cannot introspect neighboring MCPs automatically.' It also mentions 'read-only evidence,' which implies a non-destructive operation. However, with no annotations provided, the description does not fully disclose side effects, permissions, or return behavior, leaving gaps in 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 only two sentences, efficiently front-loaded with the core purpose and followed by a key limitation. Every word earns its place, with no redundancy or 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?

Given 2 undocumented parameters, no output schema, and no annotations, the description is far too minimal. It provides a high-level purpose and one limitation, but leaves out parameter usage, use-case context, and relationship to sibling tools. This is inadequate for an agent to reliably invoke the 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 description coverage is 0%, and the description does not explain the 'systems' or 'auditGoal' parameters at all. The agent has no help understanding what these inputs mean or how to use them. The description fails to compensate for the lack of schema documentation.

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

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

The description uses a specific verb 'Identify' and names the resource 'available connected systems and the read-only evidence StackSwap needs'. This clearly distinguishes the tool as an inspection capability, unlike siblings like request_system_connection or scan_stack. However, it does not explicitly differentiate from all siblings, so it loses a point.

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

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

The description implies when to use the tool (to discover connected systems and read-only evidence) but does not provide explicit usage context, exclusions, or alternatives among the 22 sibling tools. No guidance is given on when to prefer this over scan_stack or request_system_connection.

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 burden. It accurately describes a read-only retrieval operation and the output contents, but doesn't disclose edge cases like no matching partner or limitations on input categories. For a simple lookup, this is adequate but not highly 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?

A single sentence clearly structures the trigger (need), the action (return recommendations), and the output (URL and positioning). No wasted words, front-loaded with the condition.

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 only one parameter and no output schema, the description fully specifies the tool's function and the content of its return value. It gives an agent everything needed to invoke it correctly.

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

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

The schema already provides 100% coverage with a detailed description and examples for 'category'. The tool description adds some examples but doesn't offer significant additional meaning 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 recommended affiliate partners for a given need, with examples and output details. This distinguishes it from sibling tools like recommend_stack by specifying it's about partners, not stack composition.

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 'Given a need' phrasing with examples implies when to use this tool. However, it doesn't explicitly mention alternatives or when not to use it, though the purpose clarity largely covers that.

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 the description carries the transparency burden. It clearly describes what the tool returns and implies a read-only nature through 'Returns'. However, it does not explicitly state the absence of side effects, authentication needs, or rate limits, and the budget-overage behavior ('flags the overage but does not auto-swap tools') is only mentioned in the schema, not the main description. Minor gap, hence a 4.

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 output, followed by usage differentiation. Every clause adds value; no filler or redundant phrasing.

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 recommendation tool with no output schema, the description adequately explains the return payload, the use case, and how it differs from sibling tools. The input schema covers parameter details, so there are no critical contextual gaps.

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 rich descriptions for all three parameters (budget cap behavior, industry aliases, teamSize default). The description adds no parameter-specific information beyond what the schema already provides, so a baseline 3 is appropriate.

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

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

The description uses a specific verb ('Returns') and resource ('curated tool list for a given industry vertical'), enumerating the exact output contents (per-tool cost, total spend, AI-readiness/headless-readiness scores, partner links). It also explicitly distinguishes itself from the siblings scan_stack and recommend_partner, making its purpose unmistakable.

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

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

The description provides an explicit usage directive: 'Use for greenfield ... queries' and names two alternatives with their contrasting functions ('distinct from scan_stack (audits an existing stack) and recommend_partner (single category)'). This gives 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 the full burden. It discloses the operation as 'safe, read-only' and clarifies that it returns a 'request' rather than performing a connection. However, it doesn't detail any side effects, permissions, or the output format beyond that.

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 sentence with no filler words, front-loading the verb and resource. Every word adds value.

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

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

The one-sentence description gives the trigger condition, safety profile, and high-level output, but lacks details on parameter semantics and return structure. With no output schema or annotations, this leaves gaps for an agent to invoke it correctly.

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

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

The description only references the 'system' parameter via 'named system.' The 'purpose' and 'preferredMode' parameters are not explained, and since schema description coverage is 0%, the description fails to compensate for the missing schema documentation.

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 the specific verb 'Return' and identifies the resource as 'a safe, read-only connection or export request for a named system.' It also provides the context 'when an audit lacks evidence,' clearly distinguishing this from sibling tools like inspect_available_connections.

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

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

The description explicitly states when to use this tool ('when an audit lacks evidence'), providing clear context. It does not mention alternatives or exclusions, so it stops short of full usage 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 provided, the description carries the full disclosure burden. It explicitly lists the computed outputs (current spend, optimized spend, recoverable, gaps, opportunities) and mentions the inclusion of a link to a full paid audit. This conveys the tool's read-only, preview nature, though it does not discuss permissions or potential side effects.

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 exactly two sentences. The first front-loads the core purpose and outputs; the second adds the note about the paid audit link. Every word earns its place, and there is no repetition of schema content.

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

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

Given the tool's moderate complexity (3 params, no output schema), the description covers all key outputs and the audit link. It does not detail the exact return structure, but since there is no output schema that burden is partially met. The tool's purpose and primary outputs are sufficiently complete for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, and the input schema already describes each parameter (tools, industry, teamSize) including defaults and allowed enum values. The description adds only a high-level mapping of these inputs to the tool's behavior, which is minimal value beyond the schema.

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

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

The description begins with a specific verb+resource: 'Run a preview StackScan'. It clearly enumerates the inputs (list of tools, team size, industry) and outputs (current spend, optimized spend, recoverable amounts, headless gaps, top 5 opportunities). This distinguishes it from sibling tools like detect_stack_from_text or find_overlaps, which target different tasks.

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 conveys the tool's context: a preview scan for spend optimization and headless gap detection. While it doesn't explicitly name alternatives or state when not to use it, the purpose is self-evident and distinct from siblings. The 'preview' wording also implies a lightweight, pre-audit use case.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses the scope (~50 articles), the ranked result format, and the instruction to cite URLs. It does not explicitly state read-only behavior, but 'search' inherently implies it, and the description adds useful context about result 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 concise yet complete, front-loading the core purpose and return values, then providing usage context and a pointer to the next step. Every sentence adds value, and the examples are relevant without being 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 lack of an output schema, the description adequately explains what the tool returns (ranked articles with fields). It covers the content scope, typical use cases, and the follow-up action of passing the slug to get_kb_article, making the tool's workflow clear and 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 baseline is 3. The description adds minimal extra meaning beyond the schema: it mentions multi-word query scoring (already in schema) and references slugs for a different tool. No new parameter-specific semantics are provided, but the schema already documents the parameters well.

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 a full-text search across StackSwap's GTM knowledge base and specifies the return fields (title, slug, category, summary, URL). It distinguishes itself from sibling tools like search_tools (which searches tools) and get_kb_article (which retrieves the full body) by focusing on knowledge base articles.

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: 'Use when the user asks a GTM strategy/architecture/methodology question that's been written about', with concrete examples. It also names an alternative/next step: 'Pass slug to get_kb_article for the full body', offering clear guidance on when to use this tool vs 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?

With no annotations provided, the description carries the burden of behavioral disclosure. It mentions that results include monthly cost and partner sign-up links, which adds useful context, but it does not disclose details like pagination, default limit, or what happens when no query is provided (though the schema covers some of this).

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 concise and well-structured sentences, front-loading the core purpose and adding a brief statement on output. There is no wasted wording or redundancy.

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

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

For a simple search tool with two optional parameters and no output schema, the description adequately covers its primary functionality and return value. It does not address edge cases or error handling, but the low complexity and comprehensive schema make it sufficiently complete.

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

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

Schema description coverage is 100%, with both 'query' and 'limit' already documented. The description adds context about the search scope (by name) but does not elaborate on parameter semantics beyond what the schema already provides.

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

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

The description clearly states a specific action—searching StackSwap's catalog of ~400 GTM tools by name. This distinguishes it from sibling tools like compare_tools or get_tool_details, which serve different functions.

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 name-based searches but does not explicitly state when to use it over alternatives such as get_tool_details or detect_stack_from_text. It provides enough context to infer the primary use case, but no exclusions or alternative comparisons are given.

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?

Without annotations, the description carries the full burden of disclosing side effects and prerequisites. It only mentions returning a questionnaire, but does not clarify whether the tool creates a session, requires prior context, or has any state-changing effects. This ambiguity is a significant gap for a 'start' action.

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

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

The description is a single, efficient sentence that places the key purpose upfront and avoids superfluous detail.

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

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

Given the absence of an output schema and annotations, the description is too sparse for a tool with four undocumented parameters and a multi-step process. It fails to explain what an 'adaptive audit' entails or how to populate the inputs, making it inadequate for reliable invocation.

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

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

The input schema has four parameters with no descriptions, and the tool description provides no explanation of what 'goal', 'stage', 'motion', or 'systems' represent. This leaves an agent guessing about required values.

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 function: initiating an adaptive GTM architecture audit and returning a discovery questionnaire. It uses a specific verb ('Start') and resource ('audit'), and distinguishes itself from sibling tools like 'complete_stack_audit' or 'suggest_swaps' by framing the questionnaire as a precursor to recommendations.

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 this tool should be used to begin an audit process, and its mention of 'before KEEP, SWAP, or BUILD recommendations' suggests it is an early step. However, it does not explicitly contrast with alternative tools or state when not to use it, such as when an audit is already in progress.

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, but the description fully discloses the key behavioral trait: submissions queue for admin review and do not immediately mutate the catalog, only propagating after merge. It also mentions the return value (correction ID + reassurance) and the asynchronous nature. This goes beyond what annotations would typically cover.

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?

Four sentences, front-loaded with the primary action and key constraint, with no redundant or promotional language. Every sentence contributes useful information, and the 'two-way data flow' phrase, while slightly vague, does not detract from the overall clarity.

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

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

The tool has no output schema, so the description correctly explains the return value. It covers the full lifecycle (submission, queue, merge), usage context, and scope (catalog aspects). This is a complete picture for a submission tool, especially given its low complexity relative to analytical siblings.

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 each parameter already has a rich description (e.g., tool is 'fuzzy-matched against catalog; new tools accepted too', source_url is 'Strong signal for fast approval'). The description does not add additional parameter-level meaning beyond what the schema provides, so the baseline of 3 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?

The description opens with a specific verb and resource: 'Submit a correction to the StackSwap catalog,' and lists the editable aspects (pricing, feature list, gotcha, AI-readiness score, category). This clearly distinguishes it from sibling read/analysis/search tools like search_tools or get_tool_details, which do not submit corrections.

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

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

The description explicitly states when to use the tool: 'Use when the user notices a stale price, an inaccurate feature list, a gotcha that should be flagged, or wants to report a tool we don't cover.' This gives clear context and no exclusions are needed since the sibling tools are all read/analysis tools rather than submission 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?

With no annotations provided, the description carries the transparency burden. It discloses that the tool returns recommendations only 'when one exists', includes savings and reasoning, and skews toward legacy-to-modern swaps. This gives insight into expected behavior and limitations. It does not explicitly state read-only nature, but the operation is inherently non-mutating and the description covers the key behavioral aspects.

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-loads the main action, and provides meaningful examples without redundancy. Every sentence contributes explanatory value, making it concise and well-structured.

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

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

For a simple tool with one parameter and no output schema, the description sufficiently explains the return value (recommendation, savings, reasoning) and behavioral skew. A minor gap is that it does not specify the response format when no replacement exists, but the 'when one exists' clause partially covers this. Overall, the description is complete enough for an agent to use the tool correctly.

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

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

The schema has 100% coverage for the single 'tools' parameter, describing it as 'Tool names to evaluate for AI-native replacements'. The description adds minor clarity by saying 'for each tool supplied', but it does not materially enhance parameter understanding beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the verb (return), resource (StackSwap's AI-native replacement recommendation), and inputs (for each tool supplied). It also specifies outputs (annual savings, reasoning) and gives concrete examples (Outreach → Smartlead, ZoomInfo → Apollo), which distinguishes it from generic comparison or recommendation 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 context: given a list of tools, it returns replacement suggestions. It does not explicitly mention alternative tools to use instead, but the clear purpose and examples allow an agent to infer when to call this vs siblings like compare_tools or recommend_stack. It lacks explicit exclusions or '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.