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

With no annotations provided, the description carries full burden. It discloses that the tool performs a 'fresh crawl' that 'updates the database', implying mutation behavior. However, it doesn't mention permissions needed, rate limits, whether the operation is asynchronous, or what happens if a crawl is already in progress.

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

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

The description is efficiently structured in two sentences that each earn their place. The first sentence states the core action, the second explains usage context and scope. No wasted words 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?

For a mutation tool with no annotations and no output schema, the description provides adequate but incomplete context. It explains what the tool does and when to use it, but lacks details about the mutation's impact, response format, or error conditions that would be helpful for an agent.

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 the single parameter. The description doesn't add any parameter-specific information beyond what's in the schema, maintaining the baseline score 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 states the tool's purpose with specific verbs ('trigger', 'crawl', 'analyze') and resources ('site', 'SEO data'). It distinguishes from siblings by focusing on site-wide crawling and analysis rather than specific features or insights retrieval.

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 clear context for when to use the tool ('after deploying changes to refresh SEO data'), but doesn't explicitly state when not to use it or name specific alternatives among the sibling tools. The guidance is helpful but lacks exclusion criteria.

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

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

No annotations are provided, so the description carries the full burden. It discloses key behaviors: the spec auto-creates tasks (write, optimize, schema/meta), keyword data is resolved dynamically, and the response includes a spec_id. It does not mention if it is destructive or any other side effects, but as a creation tool, it is expected to be non-idempotent. The level of disclosure is good.

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 with four sentences. It is front-loaded with the core purpose and efficiently provides usage context, key behaviors, and follow-up steps. Every sentence adds value, with no redundancy or 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?

The description covers purpose, usage, key behaviors, and follow-up. It mentions that the response includes a spec_id and recommends using get_feature_spec to retrieve full data. However, it does not mention error cases or prerequisites like the cluster must exist. This is a minor gap given the tool's complexity, so score 4.

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% description coverage, so baseline is 3. The description adds extra meaning: it explains that 'domain' defaults to SEO_CLIENT_DOMAIN, 'title' is auto-generated from cluster if omitted, and 'priority' defaults to cluster priority. This enriches the semantics beyond the schema definitions.

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: creating a page-type feature spec linked to a keyword cluster. It uses the verb 'create' and specifies the resource 'content_spec'. It distinguishes from siblings by explaining its role in content strategy workflow, especially compared to tools like 'get_feature_spec' which retrieves data.

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

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

The description gives clear usage context: 'Use this after creating keyword clusters' and explains that each cluster maps to one page. It also recommends following up with 'get_feature_spec'. While it doesn't explicitly state when not to use it, the guidance is sufficient for an agent to understand the intended workflow.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly indicates this is a write operation ('Create and save'), specifies required pre-processing ('generate the complete structured spec'), and outlines the agent's responsibilities. However, it doesn't mention authentication needs, rate limits, or what happens on failure.

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 well-structured with clear sections and bullet points, but could be more concise. The 'IMPORTANT' section contains detailed instructions that earn their place, though some redundancy exists between the bullet points and schema descriptions. Overall efficient but slightly verbose.

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

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

For a complex 13-parameter tool with no annotations and no output schema, the description provides substantial context about the agent's responsibilities and the expected input structure. It compensates well for the lack of output schema by explaining what constitutes valid input. However, it doesn't address error cases or system constraints.

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 13 parameters thoroughly. The description adds minimal parameter-specific guidance beyond the schema, mainly emphasizing that parameters like 'affected_files' and 'tech_stack' should be inferred from context rather than passed as raw natural language.

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 with a specific verb ('Create and save') and resource ('feature specification to Rampify'). It distinguishes from sibling tools like 'get_feature_spec' (read) and 'update_feature_spec' (modify existing) by emphasizing creation of new specifications.

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 on when and how to use this tool versus alternatives. It specifies prerequisites ('Before calling this tool, YOU must generate the complete structured spec'), distinguishes from passing raw natural language, and implicitly contrasts with 'get_feature_spec' for retrieval and 'update_feature_spec' for modifications.

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

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

