Krawlup

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

Beyond the annotations, it discloses the scrape source and fields (name, tagline, description, icons), the override precedence, the permission prerequisite, and the non-publishing side effect — substantial behavior for a mutation tool. The one tension is that scraping an arbitrary external URL reads as open-world activity while annotations declare openWorldHint=false; the description does not resolve that mismatch.

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

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

Four tight sentences, front-loaded with the one required input, then override rules, then the publishing caveat, then the permission prerequisite. No sentence is filler; each adds a distinct constraint.

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 six-parameter mutation with no output schema, it covers preconditions, side effects, and field precedence well. The only gap is the return value — it says the product lands on the founder's dashboard but not what identifier or object comes back, which matters for chaining into set_product_public.

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 per-field meaning and limits are already documented; the description still adds value by explaining precedence ('explicit values override the scrape') and the omit-to-scrape semantics that govern all five optional fields. It does not, however, add anything about url normalization or category id formats beyond the schema.

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

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

The description states a specific verb and resource ('Add a product') plus the minimal input ('from just its URL'), and explains the scrape-and-attach behavior that distinguishes it from list_products or get_product. An agent can tell immediately that this is the creation entry point.

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

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

It states explicitly that only the URL is required and all other fields are optional, that explicit values override scraped values, and that adding never publishes — routing the agent to set_product_public (or the founder) for publication. It also names the prerequisite ('Requires the submit permission'), which tells the agent when the call will be rejected.

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 readOnly=false, idempotent=true, destructive=false, so this is a safe additive write. The description adds real context beyond those annotations: the scanner re-checks tracked keywords on its passes and top-10 positions feed the rank history, plus the KEYWORD_TRACK_CAP limit and the scope requirement. It doesn't say what happens when the cap is exceeded (error vs. silent truncation), which is the one meaningful 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?

Two dense sentences, front-loaded with the core action, followed by the consequences and the auth prerequisite. No filler or restatement of the tool name.

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 two-parameter mutation tool with no output schema, the description covers the action, the cap, downstream effects, and the auth scope. What's missing is the observable outcome: whether the call returns the accepted keywords, skips duplicates silently, or fails when the cap is reached.

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

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

Schema description coverage is 100%, so both productKey and keywords are already documented, including the trim/lowercase/dedupe normalization. The description adds only the cap concept, which is stated in terms of KEYWORD_TRACK_CAP rather than the array's maxItems of 100, so it does not materially deepen parameter meaning.

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

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

