StackSwap

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

With no annotations, the description carries the behavioral burden. It clearly discloses what the tool does and returns, including a useful parenthetical on headless-readiness. It does not explicitly state read-only/no-write behavior or failure modes, but its comparison semantics make the side-effect profile 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?

Two sentences, front-loaded with purpose, then a compact list of return fields, then usage. The parenthetical explanation of headless-readiness earns its place; 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?

With no output schema, the description compensates by enumerating the key return values and giving a concrete use case. It doesn't cover edge cases like uncatalogued tools or fuzzy-match failures, but the tool's simplicity and schema coverage make this a minor gap.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds GTM context and vendor examples, but does not materially expand on the parameter semantics already present in the input 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 opens with a specific verb and resource: 'Head-to-head comparison of two GTM tools.' It enumerates distinctive outputs (cost delta, AI-readiness, headless-readiness, overlap, swap-registry, recommended pick), and the 'two' constraint plus examples separates it from siblings like compare_tools_n_way and 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 states when to use: 'when the user is choosing between two specific vendors,' with concrete examples. It does not name alternative tools or state when not to use it, so it stops short of a full 5.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does state what the tool returns (markdown matrix with specific fields and partner sign-up links) and implies a read-only, non-mutating operation. However, it doesn't explicitly state there are no side effects, rate limits, or prerequisites. Given the tool's comparative nature, this is adequate but not exhaustive; a fully transparent description would explicitly confirm it performs no writes.

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 efficiently structured: it front-loads the core purpose, follows with the output specification, then usage guidance, and finally the sibling comparison. Every sentence earns its place, with no redundant or filler content. The example is illustrative 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 tool's simplicity (single parameter, fully documented in schema) and the lack of an output schema, the description fully explains the return value in detail (markdown matrix fields and partner links). It also covers usage conditions and differentiates from the sibling. Nothing an agent needs to call it correctly is missing.

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

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

The input schema already covers the only parameter ('tools') with a description specifying tool names and fuzzy matching. The tool description adds an example ('Apollo vs ZoomInfo vs Cognism vs Clay') and the 2–6 range (also in schema), but no new semantic meaning beyond the schema. Since schema coverage is 100%, the baseline of 3 is appropriate.

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

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

The description opens with a clear, specific purpose: 'Side-by-side comparison of 2–6 GTM tools in one shot,' which names the verb, resource, and scope. It also lists the exact output fields (markdown matrix with cost, AI-readiness, etc.) and explicitly distinguishes itself from the 2-way sibling tool by name ('compare_tools'), so an agent can tell them apart immediately.

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

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

The description gives explicit when-to-use guidance: 'Use for category bake-offs' with a concrete example, and then provides a clear exclusion criterion: 'Prefer the 2-way compare_tools for clean head-to-head pairs.' This directly tells the agent when to choose this tool over the named alternative, leaving nothing to inference.

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

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

With no annotations provided, the description must carry the full burden of behavioral disclosure. It mentions that recommendations are 'explainable' and include 'confidence, alternatives, and next prompts,' which hints at the output structure. However, it does not disclose whether the tool has side effects, requires specific permissions, or mutates any state. For an audit-completion tool, it is likely non-destructive, but that is not stated.

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 sentence that front-loads the core purpose and output characteristics. There is no filler or redundant phrasing. It is concise and efficient, earning a top score.

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 7 parameters, no output schema, and no annotations, the description is inadequate for an agent to understand the full invocation context. It does not explain the required 'systems' parameter, the meaning of 'stage' or 'motion,' or what the complete output structure looks like beyond the mentioned elements. An agent would likely need to inspect other tools or schemas to use this 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%, so the description must compensate by explaining parameters. It only implicitly references 'answers' and 'connectedEvidence' via 'user answers and connected-system evidence.' The required 'systems' parameter and others like 'goal,' 'stage,' 'motion,' and 'constraints' are left unexplained. This is insufficient for an agent to correctly construct inputs.

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: turning user answers and connected-system evidence into KEEP/SWAP/BUILD recommendations with specific output attributes (confidence, alternatives, next prompts). This is a specific verb+resource and not a tautology. However, it does not explicitly contrast with siblings like start_stack_audit or recommend_stack, relying on the tool name to imply it completes an audit, so it earns a 4 rather than 5.

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 no guidance on when to use this tool versus its alternatives. It does not mention prerequisites, such as having started an audit with start_stack_audit, nor does it exclude scenarios where recommend_stack might be more appropriate. The only implicit hint is the word 'complete' in the name, which is not enough for an agent to decide between 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 full behavioral burden, and it succeeds: it discloses that the tool returns ranked matches, confidence levels (high/medium/low), evidence snippets, and a ready-to-use array. It also reveals conservative matching behavior on ambiguous short tokens and the preference for multi-mention or canonical-name matches, which helps an agent calibrate expectations.

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

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