With no annotations provided, the description discloses that keywords not yet existing are auto-created as target keywords, and that the tool returns keywords_assigned and keywords_created counts. It does not cover all edge cases (e.g., error handling, idempotency), but the core behavioral traits are clearly stated.

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

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

The description is three concise paragraphs with no wasted words. The first sentence immediately states the tool's action, and critical usage tips (keywords array, return counts) are front-loaded. Every sentence serves a purpose.

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 (11 parameters, 1 required) and no output schema, the description sufficiently covers the main purpose, auto-creation behavior, and return values. It lacks details on error handling or idempotency but is reasonably complete for typical 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 description coverage is 100%, so parameters are well-documented in the schema. The description adds context about auto-creation of keywords and return counts but does not significantly enhance parameter-level understanding 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 clearly states that the tool creates a strategic keyword cluster with keywords in a single call, grouping related keywords by search intent and serving as a content brief. This distinguishes it from sibling tools like suggest_keywords (suggestion) or get_keyword_clusters (retrieval).

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 advises using this tool during keyword research conversations to organize findings into actionable clusters, and explicitly instructs to always include the keywords array. It provides context but lacks explicit exclusions or alternatives when not to use.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool 'analyzes page content' and 'provides recommendations,' implying a read-only analysis function, but doesn't clarify if it modifies data, requires authentication, has rate limits, or what the output format looks like. For a tool with no annotations, this leaves significant behavioral gaps.

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 and front-loaded, stating the core purpose in the first sentence. The second sentence elaborates on the analysis process without redundancy. Both sentences add value, making it efficient with minimal waste.

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

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

Given the complexity (SEO analysis tool with 4 parameters) and the absence of annotations and output schema, the description is moderately complete. It covers the what and how at a high level but lacks details on behavioral traits, output format, and differentiation from siblings. It's adequate as a minimum viable description but has clear gaps for effective agent 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?

The input schema has 100% description coverage, so the schema already documents all parameters thoroughly. The description adds no additional parameter semantics beyond what's in the schema (e.g., it doesn't explain how 'domain' and 'url_path' interact or provide examples of meta tag outputs). With high schema coverage, the baseline score of 3 is appropriate as the description doesn't compensate but doesn't detract either.

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: 'Generate optimized meta tags (title, description, OG tags) for a page.' It specifies the resource (meta tags) and the action (generate/optimize), and mentions SEO optimization. However, it doesn't explicitly differentiate from sibling tools like 'get_page_seo' or 'generate_schema', which might have overlapping SEO-related functions.

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 minimal usage guidance. It mentions analyzing page content for recommendations, but doesn't specify when to use this tool versus alternatives like 'get_page_seo' (which might retrieve existing SEO data) or 'generate_schema' (which might handle structured data). No explicit when-not-to-use scenarios or prerequisites are included.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions detection, generation, and validation but doesn't cover error handling, rate limits, authentication needs, or what happens with invalid inputs. The description is functional but lacks operational context needed for safe invocation.

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

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

The description is efficiently structured in two sentences: first states the core functionality, second adds key features (detection, validation, output format). Every phrase adds value without repetition or fluff, making it easy to parse.

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 3 parameters with full schema coverage but no annotations and no output schema, the description adequately covers the 'what' but lacks depth on behavioral aspects. It mentions the return format ('ready-to-use code snippets') but doesn't describe output structure or error cases. For a generation tool with no safety annotations, more operational context would be beneficial.

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 thoroughly. The description adds no additional parameter semantics beyond what's in the schema (e.g., it doesn't explain interactions between domain and url_path or clarify schema_type selection logic). Baseline 3 is appropriate when schema does the heavy lifting.

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

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

The description clearly states the tool's purpose with specific verbs ('Auto-generate structured data', 'Detects page type', 'generates appropriate schema') and resources ('schema.org JSON-LD', 'ready-to-use code snippets'). It distinguishes from siblings by focusing on schema generation rather than crawling, SEO insights, or feature specs.

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

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