The description states a specific verb and resource ('Adds keywords to a product's rank-tracking board') and ties the resource to the downstream consumer ('the rank history get_keyword_ranks reads'). That makes it distinguishable from remove_tracked_keywords and from the read-side siblings without needing 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?

The description gives clear operational conditions: the per-product cap and the required 'rescan' key scope. It does not explicitly name an alternative tool or say when not to add keywords (e.g., duplicates already tracked), so it stops short of full 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?

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds real value by disclosing the audit dimensions (bans, blocked platforms, existing-product ownership, category list) and the fact that it is a pre-flight gate rather than a mutation. It does not mention rate limits, auth requirements, or the shape of the verdict returned.

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 short sentences, front-loaded with the verb and the checks, with the sequencing instruction placed last where it is most actionable. The opening phrase "before adding it to krawlup" partially duplicates the closing "Run this before add_product," so a few words are redundant.

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 one parameter, no nested objects and no output schema, the description should say roughly what the audit returns (a pass/fail verdict? a list of blocking reasons?) so the agent knows how to act on the result before calling add_product. It explains what is inspected but not what comes back, leaving a meaningful gap for a pre-flight gate 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?

There is a single required parameter with 100% schema description coverage, so the schema already carries the parameter burden and the baseline is 3. The description adds no format or validation detail for the URL, and "the optional category list" is not a parameter at all, which slightly muddies rather than clarifies the input surface.

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 a specific verb (audit) and resource (a URL / prospective product) and enumerates exactly what is checked: bans, blocked platforms, existing product and ownership, and the optional category list. That is enough to distinguish it from add_product and from search_products 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?

"Run this before add_product" gives an explicit ordering constraint and names the sibling it precedes, which is exactly the routing cue an agent needs. It stops short of a full when-not rule (e.g. what to do if the audit reports a ban or an existing owner), so it is strong but not exhaustive.

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/non-destructive/closed-world annotations, the description discloses substantive behavior: windowed figures are computed identically to the dashboard, lifetime visitors are an HLL estimate with ~1.6% error, lifetime revenue comes from the payments ledger, and gated columns return null with a note rather than failing. The null-instead-of-error behavior is exactly the kind of detail an agent needs to interpret partial results.

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 is a single dense paragraph, front-loaded with the deliverable and then the data-provenance caveats, with no filler sentences. Some content duplicates the schema (the window list, the rolling-window definition), which costs a little efficiency but keeps the description self-contained.

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

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

With no output schema, the description carries the return-value burden and does so: it enumerates the columns, states that products and scores are always present, and explains that gated columns come back null with a note. For a four-optional-parameter read tool, nothing an agent needs in order to call it or interpret the response is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning: it lists the metric set that sortBy/order operate over and clarifies that products missing the chosen metric sort last. The window semantics are already spelled out in the schema, so the description's added value is incremental rather than essential.

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 (all your products, side by side) and enumerates the exact metrics returned — unique visitors, views, revenue with refunds netted, ARPC, RPV, scan scores — so an agent knows precisely what this produces. It stops short of explicitly differentiating itself from list_products, search_products, or get_product, leaving the comparison-vs-listing distinction to inference.

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 metrics roster and sorting capability suggest it is for multi-product metric comparison rather than single-product lookup or search. There is no explicit statement of when to prefer this over list_products or search_products, and no stated exclusions or prerequisites beyond the subscription gating note.

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 readOnly=true, destructive=false and closed-world, so the safety profile is covered. The description adds genuinely new behavioral detail the annotations cannot carry: the return contains two lines, the site token is already embedded in data-site, and data should appear in the dashboard Website tab within a minute of the first visit — a verification loop an agent would otherwise lack.

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 compact blocks: purpose, handling instruction, verification step. Purpose is front-loaded and each sentence carries an action an agent needs. The lack of sentence-terminating punctuation on a multi-clause first sentence makes it slightly dense, but there is no filler.

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

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

With no output schema, the description must characterize the return value and does so well (the script tag, both lines, embedded token). For a one-parameter read tool with full annotation coverage this is nearly sufficient; the only remaining gap is the absence of any alternative-tool routing or handling of a product without a website.

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 parameter with 100% schema description coverage ('The product key (see list_products)'), so the schema does the documentation work. The description adds only indirect meaning via 'a product's own website' and does not explain what happens if the product has no site configured; baseline 3 applies.

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

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

The description names the concrete artifact ('the exact <script> tag that installs krawlup first-party analytics') and what it measures (visitors, sessions, pages, referrers, countries, conversion goals), so an agent knows precisely what it gets back. It falls short of 5 because it never distinguishes itself from the sibling get_analytics_token, which an agent could reasonably confuse with 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?

It gives a clear context of use — installing analytics on a product's own website — and procedural directives about inserting both lines and never asking the founder to paste the token. It never states when NOT to use it or points to the alternative (get_analytics_token) for a raw token need, so routing between 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 readOnlyHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds non-obvious context the annotations cannot convey: the token is not a secret because it ships in page source by design, and it duplicates what get_analytics_snippet returns. It does not say what happens if a product has no analytics tag configured, which keeps it from a 5.

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

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

The core identity and the token value are front-loaded, and each clause carries information (what it is, that it is not secret, where it already exists, when to use it). The final sentence is a list of three usage modes that could be tightened, but nothing is 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?

For a one-parameter read tool with no output schema, the description covers what is returned ('the data-site value'), where it comes from, its secrecy status, and the alternatives. An agent has everything needed to call it correctly and to explain the result.

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

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

Schema coverage is 100% and the single productKey parameter is documented in-schema with a pointer to list_products. The description only implies the one-product scope ('for one product') and adds no format or validation detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific resource and scope: 'The raw analytics site token for one product — the data-site value inside the krawlup analytics tag.' It explicitly distinguishes itself from the sibling get_analytics_snippet by noting the token is already embedded in that snippet, so an agent can choose between them without opening a 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 concrete when-to-use conditions — hand-written tags, the @krawlup/analytics-tag npm package, custom integrations — and implicitly routes snippet-based setups to get_analytics_snippet. It also pre-empts a common misuse ('never ask the founder to paste the token'), which is genuine operational 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?

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), so the description's added value is the null-when-absent contract and a sketch of the returned payload (why/impact/steps plus agent prompt). That is meaningful behavior beyond the annotations, though it says nothing about what happens with an invalid productKey.

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 sentence, front-loaded with the resource and scoped to a single product, with no filler. The parenthetical payload summary is dense but earns its place by describing the return shape.

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

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

