Kong Reviews

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

The description adds substantial behavioral context beyond the readOnlyHint=true and openWorldHint=false annotations. It explains per-service outputs, assumptions when plan_id is missing, verdict categories, savings, moving costs, payback month, scorecard weighting, and presentation instructions including showing caveats verbatim.

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 a clear purpose sentence and then adds output, usage, and presentation details. It is dense and long, but nearly every sentence contributes to calling or presenting the tool correctly.

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

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

For a complex 11-parameter analysis tool with an output schema, the description is behaviorally rich and explains assumptions and presentation. It is not fully complete on input parameter semantics, but the output schema and existing schema descriptions reduce that burden.

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 45% across 11 parameters, so the description must compensate. It adds useful semantics for plan_id fallback, vendor_id sourcing from detect_stack, and priorities weighting, but leaves many parameters such as mau_now, switching, budget_monthly_usd, revenue_per_mau_usd, profile_id, and unpriced largely unexplained.

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 and resource: assess an existing app's stack and recommend actions. It clearly distinguishes the tool from detect_stack by saying to use vendor ids from detect_stack, and it names the concrete outputs (verdicts, scorecard, ranked 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?

It gives clear context for use: existing apps, after detect_stack, with optional plan_id when the user knows their plan. It does not explicitly state when not to use it versus siblings like evaluate_change or diff_stack, but the workflow guidance is strong.

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

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

Annotations establish this is a non-read-only, open-world, idempotent, non-destructive operation. The description adds useful context beyond annotations: it explains that linking a repo can replace a prior linked repo, that private repos require the GitHub Reviews App, that sign-in is needed, and that repeated id-only calls recheck the same repo.

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 and every part serves a purpose, including presentation guidance. However, the opening sentence is a long run-on that packs several behaviors together and could be easier to scan if broken into shorter statements.

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 presence of an output schema, the description does not need to explain return values. It covers the key operational context an agent needs: linking behavior, auth requirements, drift handling, and how to present results.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful parameter workflow semantics: repo is needed the first time, id alone is enough afterward, and id comes from list_saved_stacks.

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: link a GitHub repo to a saved plan and check it. It then names the concrete outcomes—found/not-found services, drift, and plan-built status—so the agent can distinguish it from siblings like detect_stack and diff_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?

It explicitly explains the first call (pass id and repo) and subsequent calls (id alone rechecks the linked repo). It also gives handling guidance for drift and not-found services, including using get_build_pack and diff_stack, and notes sign-in and GitHub App requirements for private repos.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description still adds real value by disclosing the evaluation model: fit is assessed starting at each vendor's cheapest plan, and an upgrade result carries the higher tier's cost — telling the agent how the answer is derived, not just what comes back.

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 front-loaded sentence with no filler; the outcome categories are enumerated compactly. It is efficient, though its brevity comes at the cost of context rather than being the optimal size for a 9-parameter pricing tool.

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

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

With an output schema present, return-shape explanation is not required, and the description covers the core concept plus the cheapest-plan baseline. Missing for a tool this complex: that requirements must be capability ids from list_capabilities, how the usage profile/defaults drive tier qualification, and how it relates to sibling tools — meaningful gaps but not fatal given a rich 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?

Schema coverage is 67% with rich nested descriptions for per_user, per_1k_mau, profile_id, seats and payments fields, so the schema does most of the work. The description only echoes 'each vendor' (vendor_ids) and 'each requirement' (requirements) and adds no syntax or defaults beyond that; a 3 baseline is appropriate at mid coverage.

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

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

States a specific verb and resource: for each vendor, evaluate whether each requirement is met on its cheapest plan, requires an upgrade (with cost), or is missing. That is concrete enough to distinguish a requirement-fit check from sibling tools like compare_vendors or estimate_cost, though it never names those alternatives.

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?

No when-to-use guidance, no prerequisites, no routing to alternatives. An agent must infer that this belongs after extract_requirements/list_capabilities and instead of compare_vendors, and that vendor_ids and requirement capability ids come from other tools — none of which the description states.

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?

Adds context beyond the readOnly/openWorld annotations: ratings are deterministic ('No model is used'), partial answers still produce a ranking, ruled-out options come with reasons, and each architecture carries plan_stack_arguments and share_url. That is real behavioral detail an agent could not infer from annotations alone.

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 core purpose is front-loaded, but the body is one very long run-on paragraph with a multi-clause parenthetical question list and repeated 'call it again' instructions. It is dense and useful but would scan far better broken into purpose / workflow / output sections.

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 15-parameter, multi-turn, stateful tool it covers the interplay of description, answers, requirements, and forecast well enough to drive correct calls, and it repeats return contents even though an output schema exists. Minor gaps remain around defaults for optional params and how answers map to question ids.

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 73%, so the schema carries most param meaning, but the description supplies the crucial chicken-and-egg guidance that `answers` option ids are produced by this very tool's question output, and that `description` is read both for requirements and suggested answers. Several params (founder, budget, mau) get no mention, but are documented in 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?