The description implies usage context ('for any page', 'detects page type') but doesn't explicitly state when to use this tool versus alternatives like generate_meta or get_page_seo. It mentions automatic detection vs. manual specification but lacks guidance on prerequisites or exclusions.

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

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

No annotations are provided, so the description carries the full burden. It discloses a key behavioral trait: 'No external AI call — derived from structured spec data already in the database.' It also describes the return format. This adds transparency beyond basic function.

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

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

Two short paragraphs with no wasted words. The first sentence front-loads the core purpose. Every sentence adds value: what it does, how it works, what it returns, when to use.

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

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

Given no output schema, the description adequately explains the return value. It covers all 5 parameters (via schema) and provides usage context. Lack of annotations is compensated by transparent behavior description. Minor gap: no explicit mention of required permissions or side effects, but not critical for a read-only data processor.

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 value by explaining default behavior for 'domain' (env var fallback), recommending 'task_id' for precision, and clarifying the purpose of 'files_changed'. This exceeds mere schema repetition.

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 ('Generate') and resource ('conventional-commits-style message'), clearly distinguishing the tool from all siblings which are SEO-related. The verb 'generate' accurately reflects the tool's function.

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 'Use this before committing to get a well-formatted message,' providing clear usage context. It does not explicitly state when not to use or list alternatives, but the purpose is sufficiently unique.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's dual-mode behavior (specific retrieval vs. search), return types (full spec vs. list), and when certain parameters apply (include_criteria/ include_tasks only with spec_id). However, it doesn't mention authentication requirements, rate limits, or error conditions.

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 perfectly structured: a clear purpose statement, followed by bullet-point style explanation of the two modes with practical guidance. Every sentence earns its place, and information is front-loaded with no wasted words.

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

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

For a 6-parameter tool with no annotations and no output schema, the description does an excellent job covering the core functionality and usage patterns. It explains the dual-mode operation and parameter applicability clearly. The main gap is the lack of information about return format/structure, which would be helpful given the absence of an output 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%, so the baseline is 3. The description adds significant value by explaining the two lookup modes (spec_id vs. search) and their implications, which clarifies the mutual exclusivity and purpose of these parameters beyond what the schema descriptions provide. However, it doesn't address domain/project_id usage scenarios.

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 verb ('Retrieve') and resource ('feature specification from Rampify'), and distinguishes it from siblings by specifying its unique purpose: understanding what to build, which files to touch, and acceptance criteria. It explicitly differentiates from tools like create_feature_spec and update_feature_spec by being a retrieval operation.

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 on when to use this tool ('when starting work on a feature') and distinguishes between two lookup modes (spec_id vs. search). It also advises to 'follow up with spec_id for full details' when using search mode, offering clear usage alternatives within the tool itself.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions 'AI-powered content recommendations' and the types of insights returned, but doesn't cover critical aspects like authentication requirements, rate limits, data freshness, error handling, or whether it's a read-only operation. For a tool that likely involves external API calls and data processing, this is a significant gap.

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

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

The description is efficiently structured in two sentences that clearly communicate the tool's function and outputs. It's front-loaded with the core purpose and avoids unnecessary verbiage. However, the second sentence could be slightly more concise by combining the listed return types.

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 complexity of SEO insights and AI recommendations, with no annotations and no output schema, the description is incomplete. It doesn't explain the format or structure of returned data, error conditions, or behavioral constraints. The agent would need to guess about the response format and operational characteristics.

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 thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema. It mentions 'AI-powered content recommendations' which relates to the 'include_recommendations' parameter, but this is already covered in the schema. 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?

The description clearly states the tool's purpose: 'Get Google Search Console performance insights with AI-powered content recommendations.' It specifies the verb ('Get'), resource ('Google Search Console performance insights'), and scope ('with AI-powered content recommendations'). However, it doesn't explicitly differentiate from sibling tools like 'get_page_seo' or 'get_issues', which might also relate to SEO analysis.

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

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