With no output schema, the description carries the burden of describing returns and does so adequately, including the null case and the payload contents. Minor gaps remain around failure behavior for a bad key, but an agent has enough to call it correctly.

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

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

Schema coverage is 100% and the single productKey parameter is documented in the schema with a pointer to list_products. The description only says 'for one product', adding no format or resolution detail beyond the schema, so the baseline 3 applies.

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

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

The description states a specific verb+resource: retrieving the stored AI bottleneck analysis for a single product. It implicitly separates itself from generation-style siblings by emphasizing 'stored' and 'null if not run yet', though it never names an alternative tool 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?

The phrase 'or null if not run yet' hints that this only reads pre-computed analysis and something else must produce it, but no sibling (e.g. get_fix_cards, get_insights, check_launch_readiness) is named as the alternative. Usage is implied rather than 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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds non-annotation context beyond that: the entitlement gate on the plan's ai_fix_cards facility and the fact that each card carries what/why/steps/agent prompt. It stops short of saying what happens on an unentitled plan, but the gating statement implies a refusal.

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, zero filler, with the core capability front-loaded before the prerequisite. The parenthetical card breakdown is compact and information-dense rather than redundant.

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

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

For a single-parameter read tool with full annotation coverage, the description supplies what matters: scope, return contents, and the entitlement requirement. Only minor gaps remain, such as failure behavior or volume/pagination expectations, which are unlikely to change how the agent invokes it.

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

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

Schema description coverage is 100% and the single productKey parameter is already documented, including a pointer to list_products. The description adds no extra meaning about the key's format or origin, so this sits at the baseline where the schema does the work.

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 resource and scope: 'All stored AI fix cards for one product', and even enumerates the payload shape (what/why/steps/agent prompt per issue). No sibling tool returns fix cards, so the agent can distinguish it immediately from get_insights, get_bottleneck, and the product/analytics tools.

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

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

Gives a concrete precondition: 'Requires a plan with the ai_fix_cards facility', which tells the agent when the call is valid. It does not name an alternative or exclusion path, but no sibling offers comparable output, so there is little to route against.

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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the description's added value is return-scope and gating behavior — and it delivers both by enumerating exactly what the payload contains and flagging that 'fix cards require the ai_fix_cards plan facility', a real entitlement condition the agent would otherwise discover only on failure. 'Latest' also implies freshness semantics. It loses a point for not indicating payload size, cost, or whether results are cached/computed on demand, which matters for a tool this broad.

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 is front-loaded with the useful framing before the inventory, and no clause is pure filler. But it is a single run-on sentence packing ~15 items separated by commas, with an unclosed-looking parenthetical at the end, which makes it harder to scan than a short list would be. Dense and information-rich, yet structurally weak.

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

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

With no output schema, the description carries the burden of telling the agent what comes back, and it does so comprehensively across every dashboard section, including third-party-sourced facts (CrUX, Domain Rating, OpenPageRank). The one gap is that nothing signals response size, nesting, or latency, so an agent can't plan around the payload cost of requesting everything at once.

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?

One parameter at 100% schema description coverage; the schema already documents productKey and points to list_products for lookup. The description only restates the cardinality ('one product') without adding format, source, or failure semantics for the key. Baseline 3 applies since the schema does the heavy lifting.

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 a specific resource and scope: 'Full latest insights for one product — everything the dashboard renders', then enumerates the payload (scorecards, audits, CWV, CRO, CrUX, DR/OpenPageRank, crawl, First Edit, fix cards). That enumeration distinguishes it from narrower siblings like get_bottleneck, get_fix_cards, and get_site_report by making clear this is the aggregating superset. It stops short of a 5 because it never states the exclusion explicitly ('returns everything, use X for just Y').

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?

There is no when-to-use statement and no routing against the many overlapping siblings (get_bottleneck, get_fix_cards, get_site_report, compare_products, check_launch_readiness). The only quasi-guidance is the inline note that fix cards require the ai_fix_cards plan facility, which is an entitlement caveat rather than usage guidance. An agent must infer that this is the general-purpose call from the word 'Full'.

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 an entitlement requirement (keyword_research facility) and, importantly, a conditional data-quality behavior: exact volume and CPC only appear when a Keywords Everywhere key is configured. That tells the agent to expect degraded estimates in some configurations, which annotations alone would never reveal.

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 payload description is front-loaded and the follow-up tool routing and prerequisite come after, which is a sensible structure with no filler. The first sentence is dense with enumerations but each element earns its place by describing the return payload.

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

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