States a specific two-part action (interview, then rate architectures), enumerates the candidate architectures and the ranked output shape, so an agent knows exactly what it gets back. It doesn't explicitly contrast itself with recommend_stack or plan_stack, though it links to plan_stack_arguments, leaving sibling differentiation implicit.

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

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

Gives an explicit, actionable protocol: call with description first, show the user the questions, ask unanswered ones a few at a time, call again with answers, and stopping early is fine. It also covers the later-requirement case (re-call with same answers plus new description/requirements). Only the comparison to sibling tools is absent.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely useful ranking behavior — must-haves first, then cheapest, 'cost and fit only' — but leaves unstated what happens with nice-to-have requirements (must:false), what an empty/no-match result looks like, and whether ranking is stable across identical costs.

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

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

Front-loaded with the core operation and ranking rule in two sentences, then a compact example. Slight redundancy between 'then cheapest' and 'ranking is by cost and fit only', but nothing is padded.

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?

An output schema exists, so return values needn't be described. But with 10 parameters, two nested override objects, and a profile system that interacts with per_user/per_1k_mau defaults, the description does not explain how those overrides layer. It is adequate for the common call and thin for the advanced ones.

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 60%, so roughly half the parameters are documented in the schema and several (category, mau, exclude) are bare. The single example clarifies the shape of the requirements objects and how category/mau combine, but says nothing about profile_id, per_user, per_1k_mau, seats, or exclude, which are the highest-complexity inputs. Partial compensation only.

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

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

States a specific verb and resource with scope: 'Rank vendors in one category at a given scale.' That is clearly distinct from siblings like check_fit, estimate_cost, or list_vendors, which either evaluate a single stack or enumerate data. It stops short of naming those alternatives explicitly, but the operation is unambiguous.

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

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

Use is implied by the ranking/scoping language and the sample call, but there is no explicit when-to-use or when-not, and no routing to close siblings such as check_fit (single stack fit) or recommend_stack. An agent must infer which of these to reach for.

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

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

Annotations already flag destructiveHint=true, but the description adds what the agent cannot infer: exactly what is destroyed (GitHub sign-in link and all saved stacks), that it is irreversible ("This cannot be undone"), and that authentication is required ("Needs sign-in").

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 tight sentences with the destructive action and its scope front-loaded, followed by the irreversibility warning, then the call conditions. 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?

An output schema exists so return values need no explanation, and the description covers the remaining agent-critical facts for a destructive single-parameter tool: scope of deletion, irreversibility, auth requirement, and confirmation-phrase handling.

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

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

Schema coverage is 0%, but there is only one enum-constrained parameter whose allowed value is already visible in the schema. The description still adds the operational meaning of that parameter — it acts as a consent guard that must be passed "exactly" as the enum string — rather than merely repeating the literal.

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

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

States a specific verb and resource ("Permanently delete the signed-in user's Kong Reviews account") and immediately scopes it to "their GitHub sign-in link and every saved stack", which distinguishes it from the sibling delete_saved_stack that removes a single 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?

Gives an explicit gating condition ("Only call it when the user explicitly asks to delete their account") plus a prerequisite conversational step ("after telling them what will be removed"). The scope wording also implicitly routes single-stack deletion to the sibling tool.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds real context the annotations don't: the deletion is permanent, it is scoped to the signed-in user's own stacks, and it requires sign-in. It doesn't cover what happens on an unknown id or whether dependent artifacts are affected.

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 short sentences with zero filler; the destructive verb and scope lead, followed by the call condition and the auth requirement in priority order.

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 destructive one-parameter mutation with an output schema and strong annotations, this covers safety, auth, and confirmation. The remaining gap is id provenance and not-found behavior, which is a modest omission rather than a blocking one.

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 the single `id` parameter, so the description carries the burden. It clarifies the id refers to the user's saved stack, but gives no format, no source (list_saved_stacks / get_saved_stack), and no behavior for a missing or malformed id.

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

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

States a specific verb and resource ("Permanently delete ... saved stacks") plus the scoping constraint ("one of the signed-in user's ... by id"), which cleanly separates it from get_saved_stack, update_saved_stack, and list_saved_stacks in the sibling set.

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

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

Gives an explicit gating condition ("Only call it when the user explicitly asks to delete that stack") and a workflow precondition ("confirm the name first"), which is genuine when/when-not guidance. It stops short of a 5 because it never names an alternative tool (e.g., get_saved_stack or list_saved_stacks) for locating the target.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds meaningful behavior beyond that: detection is rules-only, nothing is stored, and secrets should never be passed — but it says nothing about rate limits or how live-site probing behaves.

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?

Purpose is front-loaded in the first sentence and every subsequent clause is useful. It is a dense single paragraph, so it is slightly harder to scan than a structured list would be, but there is little 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?

An output schema exists, yet the description still sketches what comes back — catalogue vendors with evidence and confidence, unpriced services, frameworks and platforms — plus the concrete next step. 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?

Schema coverage is 75%, and the description goes well beyond it by enumerating which files matter (package.json, requirements.txt, .env.example, deploy configs) and constraining .env.example to names only. This gives an agent actionable selection guidance the schema does not.

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

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

