ranklogs

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

The description adds meaningful behavior beyond the annotations: required write access, the 20-prompt project limit, deduplication that reinforces idempotentHint=true, and asynchronous weekly result availability. This is substantial operational context that annotations alone do not provide.

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

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

The description is three short sentences, front-loaded with the core purpose and followed by constraints and timing. Every sentence adds useful information without repeating schema fields or annotations.

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

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

With only two simple required parameters, an output schema, and annotations covering safety traits, the description supplies all remaining operational context an agent needs: access requirements, quota, idempotency, and result timing. Nothing material is missing.

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

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

Schema description coverage is 100%, so both project_id and prompt are already documented in the input schema. The description mostly restates the 'question' concept and does not add new parameter-level details, so the baseline score of 3 is appropriate.

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

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

The description names a specific action and resource: 'Track a new question across AI assistants for a Ranklogs project.' This is clearly distinct from read-oriented siblings like get_ai_visibility and get_ai_citations, and from add_keywords_to_project.

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

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

It provides clear contextual guidance: a write-access connection is required, the project has a 20-prompt cap, duplicate prompts are not added, and results arrive only after the next weekly AI visibility run. It does not explicitly name an alternative tool for exclusion, but the usage 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?

Adds substantial behavior beyond annotations: write-access requirement, idempotent skip behavior, no immediate rank check, and plan-allowance partial success. These details go well beyond the idempotentHint and readOnlyHint flags, giving an agent an accurate model of side effects and timing.

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?

Purpose is front-loaded, and each subsequent sentence adds a distinct operational constraint: auth, idempotency, timing, and limits. No filler or repeated schema information.

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

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

For a two-parameter mutation tool with an output schema, the description covers the prerequisites, safety, timing, and failure/partial-success behavior. An agent has everything needed to invoke it correctly and set expectations.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful keyword behavior: already-tracked keywords are skipped and plan allowance limits how many are added. This clarifies what happens to the keywords array beyond the raw schema constraints.

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 'Start tracking new keywords on a Ranklogs project,' a specific verb and resource that clearly identifies the tool's function. It does not explicitly name or contrast sibling tools, but the keyword/project scope distinguishes it from the other add/research tools 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?

Provides clear context: requires write access, repeated calls are safe because already-tracked keywords are skipped, and results only appear after the next daily rank check. It does not mention alternative tools or when-not-to-use conditions, so it stops short of explicit routing.

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

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

Beyond the readOnlyHint and openWorldHint annotations, the description discloses that the tool may perform up to 3 cold fetches and that legacy KR add-on accounts are charged a daily research credit even on cache hits. This is substantive behavioral and cost transparency that annotations alone do not provide.

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

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

Two tight sentences front-load the core purpose, then add the most decision-relevant behavioral details (project_id conditional behavior and cost). There is no filler or repetition of schema boilerplate.

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 readOnlyHint/openWorldHint annotations, an output schema, and the optional project_id behavior, the description covers what an agent needs to invoke it correctly: scope, outputs, conditional behavior, and cost implications. No critical operational detail is missing.

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

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

The description repeats and reinforces project_id's role (overlay winnability, empty recommendations without it), but the schema already documents that. language_code and location_code are left unexplained in both the description and schema, so at 50% schema coverage the description only partially compensates for the gap.

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

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

The description opens with a specific verb and resource ('Analyze a competitor domain') and immediately lists concrete outputs: organic/paid footprint, estimated traffic and traffic value, position split, and top-ranking keywords. This makes the tool's purpose distinct from siblings like get_backlink_profile or research_keywords without needing to open the schema.

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

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

It gives clear conditional guidance: pass project_id to enable winnability overlay and recommendations, omit it to get empty recommendations. It also warns about credit costs. It does not explicitly name when to prefer an alternative sibling, but the context is otherwise actionable.

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 all annotations false, the description carries the behavioral burden and meets it: it discloses a quota-consuming side effect, async timing ('Takes about a minute'), and deferred result retrieval. These are exactly the non-obvious behaviors an agent needs to know before invoking.

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

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

Three short sentences front-load the purpose and then add only high-value operational details (quota, latency, retrieval sibling). No filler or repeated schema content.

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

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

The description covers the complete invocation lifecycle for an async, quota-consuming tool: what it does, what it costs, how long it takes, and how to obtain the result. With an output schema present, no return-value documentation is missing.

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

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