The description is four sentences with no filler. It front-loads the core purpose and example inputs, then covers output shape and tie-breaking behavior. Every sentence 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?

For a one-parameter, read-only-style inference tool with no output schema, the description is complete: it explains inputs, outputs, confidence levels, evidence snippets, and how the result can be chained into sibling tools. An agent has enough to decide when to call it and what to expect in return.

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 single parameter text is fully described in the schema (100% coverage), including type, min/max length, and examples. The tool description adds examples like careers page and DevTools network tab, but these are incremental rather than essential; the schema already does most of the work. A baseline of 3 is appropriate because the description does not meaningfully change parameter 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 and resource: 'Infer a GTM stack from a freeform text blob'. It lists concrete input examples (careers page, job posting, HTML, RFP, etc.), and distinguishes the tool from likely siblings by describing its output as ranked tool matches suitable for chaining into scan_stack or find_overlaps. This gives an agent a clear mental model of what the tool does and how it differs from related tools.

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

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

The description gives explicit usage triggers: 'Use when the user says “I don’t know what we use” or pastes a competitor’s careers page to scout.' It also indicates downstream tools (scan_stack, find_overlaps) for chaining. It does not explicitly discuss when not to use it or name an alternative tool to prefer, so it misses the full when/when-not/alternatives bar.

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 overlaps are hand-verified (curated) and that savings are included, which gives insight into the output and scope. It does not mention read-only nature or error handling, but the core behavior is clearly conveyed.

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 with no unnecessary words. It front-loads the action ('return') and the key details (104 hand-verified overlaps, savings), making it easy 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?

The description explains the high-level output (redundant pairs and savings) but does not specify the exact structure of the return value. Since there is no output schema, this is a minor gap. It is complete enough for an agent to call the tool and interpret the result, given the low complexity of the input.

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% (the only parameter 'tools' is described), so the baseline is 3. The description adds context that the tools are in a user's stack and that the output is redundant pairs with savings, but it does not add syntax or format details 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 states a specific verb ('return'), a clear resource ('redundant pairs'), and adds unique details (104 hand-verified overlaps, monthly/annual savings). This clearly distinguishes it from siblings like scan_stack or suggest_swaps, which focus on broader stack analysis or 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 gives clear context: use when you have a list of tool names and want to identify redundant pairs. However, it does not mention alternatives or when not to use this tool, so it lacks explicit exclusions or routing to sibling tools.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. The description says it 'generates' a prompt, implying a read-only transformation, but it does not disclose whether the tool performs any side effects, requires specific inputs beyond the recommendation, or how it handles invalid or incomplete recommendations. It also doesn't mention output format or whether the prompt is truly 'copy-ready' in all cases. With zero annotation coverage, this is a significant 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, concise sentence that front-loads the core purpose. It is appropriately sized and contains no filler. However, it could have used the available space to add parameter semantics or usage guidance without becoming 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 tool has 4 parameters with 0% schema coverage, no annotations, and no output schema, the description is incomplete. An agent would not know what 'output', 'target', and 'systems' mean, what the generated prompt looks like, or what constraints exist on the recommendation input. The description is adequate for understanding the tool's high-level purpose but insufficient for correct invocation in many 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 for the four undocumented parameters. The description only mentions 'recommendation' implicitly by referencing KEEP/SWAP/BUILD recommendations, but it does not explain the meaning of 'output', 'target', or 'systems'. The agent cannot infer what values these parameters should take or how they relate to the generated prompt. The description adds minimal value beyond the schema's bare 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 states a specific verb ('Generate') and resource ('a copy-ready one-shot build or migration prompt') and names the source ('StackSwap KEEP, SWAP, or BUILD recommendation'). It is clear what the tool produces, though it does not explicitly distinguish it from siblings like generate_data_layer_blueprint or suggest_swaps. The purpose is clear enough for an agent to understand the tool's 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 implies the tool is used when a KEEP, SWAP, or BUILD recommendation exists and a build/migration prompt is needed. However, it does not explicitly state when to use this tool versus alternatives like generate_data_layer_blueprint or suggest_swaps, nor does it mention any prerequisites or exclusions. Usage context is implied 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It does not mention side effects, return format, or any constraints (e.g., whether it modifies systems or just generates a document). The agent has no idea what happens after invocation, making this a significant 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 sentence, which is concise and front-loaded with the action. However, it is overly terse and omits critical information that would fit naturally in a slightly longer description, so it doesn't earn a higher score for structure.

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 4 parameters, 0% schema coverage, no output schema, and no annotations, the description is severely incomplete. An agent cannot determine how to construct valid inputs or what to expect as output, making it nearly unusable without additional context.

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

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