States a specific verb and resource: work out which services an existing app runs on, from files, a repo, or a live site. It also distinguishes itself from audit_stack by positioning this as the detection step that feeds it.

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 clear invocation guidance: from an AI coding app, read the project yourself and pass the highest-signal files, then call audit_stack with the detected services. It lacks an explicit when-not-to-use or alternative-tool exclusion, so it falls just short of a 5.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, and the description reinforces this with 'Rules only; nothing is stored,' which is genuinely additive about determinism and side effects. It also discloses that output includes a PR-ready comment_markdown and 12-month forecast pricing, giving useful 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?

One dense paragraph, front-loaded with the core action and the input convention, then results and usage. It is packed but nearly every clause carries meaning; a small amount of length could be trimmed around the results list.

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?

An output schema exists, so return values need not be spelled out, yet the description still summarizes them helpfully. Given seven params and a diff-based workflow, the main residual gap is the unexplained plans/profile_id/requirements inputs, but overall an agent can call it correctly.

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

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

With schema coverage at 43%, the description compensates partly by clarifying what base_files/head_files should contain (manifest and config files, .env.example names only) and that pricing uses 'the given users' for mau inputs. However, the seven params include plans, profile_id, and requirements that the description never explains, so the coverage gap is only partially filled.

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

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

States a specific verb and resource: pricing what a code change does to an app's bill, by passing base_files and head_files. It clearly differentiates from siblings like estimate_cost or project_stack by framing it as a before/after diff for a pull request.

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 clear usage context: use before adding a paid service or SDK, or to review a pull request. It does not name an explicit alternative sibling (e.g. evaluate_change, estimate_cost) or state when-not to use it, leaving that inference to the agent.

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

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

With readOnlyHint=true and openWorldHint=false already covering safety, the description still adds a real behavioral rule: it auto-selects the cheapest fitting plan unless plan_id pins one. That is meaningful context an agent cannot get from annotations. It stops short of noting anything about pricing-data currency or how partial usage inputs are filled.

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 short sentences plus a concrete example, with the core purpose and the plan-selection rule front-loaded. Nothing is wasted, though the example is arguably redundant given the schema.

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?

An output schema exists, so return-value explanation is not required. But for an 11-parameter tool sitting among pricing siblings (get_pricing, compare_vendors, find_cost_cliffs, check_fit), the absence of any when-to-use-this routing leaves a real 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?

At 73% schema coverage the schema already documents profile_id, its enum-like values, revenue_per_mau_usd and transactions_per_mau, and the nested objects spell out their own override semantics. The description only restates the two input pathways, adding little beyond that 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?