The description provides no guidance on when to use this tool versus alternatives. It lists what the tool returns but doesn't mention prerequisites, context for usage, or comparisons to sibling tools like 'get_page_seo' or 'crawl_site'. This leaves the agent without clear direction on appropriate 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the output includes a health score, categorized issues, and recommendations, but lacks details on permissions, rate limits, whether it's a read-only operation, or how the tool handles errors or large datasets. This is insufficient for a tool with no annotation coverage.

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

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

The description is front-loaded and concise, consisting of a single sentence that efficiently conveys the core functionality and output. Every word earns its place without redundancy or unnecessary elaboration.

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 (2 parameters, nested objects, no output schema, and no annotations), the description is partially complete. It outlines the output but lacks details on behavioral traits, parameter usage, and sibling differentiation. Without annotations or an output schema, more context is needed for full agent understanding.

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 50%, with the domain parameter well-documented but the filters object only partially described. The description adds no additional parameter semantics beyond what the schema provides, such as explaining the 'filters' object's purpose or default behaviors. With moderate schema coverage, the baseline score of 3 is appropriate as the description does not compensate for gaps.

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 with specific verbs ('Get SEO issues for entire site') and resources ('site'), and distinguishes it from siblings by specifying it returns a health score, categorized issues, and recommendations, unlike tools like crawl_site or get_page_seo which focus on different aspects.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or compare it to siblings like get_page_seo (which might target individual pages) or get_gsc_insights (which could involve Google Search Console data), leaving the agent to infer usage 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?

With no annotations, the description discloses the data returned (keywords, volume, GSC performance, audit status) and filtering behavior. No contradictions, but could mention pagination or limits.

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 concise, front-loaded sentences that efficiently convey purpose and filtering options without unnecessary words.

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

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

Adequately complete for a retrieval tool with no output schema. Covers core behavior and filters, but lacks details on pagination or result limits.

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 with descriptions (100% coverage). The description adds value by explaining target_url as exact match and name as partial match, and noting domain default. Baseline 3, plus extra context.

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 it retrieves keyword clusters with specific data (keywords, volume, GSC performance, audit status) and supports various filters, distinguishing it from sibling tools like create_keyword_cluster or lookup_keywords.

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 guidance on using filters like target_url, name, cluster_id, and explains default behavior without filters (returns all clusters). Does not explicitly mention when not to use, but 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the tool returns data from Google Search Console and other insights but doesn't specify permissions needed, rate limits, whether it's a read-only operation, or how it handles errors. For a tool with no annotation coverage, this leaves significant behavioral gaps.

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

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

The description is a single, well-structured sentence that efficiently conveys the tool's purpose and output. It's front-loaded with the core action and resource, with no wasted words, making it highly concise and effective.

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 (SEO analysis with multiple data sources), no annotations, and no output schema, the description is moderately complete. It outlines the scope of returned data but lacks details on behavioral traits, error handling, or output structure, which are important for such a 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 description coverage is 100%, so the schema already documents all 4 parameters. The description adds no additional meaning about parameters beyond implying they identify a page for SEO analysis. This meets the baseline of 3 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?

The description clearly states the specific action ('Get comprehensive SEO data and insights') and resource ('for a specific page'), distinguishing it from siblings like 'get_gsc_insights' (which focuses only on Google Search Console) and 'get_issues' (which might be broader). It specifies the scope of data returned, making 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 provides no guidance on when to use this tool versus alternatives like 'get_gsc_insights' or 'get_issues', nor does it mention prerequisites or exclusions. It implies usage for SEO analysis but lacks explicit context for tool selection among siblings.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It describes the return content ('security score, detected issues, and actionable remediation steps') and notes the 'PRIVATE BETA' status, which adds useful context about availability. However, it lacks details on error handling, rate limits, authentication needs, or performance characteristics, leaving gaps for a tool that performs analysis.

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 and front-loaded, starting with the core purpose and followed by return details and a beta note. It uses two sentences efficiently, with no wasted words. However, the 'PRIVATE BETA' note could be integrated more smoothly, and it slightly disrupts the flow.

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

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