Schema description coverage is 0%, and the description provides no explanation for any of the four parameters (systems, problem, entities, primarySourceOfTruth). It does not compensate for the lack of schema documentation, leaving the agent to guess what each parameter means and how to populate them.

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 ('Generate') and resource ('GTM data-layer blueprint') and includes a conditional clause ('when systems mirror state, drift, or lack explicit ownership') that distinguishes it from sibling tools like compare_tools or recommend_stack. However, it doesn't elaborate on what a 'data-layer blueprint' entails, so it's clear but not fully detailed.

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 a condition for when to use the tool ('when systems mirror state, drift, or lack explicit ownership'), which gives some context for selection. It does not name alternative tools or explicitly state when not to use it, leaving the agent to infer from sibling names.

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 of behavioral disclosure. It states the output size (10-20 questions), the format (each with 'why it matters' and 'watch for'), and the effect of parameters (vendor-specific gotchas, category templates, layered diligence). It does not explicitly state side-effect-freedom, but as a content-returning tool this is a minor gap given the detail provided.

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: purpose, parameter usage, and use cases, plus author credibility. It is front-loaded with the core purpose and avoids fluff. The author line is slightly tangential but adds trust without bloating the text.

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

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

For a tool with no output schema and no annotations, the description covers the essential return-value format, parameter behavior, and use cases. It could optionally mention the exact question format or pagination, but for this simple tool the information is complete enough for correct invocation.

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

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

The schema already covers the parameters 100%, but the description adds meaning beyond the schema: vendor-specific examples (Apollo credit-pool, Salesforce SKU-breakdown), the category slug list, and the 'layered diligence' interaction when both are supplied. This enriches the agent's understanding of how to combine 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 opens with a specific verb and resource: 'Return 10-20 questions a B2B GTM buyer should ask a vendor before signing.' It also specifies the output structure ('why it matters' and 'watch for'), making the tool's purpose unambiguous and distinct from sibling tools like get_vendor_fact_sheet or get_category_landscape.

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 provides explicit when-to-use conditions: 'Use when the user is evaluating a vendor, prepping for a sales call, or building a procurement checklist.' It also explains parameter choices (vendor, category, or both), but stops short of naming alternatives or when-not-to-use, so it earns a 4 rather than 5.

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

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

No annotations are provided, so the description carries the transparency burden. It discloses the return content and fields, but it overstates scope by saying 'Returns every catalogued tool' while the schema's `limit` defaults to 15 and caps at 40; it does not surface the default truncation behavior. This mismatch prevents full 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 front-loaded with the core promiseasi and then gives a compact use-case and bucket list. The long list of known buckets is justified because `category` has no enum in the schema, though the phrasing could be slightly tighter.

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?