"Monthly cost for one vendor at a given scale" gives a specific verb (estimate cost), resource (a vendor's pricing) and scope (single vendor, monthly). The single-vendor framing implicitly separates it from compare_vendors/compare_architectures, but no sibling is named outright.

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 tells the agent how to supply scale (mau + profile, or exact usage numbers) and the plan-selection default, which is usable invocation guidance. It never says when to prefer this over get_pricing, compare_vendors or find_cost_cliffs, so routing among the cost-related siblings is left 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?

Annotations already declare a safe read (readOnlyHint true, openWorldHint false), so the bar is lowered. The description still adds real behaviour: if a migration playbook covers the move and switching.hours is omitted, the switching cost uses the playbook's effort range rather than a flat 40 hours, and caveats must be reproduced word for word. A short note on what the output contains beyond the schema would push this higher.

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?

It leads with the trigger and the comparison, then the example, then the playbook caveat, then presentation rules, in a sensible order. Sentences are dense but each carries information. The presentation block is slightly long relative to the rest, but it earns its place by specifying output handling that the output schema does not cover.

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 output schema exists, so return values need not be described, and the description still covers the non-obvious behaviour of switching cost estimation. What is missing is guidance on precedence among the overlapping usage inputs (per_user, per_1k_mau, profile_id) for a 16-parameter tool, which an agent could easily get wrong.

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 56%, so some parameter work remains for the description. It usefully explains the interaction between migration_features, the playbook, and switching.hours, and its example shows category, current, mau_now, monthly_growth and requirements in context. Fault lines remain: with 16 parameters, the description says nothing about when to use per_user vs per_1k_mau vs profile_id, and nothing about what months or switch_to change in the result.

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: compare staying, optimising with the same vendor, and switching vendor, complete with one-off switching cost and payback month. That is far more specific than the title alone. It does not name its nearest siblings (compare_vendors, estimate_cost, recommend_stack), so an agent still has to infer the boundary between this and those 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 gives concrete trigger conditions: bill too high, growth, a missing feature such as SSO, or a renewal. Those are usable cues for when to reach for this tool. It does not say when not to use it, nor does it name the tool to use instead for adjacent questions such as raw cost comparison.

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?

Goes well beyond the readOnly/openWorld annotations by disclosing the degraded-mode behavior (keyword rules when no model is on the server) and the trust model for the returned vocabulary/instructions. It does not mention max input size or rate/limit behavior, and the reference to 'mode "rules"' is slightly opaque since no such parameter exists in the schema.

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 first three sentences are tight and front-loaded, but the final sentence is a long compound thought that mixes fallback behavior, return payload, and agent instructions, making it harder to parse than it needs to be.

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?

An output schema exists, and the description still adds enough about extraction scope, provenance quotes, and the rules fallback for an agent to call it correctly and use the result. The main remaining gap is input-side guidance for prd_text.

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 the single parameter prd_text, and the description does not describe its expected format or the 60,000-character limit. It does usefully describe the output shape (requirements quoting source sentences) but says little about the input itself.

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+resource ('Turn PRD or spec text into structured requirements') and enumerates the extracted dimensions (scale, capabilities, compliance, regions, budget). It explicitly bounds scope ('without planning') and names the sibling that combines both steps, so it is distinguishable from recommend_stack and plan_stack without opening either schema.

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

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

Explicitly positions the tool against recommend_stack ('does both in one call') and against plan_stack ('for plan_stack, without planning'), and adds a workflow rule: show extracted requirements to the user for confirmation before planning. It also tells the assistant to prefer doing extraction itself and treat the rules output as a starting point.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuine behavioral value by specifying what it reports (forced plan upgrades, points where usage charges start), which goes beyond the annotations. It stops short of detailing computational cost or how discontinuous ranges are sampled.

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: purpose is front-loaded, and the example immediately grounds the abstract 'range of user counts' in concrete parameters. 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?

An output schema exists and the nested per_user/per_1k_mau semantics are well documented in-schema, so the description needn't restate returns. For a 10-param nested tool it covers purpose and range well, though the profile-vs-per_user-vs-per_1k_mau relationship is left entirely to the schema.

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

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

Schema coverage is 60%, and the example concretely illustrates from_mau/to_mau, which are undocumented in the schema itself. But the description says nothing about the interaction among profile_id, per_user, per_1k_mau, seats, and required, leaving the more complex nested override parameters to the schema alone.

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

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

States a specific verb and resource (scan a range of user counts for one vendor) and precisely what it outputs: forced plan upgrades and points where usage charges start. This crisply distinguishes it from the generic estimate_cost/project_stack siblings by focusing on discontinuities rather than a single cost figure.

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 scope 'scan a range of user counts for one vendor' implies when to use it (to locate cliff points), and the from_mau/to_mau example reinforces the range concept. However, it never names an alternative such as estimate_cost or says when not to use this versus a single-point estimate, leaving the sibling choice 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?

readOnlyHint and openWorldHint already tell the agent this is a safe, closed-world read, so the description only needs to add context. It does add that qualification is computed from bank, incorporation provider, accelerator, and funding signals, but says nothing about result shape, whether unqualified vendors are returned, or how vendor ids should be sourced.

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 compact sentences plus an example, all of which carry information; the eligibility drivers are front-loaded. The opening fragment is slightly awkward and the embedded JSON example makes the sentence harder to parse than a plain enumeration would.

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 lookup whose return shape is documented by an output schema, this is nearly sufficient, but it never explains where vendor ids come from (list_vendors / search_directory) or what happens when vendor_ids is omitted. Those gaps matter for an agent deciding how to call 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 coverage is only 50%, and the description compensates by explaining what the founder object is for: gating on bank/incorporation provider/accelerator (the gateways array) and funding stage (venture_backed/arr_usd). The inline example also clarifies the expected id format and nesting. It does not explain existing_customer_of, which the schema covers anyway.

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

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

The description names the resource precisely: startup credits for a list of vendors plus an eligibility determination. It lacks an explicit verb ("Startup credits for..." is a fragment), but the result an agent gets back is unambiguous and no sibling tool operates in this space.

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?

Usage is only implied: pass vendor ids and optional founder attributes to get credits and qualification. There is no statement of when to prefer this over nearby tools (e.g., list_vendors, search_directory to obtain ids) and no prerequisite or exclusion 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?

Adds real context beyond readOnlyHint/openWorldHint: the two auth modes, the builder_profile non_developer variant where KONG.md becomes a single paste-in prompt, and the privacy guarantee that variable values never pass through Kong Reviews. The 'write KONG.md into the project root' instruction is agent-side file I/O, not a contradiction of readOnlyHint.

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

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

Front-loaded with what the pack contains (the highest-value information), then invocation, then next actions. Dense but every clause carries content; the long parenthetical service list is the only slightly heavy part.

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?

Output schema covers return values, so the description's job is inputs, auth, and post-call workflow — all present. For a zero-required-parameter read tool it leaves nothing an agent needs to call it or act on the result unresolved.

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 already 100%, so baseline is 3; the description adds the sign-in distinction for share_url vs id and the framework default implied by the builder_profile note. It does not add framework-selection detail (reading package.json), which lives in 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?

Names a specific resource (the build pack for a planned stack) and enumerates exactly what it contains: decisions with runner-up and cost, ordered setup steps, .env.example variable names, KONG.md, acceptance checklist and cost guardrails. An agent knows precisely what comes back without opening the output schema.

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

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

Gives the two invocation paths with their auth conditions (share_url = no sign-in, id from list_saved_stacks = needs sign-in) and states the follow-on workflow: write KONG.md and .env.example to project root, then walk the steps with the user. No explicit when-not or named alternative sibling, so not a 5.

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

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

The readOnlyHint and openWorldHint=false annotations already establish that this is a safe, closed-corpus read, so the description's job is only to add context. It does contribute provenance signal ('source URL and verification date') and scope signal ('unmodelled costs', 'lock-in notes'), but most of the enumerated fields restate what the output schema already declares.

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?

One front-loaded sentence that names the resource and scope before enumerating payload contents. The field list is dense but every item signals scope rather than padding; a fragment structure is acceptable for a reference tool.

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

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

With an output schema and read-only annotations in place, the description only needs to convey scope and payload character, which it does. The one meaningful omission is how to obtain a valid vendor_id, which an agent calling a single-vendor lookup will need.

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

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

There is a single required parameter at 0% schema description coverage, so the description must carry the load and it only implies that vendor_id is a single-vendor identifier via 'one vendor'. It does not say the expected format, whether it must come from list_vendors or search_directory, or what happens on an unknown id.

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 structured pricing and capabilities) and a specific scope (one vendor), which separates it from list_vendors and compare_vendors at a glance. It stops short of naming those siblings explicitly, so the differentiation is implied by scope rather than 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?

