tracetify-mcp

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

The description reveals critical behavioral details not in annotations: 'Costs credits once per day per account — repeat calls the same day are free, so refine freely.' It also explains the data is hand-verified, giving confidence in the list's reliability. This goes well beyond the minimal readOnly/destructive hints.

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 sentences, front-loaded with the core value proposition, followed by use case and cost behavior. Every sentence earns its place with zero fluff.

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

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

Given the tool's low complexity (no params, no output schema), the description comprehensively covers what, when, and the credit behavior. It could elaborate on the response structure, but the mention of 'language/type/pricing' gives a peek into the data fields, making it sufficiently 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?

With zero parameters, the schema already defines everything about inputs, earning the baseline of 4. The description adds no parameter-specific meaning (none needed) but implies the output includes language/type/pricing fields, which slightly informs the expected data but not inputs.

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

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

The description clearly states the tool provides 'a hand-verified list of directories and launch platforms that actually give links' and emphasizes quality ('dead and nofollow-only entries removed'). It uses a specific resource and verb, and the mention of 'filter client-side' distinguishes its purpose from sibling backlink analysis 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 when the user wants backlinks or launch exposure for a new product', giving a clear trigger condition. It does not name alternative tools or specify when not to use it, but the context is unambiguous for typical 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?

The annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful context beyond annotations: the polling interval, the loop guidance, and the condition to stop polling (status is 'done'). While it doesn't detail possible error states or return-field formats, it provides meaningful behavioral guidance.

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 short sentences, each adding value: the action, the next step after completion, and the polling cadence. No filler or repetition; a front-loaded and efficient example.

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

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

For a single-parameter polling tool with no output schema, the description is mostly complete: it explains the dependency on start_trace, the next step (read_report), and implies a status field by referencing status. It could explicitly list potential statuses or error behavior, but the description is fully usable 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 coverage is 100% and the job_id parameter's description reads "Job id returned by start_trace." The tool description adds little beyond the schema, simply implying that the trace was created with start_trace. Since the schema already carries the semantic weight, 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 states a specific verb and resource: "Poll a trace started with start_trace." It clearly identifies what the tool does and distinguishes it from siblings like start_trace and read_report. The follow-up instructions about read_report reinforce the intended role.

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

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

The description explicitly explains when to use this tool (to poll a running trace created by start_trace), when to move to read_report, and how to poll responsibly ("Poll every 10-15s, not in a tight loop"). This gives concrete usage guidance and names the relevant alternative for the next step.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so no safety restatement is needed. The description adds useful behavioral context: it requires a connected GSC account, reports connection status, and provides data that 'no other tool has'. No contradiction found.

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

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

Two sentences, front-loaded with the actionable use case and specific outputs. 'Free.' and 'numbers no other tool has' are brief value context rather than padding.

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

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

For a one-parameter, read-only overview tool with strong annotations, the description covers purpose, prerequisite, and connection-failure behavior. It is complete enough for an agent to select and 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?

The single optional range_days parameter is fully documented in the schema as '28 (default) or 90'. The description adds no extra semantic detail about the parameter, so the 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?

Description opens with 'Use this before touching SEO on the user's own site' and enumerates the specific data view: clicks/impressions trend, device split, and period comparison from the user's connected Google Search Console. This distinguishes it from sibling tools like gsc_pages and gsc_queries while making the resource and scope explicit.

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

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