For a tool with no annotations and no output schema, the description provides a good overview of purpose and returns, but it's incomplete. It lacks details on output structure, error cases, and behavioral traits like rate limits. Given the complexity of security analysis, more context would help the agent use it effectively, though the description meets a minimum viable level.

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% description coverage, with the 'domain' parameter well-documented in the schema. The description doesn't add any parameter-specific information beyond what's in the schema, such as format examples or constraints. Given the high schema coverage, a baseline score of 3 is appropriate, as the description doesn't compensate but also doesn't detract.

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: 'Get security analysis for a site (homepage scan only).' It specifies the verb ('Get'), resource ('security analysis'), and scope ('homepage scan only'), making it easy to understand what the tool does. However, it doesn't explicitly differentiate from sibling tools like 'get_issues' or 'crawl_site', which might also involve site analysis.

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

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

The description implies usage context by specifying 'homepage scan only' and mentioning it's a 'PRIVATE BETA,' which suggests limited availability. However, it doesn't provide explicit guidance on when to use this tool versus alternatives like 'get_issues' or 'crawl_site,' nor does it mention any prerequisites or exclusions for 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?

No annotations provided, but the description fully discloses side effects: the commit is recorded in the spec's related_commits array, commit_count incremented, and if task_id given, linked with last_commit_at. It also notes URL normalization from SSH to HTTPS.

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 somewhat long but well-structured with a clear opening, a numbered workflow, and detailed side effects. Each sentence adds useful information, though minor redundancy exists.

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

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

Given no output schema and 6 parameters, the description covers the process, parameter derivation, and behavioral effects. It could mention the return value but is otherwise complete and self-contained.

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 adequate parameter descriptions. The tool description adds value by explaining how to obtain commit_sha and repo_url (steps 3-4) and clarifying the domain/project_id distinction, going 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 clearly states that the tool links a git commit SHA to a feature spec and optionally a task, creating traceability. This is a specific verb+resource combination and is distinct from all 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 provides a deterministic 5-step workflow for AI agents, including prerequisites like retrieving the spec, committing code, and capturing the SHA. It explains when to use (after commit) and optional task linking, with no 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?