Usage is only implied by the phrase 'for one vendor', which suggests this is the single-vendor lookup as opposed to the multi-vendor comparison siblings. There is no explicit when-to-use, when-to-use-instead (e.g. compare_vendors vs estimate_cost), or guidance on where the vendor_id comes from.

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

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

Annotations only say readOnlyHint=true and openWorldHint=false, so the description adds real value by disclosing 'Needs sign-in', the confirmed/answers flow, and the fact that it re-plans on answers. It also constrains the agent ('Do not add vendors or prices that are not in the result'), which is behavior beyond the annotations. It stops short of full disclosure since rate limits, error modes and pagination are unaddressed.

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 purpose is front-loaded, but the remainder is a long run-on chain of presentation rules and caveat instructions that buries key operational facts (sign-in, id source) mid-stream. Much of the presentation guidance belongs in the output schema or a separate presentation spec, not the tool definition.

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 annotations and an output schema present, the description does more than required: auth requirement, sibling routing, answer persistence, and output-shaping rules. Gaps remain around the undocumented optional parameters and around whether the re-plan step mutates anything, but for a read-only call this is close to 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 75% with three of four parameters documented, so the schema already carries most parameter meaning, supporting the baseline 3. The description adds value only for id (take it from list_saved_stacks); it never mentions bills_month, task_intent, or output_destination, and confusingly names per_user, revenue_per_mau_usd and builder_profile, which are not parameters of this tool.

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

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

The opening sentence gives a precise verb+resource+scope: re-run a saved stack or audit against today's catalogue and diff it against the saved snapshot. It is clearly distinguishable from list_saved_stacks (source of the id) and update_saved_stack (persists answers), so an agent can route without opening 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?

Explicit trigger ('when the user asks about a stack they saved, or whether prices moved') plus a concrete prerequisite ('Pass the id from list_saved_stacks') and named sibling for follow-up writes. This is genuine when/how/with-what guidance rather than a vague hint.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds only domain context (these IDs are referenceable by requirements); it says nothing about whether the full ID set is returned, ordering, or pagination.

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 front-loaded sentence with the verb and resource first, followed by disambiguating categories and examples. No filler.

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

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

The output schema exists, so return values needn't be explained, and the purpose is clear. But with an undocumented filtering parameter and no guidance on scope (full catalog vs filtered subset), the definition is only adequate.

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

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

There is one parameter, 'category', with 0% schema description coverage, and the description never mentions it or explains how filtering by category relates to the listed category groups. The burden of documenting that parameter falls entirely on the description and it is unmet.

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 (list) and resource (capability ids) and disambiguates with parenthetical categories (features, compliance, regions) plus concrete ID examples like auth.saml_sso. It doesn't name a sibling tool, but the meaning is unmistakable against list_vendors or search_directory.

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 phrase 'that requirements can reference' implies the tool is used before writing requirements or fitting a stack, but there is no explicit when-to-use, no prerequisites, and no mention of alternatives such as searching the directory.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds real context beyond that with the auth requirement ("Needs sign-in") and the newest-first ordering. It doesn't address empty-state or volume limits, 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?

Three tightly packed sentences: what it returns first, then when to invoke it with the sibling hand-off, then auth and presentation. Every sentence carries information an agent would otherwise have to guess.

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

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

For a zero-parameter read tool with an output schema, the description supplies the trigger conditions, auth prerequisite, ordering, and even a presentation recipe. Nothing needed to select or invoke it correctly is missing.

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

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

Zero parameters, so the schema baseline of 4 applies and there is nothing for the description to disambiguate. The description correctly implies no filtering or paging inputs are required.

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

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

States a specific verb and resource plus scope: lists the signed-in user's saved stacks, newest first, with cost and link. This is clearly distinguishable from get_saved_stack (single item) and save_stack/delete_saved_stack, which appear in the 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?