Since there is no output schemahare and no annotations, the description supplies the essential return-value information: leaders/runner-ups/skip candidates, cost, AI-readiness, swap-registry status, and partner sign-up links. It misses only operational nuances like limit defaults and potential truncation, which are partially available in the input schema.

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

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

The schema already covers both parameters at 100%, so the baseline is 3. The description adds value by enumerating 21 known bucket values and clarifying that the tool returns a category-wide map, going beyond the schema's short examples. It does not add semantic detail for `limit`, but the schema handles that.

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

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

States a specific verb ('Returns') and a clear resource ('one GTM category'), and describes the output classes ('leaders, runner-ups, and skip/replace candidates'). It also explicitly contrasts itself with `recommend_partner`, helping an agent distinguish it from a dense sibling list.

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

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

Gives direct trigger conditions ('Use when the user wants to see the full landscape'), concrete query examples ('show me all CRMs', 'map the analytics category'), and an explicit alternative (`recommend_partner` is a single best pick). The known bucket list further routes requests to the correct category.

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 behavioral burden and does so well. It discloses the exact return payload (canonical URL, category, last-modified date, markdown body, related-tools footer) and adds provenance context (operator-authored, not vendor marketing) plus a citation instruction.

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

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

Three sentences with no filler: usage trigger, return contents, and provenance/citation. Information is front-loaded and every sentence earns its place.

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

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

For a single-parameter tool with no output schema, the description fully compensates: it explains where the slug comes from, what the tool returns, and how to treat the content. Nothing needed for correct invocation is missing.

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

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

Schema description coverage is 100%, and the schema already explains that slug comes from search_content with examples. The description repeats that relationship but adds no meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

States a specific verb ('Fetch'), resource ('StackSwap knowledge base article'), and format ('markdown'). The explicit tie to search_content and article slugs differentiates it from sibling tools like get_tool_details or get_vendor_fact_sheet.

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 context: use after search_content returns a slug, or when pointed at a specific article. It does not explicitly name exclusions or alternative tools, but the guidance is sufficient for correct routing.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that passing monthlySpend computes target savings and that contractEndsIn with 'days' or 'weeks' triggers compressed-timeline adjustments, and it notes the playbook is 'Authored from operator experience' as a provenance signal. It does not describe side effects or output format, but for an informational retrieval tool this is sufficient.

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 few sentences and front-loads the core purpose and content list, followed by parameter behavior, provenance, and usage triggers. Each sentence adds information, though the vendor-name list is somewhat long and could be trimmed without losing essential guidance.

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

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

Given that there is no output schema, the description appropriately enumerates the return-value components (leverage points, price anchors, discount ask, walkaway script, timing window, contract-trap callouts). It also covers required/optional parameters, supported vendor examples, and the exact user signals that should trigger the tool, making the definition complete for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by clarifying how monthlySpend is used ('compute target savings') and how contractEndsIn alters the output ('flags compressed-timeline adjustments'). This gives the agent context about parameter effects that the schema alone does not convey.

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 ('Return'), a clear resource ('renewal-negotiation playbook'), and a scope ('for a specific vendor'). It goes on to enumerate the concrete contents, which makes the tool's function unmistakable and distinguishes it from siblings like get_vendor_fact_sheet or get_buyer_questions.

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

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

The description explicitly tells when to use the tool: 'Use when the user mentions a renewal, a price increase, or "we're up for renewal" conversations.' It provides clear context for triggering, though it does not explicitly mention when not to use it or name alternative tools for other scenarios.

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 adds behavioral nuance by explaining cost confidence ('vendor fact sheet wins when fresh') and enumerates the output components, giving the agent a sense of what to expect. It doesn't mention side effects (none expected for a read-only tool) but provides enough behavioral context for a non-destructive operation.

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 compact and front-loaded with the core purpose, followed by a usage note. Every sentence adds value, and the structure is clear 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?