No annotations provided, but the description implies a read-only operation by saying 'browse and filter' and 'returns an overview'. It doesn't mention side effects, but for a listing tool this is sufficient. Could add more about env var fallbacks.

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, no fluff. Each sentence serves a purpose: purpose, return type, example queries, follow-up instruction. Well-structured and 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 9 optional parameters and no output schema, the description provides sufficient context: return type (overview with status/priority/task progress), filter capabilities (by status, priority, etc.), and stats option. Could elaborate on exact return fields.

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 value by explaining how parameters like domain/project_id fall back to env vars and gives example usage ('what's planned?'), enhancing understanding beyond schema.

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

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

The description clearly states it is for browsing/filtering feature specs, specifies it returns an overview with status/priority/task progress, and distinguishes from get_feature_spec by directing users to that tool for full details.

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

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

The description explicitly tells when to use this tool (to answer questions like 'what's in progress?') and when to follow up with get_feature_spec for full details, providing clear usage 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?

No annotations are provided, so the description carries the full burden. It discloses critical behavioral traits: the tool calls a paid API, results are cached for 30 days, repeated lookups are free, and the response includes meta fields to track cache vs API usage. It also instructs to inform the user before calling.

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 with three well-structured paragraphs. The first sentence states the purpose, the second adds important notes about caching and payment, and the third gives usage context. Every sentence is meaningful and 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?

Despite lacking an output schema, the description explains what the response contains (meta fields for cache and API counts) and the return of search volume, competition, CPC, and trends. It covers the paid API, caching, and usage context adequately for an agent to select 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?

Schema description coverage is 100%, so baseline is 3. The description adds value by specifying that keywords are limited to 100 with an example array, noting that domain defaults to SEO_CLIENT_DOMAIN if not provided, and providing example location codes for US, Canada, and UK.

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 verb 'look up' and the resource 'search volume, competition, CPC, and monthly trends for a list of keywords using DataForSEO'. It distinguishes from siblings like suggest_keywords (which suggests keywords) and get_gsc_insights (which provides Google Search Console data).

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

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

The description explicitly says 'Use this to validate keyword demand during research conversations, before creating clusters' and instructs to always tell the user before calling with the number of keywords. It does not explicitly state when not to use or name alternatives, but the context is 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?

With no annotations, the description carries full burden. It explains the tool runs a content audit and produces fix instructions for each failing check. It also discloses constraints: only text, formatting, and links are modified; structure is preserved. It does not detail side effects, auth needs, or rate limits, but the core behavior is clear and accurate.

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 paragraphs, each sentence adds value. The main purpose is front-loaded, followed by usage guidance and constraints. It is reasonably concise but could be slightly tighter 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 explains the output (actionable fix instructions) with examples, but does not specify the exact format (e.g., JSON, list) or how to handle cases with no failing checks. Given no output schema, it leaves some gaps for the agent. It is sufficient but not complete.

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

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

Schema coverage is 100% (all three parameters have descriptions). The tool description adds no additional information about parameters beyond what the schema already provides. Therefore, it meets the baseline of 3.

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

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

The description clearly states the tool generates specific optimization instructions for a page based on keyword audit results. It uses a specific verb ('generate instructions') and resource ('page optimization'), and distinguishes itself from siblings by noting it is used after get_page_seo, differentiating it from other SEO and content 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 'Use this after reviewing a page with get_page_seo to get step-by-step instructions for improving keyword optimization.' This provides clear when-to-use guidance. It also includes a constraint (preserving content structure), but does not explicitly list when not to use or mention alternatives, so slightly lacking.

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

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

With no annotations, description carries full burden and discloses paid API call, requiring user notification. This is a key behavioral trait. Lacks details on rate limits or authentication, but the warning is significant and adds value.

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 succinct sentences with clear structure: purpose, important warning, usage advice. No extraneous information, front-loaded with core functionality.

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?

Despite no output schema, description sufficiently explains return data (related keywords with search volume and competition). For a tool with 6 parameters (1 required), the description covers key aspects. Could briefly mention limit behavior or pagination, but overall complete for 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%, but description adds value by specifying default locale ('en'), default location_code (2840 for US) with examples for Canada and UK, and noting domain uses SEO_CLIENT_DOMAIN if omitted. This enriches understanding beyond schema.

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

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

Description clearly states the tool gets related keyword suggestions for a seed keyword using DataForSEO, with details on return data (up to 50 keywords, search volume, competition). It distinguishes itself from sibling like lookup_keywords by focusing on suggestion expansion.

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 guidance on when to use for expanding keyword research and finding related terms. Includes explicit instruction to inform user before calling due to paid API. Could improve by contrasting with alternatives like lookup_keywords, but usage context is well defined.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that the tool returns a 'suggested_commit message string' and mentions auto-advancement of next_action, which are valuable behavioral details. However, it doesn't cover important aspects like whether this is a destructive operation, what permissions are required, or error handling for invalid updates.

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 appropriately sized and front-loaded with the core purpose in the first sentence. The examples are helpful but could be more concise. Every sentence serves a purpose, though the structure could be slightly improved by separating the examples more clearly from the usage 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 tool's complexity (8 parameters with nested objects) and absence of both annotations and output schema, the description provides adequate but incomplete context. It explains the purpose and gives usage examples but doesn't fully address behavioral aspects like side effects, error conditions, or the format of the return value beyond 'suggested_commit message string'.

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 8 parameters thoroughly with descriptions and enums. The description adds some value through the examples that show how parameters combine in practical use cases, but doesn't provide additional semantic context beyond what's in the schema. This meets the baseline 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 states the tool's purpose with specific verbs ('update', 'mark', 'advance') and resources ('feature spec', 'tasks', 'criteria', 'spec status', 'next_action'). It distinguishes from sibling tools like 'create_feature_spec' and 'get_feature_spec' by focusing on updating existing specs rather than creating or retrieving them.

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 clear context for when to use the tool ('after completing work described in a spec task') and offers examples of specific use cases. However, it doesn't explicitly state when NOT to use it or mention alternatives among siblings (e.g., when to use create_feature_spec vs. update_feature_spec).

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