Names concrete trigger phrases ("my stacks", "the stack I saved", a stack by name) and explicitly routes to get_saved_stack when the user wants one specific stack. Both the when-to-use and the alternative are stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description confirms the closed 'pricing catalogue' scope, consistent with openWorldHint=false, but adds nothing about result volume, pagination, or ordering. An output schema exists, so return-shape disclosure is not required.

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 well-formed sentence with the action front-loaded and the filter trailing as a qualifier. The parenthetical enum is space-consuming and, given its incompleteness, does not fully earn 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 one-optional-param read tool with annotations and an output schema, most structured burden is already covered. What remains missing is sibling routing (compare_vendors, get_pricing) and a correct/complete category enumeration, leaving the definition merely adequate.

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

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

Schema description coverage is 0%, so the description should carry the parameter burden, but the enumerated category list omits six valid enum values present in the schema (storage, video, sms, push, jobs, search). That partial list actively risks misleading the agent into thinking those categories are invalid, so it adds no meaning beyond the enum and slightly subtracts.

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

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

States a specific verb and resource ('List vendors in the pricing catalogue') with the optional category filter, so the agent knows exactly what it returns. It does not distinguish itself from siblings like compare_vendors, search_directory, or get_pricing, which is the only thing keeping it from a 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?

Usage is only implied: the word 'optionally' signals that the category parameter is a filter, but there is no explicit when-to-use guidance and no mention of when to prefer compare_vendors, get_pricing, or search_directory instead. An agent can infer this is the catalogue-browsing entry point, but must guess.

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?

Goes well beyond readOnlyHint/openWorldHint: states that nothing is deployed or stored, that the person deploys the spec themselves, that the old site stays live until cutover is proven, and that verdicts may legitimately recommend staying. It also dictates output ordering and the 'word for word' caveat rule, which is real behavioral context an annotation cannot carry.

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

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

Front-loaded with purpose, then the returned artifacts in order, then the presentation rules. Dense but each clause carries information; the 'How to present' section is long and arguably agent-instruction rather than definition, which keeps it from a 5.

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 20-parameter, read-only, open-world analysis tool with an output schema, the description covers inputs sources (repo, text, files, saved id), key defaults, the ordered artifacts, and the no-side-effects contract. Nothing needed 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?

Schema coverage is already 80%, so baseline is 3; the description adds meaning on top by explaining that `features` carries dashboard-only capabilities (netlify-dns, forms, deploy-previews) and that `id` reuses a saved audit's users and plan. The remaining 20 params (per_user, per_1k_mau, seats, months, growth) are left entirely to 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?

Names a specific verb and resource (plan moving an app from one host to another), states the supported playbook (netlify → digitalocean-app-platform), and references the sibling it shares an input mode with ('as detect_stack does'). An agent can distinguish it from detect_stack, estimate_cost, or plan_stack without opening the schema.

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

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

Clear about the trigger context (the person wants to move hosts) and tells the caller to pass dashboard-confirmed feature ids in `features`, plus notes 'staying is a valid answer'. It does not explicitly exclude or route to adjacent tools such as estimate_cost or plan_stack, so the when-not guidance is incomplete.

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

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

Annotations already declare this is a read-only, closed-world planning call, yet the description still adds real behavioral constraints: never invent vendors or prices, reproduce caveats verbatim, flag unverified seed data, and link share_url so results live on kongreviews.com. The one gap is that it doesn't say anything about cost or latency for a 27-parameter computation over pricing data.

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?

Purpose and the sibling exclusion are front-loaded, and nearly every sentence is actionable. It is still a dense single block that mixes invocation guidance with output presentation rules and a raw JSON example, which makes it harder to scan than a short segmented description would be.

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 27-parameter planning tool with nested usage overrides, an output schema already present, and a multi-turn interview workflow, the description covers what an agent needs: the input contract, the ask-then-re-plan loop, how to record confirmations, and what to surface from the result. Nothing essential to calling it correctly is missing.

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

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

Schema coverage is 74%, so most parameters are self-documenting, but the description adds cross-parameter semantics the schema cannot express: interview answers are re-submitted into 'the argument each names (per_user, revenue_per_mau_usd, builder_profile)' and confirmed question ids go into `confirmed` so they aren't re-asked. The embedded example call anchors the requirements/founder/mau_now combination. It does not touch many of the pricing-override objects, but those are covered in 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?

States a specific verb and resource plus the full output shape: 'recommend a vendor per category with a runner-up, requirement fit, cost now, cost at forecast scale, year-one cost after perks, cost cliffs, trade-offs and blockers.' It explicitly separates itself from the closest sibling, recommend_stack, by input type (confirmed capability ids vs. plain-language description).

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

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

Gives an explicit when-not with the alternative named: 'Use recommend_stack instead when you only have a plain-language description.' It also routes downstream work to specific siblings with argument names ('keep answers with update_saved_stack (answers)'), so the agent knows the handoff points as well as the entry condition.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral detail beyond annotations: the output includes cost cliffs such as forced plan upgrades, sharp jumps, and credits expiring, which tells the agent what to expect. It does not state pagination, cost model assumptions, or currency.

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?