For a single-parameter read tool with no output schema, the description fully explains what the tool returns (listing all profile components) and the usage context. Nothing essential is missing for an agent to call it correctly.

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

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

The schema already describes the single parameter (name) with 'Tool name (fuzzy-matched against catalog)', covering 100% of the parameter semantics. The description adds no further parameter-level detail beyond implying the tool operates on a single tool name, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool returns a full profile for a single tool, listing specific fields (cost, AI-readiness score, category, overlaps, registry status, partner link). It explicitly differentiates from search_tools by noting it provides more than name and cost, 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 states when to use it: 'Use when the user wants depth on one tool' and names the alternative (search_tools) with a clear contrast. This gives the agent a direct routing condition without ambiguity.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It thoroughly enumerates what the fact sheet includes (pricing tiers with gotchas, integration depth scores, AI capabilities, affiliate terms, conflicts), labels provenance, and explains freshness calculation (90-day window). It also discloses the not-found response behavior, which is critical for agents.

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

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

The description is dense but well-organized: it opens with the core purpose, lists key content areas, provides usage context, and closes with the not-found behavior. Every sentence adds value; there is no filler or repetition.

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

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

Given the tool's complexity (a structured fact sheet with many fields), the description covers the essential content categories, provenance labeling, freshness, and the not-found case. Since there is no output schema, the description adequately informs the agent of what to expect in the response.

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

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

The input schema already documents the single parameter `tool` with a clear description and examples, so schema coverage is 100%. The tool description adds no additional parameter-specific meaning beyond what the schema provides, so a 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 states a specific verb ('Return') and resource ('full vendor fact sheet'), and explicitly differentiates from the sibling `get_tool_details` by noting it is 'strictly more detail'. This makes the tool's purpose unambiguous and distinguishes it from similar tools.

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

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

It provides explicit when-to-use guidance: 'Use when an agent or buyer needs the structured machine-readable view of a tool', and names the alternative (`get_tool_details`). It also describes the fallback behavior when no fact sheet exists, including a pointer to a submission endpoint.

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 operation is read-only ('read-only evidence') and mentions a limitation (cannot introspect automatically), which is helpful. However, it does not describe what happens to inputs, what the output looks like, or any potential errors or side effects. It provides some transparency but lacks depth.

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, front-loading the core purpose and including a relevant limitation. Every word serves a function; there is no fluff. It is appropriately sized for a tool of this scope, though a bit more detail on parameters would have been useful.

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 2 optional parameters, no output schema, and no annotations, the description is thin. It does not explain how to use the parameters, what response to expect, or how this fits into the broader audit workflow. An agent would struggle to know what arguments to pass or what results to expect, making it incomplete.

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 does not mention the 'systems' array or 'auditGoal' string at all. The names may be somewhat self-explanatory, but the description adds no meaning beyond the schema, failing to clarify their purpose, format, or required values. This is a significant gap.

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

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

The description clearly states the tool's purpose: identifying available connected systems and the read-only evidence StackSwap needs. It specifies a verb ('identify'), a resource ('available connected systems'), and explicitly notes the server cannot introspect neighboring MCPs automatically, which differentiates it from siblings like scan_stack or request_system_connection. This is a clear, specific 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 implies usage context by noting the server cannot introspect automatically, suggesting this tool is the manual way to obtain connection info. However, it does not explicitly state when to use this tool versus alternatives, nor does it name any sibling tools or exclusion conditions. It provides context but not explicit 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 burden: the verb 'return' implies a read-only lookup languages, and it names output fields. It does not disclose data source, behavior when no partner matches, or whether any external side effects (e.g., affiliate link generation) occur.

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 wasted words. It front-loads the trigger ('Given a need'), states the action, and names the output elements, making it scannable and 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?

For a simple one-parameter lookup tool with no annotations and no output schema, the description is reasonably complete: it defines input, purpose, and required return fields. It doesn't address edge cases like no matching partner, but those are minor for the described scope.

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 covers the single 'category' parameter with 100% coverage and examples. The description's examples ('outbound', 'CRM', 'automation') largely mirror the schema's examplesainer, adding little new semantic 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?