Schema coverage is 100%, so the baseline applies; the parameter descriptions already define url and keyword accurately. The phrase 'against the pages actually ranking' adds slight SERP context beyond the schema, but not enough to raise the score.

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

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

The description opens with a specific action and resource: 'Run a content analysis on one page for one search term' and clearly states the output ('produces a working brief'). It distinguishes itself from sibling get_content_brief by explicitly saying the result is fetched with that tool.

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

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

It communicates the use context: one page per search term, one monthly analysis consumed, and a one-minute wait before retrieving via get_content_brief. It does not explicitly contrast against other generation siblings like generate_report or get_content_action_plan, so it falls just short of a full 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 establish readOnlyHint=true and openWorldHint=false, so the description only needs to add operational behavior. It does: returns a one-time download link or local file path, requires the report feature, and notes the render is cached and free. These details go beyond the annotations without contradicting them.

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

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

The description is front-loaded and logically organized, but it contains redundancy: the opening sentence already lists the full/audit_full/audit_issues variants and the third sentence restates the same mapping. The trailing parenthetical '(free — cached render)' also feels appended. It is reasonably sized but could be tightened.

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

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

Given that an output schema exists and annotations cover the safety profile, the description covers the remaining operational essentials: output delivery, local-mode behavior, feature gating, and cost/caching. Nothing critical for calling the tool correctly appears to be missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description largely restates what the input schema already says about project_id and kind, and adds little new meaning for period or sections. It does not compensate with additional parameter-level insight 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 names the specific action ('Produce') and resource ('branded PDF report'), and enumerates the exact report variants: full, audit_full, and audit_issues. This makes it immediately distinguishable from sibling generation tools like generate_schema and generate_content_brief. The purpose is explicit and concrete.

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 by mapping the three kind values to concrete report types and stating the prerequisite that the report feature must be enabled on the account. It does not explicitly contrast with sibling tools or provide when-not-to-use conditions, but the context is strong enough for an agent to select this tool appropriately.

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

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

Beyond the readOnlyHint annotation, the description discloses useful behavioral traits: required fields are validated, errors name exactly what is missing, and the operation is 'free, no API call.' This tells an agent what to expect on failure and that no external side effects or costs occur.

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 with the core purpose, followed by a useful type list and validation behavior. The supported-types list partially duplicates the enum in the schema, but it helps agents quickly identify applicability without opening the schema.

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 rich input schema, output schema, and readOnly annotation, the description covers everything an agent needs to select and invoke the tool: what it generates, which types are supported, how validation works, and cost/external-call behavior. Nothing critical is missing.

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

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

Input schema coverage is 100%, and the schema already enumerates all 13 types and the required per-type fields. The description adds general reinforcement about validation but does not add new parameter-level meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Generate valid schema.org JSON-LD structured data' for 13 named content types. This makes the tool's function immediately clear and distinguishes it from the unrelated SEO/research sibling tools without needing to inspect the schema.

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

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

The description gives clear usage context: use it when you need schema markup 'ready to drop into a page' for any of the listed types. It does not explicitly name an alternative or exclusion, but none of the sibling tools generate JSON-LD markup, so the intended use case is unambiguous.

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

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

Annotations already mark it as readOnly, and the description adds a meaningful behavioral detail beyond that: 'Free — calling it never consumes lookups' and clarifies it provides quota balance and feature flags. This gives the agent a clearer model of side effects and cost, though it doesn't discuss authorization or other advanced 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 compact, front-loaded, and every sentence earns its place. The first sentence explains what the tool returns, and the second gives the usage context and cost guarantee. There is no filler or repetition of schema/annotation information.

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

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

For a zero-parameter, read-only account status tool with an output schema and clear annotations, the description is complete. It tells the agent what data is available, when to call it, and that it has no quota cost. Nothing necessary for correct invocation is missing.

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

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

The tool has zero parameters and the schema coverage is 100%, so there is no parameter documentation burden. The description adds useful context about what data the tool surfaces (plan, balance, allowance, features), which is more than the empty schema provides.

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

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

The description clearly states the tool's purpose: it reports the Ranklogs plan/tier, lookups balance, monthly allowance, and enabled features. It goes beyond a generic label by framing itself as the 'quota pre-check tool,' but it does not explicitly differentiate itself from sibling tools by name.

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

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

The description gives explicit when-to-use guidance: 'check here before planning research-heavy work.' It also adds a practical reassurance that calling it never consumes lookups. It does not mention when not to use it or name alternative sibling tools, so it falls 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?