One dense sentence front-loads the purpose well, but the trailing example dominates the length and only illustrates a subset of the 13 parameters. The raw JSON example is useful yet not the most token-efficient way to convey it; overall it's adequate but not tight.

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?

This is a complex 13-parameter nested tool with an output schema, so the description must carry modeling semantics. It covers projection, growth, perks, and cliff detection, and the example anchors the vendor/founder shape. It omits how vendor plan_id/required interact with the pricing model and how per_user competes with per_1k_mau, leaving minor 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 69%, and the schema itself carries the rich per_unit/per_1k_mau unit lists and profile enums. The description's main contribution is a worked example showing vendors as objects with vendor_id, plus founder.gateways, which clarifies two under-documented required/nested spots. It says nothing about per_user vs per_1k_mau precedence or how apply_perks interacts with founder.existing_customer_of.

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+resource: month-by-month cost projection for a whole stack as MAU grows, plus cost cliffs. This distinguishes it from estimate_cost (point-in-time) and find_cost_cliffs (cliff-only) by combining projection + cliffs. It doesn't explicitly name those siblings, so it falls short of a 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 word 'stack' and 'as users grow' implies usage for multi-vendor growth projections, and 'with startup perks applied if requested' hints at when to set apply_perks. But there is no explicit when-to-use-this-vs-estimate_cost/find_perks/plan_stack guidance, no prerequisites, and no 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?

The description discloses substantial behavior beyond the annotations: it explains assumptions, defaults_used, question flow, confirmed assumptions, caveats, alternatives, share_url, and that it must not invent vendors or prices. This is rich transparency for a read-only, open-world recommendation tool.

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

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

The description is long and dense, but it is front-loaded with the core action and organized as a workflow. Most sentences carry actionable guidance, though the volume of presentation instructions makes it less concise than ideal.

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, 19 parameters, output schema, and rich annotations, the description is complete enough for an agent to call it correctly. It covers input guidance, assumption handling, output presentation, caveats, alternatives, and follow-up routing to plan_stack and update_saved_stack.

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?

Although schema coverage is already high at 89%, the description adds important semantics such as which numeric arguments override text, how per_user and confirmed behave, how build_tool affects category planning, and how answers map back to specific arguments. This goes well beyond the schema’s field-level 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 opens with a clear verb and resource: 'Describe the product ... and get a recommended stack with costs now and at scale.' It also distinguishes this from the sibling plan_stack tool by saying 'Start here' and describing the workflow of confirming requirements before calling plan_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?

It explicitly tells the agent when to use this tool and how it fits with alternatives: start here, pass a PRD if available, confirm requirements, then call plan_stack with corrected requirements. It also says to use update_saved_stack for saved stacks, giving 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 readOnlyHint=false already set, the description still adds substantial disclosure: sign-in requirement, that a new bill replaces the earlier one for the same service/month (idempotent, matching idempotentHint), that remove deletes a month or a single service, that alerts can trigger an outbound email, and that a >20%/$5 gap gets flagged. Note the mild tension with destructiveHint=false given 'remove deletes a month', but this is record-level cleanup of bill entries rather than account data loss, so it does not read as a contradiction.

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 content is dense and mostly earns its place, but it arrives as one long run-on paragraph with stacked parentheticals, so key facts (mode selection, replacement semantics, return shape) are hard to scan. The trailing 'How to present' instruction is useful but adds further bulk without any structural separation.

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 7-parameter, nested-object, multi-modal tool with an output schema, this covers auth, write semantics, side effects and mode selection thoroughly. Return values are re-described despite an output schema existing, which is redundant rather than harmful; the remaining gap is error/partial-failure behaviour for CSV or invoice parsing.

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?

Goes well past the 71% schema coverage: it specifies the bills item shape (month as YYYY-MM, vendor_id or invoice name, amount_usd), what columns the csv must contain, that invoice_text is pasted PDF/email text from which service/month/total are extracted, and that preview only reads without saving. It also clarifies the id-absent behaviour and the month default, which the schema only partially carries.

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

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

States a specific verb and resource ('Record what the user actually paid each service in a month, on one of their saved stacks or audits') and the downstream comparison against the estimate. An agent can distinguish this from estimate_cost, plan_stack or project_stack without opening the schema, since this is the only one that ingests actual invoices/bills.

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?

Clearly routes the three input modes (bills, csv, invoice_text) and the id-less variant ('the bills are kept on the account, not on a stack'), plus the preview/remove sub-modes. It also tells the agent to offer update_saved_stack afterwards when the real user count differs. It never explicitly says when NOT to use it (e.g. use estimate_cost for hypotheticals), but the context is unambiguous.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent write, and the description adds auth behavior (sign-in required, the app will prompt to connect an account) plus the post-save lifecycle (reopenable, comparable against current prices, eligible for price alerts). It does not say what happens when the same stack is saved twice, which matters because idempotentHint=false — a minor but real 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 core action and accepted inputs are front-loaded, followed by the follow-up workflow, the auth caveat, and finally the gating rule. Most sentences carry weight, though the account/auth sentences could be tightened slightly without losing meaning.

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 nested-object write tool with an output schema, the description covers everything needed to invoke it correctly: which inputs to pass and in what order of preference, naming guidance, auth preconditions, the recommended downstream call, and a usage gate. Return values are handled by the output schema, so their absence from the description is appropriate.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds genuine precedence semantics not encoded in the schema: share_url is preferred and plan is the fallback when no share_url exists, and plan is defined as 'plan_stack arguments'. It also illustrates the name parameter with a concrete example.

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 (save) and resource (a recommended stack or app audit) and names the destination account, making clear it is a persistence operation distinct from generation siblings like recommend_stack, plan_stack and audit_stack. The distinction from update_saved_stack is also implied via the follow-up instruction.

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

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