Description states a specific action: 'return StackSwap's recommended affiliate partner(s)' on a concrete resource ('affiliate partner') with explicit output components ('sign-up URL and positioning'). The 'affiliate partner(s)' qualifier distinguishes it from sibling tools like recommend_stack and 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?

'Given a need' signals a clear entry condition and gives example categories, so an agent can infer when to use it. However, it does not explicitly mention when not to use it or name alternatives such as recommend_stack for broader stack-level recommendations.

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 clearly communicates a non-mutating, reference-style operation by saying the tool 'Returns' a list, and it specifies the exact result contents. It does not explicitly state read-only/no-side-effect status or failure/overage behavior, which keeps it from a 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 three purposeful sentences: purpose, returned data, and usage differentiation. It front-loads the core function, provides essential output details, and names the alternatives with zero 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 three parameters, no annotations, and no output schema, the description fully specifies the return value with per-tool cost, monthly/annual spend, readiness scores, and partner links. Edge details like aliases and budget overage handling are already in the schema, so no critical information for selecting and invoking the tool is missing.

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

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

All three parameters already have explicit schema descriptions covering accepted industry values, budget overage behavior, and the team-size default. The tool description adds no additional parameter semantics beyond the greenfield context and output contents, so the baseline 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 states a concrete action ('Returns a curated tool list') and a specific resource (a reference starter stack for an industry vertical), then enumerates the output fields. It also names the two sibling tools it is distinct from, so an agent can differentiate recommend_stack from scan_stack and recommend_partner without opening their schemas.

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

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

It explicitly tells the agent to use this tool for greenfield 'what stack should I buy?' queries. It also gives clear exclusions by contrasting with scan_stack (audits an existing stack) and recommend_partner (single category), which directly routes the agent to the right alternative.

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 responsibility for behavioral disclosure. It does state 'safe, read-only' which covers safety, but doesn't specify what the request entails, whether any system permissions are needed, or what exactly the returned request looks like. It adds some value but remains incomplete for a tool that generates requests.

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, concise and front-loaded with the action and key qualifier ('safe, read-only'). It wastes no words, though it could be slightly more structured to separate the purpose from the behavior.

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

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

For a tool with 3 parameters, no output schema, and no annotations, the description is too sparse. It does not clarify parameter semantics (especially purpose and preferredMode), nor does it describe the output format of the request. The agent is left guessing at critical details, making it insufficient 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?

Schema description coverage is 0%, so the description must compensate. It mentions a 'named system' (likely the 'system' parameter) but does not explain 'purpose' or 'preferredMode' at all. The agent has no guidance on how to fill these fields beyond their names, which is insufficient.

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 clear verb ('return') and resource ('connection or export request'), and specifies the condition ('when an audit lacks evidence'). It hints at a read-only nature, but it doesn't explicitly differentiate from sibling tools like inspect_available_connections, which might seem similar.

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 a context ('when an audit lacks evidence') but does not explicitly state when not to use it or name alternatives like inspect_available_connections. It's implied that it's for filling evidence gaps, but an agent would benefit from 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It details the outputs and includes a link to a paid audit, which is a behavioral trait. However, it does not explicitly state whether the operation is read-only, non-destructive, or whether it makes network calls or has side effects. Since it's labeled a 'preview', it implies safety, but this is not explicit, leaving a moderate gap 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 two sentences with no filler. It front-loads the action and then efficiently lists inputs and outputs. The inclusion of the paid audit link is compact and relevant. Every sentence contributes directly to understanding the tool's purpose and deliverables, making it appropriately sized and well-organized.

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 that there is no output schema, the description must explain what the tool returns, and it does list the key outputs. It also mentions the audit link, which is a relevant action. However, it does not describe the return format, data types, or any error scenarios, and it lacks usage guidance for alternatives. Still, for a simple 3-parameter preview tool, it covers the essential information an agent needs to call it correctly.

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

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