With no output schema, the description takes on the burden of describing return values and does so thoroughly: idea clustering, volume/difficulty/CPC, content actions, and per-keyword verdicts. It also covers the entitlement precondition and the degraded-data case, leaving nothing an agent needs before calling it.

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

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

There is a single productKey parameter with 100% schema description coverage, so the schema already carries the semantics. The phrase 'for one product' reinforces the single-product scoping but adds no format, lookup, or error guidance beyond what the schema provides.

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

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

States a specific resource (stored keyword research for one product) and enumerates its contents: intent-clustered ideas, volume/difficulty, CPC, prioritized content actions, and per-keyword verdicts. It is clearly distinguished from run_keyword_research (creates a new run) and from rank-tracking tools, so an agent can choose it without opening a 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 routes the agent to run_keyword_research for a fresh run and to add_tracked_keywords for follow-up on interesting ideas, and states the prerequisite ('Requires a plan with the keyword_research facility'). It does not explicitly say what happens when no research has been stored yet, but the when-to-use context and alternatives are clear.

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

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

Annotations already cover the read-only, non-destructive, closed-world profile, and the description adds genuinely new behavior: null means 'checked and not in the top-10', results are never interpolated, and an empty result can have a configuration cause rather than a data cause. It stops short of saying whether the series is ordered or bounded, but the disclosure is well above the annotation floor.

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 purpose, then layered with return semantics, empty-state cause, and prerequisite in a logical order; every sentence carries information. It is on the dense side (parenthetical null definition, inline config explanation) but not 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?

With no output schema, the description takes on the return-value burden and does so by naming the three things returned per keyword plus the null convention. The only gap is structural detail — actual field names and whether the check series is ordered or limited — which an agent may need to parse the response.

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

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

Schema coverage is 100%, so both parameters are already described in the schema, and the description adds nothing parameter-specific — its detail is entirely about return semantics. Baseline 3 is appropriate when the schema carries the parameter burden.

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?