Gives an explicit trigger condition ('Only save when the user asks to keep or save a stack'), names the preferred input source (share_url from recommend_stack/plan_stack/audit_stack) with a documented fallback (plan_stack arguments), and prescribes the natural next step (offer update_saved_stack with alerts: true). Alternatives and exclusions are both present.

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

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

Beyond the readOnly/openWorld annotations, it discloses meaningful behavior: candidate entries carry no prices, results may include availability flags (acquired, shutting_down) plus admin_note with an instruction to surface them, and closed services are excluded by default. It stops short of describing result ordering or pagination behavior, which keeps it at a 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 capability and its differentiation from the cost engine are front-loaded, followed by edge-case rules and an example. It is dense but not padded; the only slight drag is the long enumeration of categories and the closing example sitting mid-paragraph.

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 8 params, an output schema present, and annotations covering the safety profile, the description supplies everything else the agent needs: scope, filtering defaults, status semantics, and how to treat availability metadata. Nothing required 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?

Schema coverage is 75%, so the schema carries most parameter meaning; the description adds value on top by explaining candidate vs. researched semantics, the default exclusion of closed services, and a worked example ({"query":"postgres","category":"database"}). It does not elaborate on id, limit, or offset, but those are self-documenting in 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 states a specific verb and resource ("search the directory of developer services") and enumerates the covered categories, then explicitly positions it against the cost-engine siblings. An agent can distinguish it from estimate_cost, plan_stack, or compare_vendors without opening any schema.

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

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

It names the selection condition directly: use it "to find options or check a provider the other tools don't price," and notes it is "wider than the cost engine." It also gives concrete when-to-use rules for edge cases (candidate entries, include_closed, availability/admin_note disclosure).

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

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

Annotations already declare this as a safe read-only operation, so the description focuses on behavior beyond safety: results include filter-value counts, and service links connect to the directory and cost engine where priced. It does not discuss pagination behavior or rate limits, but with annotations carrying the safety profile this is a useful addition.

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 text is front-loaded with what is browsed and what each result contains, then moves to usage and an example. It is dense but every sentence contributes; there is little 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?

With 10 optional parameters, an output schema, and read-only annotations, the description is sufficient for an agent to understand the search surface and invoke it. It could be stronger by naming the closest sibling alternative, but no critical information 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 60%, so several parameters are documented but not all. The description adds an example combination ({tech: supabase, form: app}) and notes that results list filter values with counts, but it does not explain fields such as pricing, category, limit, or offset beyond schema enums/defaults. It adds only modest value over 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 a specific verb and resource: browse/search startup-built products and the stack each runs on. It enumerates the dimensions returned (form, category, pricing, frameworks/services), which distinguishes it from generic directory search. It does not explicitly contrast itself with sibling search_directory, so it falls short of a 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?

It gives a clear use case (“find real stacks to learn from, e.g. apps built with Supabase”) and an example query. However, it does not state when to use this instead of search_directory or recommend_stack, nor does it give 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?

Adds substantial context beyond the annotations: updating users re-prices the stack and resets the projection start to today, and enabling alerts triggers daily monitoring with three specific email conditions. It also discloses the auth/email-confirmation requirement (GitHub sign-in shares no email), which is exactly the kind of operational detail annotations cannot express.

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

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

Front-loaded with the core action and the field list, with the caveats following. The alerts paragraph is long — three distinct email triggers are more than an agent needs to invoke the tool — but it is dense and free of 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?

Output schema exists, so return values need no explanation, and the description covers side effects, auth and per-entity field applicability. Minor gap: `answers` (a large nested object that re-prices the stack) and `unlink_repo` (which destroys the linked repo check) are only covered inside the schema, not in the description.

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 already 80%, yet the description disambiguates the two easily-confused user fields (mau_now = today, mau_forecast = end of projection, 12 months for audits) and explains build_progress/migration_progress scope. It does not mention unlink_repo or the answers object, leaving those to 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?

States a specific verb plus resource ('Change one of the signed-in user's saved stacks or audits') and enumerates exactly what is mutable: name, mau_now, mau_forecast, alerts, build_progress, migration_progress. It also scopes which fields apply to which entity ('for plans' vs 'for audits'), which no sibling tool name conveys.

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 clear preconditions and gating rules: 'Needs sign-in', alerts require a confirmed email, and the email confirmation link must be requested first. It lacks an explicit 'use this instead of save_stack/plan_stack when…' routing sentence, so the agent must infer the edit-vs-create boundary from sibling names.

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