Schema description coverage is 100%, so the input schema already documents all three parameters (tools, industry, teamSize) with their descriptions and enums. The description merely restates these inputs without adding deeper meaning or nuances. It does clarify the meaning of 'headless gaps' in the output, but that is output-related, not parameter-related. Thus, the description adds minimal value beyond the schema, earning the baseline score.

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 ('Run a preview StackScan') and precisely lists the inputs (list of tools, team size, industry) and outputs (current spend, optimized spend, monthly/annual recoverable, headless gaps, top 5 replace/remove opportunities, and paid audit link). It distinguishes itself from siblings by emphasizing 'preview' and the paid audit path, making the tool's purpose and scope 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 implies a preview use case but does not explicitly guide when to use this tool versus alternatives like complete_stack_audit or start_stack_audit. No when-to-use or when-not-to-use conditions are stated, and no alternative tools are named as contrasts. The agent must infer from the word 'preview' without clear routing guidance.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It discloses the return format (title, slug, category, summary, URL), the source limitation (only ~50 first-party articles), and the key limitation that this tool returns summaries only — full body requires get_kb_article. It does not explicitly state that it is read-only, but 'search' and 'returns ranked articles' strongly imply no 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 four sentences with distinct jobs: purpose/scope, return shape, when-to-use with examples, and follow-up route. It is front-loaded and contains no filler; the 'Cite the URL' instruction is embedded without extra verbiage.

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 simple parameters and no output schema, the description covers the essential context: what corpus is searched, what the results contain, when to invoke it, and how to proceed to the full article. The schema handles parameter details, so nothing required for correct invocation is missing.

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

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

Schema description coverage is 100%: query, limit, and category each have explanatory descriptions, including the per-term scoring behavior for multi-word queries. The tool description adds no additional parameter-level detail; its query examples illustrate usage but not parameter semantics. Baseline 3 is appropriate given the schema already documents 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 opens with a specific verb and resource: 'Full-text search across StackSwap's first-party GTM knowledge base'. It names the collection's scope (~50 operator-narrative articles on named topics) and the return shape (ranked articles with title, slug, category, summary, URL). It also distinguishes from the sibling get_kb_article by routing the slug there for the full body, so an agent can tell this is the search/summary layer.

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 asks a GTM strategy/architecture/methodology question that's been written about' and gives three concrete query examples. It also gives a follow-up instruction: 'Pass slug to get_kb_article for the full body,' which clarifies the boundary between this tool and its sibling. The instruction to cite the URL is a clear behavioral rule.

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 that results include monthly cost and partner link, and that the search is by name. However, it doesn't state read-only behavior, potential side effects (likely none), or limitations beyond name-only search, leaving some behavioral ambiguity.

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 front-loads the core purpose and immediately includes the key output details (cost and partner link). There is no filler or redundancy.

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

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

The tool is simple, has no annotations, and no output schema. The description explains the return fields (cost, partner link) and the search target, which is sufficient for basic invocation. It could more explicitly define the result structure, but for a low-complexity search tool it is reasonably 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 both parameters (limit, query) are fully documented in the schema. The description adds minimal semantic value beyond the schema, merely saying 'by name' which aligns with the query parameter. Baseline 3 is appropriate.

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

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

