SEOmatic

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses key behavioral traits: it returns counts only, never prompt/answer text; it is free and reads connected/stored data; it is already scoped to the workspace, requiring no domain/site parameter. These details go well beyond what annotations provide.

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 verbose but every sentence contributes value—it front-loads the core distinction (observed vs. scanned), then methodically covers operations, scope, cost, and alternatives. It is well-structured and avoids fluff, though a slightly tighter version could improve readability.

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 multi-operation tool with an output schema present, the description is remarkably complete. It explains all three actions, the key distinction, scoping, cost, and even points to an alternative tool. No critical information is missing for an agent to decide and invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds significant meaning to the action parameter by explaining what each enum value returns (domestic citations vs. brand facts vs. scan results) and clarifies the 'days' and 'scanId' parameters implicitly through the operations. It enhances the schema without redundancy.

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

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

The description clearly states the tool provides first-party AI-citation data and enumerates three distinct operations (observed_citations, brand_facts, scan_results) with specific definitions. It explicitly differentiates from server-side scans and traffic_analytics, making the purpose unmistakable.

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

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

The description provides explicit guidance: it contrasts observed vs. scanned data, tells users to use traffic_analytics for per-page AI traffic, and clarifies when to use each of the three actions. Alternatives are named and conditions are stated, leaving no ambiguity about when to invoke this 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, openWorldHint, idempotentHint, and non-destructive, so the baseline behavioral safety is covered. The description adds valuable context: data is read from the link index at call time (live data), empty profiles return an empty result rather than an error, and the call bills AI credits on live vendor data while own stored reads are free. These operational details are exactly what annotations don't capture and are not implied by 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 description is about 110 words, but each sentence has a distinct function: core purpose, live-read/empty-profile behavior, usage routing, scoping, and cost. The core purpose is front-loaded in the first sentence, and nothing is redundant with the schema or annotations. It is appropriately sized for a tool with five action modes and a cost implication.

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 covering the safety profile and an output schema existing (per context signals), the description covers the remaining decision-critical points: what the tool does, when to use it, the no-error edge case, scoping, and cost. The optional user_intent parameter and action-specific parameters are fully described in the schema, so nothing an agent needs to invoke it correctly is missing. This is a complete definition for a read-only SEO analysis tool.

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

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

Schema coverage is 100%, with parameter descriptions that already explain the action enum's five modes, the domain omission rule for the connected site, competitors limit, months restriction, and defaults for limit. The description reinforces the domain scoping ('no domain or site parameter is needed') but does not add new parameter-level semantics beyond the schema. Baseline 3 is appropriate because the schema carries 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 first sentence names the verb ('Read'), the resource ('backlink profile of your own site or any competitor'), and enumerates the data categories (referring domains, anchor-text distribution, link velocity, link-prospect intersects). It also names the sibling it is not ('for rankings use serp_competitors'), which differentiates it from the many SEO tools 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?

The description explicitly says when to use this tool ('for authority and link questions') and when not ('for rankings use serp_competitors'), naming the alternative. It also clarifies the scoping rule ('Already scoped to the connected workspace and its site; call directly, no domain or site parameter is needed'), so an agent knows not to pass a domain for the connected site. This is explicit routing guidance beyond what the schema enum provides.

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 mark this as destructive/non-read-only, but the description adds valuable behavioral context: all staging is approval-gated, nothing publishes without user consent, reads are free, and credits are only billed per page when staged work executes. This meaningfully shapes agent behavior beyond the annotations and does not contradict 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?

Four sentences, front-loaded with the main verbs and resource, and every sentence adds unique context: scope, approval gating, and cost behavior. There is no filler or redundant repetition of schema content.

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

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

For a 26-parameter tool with six action modes, the description provides the essential safety, scoping, and cost context while relying on the rich schema and output schema for specifics. It is complete enough for initial selection and invocation, though action-specific prerequisites are left 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 description coverage is 100%, with each parameter already explained per action, so the baseline is 3. The description adds a mild clarification that workspace/site scoping is implicit and no domain/site parameter is needed, but it does not elaborate on parameter usage 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 specific operations: read campaigns and stage page-scale, content-sweep, or bulk-edit campaigns and blog articles, with the proposal-based model made explicit. It identifies the resource and action scope clearly. It doesn't explicitly differentiate from siblings like task_manage or generate_article, so it is not 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 description gives clear guidance on when to call: for reading campaigns and staging proposal-based work, with the approval gate and no-domain-parameter context stated. It does not name alternatives or explicitly say when not to use the tool, but the context is strong enough for safe routing.

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

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

Annotations already mark this as a non-read, non-idempotent mutation, and the description enriches that by explaining the consent doctrine, that a confirmation claims the fact for writers, that the action is reversible in Settings, and that it costs no AI credits. It is fully consistent with the annotations, so no 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 description is front-loaded with the action and then delivers high-value guardrails (consent, no bulk, reversibility, cost). It is slightly verbose with the all-caps explanations, but each sentence contributes behavioral guidance.

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

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

Given the simple 2-parameter surface, rich annotations, and an output schema, the description covers everything an agent needs: the trigger condition, the source of factId, the effect, reversibility, and cost. 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?

Both parameters are fully documented in the schema (factId and user_intent), so with 100% schema coverage the description has a low burden. It restates that factId comes from show_trust_facts_card, which the schema already says, and does not add meaning for user_intent beyond the schema.

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

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

The description opens with a specific verb and resource: it 'Record[s] the USER'S confirmation of one harvested trust fact', and ties the fact id to show_trust_facts_card. This clearly distinguishes it from sibling read/list tools like get_trust_facts and show_trust_facts_card by establishing a single-fact write action.

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

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

