SEOmatic

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

The annotations already set readOnlyHint, idempotentHint, and openWorldHint. The description adds behavioral context about being scoped to the connected workspace and that no domain parameter is required, which goes beyond the annotations. No contradictions exist.

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

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

The description is a single focused paragraph that leads with the core purpose, then specifies scope and usage guidance. It is concise, well-organized, and avoids redundancy, including a clear contrast with the sibling 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?

Given the tool's moderate complexity (six parameters, one required, with enums), the description covers purpose, usage, scoping, and alternatives. It does not delve into output specifics, but the presence of an output schema covers that. It lacks discussion of edge cases or errors, but these are not critical for basic usage.

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 descriptions are already detailed (e.g., action enum explanations, domain optionality, competitors list). The tool description does not add significant new semantics beyond restating the overall purpose; it mainly reinforces what the schema already covers, so it provides minimal additional value for parameter understanding.

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

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

The description explicitly states the tool reads backlink profiles for own or competitor sites, lists the key metrics (referring domains, anchor text, velocity, prospects), and differentiates its use case (authority/link questions) from the sibling tool serp_competitors, making its purpose clear and distinct.

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 this tool ('for authority and link questions') and when to use an alternative ('for rankings use serp_competitors'). It also clarifies that no domain parameter is needed because it's scoped to the connected workspace, giving concrete usage instructions.

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 carry only generic flags (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the description takes on the behavioral burden and delivers: the approval-gating guarantee ('All staging is proposal-based and approval-gated; nothing publishes without the user') and the free-tier upgrade-path behavior. Both are operational facts an agent cannot infer from the schema or annotations, and neither contradicts the annotation flags.

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 around 90 words with the purpose front-loaded in the first sentence. However, the approval-gating point is redundantly stated twice — 'nothing publishes without the user' is restated as 'Every staged change still requires human approval in SEOmatic before anything goes live' — which wastes a sentence that could have held new information.

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

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

For a complex 31-parameter, 6-action tool, the schema (100% coverage) and output schema already document parameters and return shapes; the description supplies the missing operational context an agent cannot derive elsewhere: the approval gate and the free-tier upgrade-path behavior. That is the most important guidance for calling this tool correctly in the current environment. The only shortfall is the duplicated approval language, not missing substance.

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 action enum's description already enumerates all six operations with their purposes and required companion fields, so the schema carries the load. The description adds only a high-level grouping of the staging actions and no per-parameter detail beyond what the schema provides. The baseline 3 for high schema coverage applies.

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

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

The description opens with specific verbs ('Read', 'stage') tied to concrete resources (campaigns, blog articles) and enumerates the three staging modes (page-scale, content-sweep, bulk-edit). This cleanly differentiates campaign_manage from its research-oriented siblings (keyword_research, site_audit, serp_competitors), which are all read/analysis tools, making the agent's selection 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 delivers a decisive usage signal for this environment: the key is on the free insight tier, so calling any action returns 'the exact upgrade path to relay to the user instead of refusing.' This tells the agent exactly what to expect and how to respond to the user rather than treating the call as a normal execution. It does not explicitly name sibling alternatives or exclusion conditions, but no sibling is a campaign/content tool, so routing is already clear.

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

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

Annotations already carry readOnly, idempotent, and non-destructive hints. The description adds valuable behavioral context beyond those annotations by confirming the tool is pre-scoped to the connected workspace and site, and that no domain/site parameter is required.

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

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

Two tight sentences front-load the tool's scope and enumerate all actions with zero filler. Every clause earns its place, and the critical 'no domain/site parameter needed' note is clearly stated.

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 full input schema, output schema, and comprehensive annotations, the description supplies the only additional context needed for correct invocation: pre-scoping and the absence of a domain/site parameter. Nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema fully documents action, limit, datasetId, templateId, and user_intent. The description only adds a meta-point about scoping and doesn't deepen individual parameter semantics beyond what the schema already provides.

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

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

The description names four concrete operations with verb+resource pairs: list datasets, sample rows, list templates, and read one template. This makes the tool's purpose unmistakable and distinguishes it from mutation-focused siblings like import_attachment_as_dataset.

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

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

The description clearly tells the agent the tool is already scoped to the connected workspace and site, and that it should be called directly without a domain or site parameter. It doesn't explicitly name alternatives or when-not conditions, but this is sufficient guidance for a read-only library 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?

The description states 'reads stored scan results only; it never runs a new scan,' which implies a read-only, side-effect-free operation. However, the annotations declare readOnlyHint=false, directly contradicting the description's safety profile. This mixed signal can mislead an agent about whether invoking the tool may have side effects.

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

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

The description is dense but efficient: two sentences convey scope, output contents, the read-only guarantee, and the fallback behavior when no scan exists. Every clause adds useful information with 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?

An output schema is present, so the description correctly avoids explaining return values. It covers all non-obvious operational details an agent needs: read-only behavior, no new scan, and the dashboard-link fallback. This is complete for a tool of this complexity.

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 no parameter-level detail beyond what the schema already documents for scanId and user_intent, and it does not mention either parameter explicitly.

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: 'Read the workspace's latest completed AI-search visibility scan' and then enumerates exactly what is returned (per-engine visibility, missed prompts, winners, competitors, sources). This clearly differentiates the tool from its siblings, none of which promise AI-search visibility scanning.

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 context for when to call the tool: it reads stored scan results only and 'never runs a new scan,' with a clear fallback behavior (returns dashboard link when no scan exists). It doesn't name an alternative tool, but no sibling tool covers this domain, and the 'FREE' note plus fallback adequately routes the agent.

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

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

Annotations already indicate readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false. The description adds meaningful behavioral context beyond these: the 2-hour stash lifetime, the private-library destination, and the hard constraint that only conversation-uploaded files are eligible. This is strong but not exhaustive, as it doesn't describe duplicate behavior on repeated calls.

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 purpose and then delivers trigger conditions and constraints in a dense paragraph. Every clause adds value, though the single long sentence is slightly run-on; splitting it into separate sentences would 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?

With a simple 3-parameter schema, an output schema available, and rich context covering source precondition, trigger, downstream destination, and storage lifetime, the description fully equips an agent to invoke this tool correctly. 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 description coverage is 100%, so the schema already documents all three parameters. The description adds context around attachmentId ('preview carries an attachmentId') but this is largely redundant with the schema's 'attachmentId shown in the uploaded file preview.' 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 action ('Promote a spreadsheet... into a private dataset'), a specific resource (uploaded CSV/Excel with attachmentId), and clearly differentiates from siblings with 'Only works on files uploaded here... nothing else is creatable this way.' This is a clear verb+resource+scope definition.

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

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

It explicitly tells the agent when to call this tool ('Call it when the user wants the file used as campaign data... or asks to save it as a dataset'), and when not to call it ('Only works on files uploaded here... nothing else is creatable this way'). It also explains the downstream flow with propose_page_scale_campaign, making selection unambiguous.

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

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

Annotations already cover read-only, idempotent, open-world, and non-destructive behavior. The description adds useful behavioral context beyond that: the tool is scoped to the connected workspace and its site, and it can be called directly without a domain parameter. This is meaningful, though more operational details like rate limits or result ordering are not disclosed.

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

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

The description is two dense sentences with zero filler. It front-loads the primary purpose and output categories, then gives a routing rule and a scoping note that directly affect how the agent should invoke the 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 keyword research tool, the description covers the purpose, output types, key alternative tool, and important scoping behavior. An output schema is present, so return values do not need to be described. An agent has enough context to decide when to call this tool and how to call it correctly.

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

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

The input schema already provides 100% coverage and fully explains each parameter and the action enum. The description adds one valuable parameter-related clarification: no domain or site parameter is needed because the tool is already scoped, which helps prevent an agent from inventing a non-existent parameter.

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 and resource ('Research keyword demand') and enumerates the concrete outputs: search volume, difficulty, CPC, intent, keyword ideas, Google Trends interest, related queries, and Google Ads performance. It also explicitly distinguishes itself from serp_competitors, so an agent can tell exactly which tool answers which question.

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 guidance: use this tool for what to target and demand existence, and use serp_competitors for who ranks today. It also states that the tool is already scoped to the connected workspace and site, so no extra domain or site 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 establish readOnly, idempotent, and non-destructive behavior, so the description does not need to restate safety. It adds meaningful behavioral context by disclosing that available actions depend on workspace connections and that results are already scoped to the connected workspace and site. This goes beyond the structured annotations and helps the agent understand variability and invocation expectations.

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

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

Three sentences with no filler. The first sentence states purpose, the second flags a dependency caveat, and the third gives usage guidance plus an explicit alternative. Every sentence earns its place, and the most decision-relevant 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?

Given the tool's modest complexity, full parameter schema coverage, output schema presence, and safety annotations, the description covers everything an agent needs: what the tool reads, when to use it, which sibling to prefer otherwise, the dependency on workspace connections, and the fact that no domain/site parameter is required. There are no material gaps.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds useful semantic context: it refers to 'money keywords' for the keywords parameter and clarifies that no domain or site parameter is needed, reducing the chance of the agent inventing parameters. The action enum is already well documented in the schema, and the description reinforces that actions depend on workspace connectivity.

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

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

The description opens with a clear verb-resource pairing: 'Read the local search presence of the connected business,' and enumerates what that includes: Business Profile locations, local ranking for money keywords, and review ratings. It also explicitly distinguishes itself from the sibling tool serp_competitors by scoping this tool to local and map-pack questions, making it easy for an agent to select correctly.

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 direct usage guidance: 'Use for local and map-pack questions; for national rankings use serp_competitors.' It also tells the agent not to pass domain or site parameters because the tool is already scoped to the connected workspace, and notes that available actions depend on what is connected. This is explicit, actionable, and prevents misuse.

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 supply readOnly, idempotent, and non-destructive hints, so the bar is lower; the description adds meaningful behavior by noting the tool inspects live data and is already scoped to the connected workspace. It explicitly says to call directly and omit the domain for the workspace's own site, passing a domain only for competitors. 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?

Three sentences with no filler: the first packs the tool's scope, the second gives the use-case, and the third clarifies scoping and call convention. The most important information is front-loaded. Every sentence earns its place.

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

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

Given the multi-action nature, the description plus the fully documented schema and output schema cover the key requirements: what it inspects, which sibling covers demand, how domain/scoping works, and what each action returns. No critical calling information is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 100% and the action enum entries already document each operation thoroughly, so the description does not need to repeat parameter syntax. It contributes a small contextual note about not needing a domain/site parameter for the workspace's own site, but the schema's domain field already says this. This is the baseline schema-driven score.

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

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

Description opens with a specific verb ('Inspect') and resource ('live search landscape'), then enumerates concrete outputs: SERP features, domain-level top rankings, visibility distribution, and competitor domains. It also distinguishes itself from the sibling keyword_research by assigning that tool to 'keyword demand.' This is enough for an agent to know what the tool does and when to pick it.

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

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

Provides explicit usage framing: 'Use for who ranks and why' versus 'for keyword demand use keyword_research,' naming the relevant alternative. It also tells the agent the tool is pre-scoped to the connected workspace, so no domain/site parameter is required for the own-site case. This is clear guidance without ambiguity.

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

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

Annotations are sparse (only readOnlyHint, openWorldHint, idempotentHint, destructiveHint), so the description carries the burden and does so well. It discloses the crawler used, the 30-page bound, the free/no-vendor-spend trait, the time budget, the explicit partial-crawl notification, and the HEAD-check behavior for link targets.

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: scope, crawl source, issue examples, cost, and behavioral caveats. The most important decision-relevant phrase, 'Site-WIDE technical SEO audit,' 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?

Given the output schema exists and parameters are fully documented, the description covers everything else an agent needs: what pages are crawled, default versus explicit urls, cost implications, time limits, and how partial results are reported.

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 three parameters. The description adds useful context about the inventory source and url override but does not need to compensate for missing schema documentation.

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

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

The description opens with 'Site-WIDE technical SEO audit' and names a concrete verb-resource pair that separates it from single-page checks. It enumerates the exact cross-page issue categories it aggregates, so an agent can immediately identify when this tool and not another one is needed.

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

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

The description clearly states the tool is for cross-page issues that 'a single-page check cannot see,' giving the agent a useful selection criterion versus the sibling site_pages tool. It does not explicitly name an alternative or provide when-not-to-use exclusions, but the contrast with single-page checks is strong enough context.

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

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

The annotation already declares read-only, idempotent, non-destructive behavior. The description goes beyond by clarifying the scoping behavior (already bound to workspace/site) and summarizing the returned data types. It does not mention edge cases or error conditions, but that is not essential given the safe annotation profile.

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 well-structured: it states the action, lists outputs, gives usage guidance, and notes scoping in three sentences. No redundant or filler content is present.

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 moderate complexity, the description fully covers the tool's purpose, usage context, and scoping. The existence of an output schema (as per context signals) means the description does not need to explain return structures, so it is complete as is.

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

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

The input schema has 100% coverage with detailed descriptions for each parameter (action, url, user_intent). The tool description adds no extra meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Analyze pages') and enumerates concrete outputs: on-page SEO score, critical issues, raw crawl metadata, and page inventory. It also explicitly differentiates from the sibling tool gsc_performance, making its purpose unambiguous.

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

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

The description provides direct guidance: 'Use for page-level diagnosis; for search performance of those pages use gsc_performance.' It also tells the agent that the tool is pre-scoped, so no domain or site parameter is required, eliminating confusion about invocation.

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 annotations by disclosing that proposals NEVER execute, every change requires human approval, and this key returns an upgrade path instead of refusing. These are critical behavioral traits that annotations alone don't 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?

Three dense sentences, each earning its place: purpose, non-execution guarantee, approval gating, and the free-tier upgrade-path behavior are all front-loaded with no filler.

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

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

The description covers the core workflow and the free-tier behavior well, and an output schema exists so return values need not be repeated. However, the opening promise to 'Read the agent's plan board' is not cleanly supported by the action enum (only create and decide), and the description doesn't resolve that mismatch or give explicit routing guidance compared to siblings.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds useful framing about approval gating and upgrade behavior, but doesn't add per-parameter meaning beyond what the schema already provides for action, tasks, taskId, decision, and user_intent.

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 purpose: read the agent's plan board and stage new SEO task proposals. It clarifies these are approval-gated and never execute, which distinguishes this from execution-oriented SEO tools. It doesn't explicitly name a sibling, but the task-proposal framing makes the tool's role reasonably clear.

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 useful context: the tool is paid-plan only, this key is on the free tier, and any action returns an upgrade path to relay. It also explains the approval-gated workflow. However, it doesn't explicitly say when to use this tool versus alternatives or when not to use it, leaving some usage inference to the agent.

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