The description states a specific verb ('Search'), resource ('StackSwap's catalog of ~400 GTM tools'), and scope ('by name'), and mentions the returned fields (cost, partner link). This clearly distinguishes it from sibling tools like search_content and 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 when to use the tool (searching for tools by name) but provides no explicit 'when not to use' or references to alternatives. It doesn't mention that get_tool_details may be needed for full details, so usage is only implied.

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 only says the tool 'starts' an audit and returns a questionnaire; it does not disclose any side effects (e.g., whether it persists state, triggers other processes), required inputs, authentication, rate limits, or response format. For a starting tool, one would expect information about whether it mutates anything or is purely diagnostic. The description is silent on these behaviors.

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 front-loads the primary action ('Start an adaptive GTM architecture audit') and the outcome ('return the smallest discovery questionnaire'). It is concise with no filler. While it is brief, it is efficient in conveying the core purpose without redundancy.

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

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

Given the tool has 4 parameters, no annotations, and no output schema, the description is notably incomplete. It does not explain the parameters, the nature of the collected questionnaire, the workflow context (e.g., that 'complete_stack_audit' might follow), or any prerequisites. An agent would have insufficient information to invoke it correctly, especially without guidance on what 'adaptive' means or how the inputs influence the output.

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 4 parameters (goal, stage, motion, systems). It does not mention any of them or their roles in producing the questionnaire. The phrase 'adaptive GTM architecture audit' gives a high-level hint but no concrete semantics for the inputs. This is a significant gap for a tool with no required parameters and zero 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 states a clear verb+resource: 'Start an adaptive GTM architecture audit' and 'return the smallest discovery questionnaire.' It distinguishes the tool as the entry point from siblings like 'complete_stack_audit' (which is the follow-up) and 'detect_stack_from_text' (which ingests text). However, it does not explicitly name a sibling or contrast itself, so it's clear but lacks explicit differentiation.

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

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

The description implies this is the first step in an audit workflow ('Start' and 'before KEEP, SWAP, or BUILD recommendations'), but it does not state when to use this versus alternatives like 'complete_stack_audit' or 'scan_stack'. There is no mention of exclusions, prerequisites, or conditions under which another tool should be chosen. Usage is implied but not explicit.

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 to fall back on, the description carries the full behavioral burden and does so well. It explicitly discloses that submissions queue for admin review, only propagate after merge, and do NOT immediately mutate the catalog. It also states the return value: a correction ID plus reassurance that the submission is queued.

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 action, supported by clear use cases, and includes necessary lifecycle and return-value details. The phrase 'Two-way data flow that helps keep the catalog accurate' is a filler value statement rather than operational guidance, but it does not hurt 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?

Given no output schema, the description compensates by stating what is returned (correction ID + queued reassurance). It covers the async admin-review lifecycle, enumerates accepted fields, and all six parameters are fully documented in the schema. An agent has enough to invoke the tool correctly.

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

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

Schema description coverage is 100%, and all six parameters are already well explained in the schema. The tool description mostly enumerates the field values that the schema enum already provides, so it adds little semantic value beyond the structured parameter descriptions. 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 opens with a specific verb and resource: 'Submit a correction to the StackSwap catalog,' and enumerates the targeted aspects (pricing, feature list, gotcha, AI-readiness score, category, or other). It also covers the edge case of reporting a tool not yet in the catalog, which distinguishes it from the search/compare/generate siblings.

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

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

The description provides explicit usage scenarios: stale price, inaccurate feature list, gotcha to flag, or reporting an uncovered tool. It does not name alternatives or state when not to use this tool, so it falls just short of a 5, but the context is clear enough for an agent to route the call correctly.

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

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

With no annotations, the description carries the full behavioral burden. It discloses that results are conditional ('when one exists'), includes annual savings and reasoning, and states the legacy→modern bias. It doesn't detail response format or multiple-result handling, but those are minor for this simple 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?

Two dense sentences with no filler. The main action and returned fields are front-loaded, and the parenthetical examples demonstrate the swap bias 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?

For one required parameter and no output schema, the description covers the parameter, the conditional result, the cost/savings data, and the reasoning output. It doesn't specify exact response shape or behavior for unknown inputs, but nothing essential is missing.

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

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

Schema coverage is 100% and the schema already describes 'tools' as names to evaluate. The description reinforces the per-tool iteration but doesn't add format or domain-constraint details beyond the schema. Baseline 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?

States a specific verb (return), resource (StackSwap's AI-native replacement recommendation), and required output (annual savings, reasoning). Examples and 'skews toward legacy → modern swaps' sharpen intent and distinguish it from comparison/audit siblings.

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

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

Clear context: take supplied tools and return AI-native replacement recommendations, which tells an agent when to choose this over general compare/audit tools. It does not explicitly name alternatives or conditions to avoid, so it stops short of a 5.

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