It gives an explicit when-to-use directive ('before touching SEO on the user's own site') and notes the prerequisite (GSC connected) plus a fallback ('this tool tells you if it is not'). It does not name sibling tools or explicitly state when not to use it, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, so the tool is safe. The description adds context about data source (connected Search Console) and cost (free), and mentions the typical use case (fixing underselling pages). It does not contradict annotations and enriches understanding slightly. However, it doesn't reveal any hidden side effects or operational details beyond 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?

Two sentences, front-loaded with the core purpose. The second sentence adds context about the use case (fixing titles/descriptions) and ownership/free aspect, but is not redundant. Slightly wordy with 'right in this editor' but overall compact.

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

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

For a simple read-only tool with one parameter and no output schema, the description is sufficient. It explains the primary purpose and the key value proposition (high-impression low-CTR pages). It does not explain return format, but that is not critical for this complexity 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 single parameter (range_days) is fully described in the schema with default and values. The description adds no additional meaning or usage details for the parameter. Baseline of 3 is appropriate since schema coverage is 100% and description does not compensate.

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?

Clearly states it lists the user's pages ranked by search performance, and specifically calls out high-impression low-CTR pages for optimization. This distinguishes it from siblings like gsc_queries (queries) and gsc_overview (aggregate), and the verb 'ranked' + resource 'pages' is specific.

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 for identifying and fixing underperforming pages, but does not explicitly state when to choose this tool over siblings like gsc_overview or gsc_queries. No when-not guidance is given.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context about the data source (own Search Console) and cost (free) but does not elaborate on pagination, response format, or other behavior. With annotations present, this level of additional context is adequate but not deep.

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, front-loaded with the core value proposition, and every sentence earns its place. It covers purpose, use cases, and data origin without unnecessary fluff. Slightly less structured than ideal but still efficient.

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

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

With only one optional parameter, no output schema, and annotations covering safety, the description is reasonably complete. It explains what data is returned (position, clicks, CTR) and when to use it. It could mention that data range is limited to 28/90 days, but that's in the schema. Overall, well-suited for the tool's simplicity.

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

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

The schema already documents the single parameter 'range_days' with values 28 (default) or 90. The description does not mention the parameter at all, but since schema coverage is 100%, the baseline of 3 applies. No additional meaning is added by the description.

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

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

The description clearly states the tool's function: accessing the user's real ranking keywords with position, clicks, and CTR. It gives a concrete example of use (finding queries at position 5-20) which helps distinguish it from sibling tools like gsc_overview or gsc_pages.

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 use cases ('use when deciding what to write or which page to improve') and even a verification workflow ('After you edit a page, this is how you verify it moved'). It does not explicitly name alternative tools, but the guidance is clear and context-rich.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds behavioral context: it is free, contains content types like '"origin story, dated evidence and SEO footprint"', and reveals that some fields may appear locked. This goes beyond the structured metadata, though output shape details are not fully explained.

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

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

Every sentence earns its place: it front-loads the core action and source, then adds cost and content context, then closes with the locked-fields exception. No filler or redundant restating of the tool/title.

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

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

For a single-parameter read tool with no output schema, this description is complete enough: resource identification, slug sourcing, content scope, cost mention, and the unlock alternative are all covered. A more explicit description of return fields would be useful, but the description covers the main operational needs.

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

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

Schema coverage is 100% and the slug parameter is documented, but the description adds operational meaning by explaining where the slug comes from ('from search_reports or a finished trace'). This guidance improves invocation accuracy beyond the schema alone.

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

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

The description clearly states the tool 'Read one growth report by slug' (a specific action on a specific resource). It also distinguishes the tool from unlock_report by referencing locked timeline fields, 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?

It explicitly tells users where the slug comes from ('search_reports or a finished trace') and provides a clear alternative: 'If timeline fields show as locked, unlock_report can open them' — giving both when-to-use and when-to-use-something-else 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?

The description explains that the tool 'Costs credits; cached results are free,' which is a behavioral trait beyond the annotations. It doesn't explicitly describe the safety profile, but the annotations already mark it as not read-only and not destructive. The extra context is meaningful, though it lacks detail about auth or rate limits, keeping it from a 5.

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

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

Three sentences, front-loaded with purpose, then usage, then logistics. 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 simple one-parameter tool with no output schema, the description fully covers purpose, use cases, cost, and a related alternative. Nothing 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?

With one parameter and 100% schema coverage and a clear description, the description doesn't need to add much. The 'domain' parameter is straightforward, and the description's mention of 'domain' provides adequate context, though it doesn't elaborate on format. As per the rubric, with 100% coverage, the baseline is 3; the description adds a bit by implying the domain format.

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 "Who links to a domain: referring domains, authority and anchor texts," which is a specific verb+resource+scope. It exceeds the title 'Backlink profile' and distinguishes the tool from siblings like research_domain_overview and get_trace by describing the backlink-specific 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?

It explicitly states when to use ('when planning link building or judging how defensible a competitor's ranking is') and also names a sibling alternative ('Pair with backlink_directories'), providing clear context and a directly related alternative.

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

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

Annotations are present (readOnlyHint: false, destructiveHint: false) but they don't convey much safety. The description adds crucial behavioral context: it costs credits, which is not in annotations, and it indicates that cached results are free, implying a cost model. It doesn't fully describe what data is returned, but given annotations are minimal, this adds significant 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?

The description is concise (three sentences) and front-loaded with the core purpose. It maximizes information density: what it does, when to use, and cost implications—all without fluff. 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 complexity (one parameter, no output schema, annotations present but minimal), the description covers all essential aspects: purpose, usage trigger, cost behavior, and returned data type. It is complete for the agent to decide and invoke correctly.

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

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

The schema has 100% coverage with a single parameter 'brand' described as 'Brand or domain', which is already quite clear. The description reinforces it by mentioning 'brand' in the context. It doesn't add extra meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool's function: it checks how AI assistants cite a brand, what platforms are involved, mention counts, and associated entities. It also distinguishes itself from siblings by specifically addressing AI assistant citations, which is unique among the listed siblings (e.g., research_backlinks for links, research_domain_overview for domain metrics).

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 the user asks 'does AI recommend us/them?'. It also mentions cost implications ('Costs credits; cached results are free'), which helps the agent decide when to invoke it and informs about potential retries.

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

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

Annotations only show readOnlyHint: false and destructiveHint: false, so the description carries the burden. It discloses credit costs, free cached results, and that a domain already looked up via research_domain_overview is free here, adding meaningful operational behavior beyond the structured fields.

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, each earning its place: what the tool returns, when to use it and the report alternative, then cost behavior. No filler or redundancy.

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

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

For a single-parameter tool with no output schema, the description covers the return fields, usage scenario, alternative path via read_report, and cost/caching behavior. This is enough for an agent to select and 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 coverage is 100% and already describes the domain parameter. The description adds targeted meaning by referring to the 'target' domain and clarifying that using a domain already looked up via research_domain_overview makes the call free, which is useful semantic context for the parameter value.

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 concrete output definition: domains competing for the same search terms with shared-keyword count, keyword totals, and average rank. It also states exactly when to use it ('when the user asks who their competitors are') and references the sibling read_report, which differentiates it from related research 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?

Explicitly says 'Use when the user asks who their competitors are, or who a company is up against.' It also provides an alternative for existing growth reports: 'read those with read_report for free instead of tracing them again,' plus cost/caching conditions that guide when it is cheaper to call.

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 provide readOnlyHint=false and destructiveHint=false, but description adds valuable context: it costs credits and caches results for a week. This goes beyond annotations by disclosing cost and side-effect of credit consumption, though it doesn't detail all potential behaviors (e.g., rate limits). No contradiction.

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

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

Three sentences, each serving a distinct purpose: purpose, cost/caching, and alternative tool guidance. Front-loaded with the core purpose, no redundancy or filler.

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

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

For a single-parameter tool with no output schema and minimal annotations, the description fully covers purpose, usage, cost, caching, and alternatives. It tells the agent exactly what to expect and when to use it, leaving no critical 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 covers 100% of the single parameter (domain) with a clear example. The description reinforces that it works for ANY domain and mentions competitor use, but this is tool-level guidance rather than parameter-specific detail. Baseline 3 is appropriate since schema already handles parameter meaning.

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

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

Description clearly states it provides estimated organic traffic, keyword count, and top keywords for any domain, with an explicit use case (sizing up competitors). This distinguishes it from sibling tools like research_backlinks and gsc_overview, which focus on other data types.

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

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

Explicitly tells when to use (competitor analysis) and when not (for user's own site, prefer gsc_* tools). Also explains caching behavior and cost implications, giving clear context for tool selection.

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

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

Annotations only say readOnlyHint=false and destructiveHint=false, which are minimal. The description adds meaningful behavioral context beyond them: the tool 'costs credits' and the same keyword set re-queried within a week is free. This discloses cost/quota impact and caching behavior that the annotations do not convey, which is exactly the kind of trait an agent needs before invoking a non-read-only tool.

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

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

Three sentences, roughly 65 words, with the core purpose front-loaded in the first sentence. The second sentence handles usage triggers, and the third covers parameter behavior plus cost/caching. Every sentence earns its place with zero 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?

Even though there is no output schema, the description enumerates the returned data points (monthly search volume, CPC, competition, 12-month trend), so an agent knows what to expect. Combined with fully documented parameters, credit-cost disclosure, free re-query policy, and max-keyword constraint, nothing essential is missing for correct invocation.

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

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

Schema coverage is 100% with rich descriptions already, including example values for keywords and specific market codes for location_code. The description adds only marginal value by restating the omit-for-worldwide behavior and clarifying that a market code targets one country. Given the high schema coverage, 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 names a specific action and resource: retrieving 'Google Ads (Keyword Planner) monthly search volume, CPC, competition and 12-month trend'. This is a specific verb+resource with concrete metrics and constraints (up to 10 keywords, one call). It clearly differentiates from siblings like research_backlinks and research_competitors by focusing on keyword search metrics rather than link or competitor 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 gives explicit when-to-use guidance: 'Use when the user asks how often something is searched, or to size a keyword before writing a page.' This establishes clear context for invocation. However, it does not name alternatives or state when-not-to-use, which keeps it a step below full routing clarity.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety bar is lowered. The description adds context by explaining that reading is 'free' and that the tool returns report slugs for read_report, which clarifies the output behavior beyond simple read-only indication.

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 sentences, front-loaded with the most important guidance ('Use this FIRST'), and every phrase earns its place. It avoids redundancy and is highly scannable.

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

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

For a one-parameter search tool with good annotations and no output schema, the description is complete: it explains when to use it, what it returns, and how to chain it with read_report. No critical gaps remain 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 single parameter 'query' is already well-described with an example. The description adds minimal extra meaning ('Searches by domain or name fragment'), but this largely mirrors the schema, so the baseline 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 tool searches for growth reports by domain or name fragment and returns matching report slugs. It explicitly names the companion tool read_report, which distinguishes it from siblings and gives a precise action ('search' + resource 'reports').

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 instructs to 'Use this FIRST whenever the user asks how a product, competitor or domain grew...' and notes that 'reading it is free', providing strong usage context. It implies this tool should precede read_report and positions itself as an initial discovery step, though it doesn't explicitly list alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds behavioral context: it's 'free to read', it's a polling operation, and it returns the issue list grouped by severity with affected URLs. This goes beyond the annotations and helps the agent understand the tool's behavior.

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

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

The description is a single, dense sentence that conveys purpose, usage, output, and workflow with no redundancy. It is front-loaded with the key verb and resource.

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

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

For a simple 1-parameter read tool with good annotations, the description fully explains when to use it, what it returns, and how to act on the results. No output schema exists, so describing the return format is valuable and done.

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 has 100% coverage with audit_id described as 'Audit id from site_audit_start'. The description does not add further parameter detail, but the schema is sufficient. Baseline 3 applies since the schema handles the parameter semantics.

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

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

The description clearly states the tool's function: polling an audit started with site_audit_start and returning the issue list. It names the specific resource (site audit) and distinguishes itself from sibling site_audit_start by explicitly referencing it as the start 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?

Explicitly ties usage to site_audit_start ('Poll an audit started with site_audit_start'), indicates when to use it ('When finished'), and provides a workflow ('work through it top-down and re-run after fixes'). This gives clear context and alternatives.

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

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

Descriptions go beyond annotations by disclosing cost side effects and the two-step confirmation flow: 'Costs credits (price returned before any charge on the confirmation field)'. Also mentions the output structure (each finding names the page) and async behavior. No contradiction with readOnlyHint/destructiveHint.

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 concise sentences pack in when to run, what it does, what content it returns, cost/confirmation behavior, and async polling. Slightly long first sentence but remains readable and efficient without redundancy.

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

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

Given the side-effecting nature (cost, async), the description covers all critical usage context: timing, confirmation flow, cost, and polling method. Without an output schema, it hints at the return shape ('each finding names the page'). Could be more explicit about error handling or cancellation, but not necessary for a minimum-viable 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?

Input schema already provides 100% documentation for all three parameters with clear descriptions. The description adds context about the confirmation flow and cost but does not add new parameter-specific semantics beyond what the schema already covers. Baseline 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 tool crawls a site and reports specific audit findings (broken links, missing titles, etc.), using an imperative verb and identifying the target resource. It also differentiates itself from siblings by noting the async pattern ('Async: poll with site_audit_get') and the timing ('Run right after deploying').

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

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

Explicitly tells when to use ('right after deploying') and how to handle async flow, but does not explicitly state when *not* to use it or list alternative tools for contrast. The reference to 'site_audit_get' provides a helpful companion but falls short of a full alternatives comparison.

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

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

The description discloses behavioral traits beyond annotations: it incurs credits, takes 60-90 seconds, and may return a cached report for free if fresh. This adds context about side effects and efficiency, and does not contradict the annotations (readOnlyHint=false, destructiveHint=false).

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 sentences, front-loaded with the key trigger condition, and includes essential details (sources, time, cost, caching, polling) with no fluff. 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?

For a tool that initiates a long-running, cost-incurring process, the description covers when to use it, what it does, how long it takes, cost implications, caching behavior, and how to retrieve results (via get_trace). This is sufficient for an agent to use it appropriately without 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 coverage is 100%, so parameters (url and refresh) are documented. The description adds value by explaining the caching behavior and cost implications, which indirectly clarifies the refresh parameter's effect (forcing a fresh run vs. potentially using a cached report for free). This is a slight enhancement over the schema.

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

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

The description clearly states the tool's purpose: to start tracing how a product grew by rebuilding the growth story from 12 public sources. It distinguishes itself from search_reports by specifying it should be used when search_reports finds nothing or fresh data is needed, and from get_trace by indicating that get_trace is for polling results.

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

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

Explicitly provides usage context: 'Run this when search_reports finds nothing (or the user wants fresh data) for "how did X grow?"'. It also gives guidance on cost and caching behavior, and instructs to poll with get_trace, making the tool selection and follow-up steps 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?

Beyond annotations, the description discloses key behavioral traits: it permanently unlocks content, costs credits, is idempotent (never charges twice), and leaves the verdict on the website. It also states the agent's role as analyst, which clarifies the post-call context. There is no contradiction with the annotations.

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

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

The description is three focused sentences: first states the action, second covers cost and consent prerequisites, third explains idempotency and post-call expectations. Every sentence earns its place with no filler or redundancy.

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

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

For a single-parameter mutation with no output schema, the description is complete: it explains the effect, cost, consent requirement, idempotency, permanence, and account scope. The agent has enough information to select and invoke the tool safely and appropriately.

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 one parameter, slug, described as 'Report slug'. The description does not add parameter-specific details, but the schema already fully documents the only input, so the baseline 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 uses a specific verb and resource: 'Permanently unlock a report's full timeline, evidence and SEO detail for this account.' This clearly differentiates the tool from read-only siblings like read_report or search_reports by naming the unlock action and the exact scope of what becomes available.

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

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

The description gives explicit usage conditions: quote the exact price first, call only after explicit user agreement, and note the idempotent behavior. It does not name an alternative tool for the same task, but the prerequisite and consent requirements provide clear context for when invocation is appropriate.

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