The description explicitly states the only valid trigger (explicit user confirmation via the widget button or user's own words) and lists hard prohibitions: never confirm on judgment, never in bulk, never treat silence as consent. It also ties the doctrine to task_manage decide, giving the agent a consistency anchor.

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 adds substantial behavior beyond the annotations: sample rows are capped, empty libraries return empty lists rather than errors, data is read as-is, and the call is free with no AI credits. This meaningfully prepares the agent for how the tool behaves at runtime, with no contradiction to the readOnlyHint/idempotentHint annotations.

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

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

The description is three concise sentences, front-loaded with the tool's purpose, then behavioral caveats and scope/cost. Every sentence contributes useful context, and the structure is easy to scan.

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 output schema, fully documented parameters, and read-only annotations, the description covers the remaining essentials: scope, edge-case behavior, and invocation requirements. An agent has what it needs to call this tool correctly.

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

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

The schema already describes all parameters with 100% coverage, so the description correctly relies on it. It adds only minor context like 'sample rows are capped,' which slightly informs the limit parameter's effect but does not substantially enhance per-parameter semantics.

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

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

The description clearly states the resource ('dataset library and page templates') and the operations it supports: list datasets, sample rows, list templates, and read one template. It does not explicitly name or contrast a sibling tool, but its read-only library role is distinct from the analytics and generation 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 clear invocation guidance: already scoped to the connected workspace and site, so no domain or site parameter is needed. It does not explicitly state when to use this tool instead of alternatives or list exclusions, but the operation list implies the intended use cases.

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 indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description adds valuable behavioral context: the operation is async, costs $9/1 unit, is research-grounded and quality-gated, and returns a payment_required payload when balance is empty. It also clarifies the cost model ('FREE - reads your connected/stored data, no AI credits'), which is a meaningful behavioral disclosure beyond the annotations.

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 information-dense but well-organized: it front-loads the core action and cost, then explains the async flow and error handling. It's slightly long but every sentence earns its place—the payment_required handling and async polling instructions are critical for correct usage.

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

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

The description covers the essential workflow (async generation, polling, payment failure handling) and the output format (markdown + HTML). It doesn't detail the output schema's contents, but the output schema exists and the description doesn't need to explain return values. The only minor gap is not specifying what happens if the topic is invalid or if generation fails for non-payment reasons, but the core usage is well covered.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds context about the topic being a keyword/topic for SEO, but doesn't add new parameter-level meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description states a specific verb ('Write'), a specific resource ('one in-depth SEO article'), and the delivery format ('markdown + HTML'). It also distinguishes itself from siblings by naming get_article as the polling mechanism and mentioning the payment_required payload, which clearly separates it from other tools in the 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?

The description explicitly explains the async workflow: call this tool, receive an article_id, then poll with get_article. It also gives clear guidance on how to handle the payment_required response (relay price and link, don't treat as failure), which is essential for correct agent behavior.

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, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds valuable context: it is FREE, reads connected/stored data (implying no additional setup cost), and explains the meaning of the 'connected' flag. This goes beyond the annotations, warranting a high score, though not the maximum because it doesn't describe response format or retry behavior.

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

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

The description is concise yet information-dense. It front-loads the core purpose, then covers the connectivity nuance, and ends with cost information. Each sentence adds a distinct piece of context without redundancy, and the structure flows logically from what to how to cost.

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

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

Given that the tool has an output schema (which should describe return values) and only two optional parameters, the description covers the key aspects an agent needs: what it does, how to interpret connectivity, and cost implications. Nothing critical 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 description coverage is only 50%: user_intent has a description but windowDays does not. The description mentions 'trends' which implies a time window, but it doesn't explicitly explain windowDays semantics beyond its name and schema constraints (min 7, max 90). The description does not compensate for the missing schema description, so the agent must infer the meaning from context. A 3 reflects that the description provides some context but not full parameter clarity.

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

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

The description clearly identifies the resource (AI crawler activity) and specifies exactly what it returns: which bots visited, classification by purpose, trends, top pages, and the crawl-to-citation funnel. It also distinguishes itself from sibling tools like get_ai_funnel by focusing on crawler activity rather than the funnel specifically.

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

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

The description gives clear context on when this tool is relevant, especially the note about 'connected=false' meaning the customer hasn't set up ingest yet. However, it doesn't explicitly name alternative tools or state conditions for choosing this over the many related siblings (e.g., get_ai_visibility, get_ai_funnel). The intent is inferable but could be more direct.

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, idempotentHint=true, and destructiveHint=false. The description goes further by explaining the 'measured' flag and false-flag semantics (UNMEASURED, never zero), the meaning of each stage combination, and that it consumes no AI credits. This adds substantial behavioral context beyond the annotations.

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?

Though long, every sentence earns its place: purpose, measurement breakdown, honesty warning, interpretation guide, and cost. The most critical info (what it returns) is front-loaded, and the structure is logical. 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?

Given the tool's complexity (three joined measurements, a honesty flag, and interpretation patterns), the description fully covers what an agent needs to call it correctly and interpret results. An output schema exists, so return values need no explanation. Cost and read-only behavior are explicitly stated. Complete.

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

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

The single parameter 'user_intent' is already fully documented in the schema with a clear description and max length. Schema coverage is 100%, so the description adds no additional parameter details, which is acceptable per baseline. It correctly omits redundant information.

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 ('get') and a precise resource ('full AI-search funnel per page') with the three joined measurements (CITED, CRAWLED, REFERRED) and a stage 0. It distinguishes itself from siblings like get_ai_visibility or get_ai_crawler_activity by naming exactly what it composes, so an agent can tell it apart 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?

The description explains when to use it (to see the full funnel) and how to interpret results ('check measured first', the false-flag warning, and the cited/crawled/referred combinations). It also states the cost is FREE, which informs whether to invoke it. It lacks explicit exclusions or alternatives, but the context is clear enough for correct selection.

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 provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description aligns with them while adding real behavioral value: fetching is free and uses stored data, a ready article contains both markdown and HTML, and markdown is the source of truth. It also discloses that the list mode reveals prepaid balance, going beyond 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?

Three sentences cover the primary action, the alternative list mode, format details, and cost behavior, all without fluff. The main usage is front-loaded, and each sentence contributes useful information, though the 'pay-as-you-go' phrasing adds minor ambiguity alongside the 'Cost: FREE' clarification.

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

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

The tool is simple, has an output schema, and is backed by rich annotations. The description covers polling workflow, the two returned formats, the source-of-truth relationship, and cost behavior, so an agent has everything needed to select and invoke this tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters well. The description reinforces that article_id comes from generate_article and that omitting it triggers listing, but it adds little beyond the schema's own text. Baseline 3 is appropriate.

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

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

The description starts with a specific verb and resource, 'Fetch a pay-as-you-go article by id,' and also covers the list mode when article_id is omitted. It explicitly ties the id to generate_article, which differentiates it from the sibling generation tool and clarifies the article lifecycle.

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 usage context: poll with the id returned by generate_article, or omit the id to list recent articles and prepaid balance. It doesn't spell out exclusions, but the reference to generate_article and the dual-mode behavior make the intended workflow obvious.

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 mark the tool as read-only, idempotent, and non-destructive, and the description adds valuable behavioral details beyond that: it reads stored/own data, costs no AI credits, lists free operations explicitly, shows refunds as negative credits, and reconciles with the plan meter. No contradiction exists.

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

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

The description is compact and front-loaded with the core purpose, followed by useful specifics: reconciliation, free operations, refunds, and cost. The opening sentence is a bit dense, but every clause contributes meaningful information and 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 an output schema present, the description doesn't need to enumerate return fields. It fully covers the data grouping, granularity, reconciliation, free operations, refund behavior, and the cost implication, giving an agent everything needed to understand and invoke the tool correctly.

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

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

The only parameter, user_intent, is optional and fully described within the schema with a maxLength and explanation. The description itself adds no additional parameter semantics, but schema coverage is 100%, 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 clearly states what the tool does with specific verbs and resources: retrieving AI credit usage for the current billing period, including customer-language groups (items) and a per-feature ledger (features). It also clarifies the granularity as per-agent/per-action, which distinguishes it from sibling tools focused on articles, pages, or analytics rather than billing/credits.

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

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

The description gives clear context about when to use this tool: when integration-level granularity of credit usage is neededharee, and it notes that the total reconciles with the plan meter. It doesn't explicitly name an alternative or exclusion, but there is no close sibling tool, so the guidance is sufficient.

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

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

The annotations already mark the tool as read-only and idempotent, and the description adds valuable behavioral context: reward timing (earned at first win, not signup), the free/no-AI-credits cost, and that it deals with the user's own data. This goes well beyond what the annotations alone convey.

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

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

The description is dense but well-structured: purpose, returned fields, timing details, and cost are each clearly signaled. No sentence is wasted, and the most important information is front-loaded.

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

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

With an output schema present and the input schema fully covered, the description still supplies essential context: reward timing, cost, and data scope. An agent has everything needed to decide when to call this tool and what to expect from 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?

The only parameter, user_intent, is fully documented in the schema, so the baseline applies. The description adds no parameter-specific guidance, but none is necessary given complete schema coverage and the parameter being optional.

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

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

The description explicitly identifies the resource (the user's personal SEOmatic referral link and reward status) and enumerates the exact returned fields, so an agent knows precisely what this tool does. It is clearly distinct from broader analytics or credit-usage siblings by focusing on the referral funnel and rewards.

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

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

The description gives a clear context for use: it is for reading the user's own referral link, funnel counts, and rewards. It does not explicitly name sibling tools or state when not to use this tool, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false; the description adds useful behavioral context beyond that: it is FREE, reads connected/stored data with no AI credits, and reveals that rollback_data stores the full pre-edit state before writing. This is meaningful supplement without contradicting annotations.

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

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

The description is dense but each sentence earns its place: rollback mechanism, when to call, what is returned, and cost. The opening phrase 'What the pipeline can RESTORE' is slightly awkward as a noun phrase rather than an action verb, but the information is front-loaded and efficient.

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

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

Given that an output schema exists, the description does not need to detail return values. It covers when to use the tool, the underlying data mechanism, what the caller can learn, how restore is triggered, and cost. For a read-only tool with one required parameter, this is complete.

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

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

Schema description coverage is 100%, so the schema already documents taskId and user_intent. The description only clarifies that the task is an 'executed task' and implies taskId is the required identifier, but it does not add significant semantic detail beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly identifies the resource (rollback state for an executed task) and what the tool returns (recoverable fields, original embed code, restore trigger). It does not explicitly name a sibling alternative or use a crisp verb like 'retrieve', but the meaning is unambiguous and distinct from task_manage and other 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?

Provides an explicit when-to-use rule: 'Call this FIRST whenever the user reports an agent edit removed, broke, or damaged something on a page.' It also gives a strong when-not-to-assume rule: 'NEVER tell the user original content is lost without checking here.' This gives the agent a clear decision procedure.

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/idempotent annotations, the description discloses cost, data-source limitations (blind to cited-without-querying hosts), the 2026-09-15 fan-out exposure caveat, and semantic distinctions such as ownSite hygiene vs outreach. It also clarifies what progress.opened means and how to act on it.

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

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

The description is dense and front-loaded with the core definition, but it is a single long paragraph with metaphorical language like 'honest cross' and 'corroboration homework' that could be tightened. Every clause adds information, but the structure could be clearer.

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 output schema exists and the sole parameter is optional, the description covers all critical interpretive pitfalls: data source, entity classifications, hygiene semantics, denominator caveat, progress.opened usage, and cost. An agent has enough context to invoke and interpret the tool correctly.

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

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

Schema description coverage is 100% and the only parameter, user_intent, is fully described in the input schema. The tool description adds no extra meaning to this optional parameter, 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 clearly identifies the tool as returning trust entities AI engines consult, with a specific resource and provenance. It does not explicitly reference sibling tools, so differentiation rests on the unique 'trust entities' concept rather than naming an alternative.

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 context: it reads connected/stored data, is free, and explains when low findingsWithFanouts should trigger a fresh scan rather than being read as absence. It does not explicitly list when-not-to-use or direct the agent to a named 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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description discloses critical behavioral details: each fact carries a source URL and confirmation status, the empty-list behavior instructs the agent not to invent claims, and the cost is FREE with no AI credits. It also explains the provenance and verification model. These traits are not inferable from the annotations alone and materially change how an agent uses the 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 a dense, four-sentence block where every sentence adds a distinct piece of information: what the facts are, their attributes, the empty-list behavior with a fallback path, and cost. It is front-loaded with the primary purpose and avoids redundancy. Despite its length, it is appropriately sized because each sentence earns its place for a tool with significant behavioral nuance.

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

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

Given the simple schema (one optional parameter), rich annotations, and an output schema that presumably defines the return format, the description covers all external context an agent needs: the content and provenance of facts, the empty-list policy, how to escalate for more facts, and cost implications. It also distinguishes itself from related tools like confirm_trust_fact and get_trust_entities via the Settings indication and read-only stance. Nothing critical 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 only parameter, user_intent, is already fully documented in the input schema with its purpose, optionality, and usage. The description adds no additional meaning to the parameter, so the schema carries the entire burden. This aligns with the baseline of 3 for high schema 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?

The description clearly defines the resource as the workspace's TRUST PROFILE and specifies the verb 'get' through its name, while elaborating on the content of the facts (credentials, years of experience, etc.) and their provenance. It distinguishes itself from mutation siblings by stating that adding/confirming happens in Settings, never through chat, which routes the agent away from get_trust_facts for write operations. This is a precise statement of what the tool does and what it is not for.

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

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

The description gives explicit usage context: when the list is empty the agent must write around trust claims rather than invent them, and if stronger E-E-A-T content is desired, the agent should direct the user to Settings → Agent → Trust Profile. It also explicitly excludes modifying trust facts through chat, providing a clear boundary relative to the confirm_trust_fact sibling. This is strong when/when-not guidance with an actionable alternative.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive; the description adds meaningful behavioral detail beyond that: the 50-URL batch cap, per-URL independent failure isolation, workspace scoping, and the fact that it reads stored data without consuming AI credits. No contradiction with annotations exists.

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

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

The description is three focused sentences with no filler: purpose first, then limits and failure behavior, then scoping and cost. Every sentence contributes necessary operational information and nothing is redundant with the schema or annotations.

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 existing output schema and safety annotations, the description covers all non-obvious operational needs: scope, batch caps, failure isolation, and cost. An agent has everything required to invoke the tool correctly without additional 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% and each parameter already has a descriptive comment. The tool description adds value beyond the schema by explaining the batch limit, the semantics of per-URL independent reporting, and why no domain/site parameter is required due to workspace scoping.

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 leads with a specific verb 'Check' and a precise resource: Google index status and coverage diagnostics, listing concrete diagnostic aspects like coverage state, crawl status, and robots/canonical issues. It clearly distinguishes single-URL from batch operation, which separates it from sibling analytics tools like gsc_performance and gsc_insights.

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 conveys clear operational context: batch inspection caps at 50 URLs per call, failure isolation behavior, and the fact that the tool is pre-scoped so no domain/site parameter is needed. It stops short of naming sibling alternatives or explicit when-not-to-use conditions, so it lacks 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, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine context beyond that: the weekly-finalization lag, the cost implication (FREE, no AI credits), and the fact it reads stored/connected data. No contradiction with the annotations. Minor gap: it doesn't disclose that different actions return different output shapes, but the output schema absorbs that.

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

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

The description is dense but efficient: the analysis list is front-loaded, followed by scoping, sibling routing, and cost. Every sentence earns its place, and the cost/staleness notes would be missed if omitted. It is longer than the calibration minimal, but for a six-action dispatch tool the length is justified.

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

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

Given a moderate-complexity dispatch tool with six actions, rich annotations, 100% schema coverage, and a present output schema, the description covers the essentials: what it computes, data freshness, scoping, cost, and the sibling to use for raw metrics. Nothing an agent needs to invoke it correctly is missing. A 5 would require even more nuance (e.g., per-action output variance highlighted in prose).

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 each parameter (action, days, brandTerms, user_intent, minImpressions) already carries a rich description, including per-action behavior inside the action enum values. The description adds little per-parameter detail beyond schema; its scoping note ('no domain or site parameter is needed') is useful but marginal. Baseline of 3 for full schema coverage is appropriate.

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

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

The description names a specific resource (captured Search Console history) and enumerates all six derived analysis types (cannibalization, brand_split, CTR outliers, search_appearance, seasonality, sitemaps). It explicitly distinguishes itself from the sibling gsc_performance: 'Use gsc_performance for raw metrics; use this for the diagnosis layer.' An agent can tell exactly what this tool produces and how it differs from its neighbors.

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 alternative and selection condition ('Use gsc_performance for raw metrics; use this for the diagnosis layer'), which doubles as a when-not. It also flags the data-lag constraint ('finalized weekly... lag live Google by a few days') that should steer an agent away from using it when live data is required, and clarifies scoping so the agent knows no site/domain parameter is needed.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: data is Google-finalized with a ~2-3 day lag, days/dates bound every action, compare_periods contrasts with the immediately preceding window, and the tool is FREE with no AI credits. It does not contradict annotations.

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

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

The description is compact and front-loaded: the core purpose and metrics appear in the first sentence, followed by data-lag, scoping, and routing guidance. The final cost note is useful but slightly tangential. Every sentence earns its place, though the cost sentence could arguably be trimmed.

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 tool with 10 parameters, 100% schema coverage, an output schema, and strong annotations, the description covers the essential context: data freshness, scoping, cost, and when to use the sibling. It does not enumerate return shapes, but the output schema exists and the description need not explain return values. Minor gap: no explicit mention of pagination or row caps, though the schema covers limit/maxRows.

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

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

Schema description coverage is 100%, so the schema already documents all 10 parameters thoroughly, including enums and per-action applicability. The description adds a few cross-cutting semantics (days/dates bound every action, compare_periods contrasts with the immediately prior window, cost is FREE) but does not need to repeat parameter details. Baseline 3 is appropriate since the schema carries 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 opens with a specific verb ('Read') and resource ('Google Search Console performance'), then enumerates the exact metrics (clicks, impressions, CTR, position) and grouping dimensions (query, page, dimension, period comparison). It also names the sibling tool it is not (gsc_insights) and states the data source is the user's own connected property. This clearly distinguishes it from the 28 sibling tools.

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

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

The description explicitly says when to use this tool vs alternatives: 'For diagnosis (cannibalization, CTR outliers) use gsc_insights rather than recomputing here.' It also states the tool is already scoped to the connected workspace and site, so no domain/site parameter is needed, and notes the ~2-3 day data lag. This gives an agent clear decision criteria for selecting this tool over siblings.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true. The description adds valuable context: the 2-hour stash lifetime, the cost ('Cost: FREE - reads your connected/stored data, no AI credits'), and the exact next-step usage (libraryDatasetId with rowSourceKind 'library'). No contradiction with annotations; it enriches 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?

The description is moderately long but each sentence serves a purpose: purpose, when-to-use, constraint, cost, and integration. The key information is front-loaded with the action and resource. It is not overly verbose and avoids redundancy.

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

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

Given the tool's complexity (mutation with output schema and integration), the description covers the essential usage, constraints, and next steps. It omits error scenarios (e.g., expired attachment) but the output schema and annotations fill most gaps. The description is complete enough for an agent to call it correctly.

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

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

Schema coverage is 100%, so all three parameters are documented in the schema (attachmentId from preview, name defaults, user_intent). The description does not add new parameter-specific meaning; it repeats the source of attachmentId and mentions defaults, but these are already in the schema. Baseline 3 is appropriate given full schema 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?

The description states a precise action: 'Promote a spreadsheet ... into a private dataset in their library'. It identifies the specific resource (CSV/Excel uploaded in this conversation) and distinguishes it from siblings by noting 'Only works on files uploaded here; nothing else is creatable this way.' This clearly sets it apart from dataset_library and other dataset management 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?

Explicit guidance is given: 'Call it when the user wants the file used as campaign data (pages-at-scale rows, bulk targets) or asks to save it as a dataset'. It also states the exclusion ('Only works on files uploaded here') and the downstream integration ('the returned id then goes to propose_page_scale_campaign...'). No ambiguity about when to use it.

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

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

Annotations already mark read-only/idempotent; the description goes further by disclosing that the map reflects the last refresh and is empty until GSC history exists, plus the cost implication of no AI credits. This is genuine added context beyond structured metadata.

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?

Every sentence carries unique information: definition, freshness, alternative, scoping, cost. It is not overly long and the core purpose is front-loaded, though the cost sentence could be seen as extra but is ultimately useful.

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

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

With an output schema present and a single enum action, the description covers the essential runtime behavior (cached, pre-scoped, free) and routes to keyword_research when freshness matters. Nothing an agent needs to invoke it correctly is 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 100% for both parameters, so the baseline is 3. The description adds the important clarification that no domain or site parameter is needed, which prevents an agent from trying to pass workspace-scoping arguments; the action enum and optional user_intent are otherwise fully self-explanatory.

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 the exact resource ('cached keyword-cluster map') and its content types, and contrasts with keyword_research for live numbers. The tool name and schema action 'list' align, so an agent knows it is a lookup of the precomputed map.

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 names the alternative tool for live demand ('use keyword_research') and explains the cached nature, telling the agent when to pick this over a recomputation. Also clarifies that the tool is pre-scoped and requires no domain/site parameter, removing a common invocation uncertainty.

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 mark the tool read-only, open-world, and idempotent, and the description adds crucial behavior beyond that: live vendor data, an explanatory rather than fabricated error when credits are missing, and never-fabricated numbers. It also discloses billing behavior (AI credits vs free operations) and workspace scoping, which is exactly the kind of context an agent needs.

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 dense sentences with no filler. The core purpose is front-loaded, then caveats (live data, no fabrication), then usage scoping, then cost model. Every sentence earns its place despite covering a multi-action 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?

For a multi-action tool with an output schema, the description covers purpose, alternatives, scoping, error behavior, and cost thoroughly. It loses one point because the 'performance' mention is not backed by a matching action enum entry, so an agent reading the description could expect an operation the schema doesn't offer.

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

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

Schema coverage is 100% and the schema already documents action, keyword(s), limit, and user_intent. The description adds value by mapping actions to cost (metrics/suggestions bill credits; trends/related/compare are free) and clarifying that keyword is single vs keywords is a set. Minor deduction because the description references 'performance' as a free operation, but no 'performance' value appears in the action enum, so the parameter mapping is slightly muddled.

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 and resource: 'Research keyword demand' and enumerates concrete outputs (volume, difficulty, CPC, intent, keyword ideas, Trends interest, related queries, Ads performance). It also explicitly contrasts itself with the sibling serp_competitors ('for who ranks today'), so an agent can disambiguate the tool's scope.

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

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

Provides explicit when-to-use guidance ('Use for what to target and how much demand exists') and names the alternative for the non-target case ('for who ranks today use serp_competitors'). It also tells the agent no domain/site parameter is needed because the tool is already scoped to the connected workspace.

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 read-only and idempotent, but the description adds crucial behavioral details: cost implications (list_locations/reviews are free, visibility bills AI credits), dependency on what is connected, and that it is already scoped. This adds value beyond annotations and helps the agent understand side effects and prerequisites.

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

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

The description is a bit long but well-structured: it front-loads the purpose, then usage guidance, scoping, and cost. Each sentence carries information, though the mention of actions not in the schema adds minor redundancy. It is efficient overall.

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

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

Given the tool has an output schema (not shown) and annotations cover safety, the description covers usage, scoping, cost, and alternatives. The mention of actions outside the schema is a minor gap, but for the visible visibility action, everything needed is present. It is complete for practical use.

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 cost context for the visibility action and mentions other actions (list_locations, reviews) that are not in the schema's enum, which could confuse the agent. It doesn't enrich parameter meaning beyond what the schema already provides, but the cost note is useful.

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

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

The description clearly states the tool reads local search presence including Business Profile locations, local rankings for money keywords, and review ratings. It also explicitly distinguishes itself from serp_competitors for national rankings, making it easy to select among 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 provides explicit guidance on when to use (local and map-pack questions) and when not to (national rankings, use serp_competitors). It also clarifies that it is scoped to the connected workspace, so no domain parameter is needed, which prevents incorrect usage.

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 goes well beyond the annotations by disclosing that the token is single-use, stripped amount-capped, prices are fixed server-side, and units become usable immediately on success. It also clearly states the cost implications: charges the user's approved payment method and consumes no AI credits. No contradiction with annotations exists.

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

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

The description is dense but every sentence earns its place. It front-loads the core action and token requirement, then gives product details, safety rules, fallback behavior, and side effects in a logical order. The repeated warnings are justified given the financial risk.

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 payment-triggering tool with an output schema available, the description is complete: it covers preconditions, product semantics, fallback routing when the tool cannot be used, postcondition behavior, and cost implications. Nothing critical is missing for an agent to decide whether and how to call 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?

The schema already documents 75% of the parameters, and the description adds substantial meaning beyond it: product meanings and prices, the default SKU, token provenance, and single-use/amount-cap behavior. Quantity is not elaborated beyond what the schema's min/max provides, but the rest of the parameter semantics are well enriched.

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

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

The description clearly states the tool's function: paying for prepaid units with a Stripe Shared Payment Token. It specifically enumerates the purchasable products (article, question_pack, visibility_scan, competitor_scan) with prices and default behavior, making it easy to distinguish from sibling tools like generate_article or get_credit_usage.

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

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

The description gives explicit when-to-use and when-not-to-use guidance. It states 'Only call this with a real token from your platform's payment system', explicitly warns against inventing tokens or asking users for card credentials, and directs agents to relay the buy link from payment_required instead if their platform cannot mint SPTs.

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 non-obvious behavior beyond annotations: resuming is free but each released page bills AI credits; the token's derivation from the hold proves evidence was read; and the drip stopped itself after poor search appearances. This aligns with readOnlyHint=false/idempotentHint=false and adds cost and accountability context 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?

The description is compact and front-loaded: the first sentence states the trigger condition, then the token requirement, the caution about fixing content, and the cost consequence. Each sentence carries new, decision-relevant information without 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 conditional resume operation with an output schema, annotations, and a rich input schema, this description covers the complete decision context: when the hold occurs, what proves informed consent, what happens after resuming, and at what cost. No critical missing guidance remains for choosing or invoking 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 already covers all three parameters with 100% coverage, so the high-coverage baseline applies. The description adds extra semantic value for resumeToken—that it is derived from the hold and proves informed consent—beyond the schema's provenance note, though campaignId and user_intent get no additional description-level detail.

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 operation—resuming a page campaign only when the scale governor paused publishing—and explains the hold condition. This clearly distinguishes it from the many content/visibility/campaign siblings by defining the exact state and mechanism involved.

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 context: only for scale-governor holds, and requires passing the hold's resumeToken after reading evidence. It also warns to strongly consider fixing template/content first, defining when resuming is inadvisable, and notes the credit-billing consequence.

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?

Despite annotations being sparse (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), the description fully carries the behavioral burden: it discloses cost in AI credits, latency (minutes), immediate return of scanId, the need to poll with get_ai_visibility, and the hourly rate limit. No annotation contradiction exists.

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?

Every sentence earns its place: it front-loads the core action, then covers cost, latency, return value, polling alternative, and rate limit. The description is dense but not bloated, and it is well structured with clear separations of concerns.

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, the description covers all essentials an agent needs to invoke it correctly: what it does, what it costs, how long it takes, what it returns, how to retrieve results, and operational limits. The output schema exists, so return-value details beyond scanId are not required 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 100%, so the baseline is 3. The description adds meaningful context beyond the schema by clarifying that omitting domain scans the user's own site and providing a domain scans a competitor instead. This materially enriches the domain parameter's semantics, though user_intent remains only explained by 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 uses a specific verb ('Start') and a precise resource ('FRESH AI-search visibility scan'), explains what the scan does (queries live AI engines with buyer-intent prompts and checks brand visibility), and implicitly distinguishes itself from the sibling get_ai_visibility by noting it returns a scanId for later polling. This is strong, differentiated purpose clarity.

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

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

The description gives explicit when-to-use guidance: check get_ai_visibility first because reading an existing recent scan is free, and only run a fresh scan when needed. It also states the one-scan-per-hour limit and directs the agent to inform the user before calling. These are clear usage rules and alternatives.

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

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

Annotations already mark readOnly/openWorld/idempotent/destructive, and the description adds important behavioral context: results are live at call time, capped by limit, and billed as AI credits for vendor data. It also clarifies no side effects to stored data ('reads of your own stored data elsewhere are free').

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?

Information is front-loaded with purpose, followed by live-source behavior, use-case guidance, scoping, and cost. Every sentence carries distinct operational value with no fluff.

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

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

Given four actions and five parameters, the description plus schema and output schema cover both invocation semantics and operational constraints. It even handles the subtle case of domain omission and cost, leaving little ambiguity for a complex 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 covers all parameters at 100%, so the baseline is 3; the description improves on it by explaining default domain resolution ('Omit for the connected workspace's own site; pass only for a competitor') and that limit applies per action. It doesn't need to restate schema details.

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

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

Description opens with a specific verb and resource ('Inspect the live search landscape') and enumerates concrete capabilities: SERP features, domain-level rankings, visibility distribution, and competitor domains. It also contrasts with keyword_research, making its role distinct from 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?

Explicitly states the intended use case ('Use for who ranks and why; for keyword demand use keyword_research') and directs agents to call directly with no domain/site parameter due to workspace scoping. Cost explanation helps agents decide when it is worth 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?

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false. The description adds genuinely useful context beyond those: the cards render directly in the reply, no dashboard navigation is needed, and the operation is free with no AI credits. It does not disclose what happens when a user actually approves or dismisses an item, but for a card-rendering tool this is a minor gap.

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

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

The description is compact and front-loaded: purpose, prerequisite, usage trigger, and a clear anti-pattern in four short sentences. It loses a point because 'Render inline Approve/Dismiss cards' and 'the cards appear directly in your reply' are slightly redundant, and the cost note could be tightened, but every sentence still earns its place.

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

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

Given the output schema exists and the parameter count is small, the description is largely complete: it covers what the tool does, when to call it, how to get IDs, and what not to do. The main omission is a clearer statement of whether taskIds, campaignIds, neither, or both are required to render a useful result; the schema says 0 required, but the description's 'get ids first' implies at least one should be present.

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 low (33%), but the description compensates by telling the agent to source taskIds and campaignIds from list_seo_tasks / list_seo_campaigns first, which adds real meaning beyond the raw parameter names. It does not restate the maxItems constraints or explicitly discuss optionality, but those are already visible in the schema and the description's 'existing proposals' framing covers the core semantic gap.

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

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

The description states a specific verb and resource: 'Render inline Approve/Dismiss cards for EXISTING proposed tasks and campaigns.' It also distinguishes the tool from the dashboard and from list-style tools by requiring IDs from list_seo_tasks/list_seo_campaigns first, so an agent can tell exactly what this tool does.

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

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

The description gives an explicit trigger: 'Call this whenever the user wants to see, review, or act on proposals that already exist.' It also states a clear when-not-to: 'NEVER send the user to the dashboard to approve something,' and names the prerequisite source of IDs. This is concrete, actionable 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 carry the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), and the description adds meaningful context beyond them: the confirmation semantics ('never claim a fact is confirmed until they act') and the cost note (FREE, reads stored data, no AI credits). No contradiction with annotations; 'Render' aligns with 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?

Four sentences, front-loaded with the core purpose, then usage, then the critical behavioral caveat, then cost. Each sentence earns its place; slightly longer than minimal but every clause adds agent-relevant 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?

Complete for a read-only rendering tool: an output schema covers return values, annotations cover safety, and the description covers purpose, empty vs non-empty states, usage context, a behavioral constraint, and cost. 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 description coverage is 100% and the single optional parameter (user_intent) is fully documented in the schema, so the description need not add param detail. The description correctly implies the parameter is optional context only. Baseline 3 is appropriate when 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 ('Render') and resource ('Trust Profile card'), and describes exactly what the card shows (harvested-but-unconfirmed facts with Confirm buttons, or a 'Scan my site' button when empty). It clearly distinguishes from siblings like get_trust_facts (data retrieval) and confirm_trust_fact (user action) by being the inline UI-rendering tool.

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

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

Explicitly states when to use it: when the conversation touches E-E-A-T/credibility/trust, or when explaining omitted trust claims. It gives clear context but does not name alternatives or explicit when-not conditions, so an agent must infer that get_trust_facts/confirm_trust_fact serve different steps.

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 mark it read-only and idempotent; the description adds concrete runtime behavior: crawling up to 30 pages, HEAD-checking link targets, respecting a time budget, explicitly reporting partial crawls, and using its own crawler for free. These disclosures go well beyond the annotations.

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 sentence is dense and valuable, listing scope and issue categories. However, the cost information is stated twice: 'FREE: fetches with SEOmatic's own crawler, no vendor spend' and 'Cost: FREE - crawls with SEOmatic's own crawler at call time, no AI credits.' This redundancy costs a point.

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 audit with an output schema and fully described parameters, the description covers crawl source, size limit, cost, time-budget behavior, and partial-crawl caveat. 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 description coverage is 100%, so the baseline is 3. The description adds only the distinction between inventory-based crawling and passing specific URLs, which the schema already states. No additional parameter semantics are provided beyond what the input schema covers.

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 'Site-WIDE technical SEO audit' and enumerates concrete issues it detects: duplicate titles, missing metas, canonical mismatches, broken internal links, etc. This clearly differentiates it from general page-listing or performance tools like site_pages and gsc_*.

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

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

It provides clear context: use this tool when cross-page issues need to be surfaced beyond what a single-page check can see, and choose between the synced inventory or explicitly provided URLs. It does not explicitly name alternative tools or state when not to use it, but the context is sufficient.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, but the description adds critical behavioral details: analyze/crawl fetch the LIVE page at call time (unreachable URL returns fetch error), while inventory reads the stored daily-synced index (brand-new pages can lag). It also discloses the cost (FREE, no AI credits). This goes well beyond annotations and covers behavior an agent needs to know.

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 fairly long but well-structured: it starts with the core purpose, then breaks down actions, then covers data freshness, then sibling tool, then scoping and cost. Each sentence contributes distinct information, and the most important guidance (live vs. stored) is early. Slightly verbose but not bloated, so a 4.

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 (four actions, multiple parameters, and an output schema), the description covers all essential aspects: what each action does, when to use which, data source differences, scoping, cost, and relationship to the sibling tool. The output schema is available separately, so return format doesn't need to be in the description. Nothing critical 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 baseline is 3. The description adds meaning by explaining the action enum ('analyze' vs 'crawl' vs 'inventory' vs 'score_draft') and clarifying the data source (live vs stored). It also mentions that score_draft is deterministic and free, which is not in the schema. This adds value beyond the parameter descriptions, so a 4 is warranted.

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 what the tool does: analyze pages for on-page SEO score, critical issues, raw crawl metadata, and page inventory. It distinguishes the actions (analyze, crawl, inventory, score_draft) and explicitly names the sibling tool gsc_performance to clarify scope. The verb 'analyze' plus resource 'pages' and specific outputs make the purpose unambiguous.

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

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

The description explicitly says when to use this tool ('Use for page-level diagnosis') and when not to ('for search performance of those pages use gsc_performance'). It also explains the live vs. stored data distinction (analyze/crawl fetch live, inventory reads daily-synced index) and notes that it's already scoped to the connected workspace, so no extra parameters are needed. This provides complete 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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds meaningful behavioral context: signals refresh nightly while strategy updates weekly, and undiagnosed workspaces will be reported as such rather than invented. It also discloses cost (free, no AI credits), which is not present in annotations. No contradictions.

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

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

The description is a single 4-sentence paragraph that front-loads the core purpose, then adds refresh cadence, non-fabrication behavior, scoping, and cost. Each sentence provides distinct, useful information with no filler or repetition. Slightly longer than minimal but every clause earns its place.

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

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

Combined with the output schema and annotations, the description covers the tool's purpose, freshness, scoping, cost, and an important edge case (undiagnosed workspace). It does not detail return values, but the output schema handles that. For a 3-parameter tool with an enum, this is sufficiently complete for correct invocation.

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

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

Schema description coverage is 100%, so the input schema already documents action, signal, and user_intent thoroughly. The description adds the meta-note that no domain/site parameter is needed, which clarifies invocation but does not add deeper semantics to the existing parameters. Baseline 3 is appropriate given full schema 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?

The description clearly defines the tool as 'the agent's cached diagnosis for this workspace' and enumerates four concrete components (snapshot, strategy, raw signal, content scores). It states the resource and scope, and distinguishes itself by being workspace-scoped and requiring no domain/site parameter. However, it doesn't explicitly name a verb like 'get' or 'retrieve' or compare against a specific sibling.

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

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

Provides clear context that the tool is already scoped to the connected workspace and site, so agents can call it directly without domain/site parameters. This implies when to use it (for cached diagnosis of the current workspace) but does not explicitly mention alternatives or when-not conditions. The refresh cadence hints at staleness but does not guide agents to other tools for fresher data.

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 annotations, the description discloses a great deal of operational behavior: which actions are free, that execute bills AI credits, that approving auto-dispatches work, that rollback is an action rather than a read, and that inspecting tasks never triggers re-analysis. These details add real safety and cost-awareness value, and there is no contradiction with the annotations.

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 information-dense and front-loads the core lifecycle, but it is a single long paragraph with some redundancy (e.g., 'Staging never runs anything' and 'create only STAGES proposals, nothing runs') and an unclear phrase ('the instant path declined'). It earns its content but would benefit from clearer structure.

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

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

For a complex multi-action tool, the description covers the essential context: safety gates, cost implications, workspace scoping, rollback semantics, and execution behavior. Combined with the 100%-cover parameter schema and output schema, little critical guidance for correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents each parameter in detail. The prose adds some context such as 'create accepts up to 5 per call' and the reviewToken release flow, but much of this repeats schema descriptions, so the description does not substantially compensate beyond the structured schema.

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

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

The description opens with 'The agent's full task lifecycle' and concretely enumerates the six operations: list, get, create, decide, execute, and rollback, with clear verbs and objects for each. This makes the tool's role obvious and distinguishes the operation modes without needing to inspect the action enum.

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 practical usage context: staging never runs anything, mutations are human-approval-gated, execute can force-run or release held work via reviewToken, rollback is drift-guarded, and the tool is already scoped to the connected workspace so no domain/site parameter is needed. It stops short of 5 because it does not name sibling tools as alternatives (e.g., get_task_rollback or show_approval_cards).

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 mark the tool as read-only, idempotent, and non-destructive; the description adds valuable behavior beyond that: missing connections are named rather than silently returning empty data, GA4 cannot attribute AI traffic so it files it as 'Direct', and the tool reads connected/stored data without consuming AI credits. No contradiction with annotations.

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

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

The description is dense but front-loaded with the core purpose and then expands into distinctions, alternatives, and cost. Each sentence carries useful information, though the long enumeration of action groups could have been tightened 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?

The description covers purpose, scoping, measurement differences, missing-connection behavior, AI engagement attribution, and cost, and an output schema exists. The main gap is the mismatch between described actions and the actual action enum containing only ai_pages, which leaves an agent uncertain about whether other described actions are callable.

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

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

Schema description coverage is 100%, so the parameters are already well documented. The description adds useful action-level semantics, notably that GA4 actions and Ads actions target different systems, but it does not explain days or limit in more depth. Given the baseline of 3 for full schema coverage, this is adequate.

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

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

The description clearly states the tool's purpose: GA4 traffic and Google Ads account/campaign/search-term performance, plus first-party AI engagement. It also differentiates from gsc_performance by noting Search Console clicks are measured separately. However, it references action names like overview/sources/landing_pages/top_pages and ads_* that are not present in the action enum, which slightly blurs what the tool can actually execute.

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

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

Provides explicit alternative routing: 'for search clicks use gsc_performance'. It also clarifies GA4 vs Search Console measurement semantics, states the tool is pre-scoped so no domain/site parameter is needed, and explains how missing connections behave instead of returning empty data. This gives an agent enough context to decide when to call this tool versus its siblings.

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

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

Annotations already set readOnlyHint=false, destructiveHint=false, and openWorldHint=true, and the description adds useful behavior beyond that: it returns the same attachmentId a chat upload would mint, it stages the text, it is free and consumes no AI credits, and the content must come from a user-chosen file. No annotation contradiction is present.

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 longer than average but every sentence earns its place: purpose, host-specific context, routing to the sibling, chat exclusion, safety warning, and cost. The key purpose and warning are front-loaded before the cost detail.

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

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

For a three-parameter staging tool with an output schema and full parameter coverage, the description covers the entire call flow: where the file text comes from, what is returned, which sibling to call next, and when to avoid the tool. Nothing required for correct invocation is missing.

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

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

Schema coverage is 100% and the parameter descriptions are already explicit, so the baseline is 3. The description adds contextual color by tying csvContent to 'the user's file in the browser' and by explaining the returned attachmentId, but it does not add new parameter-level syntax 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 opening sentence names a specific verb and resource: 'Stage CSV TEXT so it can be imported as a dataset.' It also distinguishes itself from the sibling import_attachment_as_dataset by explaining it produces an attachmentId that should be passed to that tool, and clarifies it is not a generic upload by warning not to invent content.

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

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

The description explicitly says when to use it ('MCP Apps hosts... no file transport'), when not to use it ('In chat you never need this'), and names the next step ('Pass that id straight to import_attachment_as_dataset'). It also gives a strong negative guideline: 'Do NOT invent CSV content to call this with.'

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 goes well beyond the annotations by disclosing that config changes apply directly with no staging, that changes are plan-capped, that cadence 'daily' multiplies spend ~7x and requires explicit user ask, and that each active prompt raises recurring scan cost. This is exactly the kind of behavioral context an agent needs before invoking mutations.

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

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

The description is front-loaded with the core purpose and then delivers high-value constraints. It is slightly repetitive about the 'daily' cost multiplier, appearing both in the cadence explanation and again in the cost summary, but each sentence still earns its place and the structure is scannable.

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 (10 parameters, 5 actions, cost implications), the description covers everything needed to invoke it correctly: scope, routing to sibling tools, plan caps, cost levers, consent requirements, and direct application of changes. An output schema exists, so return-value details do not need to be in the prose.

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

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

Schema description coverage is 100%, so the baseline is 3, and the schema already documents every parameter. The description adds meaning above the schema by explaining the spend implications of 'daily' cadence and active prompts, and by emphasizing the need for explicit user confirmation before setting the expensive cadence.

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 ('Manage'), a clear resource ('AI-visibility monitor'), and enumerates the exact operations: list, add/edit/remove prompts, and set cadence. It also differentiates from siblings by noting that scan results live in ai_citations and that fresh scans must go through the dashboard, so an agent knows precisely what this tool does and does not do.

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

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

The description explicitly routes the user elsewhere for related but different actions: 'Reads of scan RESULTS live in ai_citations action scan_results' and 'Running a FRESH scan is not available over MCP; point the user at the dashboard.' It also clarifies that no domain or site parameter is needed, preventing unnecessary calls.

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