The annotations already declare readOnlyHint=true, and the description adds a valuable behavioral guarantee: calling it never consumes lookups. It also clarifies the output structure around top cited pages and corroboration gap. No contradictions with annotations are present.

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

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

The description is three focused sentences: the first states the main output, the second explains parameter relationships and the key concept, and the third adds the cost-free guarantee. Every sentence contributes useful information with no 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 output schema exists and annotations cover safety, the description is complete enough for an agent to select and call the tool correctly. It explains the meaning of project_id, the optional prompt_id behavior, and the value of the corroboration gap, 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 description coverage is 100%, so the input schema already documents both project_id and prompt_id clearly. The description reinforces these meanings and explains the corroboration gap, but it does not add substantial new parameter-level semantics beyond what the schema provides.

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

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

The description clearly identifies what the tool returns: AI answer engine citations for a project, broken down by tagged pages and the corroboration gap. This distinguishes it from sibling tools like get_ai_visibility or get_prompt_gap_brief, which focus on different metrics. The resource and scope are specific and immediately understandable.

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: project_id is a ranking id from list_projects, and prompt_id is only needed when full per-engine evidence for a tracked prompt is desired. It does not explicitly mention when to avoid this tool in favor of an alternative, but the context is sufficient for correct invocation.

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

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

Beyond the readOnlyHint annotation, the description explicitly explains the data scope: aggregate figures across four engines, per-engine breakdown, and a clear caveat that there is no per-engine citation-rate split. It also states the free cost behavior, adding valuable operational context.

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

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

The description is front-loaded with the core purpose, then flows through parameter source, metric scope, a granularity caveat, and cost. Every sentence adds distinct value and there is no filler or redundancy.

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

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

Given the output schema exists and annotations already cover read-only behavior, the description leaves no critical gaps for invoking the tool correctly: metrics, engines, project_id source, and cost are all explicit. Only explicit sibling routing is absent, but that gap is already reflected in usage_guidelines.

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 both parameters with 100% coverage. The description adds meaningful extra context by clarifying that project_id is a ranking id from list_projects and by describing how the reported figures are measured, which helps an agent select and pass the parameter correctly.

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 clearly that the tool reports a project's visibility across AI answer engines, including share of AI voice, presence, citation rate, and competitive rank. It lacks an imperative verb like 'get', but the purpose is unambiguous and the metric naming separates it from related 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 gives useful context by explaining that project_id comes from list_projects and noting the call is free, which implies when it can be safely used. However, it never explicitly contrasts this tool with siblings like get_share_of_voice or get_ai_citations, so when-to-use guidance is mostly inferred.

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

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

Annotations already mark the tool as read-only and not open-world, and the description adds meaningful behavioral context: list items carry their own how-to-fix steps while detail mode provides full fix steps, and calls are free/never consume lookups. This rate-limit and output-mode context goes beyond the annotations, though the description does not detail every return value, which is acceptable given an output schema exists.

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

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

The description is compact and front-loaded: the first sentence gives an overview, and the second paragraph gives precise mode-based instructions. Every sentence earns its place, including the cost/rate-limit note, with no filler or repetition.

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

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