Opens with a specific verb+resource ('Rank history for a product's tracked keywords') and immediately scopes it to scanner scan passes, which separates it from sibling tools like get_scan_history or get_keyword_ideas. The per-keyword return contents (latest, best, series) further pin down what the tool actually yields.

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

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

It states the two preconditions an agent must check — a plan with the keyword_research facility and a configured SERP source (searchConfigured=false → empty board) — which is real usage guidance. However, it never says when to prefer this over run_keyword_research or get_scan_history, nor what to do when the board is empty (configure vs. wait).

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, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds one genuinely behavioral fact beyond them — results are ordered 'most recent first' — but says nothing about how many products are returned, whether results are truncated or paginated, or when the list is empty.

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 clipped sentence with the resource up front and the ordering constraint trailing — no filler, no restatement of the title 'Get product visibility'. Every clause carries information.

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

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

With no parameters, no output schema, and safety already covered by annotations, the description is close to sufficient for invoking the tool. But because there is no output schema, it should say more about what each entry contains (identifier, name) and whether the list is capped — an agent cannot otherwise anticipate the response shape.

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

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

The tool takes zero parameters, so per the baseline there is no parameter meaning for the description to add. The sentence correctly implies an unfiltered, unpaginated call with nothing to supply.

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 concrete resource ('Your products') and the specific attribute returned ('directory visibility (public/private)'), which is more informative than the bare tool name. It does not, however, distinguish itself from sibling list_products or get_product, so the agent must infer the division of labor from names alone.

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?

There is no explicit when-to-use guidance — nothing says why to pick this over list_products, search_products, or get_product. The possessive 'Your' hints at owned-vs-public scope, but that is inference, not guidance, and no exclusions or prerequisites are given.

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

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

Annotations already establish read-only, non-destructive, non-open-world behavior. The description adds meaningful behavioral context beyond that: the status lifecycle includes active, trial, 3-day renewal grace, and expired read-only, and it explains that a limit of 0 means unlimited.

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

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

The description is front-loaded with the resource and then the returned data, with a clear final usage instruction. It is dense as a single long sentence, but nearly every clause carries useful information; the status parenthetical is slightly run-on but not wasteful.

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 no output schema, the description explains the return shape thoroughly, including status values, limit semantics, usage meters, and the can-do summary. It also supplies the critical preflight instruction, so an agent has what it needs to call it correctly.

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

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

The tool takes no parameters, so there are no parameter semantics for the description to document. The baseline for a zero-parameter tool is 4, and the description correctly avoids unnecessary parameter discussion.

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 resource, the founder's current subscription, and enumerates exactly what it returns: plan name and price, status, abilities and limits, usage against meters, and a can-do summary. It is not tautological and clearly distinguishes this from the product/keyword/report tools listed as siblings.

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

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

It gives an explicit routing instruction: call this FIRST before using any other tool to check which features the plan allows. That is a clear when-to-use rule tied to the tool's role as a preflight authorization check.

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, destructiveHint=false and openWorldHint=false, so safety is covered structurally. The description adds a small amount of behavioral context with "full public listing", hinting at the returned scope and possibly visibility constraints, but it does not clarify pagination, error behavior for unknown slugs, or whether non-public records can be fetched.

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 short sentence, front-loaded with the resource and scope, with no filler or redundancy. Nothing in it is wasted or misplaced.

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 simple single-parameter read with annotations and full schema coverage, so not much is required. However, with no output schema, the description is the only place to say what "full public listing" contains, and that phrase remains vague about the returned fields and shape.

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

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

Schema coverage is 100% and the single parameter already documents both accepted forms with an example ("acme-app") and the "domain" interpretation of key. The description's "by slug or key" merely restates the schema, adding no format, case-sensitivity, or lookup-precedence detail beyond it. Baseline 3 applies.

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

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

"The full public listing for one product, by slug or key" names the resource (one product) and the retrieval key (slug or key), and "one product" implicitly contrasts with the list/search siblings. It stops short of naming list_products or search_products explicitly, so an agent must infer the boundary, but the core purpose 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?

Usage is only implied: "one product" suggests this is the single-record fetch versus list_products/search_products, but no when-to-use or when-not-to-use condition is stated. There is also no mention of prerequisites, such as whether the product must exist or be accessible, nor of what happens for private products given the sibling set_product_private 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 readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered without the description. The description adds a meaningful behavioral bound — the series is capped at the last 100 scans and is chronological — which the annotations do not express. It says nothing about pagination or how missing scans are handled.

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, front-loaded sentence that leads with the scope (score-over-time series for one product, last 100 scans, chronological) and then lists the returned metrics. The metric enumeration is long but every item carries information; no filler or redundant restatement of the tool name.

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

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

With no output schema, the description carries the burden of explaining return values, and it does so by enumerating the metric families plus per-run source and timestamp. Given a one-parameter tool with full schema coverage and read-only annotations, little else an agent needs in order 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 description coverage is 100% and the single productKey parameter is documented in the schema as referencing list_products. The description reinforces that the series is scoped to 'one product' but adds no format or syntax detail beyond the schema, so the baseline of 3 applies.

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

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

The description gives a specific verb+resource: a score-over-time series of the last 100 scans for one product, and enumerates the metrics returned (performance, AEO, CRO, SEO crawl, scorecards, CrUX, openRank, issue counts). It is clearly distinguishable from siblings like get_product or get_site_report, though it never names an alternative explicitly.

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 implied by the phrase 'score-over-time series for one product', which suggests this is the tool for tracking trends over time rather than a current-state snapshot. There is no explicit when-to-use/when-not guidance or pointer to a sibling such as get_product for current values, so the agent must infer the distinction.

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 destructiveHint=false, and the description adds real value on top: it is cached and never generates, it exposes hasReport/scanStage state, and it prescribes the polling loop. It stops short of describing error behavior for invalid or unknown domains, so it is strong but not exhaustive.

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

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

Front-loads identity ("The free public site report for any website") before the coverage list and the fallback procedure. The feature enumeration is dense but each item helps an agent decide whether this tool answers its question; minor trimming is possible.

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

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

With no output schema, the description usefully tells the agent what comes back (the same data the public site-report page renders) and which state fields to inspect (hasReport, scanStage). For a single-parameter read tool this is nearly complete, lacking only failure-mode detail.

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 only one parameter (domain) and schema description coverage is 100%, so the schema already carries the semantics. The description adds nothing about the domain format, normalization, or whether subdomains/paths are accepted, making the baseline 3 appropriate.

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

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

Names a specific verb+resource (get the site report for a domain) and then enumerates exactly what sections it returns: performance, AEO, CRO, SEO crawl, CrUX, OpenPageRank, scorecards and named checks. It explicitly distinguishes itself from the sibling run_site_report by framing itself as the read of already-computed data.

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 explicit when-to-use and when-not-to-use guidance: this is the cached read that never generates, and if hasReport is false the agent should call run_site_report and then poll this tool until scanStage clears. That names the alternative and the exact condition that selects it.

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

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

Annotations already cover readOnly/non-destructive/closed-world, so the description is not obligated to restate safety. It does add real behavioral context beyond them: a 'partial flag when a crawler query failed' (a data-quality caveat an agent should report) and the conditional that conversion events and goals only appear when the plan carries the analytics_conversion facility. Missing are freshness/lag, pagination, and size limits, which keeps it off a 5.

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

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

The core purpose is front-loaded in the first clause, which is good, but the remainder is a single run-on laundry list of roughly 25 metric names with no grouping or punctuation hierarchy. Because there is no output schema the enumeration has informational value, but it could be grouped into categories in a fraction of the words.

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

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

With no output schema, the description carries the burden of telling the agent what comes back, and it does so thoroughly, including feature-gated sections and the partial-result flag. The remaining gap is operational context (setup prerequisite, data latency, result size) for a tool that could return a large daily series.

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

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

Schema description coverage is 100% and the only two parameters are documented there, including the 'Defaults to 7d' enum hint. The description contributes nothing parameter-specific beyond 'for one product', implying productKey scoping, so the baseline 3 applies.

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

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

The description opens with a specific resource and scope: 'First-party website analytics for one product', and enumerates exactly what data classes are returned. It does not, however, differentiate itself from plausible siblings such as get_site_report or get_insights, so an agent cannot tell purely from the text which analytics-flavored tool to pick.

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

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

There is no when-to-use / when-not-to-use guidance and no mention of alternatives among the 25 siblings. It also omits the prerequisite that analytics must be set up for the product (implied by the existence of get_analytics_snippet and get_analytics_token), which is exactly the kind of condition that determines whether calling this tool is useful.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered without description help. The description adds that results carry 'latest scan scores', which is genuinely useful content information, but says nothing about result volume, ordering, or whether all products are returned.

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 short sentence that front-loads the action and resource, with the outcome detail trailing. There is no filler and nothing that could be trimmed 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?

With no parameters, no output schema, and full annotation coverage, a one-line description is close to sufficient. A brief note on scope (all products vs. filtered) would close the remaining gap against the overlapping siblings.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly implies no input is required and instead characterizes what comes back, which is the only parameter-adjacent information that could matter here.

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 pairs the specific verb 'List' with the resource 'products' and adds the payload detail 'latest scan scores', so the agent knows this is a bulk retrieval rather than a single-record fetch. It does not explicitly distinguish itself from close siblings like get_my_products_status, search_products, or compare_products, which keeps 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?

There is no when-to-use guidance and no mention of alternatives, even though the sibling set contains several overlapping retrieval tools (get_product for a single item, search_products for filtered lookup, get_my_products_status). The agent must infer that this is the unfiltered 'list everything' entry 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 destructiveHint=true and idempotentHint=true, but the description goes further by specifying exactly what is destroyed (stored rank-check history) and the required authorization scope (rescan). It stops short of stating the behavior for keywords that are not currently tracked or the effect of re-adding them.

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

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

Three short sentences, front-loaded with the action and immediately followed by the destructive consequence and the auth prerequisite. No filler or restatement of the tool name.

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 two-parameter destructive tool with no output schema, the description covers the essential decision inputs: what gets removed, that history is permanently deleted, and what credential is needed. Only edge-case behavior (untracked keywords, partial failures when removing many) is left unaddressed.

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

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

Schema description coverage is 100%, so both parameters (productKey, keywords) are already documented, including the 100-item cap. The description adds no formatting or semantic detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb (removes) and resource (keywords from a product's rank-tracking board), which cleanly distinguishes it from the sibling add_tracked_keywords. An agent can identify the operation 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?

Usage is only implied by the mutation semantics; there is no explicit when-to-use guidance, no mention of when to prefer an alternative (e.g., add_tracked_keywords to reverse), and no preconditions beyond the auth requirement. Adequate but with clear gaps.

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 declare readOnlyHint=false and openWorldHint=true, and the description goes well beyond them: it discloses the quota cost ('Spends one of the founder's monthly keyword-research runs') and the authorization requirement ('Requires a key with the rescan scope'), plus what the output contains. Those are exactly the operational consequences an agent needs before triggering an open-world mutation.

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 action and output summary are front-loaded, then the quota warning, then the prerequisite — a sensible order with no filler sentences. It is dense with domain jargon ('Jev-scored fit/demand/competition') that mildly slows parsing, but every clause carries information.

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

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

For a two-parameter mutating tool with no output schema, the description covers purpose, produced artifacts, cost, prerequisites, and the alternative to try first. 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 description coverage is 100%, so both parameters are already documented, and the description's mention of a 'Google-autocomplete sweep' implies the seed without adding format or defaulting detail. Baseline 3 is appropriate since the schema carries the parameter burden.

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 ('Runs one keyword research for a product') and then enumerates what the run produces: a Google-autocomplete sweep, model-clustered intent groups, volume/difficulty estimates, and prioritized content actions. This is clearly distinguishable from the sibling get_keyword_ideas, which serves stored research rather than producing a new sweep.

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

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

Explicitly tells the agent to 'check first with get_keyword_ideas whether the stored research still serves', naming the alternative and the condition selecting it. It further adds a pre-condition (a key with the rescan scope) and a cost constraint (one monthly run), so an agent knows both when to call and when not to.

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 it is a non-read-only, idempotent, open-world call; the description goes well beyond that by disclosing the async contract (returns immediately, must poll), the exact quota model (2 full scans per calendar month per credential, shared per-IP monthly budget for anonymous callers), and a hard refusal condition for existing products. These are precisely the operational facts an agent needs before spending a limited scan budget.

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

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

Four sentences, each load-bearing: action and async behavior first, then quota, then the polling follow-up, then the refusal case. No restatement of the tool name or filler, and the ordering front-loads the things an agent must know before calling.

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?

There is no output schema, and the description compensates by explaining that this call yields no report at all and that results come from polling get_site_report. With one fully documented parameter and annotations covering the safety profile, nothing material is missing for correct invocation.

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

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

Schema coverage is 100% for the single 'domain' parameter, so the baseline would be 3; the description earns one more by adding a constraint the schema does not express — that domains already registered as krawlup products are rejected. It does not add format or normalization details beyond the schema's 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 and resource — 'Start the free public scan for any website' — and immediately clarifies that it returns asynchronously rather than delivering results. This cleanly separates it from the sibling get_site_report (which fetches the result) and from trigger_rescan (which targets already-tracked products).

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 explicit next-step guidance ('Poll get_site_report for the domain until scanStage clears') and an explicit exclusion (domains already listed as krawlup products are refused, use the dashboard instead). The one gap is that trigger_rescan is never named, so an agent can't tell from this description which of the two scan-starting tools to use for a product it already owns.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine scope detail beyond them (only public, only launched products, plain-language queries), but says nothing about result ordering, pagination, or what happens at the limit boundary.

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 with the resource scope first and the input constraint attached; nothing is redundant or 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?

For a simple two-parameter, read-only search with a fully described schema and explicit annotations, the definition covers what the agent needs to call it correctly. Minor gaps around result ordering and pagination behavior remain.

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

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

Schema description coverage is 100%, so both parameters are already documented, including the limit default and maximum. The description's 'plain language' phrasing adds a small hint about query formulation and its 2-character minimum supplements the schema, but otherwise the schema does the heavy lifting.

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 (Search) and a clearly scoped resource (public catalog of launched products), which distinguishes it from get_product (single item) and list_products (enumeration). It stops short of naming those siblings explicitly.

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 implied: use it to find products by natural-language query, with a minimum query length of 2 characters. There is no explicit guidance on when to prefer this over list_products or get_product, or what to do when no results are found.

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, and the description goes further: it explains what is actually affected (what the site's analytics records), that discarded visits are never stored or counted, that an empty array wipes the board, and the required scope. It also adds a client-side confirmation protocol that 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?

Four tight sentences with the destructive warning and the replacement semantics front-loaded, followed by the confirmation gate and the scope requirement. No filler and no 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?

For a 3-parameter destructive mutation with no output schema, everything an agent needs is present: what is replaced, what destruction means, the empty-array edge case, the auth scope, and the human-approval requirement. Nothing material is left to inference.

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 schema already documents productKey, paths (full replacement, max 25, empty clears), and confirm. The description's statements about empty arrays and the confirm gate restate schema semantics rather than adding new meaning, so baseline 3 applies.

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

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

States a specific verb and resource — "Replace the per-product Excluded pages board" — and immediately defines the resource's effect ("paths whose visits are discarded at intake"). No sibling tool in the list deals with exclusion boards, so an agent can distinguish it unambiguously.

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 explicit preconditions: requires a submit-scope key, empty array clears the board, and confirm=true only after the owner approves the exact list in conversation. It does not name any alternative tool, but no sibling covers this capability, so the routing gap is minimal.

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=false, destructiveHint=false, and openWorldHint=false, so the safety profile is partially covered. The description adds a genuine behavioral fact beyond the annotations — the operation is permitted on any plan — but it never explains the consequences of unpublishing: whether the product data survives, whether the product key remains valid, or how to reverse it via set_product_public.

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 short sentence with the action front-loaded and the availability constraint parenthetically attached. No filler, nothing to cut.

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

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

For a one-parameter tool with annotations and full schema coverage, this is close to sufficient, but the irreversible-looking nature of unpublishing (visibilility change, published URL going dark, recovery path) is left entirely to inference. A single clause on the effect and reversibility would close the 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?

The single parameter has 100% schema description coverage, and the schema already explains that productKey is the domain returned by add_product or list_products. The description adds nothing about parameter format or sourcing, so the baseline of 3 for high-coverage schemas applies.

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

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

States a specific verb and resource: 'Remove one of your products from the public directory.' That is unambiguous and, read against the sibling set (set_product_public, add_product), an agent can immediately tell this is the unpublish path. It stops short of naming the inverse sibling explicitly, so a 5 is not warranted.

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?

'Always allowed, any plan' conveys the key precondition: there is no subscription gate on this operation, which is meaningful versus plan-limited siblings. However, it gives no explicit when-to-use/when-not guidance and never names set_product_public as the alternative for republishing.

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=false, destructiveHint=false and openWorldHint=false, so the description's job is to add gating context, which it does: entitlement rules, the permission requirement, and the fact that a 403 message names the failing condition. It does not say what happens when the product is already public (idempotency) or what a success response contains, 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 tight sentences, front-loaded with the action, then the eligibility gate, then the sibling routing and permission. Nothing is redundant with the name or title, and every clause carries operational information.

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

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

For a one-parameter mutation with no output schema, the description covers the things an agent could otherwise get wrong: entitlement checks, the required permission, the error semantics, and the inverse tool. Only the return/result behavior of a successful publish is left implicit.

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 a single parameter at 100% schema description coverage, the schema already explains that productKey is the domain returned by add_product or list_products. The description adds only the qualifier "this exact product" in relation to grants, which is marginal beyond the schema's own documentation — baseline 3.

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

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

The description opens with a specific verb and resource: "Make one of your products public in the krawlup directory." It also names the inverse sibling (set_product_private), so an agent can distinguish the publish/unpublish pair without inspecting 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?

It states the exact preconditions for use — an active paid subscription (explicitly no trial) OR an admin-approved grant covering this exact product — and routes the opposite operation to set_product_private. The required submit permission is called out, which is the kind of gating an agent must check before invoking.

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 annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true) by disclosing the real cost model: one full-analysis allowance per product and across all products for the billing period, plus one page speed check. It also explains the async contract ('returns immediately') and the auth requirement (rescan scope), which is exactly the context annotations 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?

Three sentences, front-loaded with the action, then cost, then poll instruction. Every clause is load-bearing — quota, auth scope, and polling target are all things the agent would otherwise get wrong.

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?

Although there is no output schema, the description covers the return behavior (immediate return, results land in get_insights), the cost side effect, and the auth prerequisite. For a one-parameter async mutation, nothing an agent needs in order to call it correctly is missing.

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

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

The single productKey parameter is fully documented in the schema, including a pointer to list_products. The description reinforces the 'one product' scoping but adds no format or retrieval detail beyond the schema, so the baseline 3 for high coverage applies.

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

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

States a specific verb and resource ('Starts a fresh full analysis of one product') plus its execution mode ('in the background'), which cleanly separates it from read-only siblings like get_insights or get_scan_history. An agent knows exactly what this does 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?

Gives clear when-to-use context (you want fresh numbers) and an explicit follow-up path: poll get_insights until scanPending is false. It also surfaces the precondition of a rescan-scoped key. It lacks an explicit 'when not to use' comparison against siblings such as run_site_report, which keeps it off a 5.

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