Given the tool's moderate complexity, the presence of an output schema, and annotations covering read-only safety, the description is complete enough for an agent to call it correctly. It covers both usage modes, all parameter roles, the source of project_id, filtering, pagination, and cost behavior.

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 0%, so the description carries the full burden. It clearly explains project_id as a ranking id from list_projects, issue_key as the drill-down selector, severity as the list filter with its enum values, and page as the pagination control for detail results. This adds substantial meaning the schema alone does not provide.

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: retrieving web audit issues for a project, with a clear two-mode behavior (severity-filtered list vs. drill into one issue's affected pages and fix steps). This distinguishes it from sibling tools like get_audit_summary by specifying the exact output form and granularity.

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 operational guidance: omit issue_key for the list, pass it for detail, use severity to filter, and use page for paginating detail results. It also anchors project_id to list_projects. It does not explicitly name sibling alternatives or state when not to use this tool, so it falls just short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds value beyond that by specifying the output contents and by stating that calling it never consumes lookups, which is a meaningful behavioral/cost guarantee.

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

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

The description is front-loaded with the core result and keeps the remaining details in two compact sentences. Every sentence adds relevant information, though the second sentence is somewhat dense with output components.

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 single required parameter and the presence of an output schema, the description is complete for invoking the tool. It explains the parameter source, the output highlights, and the free/no-lookup behavior, leaving no critical gap for correct 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?

With 0% schema description coverage, the description compensates by explaining that project_id is a ranking id from list_projects. This gives the agent a concrete source for the value, though it stops short of a full format example or additional constraints.

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 exactly what the tool returns: a web audit health summary with site health score, change since last crawl, and top-3 prioritized fixes. This scope clearly differentiates it from siblings like get_audit_issues by focusing on the health summary rather than raw issue listing.

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 tells the caller that project_id should come from list_projects and that the call is free, which is useful context. However, it does not explicitly say when to prefer this tool over related siblings such as get_audit_issues or get_project_overview, leaving the choice to inference.

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

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

The annotations already establish readOnlyHint=true and openWorldHint=false, so the agent knows this is a safe read operation. The description adds some behavioral context beyond annotations, such as 'Results are prioritized with risk notes flagging what needs attention.' The parenthetical '(may use lookups)' is vague and does not meaningfully clarify 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 compact and front-loaded, opening with the tool's purpose and primary metrics in the first sentence. The second sentence adds necessary parameter context and output behavior. The only slight weakness is the vague parenthetical '(may use lookups),' which adds little value and could be clarified or removed.

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-only tool with an output schema available, the description covers the key points: what data is returned, how to obtain project_id, and the fact that results include prioritized risk notes. It does not explicitly address sibling differentiation or the meaning of 'may use lookups,' but these are minor gaps given the available schema and annotations.

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

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

There is only one parameter and schema description coverage is 0%, so the description must compensate. It does so by explaining that project_id is 'a ranking id from list_projects,' which is essential semantic information not present in the schema. This gives an agent enough guidance to correctly source 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?

The description states a clear verb and resource: it returns a backlink profile summary for a project, listing concrete metrics such as Domain Score, total backlinks, spam score, and anchor health. This is not a tautology and gives an agent a solid idea of what the tool does. It does not explicitly differentiate itself from the sibling get_new_lost_backlinks, though the word 'summary' hints at a higher-level view.

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 useful prerequisite by noting that project_id is a ranking id from list_projects, and it implies use for prioritized risk overviews with the phrase 'risk notes flagging what needs attention.' However, it does not explicitly state when to choose this tool over siblings like get_new_lost_backlinks or get_project_overview, leaving the when-to-use guidance mostly implicit.

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

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

Annotations already mark the operation read-only, and the description adds meaningful behavioral context: the plan is 'computed nightly from the project's own data' and ordered by business impact. This tells the agent the data may be refreshed only nightly and that ordering is deterministic by impact, going beyond the annotation.

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

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

Two short sentences front-load the core definition immediately and add only the useful cadence/data-source detail. Every phrase earns its place; no filler.

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

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

For a read-only retrieval tool with one fully documented parameter and an output schema, the description gives enough context: what the plan contains, how it is ordered, and that it is computed nightly. Nothing needed to invoke it correctly is missing.

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

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

The input schema fully documents the single parameter, project_id, including its type, source ('Ranking id from list_projects'), and exclusivity. The description adds no parameter-level info, but the schema already covers it, so the baseline 3 applies.

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

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

The description explains the resource as 'the project's prioritized to-do list' and enumerates what it contains ('what to brief, which AI prompts you're losing, what's technically at risk'), so an agent can tell what it returns. It does not state a verb explicitly or name sibling tools, but the content is specific enough to distinguish from other report-style get_* 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 implies when to use the tool: when an agent needs the project's prioritized action plan, ordered by business impact. It does not explicitly mention alternatives or conditions when another tool should be used instead, so usage guidance is present but not fully explicit.

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 readOnlyHint annotation already communicates that this is a safe read operation, so the description does not need to restate that. It adds useful context by calling the brief 'finished' and by specifying that the score is measured against pages actually ranking, but it does not disclose behavior around stale briefs, regeneration, or data freshness. 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 a single dense sentence with the core resource front-loaded before the distinguishing details. There is no filler, no repetition of the title, and every listed element adds useful information.

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

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

For a one-parameter, read-only tool with an output schema, the description covers the essential purpose and output contents well. It could be slightly stronger by explicitly routing users to generate_content_brief when no finished brief exists, but the current definition is sufficient for correct selection and 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?

The schema already provides 100% parameter documentation, including that target_id comes from get_content_targets. The description only reinforces that the brief is for a single target page, adding little semantic value 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 identifies the resource as a finished content brief for one target page and lists its concrete contents: a 0–100 score, terms to add, questions to answer, suggested outline, and internal links. The phrase 'finished' and 'one target page' distinguishes this from generate_content_brief and from broader brief-related 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 implies this should be used for an already-computed brief rather than for creating one, but it never explicitly states that preference. It also does not mention when to choose this over generate_content_brief or identify generate_content_brief as the alternative for creating a brief.

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 openWorldHint=false, so the safety profile is known. The description adds that the result includes scores and the monthly analysis allowance, but it does not disclose quota behavior, error cases, or other side effects—acceptable for a read-only tool, though not rich beyond the annotations.

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

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

A single short sentence with no filler, no repeated schema information, and no redundant annotation restating. It front-loads the resource and then lists the payload contents efficiently.

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, read-only getter with an output schema, the description is largely complete: it names the returned resource and data. The only gap is usage/alternative guidance, but that does not hinder correct invocation given the schema and annotations.

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

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

The only parameter, project_id, is fully documented in the schema as an integer ranking id from list_projects, so schema description coverage is 100%. The description adds no additional parameter-level meaning, so the baseline score of 3 applies.

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

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

The description names a concrete resource ('pages under content optimization for a project') and the included data ('scores and the monthly analysis allowance'), clearly distinguishing it from sibling content tools like get_content_action_plan or get_content_brief. The verb is supplied by the tool name, and the noun-phrase construction still conveys the exact retrieval purpose.

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?

No explicit guidance is given about when to use this tool versus sibling tools, and no exclusions or alternatives are mentioned. The only usage signal is indirect: the description states what the tool returns, leaving the agent to infer when it should be selected.

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 and openWorldHint, and the description adds meaningful non-obvious behavior: legacy KR add-on accounts are charged a daily research credit per call even on cache hits. It also explains what the gap list represents, giving the agent useful output semantics beyond the schema.

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

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

The description is front-loaded with the core purpose, then explains the gap list, usage pattern, and cost caveat. All sentences earn their place, though 'May use lookups' is cryptic and slightly weakens clarity.

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

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

With an output schema present and read-only annotations, the description covers the main decision points: what the tool does, how to provide your domain, the pairwise limitation, and a cost caveat. It does not explicitly explain the optional language/location parameters, but the schema supplies defaults and the tone is enough for a competent 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?

The schema covers domain_a, domain_b, and project_id, and the description reinforces the domain_a/project_id relationship. However, language_code and location_code are only partially addressed via the vague phrase 'May use lookups,' leaving their meaning and usage underspecified.

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 a specific operation: a strictly pairwise head-to-head between your domain and one rival, producing keyword intersection with both positions plus a gap list. It emphasizes 'one rival' and 'strictly pairwise,' which distinguishes it from broader competitor-analysis 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 gives clear usage context: 'call it once per rival' and 'Provide domain_a, or project_id to use your project domain.' It does not explicitly name alternatives or state when not to use the tool, but the pairwise constraint is strong enough guidance for an agent to select it correctly.

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

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

Annotations already mark it read-only and non-open-world. The description adds valuable behavioral context beyond annotations: calling it never consumes lookups, tracking type is detected automatically, and it returns visibility, traffic estimates, and top-N counts. No contradictions with annotations.

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

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

Two dense, front-loaded paragraphs with no filler. The first sentence gives the high-level summary, and the second paragraph packs all parameter and behavior guidance efficiently. Every sentence contributes.

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

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

Given the moderate complexity, existing output schema, and read-only annotations, the description is complete: it covers scope, supported project types, parameter usage, output contents, and cost behavior. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 0%, so the description carries the parameter-documentation burden. It explains project_id provenance ('a ranking id from list_projects'), that query filters, that sort orders by position/change/volume/traffic, and that limit caps at 50. It doesn't deeply define each sort option's semantics, but all four parameters receive meaningful guidance.

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

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

The first sentence clearly identifies the resource and scope: 'Keyword positions and KPIs for one project' with an explicit list of included KPIs. The per-keyword detail description (position, change, best URL, intent, volume, Keyword Score) makes it easy to distinguish this from sibling tools like get_ranking_alerts or get_ai_visibility.

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 strong when-to-use guidance: project_id comes from list_projects, it works for web/local/YouTube projects with automatic tracking-type detection, and it is free, never consuming lookups. It doesn't explicitly name alternative tools or state when not to use it, but the context is clear enough for an agent to select it appropriately.

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

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

Annotations declare readOnlyHint=true and the description is fully consistent with that, so no contradiction. The description adds genuine behavioral value beyond the annotations by disclosing the 25-per-side cap and enumerating the fields returned per backlink, which the schema alone does not convey.

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

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

Two short, dense sentences with no filler. The first packs result shape, scope, cap, and returned fields; the second covers project_id provenance. Key constraints are 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?

For a simple read-only listing tool with an output schema and safety annotations, the description adequately covers what is returned, the cap, and required-parameter provenance. The minor gap is that it does not explicitly tie limit/status to the per-side behavior or state when this tool is preferable to backlink-related siblings.

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

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

Schema description coverage is 0%, but the description compensates for the most important gap: it explains that project_id is a ranking id obtained from list_projects, which is exactly the semantic an agent needs for the required parameter. The other parameters (limit, status) are largely self-explanatory given their schema defaults and enum values.

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 — it returns new and lost backlinks for a project — and adds concrete detail on what each result contains (Domain Score, anchor text, follow status) plus a 25-per-side cap. The new/lost framing distinguishes it from broader backlink siblings like get_backlink_profile, though it never names them explicitly.

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

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

The note that project_id is a ranking id from list_projects provides useful sourcing context and implies a lookup workflow. However, the description gives no explicit guidance on when to choose this tool over alternatives such as get_backlink_profile or get_audit_issues, and no exclusions are stated.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the description doesn't need to restate safety. It does add useful context by explaining the link-gap ranking behavior and the project_id source. However, it gives no further operational details such as output scope, pagination, or what 'may use lookups' actually means.

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 short and front-loads the tool's purpose before explaining the key parameter. The phrasing 'protect, and fix' is vague and 'may use lookups' is elliptical, but overall it avoids unnecessary repetition and stays appropriately 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?

With an output schema present, return values don't need to be described. The required parameter and optional link-gap mode are explained. However, the description names three recommendation categories — outreach, protect, fix — and only elaborates on the outreach/link-gap case, leaving significant ambiguity about what the other modes produce.

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

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

Schema description coverage is only 50%, and the required project_id is undocumented in the schema itself. The description fills that gap by identifying project_id as a ranking id from list_projects. competitor_domain semantics are covered both in the schema and again in the description, so all parameters are meaningfully explained somewhere.

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 clear topic: 'Backlink outreach, protect, and fix recommendations for a project.' It is more specific than a tautology and names the link-gap mode, which helps distinguish it from raw profile tools like get_backlink_profile or get_new_lost_backlinks. However, 'protect' and 'fix' are left undefined, and it doesn't explicitly differentiate itself from 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 gives a concrete condition: pass competitor_domain to get link-gap domains that link to a rival but not to the user. It also explains that project_id comes from list_projects. But it does not state when to prefer this tool over sibling backlink or analysis tools, nor when not to use it.

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

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

Annotations already mark this read-only, and the description adds genuinely new behavior: premium briefing fallback to 'base health/visibility/backlink metrics instead and says so,' plus the cost trait 'never consumes lookups.' No contradiction with readOnlyHint/openWorldHint.

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

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

Three tight sentences: the first gives the overview value, the second explains the parameter and premium fallback, and the third clarifies cost. Every sentence adds distinct information and the core purpose is front-loaded.

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

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

For a one-parameter briefing tool with an output schema and read-only annotations, the description covers selection, prerequisite, fallback behavior, and cost. There is no obvious missing detail an agent needs 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?

With schema_description_coverage at 0%, the description compensates by explaining that 'project_id is a ranking id from list_projects' and by instructing the caller to get it from list_projects first. That is meaningful beyond the raw integer schema but leaves some nuance (e.g., how to obtain the ID from list_projects output) implicit.

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 single resource ('one project') and specifies the deliverable: 'health, visibility, top movers, and the highest-priority things to fix now.' It is clear that this is a project-level briefing, though it does not explicitly contrast with sibling tools like get_audit_summary or get_ai_visibility.

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 explicit context for when to use the tool ('The briefing for one project') and a hard prerequisite: 'call list_projects first.' It does not name alternatives or exclusions, but the stated precondition and account-state fallback are useful selection guidance.

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

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

Annotations already mark this as read-only, and the description adds valuable non-obvious behavior: the result is null until win_prompt has run. It also discloses the output's three components (answer, gap versus cited pages, schema to add) without contradicting 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 one dense, well-structured sentence: it names the resource, enumerates the three output components, and ends with the key null precondition. No filler, no 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?

With an output schema present, return-value details are already covered. The description supplies the essential missing context: the dependency on win_prompt and what the brief conceptually contains. The two parameters are self-describing in the schema, so nothing needed for correct invocation is missing.

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

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

Schema description coverage is 100%, with both project_id and prompt_id already explained in the schema. The description does not add parameter-level meaning beyond that, so the baseline score of 3 is appropriate.

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

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

The description clearly identifies the tool's output: a gap brief for one AI prompt containing a quotable answer, a comparison of cited pages versus the site, and the schema to add. It references win_prompt, which anchors its role, but it does not explicitly differentiate itself from related siblings like get_ai_citations or get_content_brief.

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

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

The phrase 'null until win_prompt has run' gives a clear precondition, telling the agent this tool should be called only after win_prompt has executed. It provides useful temporal context, though it does not name alternatives or explicitly say 'use this instead of X'.

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

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

Beyond the readOnlyHint, it discloses that calls are free and never consume lookups, and it honestly scopes the data as computed movements rather than user-configured alerts. It also reveals that events carry Google-update-date annotations, adding behavioral detail annotations do not cover.

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

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

Three dense sentences carry the definition, exclusions, parameter source, and cost behavior with no filler. The most important identifying information is front-loaded in the first sentence.

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

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

For a two-parameter read-only tool with an output schema, the description covers all necessary invocation context: what it returns, how to identify the project, the time window, the cost implications, and the borderline between computed events and alert rules.

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 0% schema description coverage, the description compensates fully: days is explained as the trailing N-day window with the 7–90 range restated, and project_id is given real meaning as a 'ranking id from list_projects' rather than just a positive integer.

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

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

The description opens with a precise definition: threshold-crossing ranking events for a single project over a 7–90 day window, including exact event types (entering/leaving top 3/10/100, big gains/drops). It also distinguishes this tool from saved-alert rules, which prevents confusion with the 'alerts' label.

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

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

It gives clear usage context: one project, last N days, project_id sourced from list_projects. It explicitly says this is not a saved-alerts feature, offering a when-not, though it does not name a concrete sibling alternative for saved alerts or current rankings.

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

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

Beyond the readOnlyHint annotation, the description adds meaningful behavioral details: the tool never consumes lookups, is presence-based rather than volume-weighted, and provides no historical trend. It also defines what a 'gap' means. This is valuable context for an agent deciding whether the answer will satisfy the user's underlying request.

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

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

The description is compact and front-loaded: the core metric appears first, followed by a definition of gaps, explicit scope limitations, parameter sourcing, and cost behavior. Every sentence provides distinct, useful information without redundancies.

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-only tool with an output schema present, this description covers the key decisions an agent needs: what the metric means, what it excludes, where to get the id, and what invoking it costs. Nothing essential is missing.

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

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

The schema only says project_id is a positive integer, but the description explains it is a ranking id from list_projects. This significantly compensates for the 0% schema description coverage and tells the agent where to obtain a valid 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?

The description defines exactly what the tool computes: project-scoped share of voice, top-10 presence versus tracked competitors, and per-keyword gaps. This clearly distinguishes it from sibling tools like get_keyword_rankings or get_ai_visibility by including a scope and specific metric.

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 explicit context: tracked keywords only, presence-based not volume-weighted, and no historical trend. It also tells the agent project_id comes from list_projects and that calling is free. It stops short of naming alternative tools for cases where volume or historical trend is needed, so it lacks explicit sibling routing.

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

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

Annotations already convey readOnlyHint and openWorldHint, and the description does not contradict them. It adds useful behavioral context by explaining that the pillar page is the highest-volume member and that this tool returns data behind the interactive map, plus how project_id changes the result.

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

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

The description is compact and front-loaded with the main purpose, then adds only relevant context about the map and project_id. The final parenthetical '(may use lookups)' is cryptic and adds little, preventing a 5.

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, together with a rich input schema and an output schema, provides enough for an agent to invoke the tool correctly for basic use. It explains the optional project_id overlay and the return concept. It lacks explicit exclusions or mention of limit/language/location semantics, but those are largely inferable from 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?

With 0% schema description coverage, the description must compensate for parameter meaning. It adds value for project_id by identifying it as a ranking id from list_projects and explaining the overlay behavior, and seed is referenced. However, limit, language_code, and location_code are not addressed at all in 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 states a specific action and resource: 'Groups keyword ideas for a seed into topic clusters' and names the key outputs (keyword count, total search volume, suggested pillar page). It does not explicitly contrast itself with sibling tools like research_keywords or get_content_targets, so it falls just short of a 5.

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

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

Usage is implied by the described function: call it when you need topic clusters for a seed. It also gives a conditional usage hint by saying passing project_id overlays tracked keywords. However, it names no alternatives or when-not-to-use conditions, so guidance is only implicit.

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

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

Beyond the readOnlyHint annotation, the description discloses that the call is free and never consumes lookups, and warns that demo/sample projects are flagged is_demo and must not be mistaken for customer sites. This is behaviorally useful context not present in the annotations.

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

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

Three tightly written sentences: the first states the output and columns, the second clarifies project_id and tracking_type, and the third adds the demo caveat plus cost/first-call guidance. Every sentence earns its place with no filler.

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

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

Given the tool has an output schema, the description does not need to restate return values. It covers output structure, project_id reuse, demo flags, cost behavior, and the recommended call order, so an agent has enough context 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?

The schema has one optional limit parameter with zero description coverage, and the tool description never mentions limit. Since the description is expected to compensate for low schema coverage but does not, the parameter semantics are under-specified, though the parameter is optional and nominally self-explanatory.

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

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

States a specific verb ('List') and resource ('Ranklogs projects') and enumerates the flattened output columns. It also positions the returned project_id as the value to pass to other tools, which distinguishes this foundational listing tool from sibling get_* 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 instructs the agent to call this tool first to obtain valid project_id values before calling anything else. The additional note that it is free and never consumes lookups further clarifies when it is safe 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?

Annotations already indicate readOnlyHint and openWorldHint, and the description adds valuable behavioral context beyond them: results include from_cache/stale flags, the remaining-lookups balance, and the fact that lookups may be consumed. This helps the agent anticipate cost and data freshness without contradicting 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 compact and front-loaded with the core purpose, followed by parameter notes and behavioral caveats. Each sentence adds useful information, though the parenthetical '(may use lookups)' and the word 'honest' add slight stylistic clutter without major harm.

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

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

The description covers the required parameters, modal variants, source restriction, project_id provenance, caching flags, and lookup consumption. An output schema exists, so return-value details are not required. The main missing context is a brief explanation of what each mode conceptually returns and the meaning of language_code/location_code, but defaults and names largely compensate.

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 0% description coverage, so the description must compensate. It clarifies mode, term, source, and project_id meaningfully, but it leaves limit, language_code, and location_code to rely on their names and schema defaults. This is partial compensation rather than complete parameter documentation.

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

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

The description clearly states the tool performs keyword research and lists the modes (overview, ideas, suggestions, related) and output metrics (volume, difficulty, intent, CPC, opportunity score). This distinguishes it from ranking-focused siblings like get_keyword_rankings, though it does not explicitly name an alternative.

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

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

The description gives useful within-tool constraints, such as source being valid only for overview and suggestions and project_id being optional for overlaying tracked keywords. However, it provides no guidance on when to choose this tool over related siblings like get_keyword_rankings or analyze_competitor_domain.

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 all false and uninformative, so the description carries the burden and fills it well: it discloses that the tool consumes one monthly content analysis and that the result must be fetched later via get_prompt_gap_brief, implying an asynchronous or job-based analysis action. This goes beyond what the annotations or schema convey, and it does not contradict them.

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

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

The description is compact and front-loaded: the first sentence states the purpose, the second covers the optional comparison, and the third gives quota impact and the retrieval step. Every sentence earns its place with no repetition 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?

Given that the schema is fully documented and an output schema exists, the description covers the essential call-time knowledge: what the tool does, when to use it, the optional parameter, the quota cost, and how to fetch the eventual result. This is complete enough 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 parameters are already well documented with source references like get_ai_visibility, add_ai_prompt, and list_projects. The description adds only mild extra context for the optional own_url comparison, which is useful but not a substantial improvement 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 opens with a specific verb and resource: 'Run a gap analysis on an AI prompt the site is absent from.' It explains what the tool actually does by reading cited pages and briefing how to become the cited answer, and it clearly points to get_prompt_gap_brief for the result, distinguishing it from related siblings like get_ai_visibility and add_ai_prompt.

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

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

The description gives a clear trigger condition — the site is absent from the AI prompt — and describes the optional comparison mode against an own page. It also mentions the quota cost ('Uses 1 monthly content analysis') and the follow-up tool, providing enough context to use it appropriately, though it does not explicitly name exclusions or alternative tools.

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