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

Annotations declare a non-idempotent, open-world, non-destructive mutation; the description goes well beyond that by disclosing the side effects: the suggestion leaves the pending list, sibling suggestions from the same cycle are untouched, the new prompt counts against the workspace plan, and measurement starts from the next run. It even routes to get_account for the timing detail.

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?

Front-loaded with the core action and outcome, then side effects, then parameter behavior. Mostly earns its place, though 'the same way accepting it in the PromptEye app does' is a slightly decorative clause that adds little for an agent.

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

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

For a mutation tool with full annotations and an output schema, the description covers everything the agent needs: what it produces, what it removes from the pending list, the isolation from siblings, and the billing/measurement consequence. Return values are covered by the output schema.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining the semantic effect of promptText — it edits the wording 'before it starts being asked' — rather than just restating that it replaces the suggestion text.

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 (accept) and resource (prompt suggestion), and clarifies the outcome: the suggestion becomes a tracked prompt of the active project. It names list_prompt_suggestions as the source, so an agent can distinguish it from the sibling that merely lists suggestions.

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

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

Gives clear context (turning a pending suggestion into a tracked prompt) and the condition for the optional override (use promptText to edit wording, omit to accept verbatim). It does not explicitly say when NOT to use it or name an alternative accept path, so it stops short of 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 cover the mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false). The description goes beyond them by disclosing the plan-quota cost ('every prompt counts against the workspace plan'), the group-creation side effect, and the important consequence that unvalidated prompts sit at 0% visibility. It stops short of stating reversibility or exact failure modes, but the added context is substantial.

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 warning and the recommended alternative are front-loaded, and the structure (what it does → why not → what it skips → how groups work → when to use) is logical. It is on the long side, with some restatement of the duplicate/0%-visibility consequences, but each block carries decision-relevant information.

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

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

With an output schema present, return values needn't be explained, and the annotations cover safety. The description supplies everything else an agent needs: the bypass semantics of confirmBypassPromptIntelligence, group behavior, plan cost, and the decision rule for choosing this over list_prompt_suggestions.

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

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

Schema description coverage is 100%, so the schema already documents prompts, groupName, and confirmBypassPromptIntelligence in detail. The description's group-name explanation ('created after the existing groups', 'reused') largely restates what the schema states, adding no new syntax or format detail. 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?

States a specific verb and resource ('Tracks prompts written by hand in the active project') and immediately distinguishes itself from the sibling-generated path. The title's parenthetical and the body's contrast with list_prompt_suggestions make the tool's niche unmistakable.

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

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

Explicit when-to-use ('only when the user has prompts of their own that must be tracked verbatim — migrating from another tool, or a list a client insists on'), when-not ('if the user simply wants more prompts, use list_prompt_suggestions'), and a fallback directive ('when unsure, ask the user'). It even names upsert_prompt_group for the follow-up rename/describe case.

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 supply readOnlyHint/openWorldHint, so the description carries the behavioral load and does so: it discloses that results are ranked not paged with no cursor, that `partial` signals truncation, that `verified` is per-request and cannot be filtered or split, and that a disconnected integration yields misleading zeros. That is exactly the context annotations cannot express.

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

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

The routing and caveat content is front-loaded and useful, but the description runs long with rhetorical padding ('Each one is a citation that went elsewhere,' 'the supply side of visibility') that does not help an agent select or invoke the tool. Several sentences could be cut without losing selection-relevant information.

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

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

With 9 params, a required groupBy, and an output schema already present, the description covers what it must: result ordering/truncation semantics, the verified-request caveat, the integration-not-connected failure mode, and cross-tool boundaries. Nothing an agent needs to call this correctly or interpret the response 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 is 3, but the description goes further: it interprets each groupBy value in operational terms, gives a concrete botId example, and clarifies that vendor is not the `assistant` field of get_ai_traffic. The remaining schema-documented params (limit, startDate/endDate, status) are not elaborated beyond the schema, so it falls short of a 5.

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

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

Opens with a precise framing: 'The same requests as list_bot_visits, counted by the API rather than listed.' That is a specific verb (count), a specific resource (bot visits), and it explicitly distinguishes itself from the sibling list_bot_visits. An agent can route between the two without opening either 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 tells the agent which groupBy answers which question, singles out botId=chatgpt-user with groupBy=path as 'the sharpest reading here,' contrasts itself against list_prompts, list_competitors, list_sources and get_ai_traffic, and gives a hard precondition: call get_integrations_status before reporting a zero. When-to-use, when-not-to-trust, and alternatives are all present.

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 mark it non-read-only but non-destructive; the description adds the crucial async lifecycle (pending → success/partial/error), timing expectations (instant to under a minute), and the quota/billing side effect of auditing URLs. These are real behavioral traits 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?

Three short paragraphs, front-loaded with purpose, then lifecycle, then billing. Every sentence carries information; the billing paragraph is slightly dense but justified given two plans and a quota.

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

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

With an output schema present, the description needn't explain return fields; it instead covers the asynchronous completion model, polling target, and billing/quota consequences. 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?

Schema coverage is 100%, so the baseline is 3. The description still adds meaning the schema does not: that audited URLs count against the selected plan's monthly URL quota, and that omission falls back to the key holder's plan. It reinforces rather than merely restates projectId.

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 (audits) and resource (given URLs) and enumerates the concrete signals checked: schema markup, breadcrumbs, headings, crawlability, authority, reading level and style. This clearly distinguishes it from sibling read tools like get_audit, which only fetches 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 describes the workflow: run it, it returns `pending`, poll with get_audit until success/partial/error, and check quota with get_audit_usage. It also tells the agent how to choose billing via projectId vs omitting it, which is genuine when-to-use 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 mark this as non-read-only, non-idempotent and open-world, and the description adds substantial context beyond that: the run is asynchronous, returns `processing` and later `ready`/`error`/`corrupted_response`, is blocked by an in-flight run or unchanged inputs, and consumes the workspace's monthly brand-analysis quota. That quota and blocking disclosure is exactly the kind of behavioral detail annotations cannot express.

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

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

Three tight paragraphs that front-load what the tool does, then lifecycle, then constraints. Every sentence carries information (states, polling, blocking rules, quota), though the lifecycle detail borders on verbose for a zero-parameter call.

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

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

Despite an output schema existing, the description still supplies the asynchronous state machine and the refusal conditions an agent needs to call this correctly and interpret the returned status. Nothing needed to invoke or follow up 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 takes zero parameters, so there is no parameter semantics to document and the baseline of 4 applies. The description correctly spends no words on 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?

States a specific verb and resource ('starts a brand analysis run for the active project') and immediately explains the actual work performed: comparing tracked prompts against competitors to find and size topical gaps. This is clearly distinguishable from sibling analysis tools like create_audit or create_topical_map.

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

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

Gives explicit prerequisites and routing: call get_brand_analysis_availability first to learn whether and why a run is possible, and use get_brand_analysis_run to poll the result. It also names the exact conditions under which this call is refused (a run in progress, unchanged tracking results).

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 cover the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=true), and the description adds real behavioral context beyond that: only one level of nesting is allowed, the source is always `manual` and never a PromptEye proposal, and a same-name sibling at the same level is refused. That uniqueness and nesting constraint is the kind of thing annotations cannot 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?

Front-loaded with the core action, then the parent/nesting rule, then the source guarantee and duplicate refusal. Every sentence carries distinct information, though it is denser than strictly necessary for a two-parameter tool.

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

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

With an output schema present and annotations covering the safety profile, the description fills the remaining gaps an agent needs: nesting depth limit, the forced `manual` source, the duplicate-name refusal, and the follow-up tool for filing prompts. 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 coverage is already 100%, so the baseline is 3, but the description adds meaning beyond the schema: parentCategoryId must reference an existing top-level category and produces a subcategory with a one-level nesting cap. That constraint is not stated in 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?

States a specific verb and resource ('Adds a category the active project can file prompts under') and immediately distinguishes itself from the list_categories sibling by describing the write action. An agent knows this creates a category rather than reading or updating one.

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 to pass an existing top-level category as parentCategoryId to make a subcategory and that omitting it creates a top-level category, and it names update_prompt with categoryId as the route for filing existing prompts. No explicit 'when not to use', but the conditional usage is clear.

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

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

Annotations cover the safety profile (non-read-only, non-idempotent, open-world), and the description reinforces and extends it: 'Every call orders a new brief, so asking twice for the same prompt makes two,' the async status ('comes back processing'), and the important caveat that a generated article is a draft and does not guarantee citation. It also discloses what happens outside the tool (writing/publishing occurs in the PromptEye app and the user's own site).

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 core action, triggers, and side effects are front-loaded in the first paragraph, and the non-idempotency warning is placed at the end. It is longer than strictly necessary — the visibility-loop narrative and the app/publishing paragraph could be trimmed — but every sentence carries usable 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?

With an output schema present, return values needn't be explained, and the description covers everything else an agent needs: prerequisites (active project), trigger conditions, the promptId tradeoff, the async processing state, the follow-up read tool, and where the remaining workflow happens.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema: promptId links the brief so that prompt's visibility is what measures the article, whereas an untracked prompt still gets a brief but 'nothing will measure its impact.' It also frames prompt as the question phrased to an assistant, reinforcing the schema's wording.

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

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

The opening sentence states a specific verb and artifact ('orders a brief — a title and an H2/H3 outline — for an article that targets one prompt') and explicitly sets up the read/write pairing with get_content_brief. An agent can distinguish this from get_content_brief without inspecting either 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 names concrete trigger conditions ('when the user wants PromptEye to generate content, write an article, or close a visibility gap'), names the companion tool (get_content_brief), and explains the follow-up sequencing of the visibility loop. It also gives explicit guidance on when to pass promptId versus leaving it out.

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 non-read-only, non-idempotent, non-destructive, and open-world behavior. The description adds key side effects beyond annotations: the new project becomes the active project, duplicate creation for the same brand and market is refused, the action consumes workspace plan quota, and assistants are idle until prompts exist. No annotation contradiction is present.

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

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

The description is front-loaded with purpose and creation rules, but the final paragraph about PromptEye prompt generation and list_prompt_suggestions is largely tangential to invoking create_project. It adds length without direct invocation value, though the structure remains readable.

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

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

An output schema exists, so return values need not be explained. The description covers scope, side effects, duplicate handling, quota impact, and the list_projects prerequisite, leaving little an agent needs missing before calling the tool.

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

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

Schema description coverage is 100%, so parameter meanings are already fully documented in the schema. The description reinforces the brand/country relationship for multi-market projects but adds little syntax or semantics beyond what the schema provides, making the baseline 3 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?

States a specific verb ('Starts tracking') and resource ('one brand in one market'), then explains that the project becomes active and is the unit everything else hangs off. It distinguishes creation from siblings like list_projects, select_project, and update_project by describing creation scope and duplicate refusal.

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

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

Gives clear context: one project per brand per market, check list_projects first, duplicate creation is refused, and creating counts against the workspace plan. It names adjacent tools such as list_projects and list_prompt_suggestions, but does not explicitly contrast create_project with update_project or select_project for existing projects.

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?

Goes well beyond the annotations: it discloses that the report is booked to the API key's account and spends that account's lead-magnet quota, that the endpoint is public with no API key, the 30-day same-domain/same-account dedup that re-sends instead of rebuilding, and that a new report returns `processing` with no score for minutes. This is exactly the mutation-side context annotations alone (write, non-idempotent) do 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?

Front-loads the purpose in the first sentence, then layers behavior, quota, and async notes in a logical order. It is on the verbose side with some product-context padding (white-label lead-magnet framing), but each paragraph informs correct invocation rather than restating tooling.

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

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

An output schema exists, so return-value detail is not required, yet the description still explains the result distinguishes cached-resend from new build and warns figures arrive minutes later. Combined with annotations and a full schema, an agent has everything needed to call and interpret it.

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

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

Schema coverage is 100%, so all seven parameters are already documented in the schema, and the description adds only scattered reinforcement (email is 'the address given', website is the cache-match key, reach decides the questions). The baseline of 3 is appropriate when the schema carries the field-level burden.

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 and resource ('Generates the free visibility report... and emails it'), and contrasts it with the read/get side of the same object by naming get_report and get_report_integration. An agent can distinguish it from siblings like list_reports or get_report without opening a 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?

Gives clear context (agency lead-magnet, one-off sample, not tracking) and explicitly routes the agent: 'Reach for get_report_integration when the question is how to wire that form up' and 'read them with get_report.' It does not state explicit exclusions or when a different report-creation path would be preferred, so it falls just short of a full when/when-not treatment.

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 the annotations: the call is slow because it invokes a model, it returns asynchronously with `processing`/`ready`/`error` states, and it must be polled with get_topical_map. It also confirms the non-idempotent semantics ('every call starts a new map; no limit'), reinforcing idempotentHint=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?

Front-loads what the tool produces, then the async lifecycle, then the repeat-call behavior — good ordering. The 'most complete source for both search engines and AI models' clause is mildly promotional rather than operational, but overall the text is tight.

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

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

An output schema exists, so return values need no explanation, and the description still supplies the one thing an agent must know to call this correctly: it is async and must be polled. 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 coverage is 100% with both parameters fully described (topic example, two-letter language code), so the schema carries parameter meaning. The description adds no further syntax or format detail, making the baseline 3 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?

States a concrete verb and artifact ('Builds a pillar-and-clusters content plan... one compendium page and supporting article titles, grouped by category'). It is clearly distinguishable from siblings get_topical_map, list_topical_maps, and regenerate_topical_map_cluster.

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?

Explains the operating context ('for a topic in the active project') and the follow-up read path via get_topical_map. It does not explicitly state when NOT to use it (e.g. when a map already exists), but the 'every call starts a new map' note covers the main alternative decision.

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 destructive=true, idempotent=true and write semantics, so the safety bar is partly met. The description adds genuinely new behavior: paused prompts count toward emptiness, non-empty groups are refused rather than partially deleted, and the operation is irreversible. It does not discuss permissions or what the response contains, but that is minor given the annotation coverage.

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

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

Three sentences, front-loaded with what the tool does, then the constraint, then the recovery procedure and the irreversibility warning. No filler or repetition of 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?

For a one-parameter destructive tool with an output schema and full annotation coverage, the description supplies everything an agent needs: precondition, error semantics, remediation, and irreversibility. Return values are handled by the 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% for the single groupId parameter, and the schema already says it is the id as list_prompt_groups reports it. The description only alludes to group ids indirectly through the update_prompt remediation, 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?

States a specific verb and resource ('Deletes one prompt group of the active project') and immediately narrows scope to empty groups, which cleanly distinguishes it from upsert_prompt_group and update_prompt. An agent can pick it without opening 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?

Gives an explicit precondition ('only when it has no prompts — paused prompts count too'), the failure mode ('a group that still has prompts is refused'), and the exact remediation path via update_prompt with groupId of another group or null. This covers when to use, when not to use, and the alternative tool by name.

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 mark this as non-read-only and non-idempotent; the description adds the critical behavior that the call schedules work and returns immediately while the cycle runs in the background for a minute or more. It also documents the skipped case (runId null with a reason, explicitly not an error) versus the refusal case, which an agent could not infer from 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?

Purpose and the async/skip semantics are front-loaded, and the routing advice lands at the end. The middle explanation of what PromptEye generates and scores is somewhat expansive and restates the opening cycle description, costing a little efficiency.

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 background-triggering mutation with an output schema already present, the description covers everything an agent needs: that it is asynchronous, that results are fetched elsewhere, and how to interpret the skipped and refused outcomes.

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 a single parameter with 100% schema description coverage ('Id of the prompt group, as list_prompt_groups reports it'), so the schema carries the load. The description only loosely adds that the group belongs to the active project; it contributes no format or constraint detail beyond the schema.

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

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

The description states a concrete verb and resource ('propose new prompts for one prompt group of the active project') and goes further by enumerating the internal cycle it triggers. It is clearly separable from list_prompt_suggestions (returns the results) and get_prompt_suggestion_availability (checks whether a run is possible).

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 sequencing: call list_prompt_suggestions afterwards for output, and call get_prompt_suggestion_availability first to distinguish a graceful skip from an API refusal. It also names the conditions under which a run is not worth scheduling (healthy group, plan coverage, pending proposals).

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 declare readOnlyHint and openWorldHint, so the description carries real extra weight: it explains that nextScanAt is when the run begins, not finishes, and that figures arrive gradually over tens of minutes, with explicit guidance to say the run started rather than results are ready. This is exactly the kind of semantic trait annotations cannot express.

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

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

The opening sentence front-loads the returned fields, and the second paragraph earns its place by clarifying the non-obvious nextScanAt timing. It is slightly dense and list-heavy, but no sentence is wasteful.

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

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

An output schema exists, so return-value documentation is not required, yet the description still adds semantic meaning to the key fields (prompt counts vs limit, next-run timing). For a zero-parameter read tool, nothing an agent needs to call it correctly is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; per the rubric this establishes a baseline of 4. No parameter-level detail is needed or missing.

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 resource (the account behind the configured API key) and enumerates the concrete data returned: key owner, plan, prompt count against limit, assistants, and next run start. This is unmistakably distinct from siblings like get_active_project or list_workspaces, which deal with projects, not the key's account/plan context.

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

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

Gives three explicit call scenarios: diagnosing a key, checking plan feature coverage before promising it, and answering when fresh figures arrive. That is strong when-to-use guidance, but it names no alternative tool or exclusion condition (there is no close sibling, so the omission is minor).

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=true, so the safety profile is covered. The description adds real context beyond that: the returned value is conversation-level state shared by all other tools, not a parameterized lookup, which explains why it takes no arguments.

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, zero waste, with the identity of the resource front-loaded and the usage trigger second. Nothing is redundant with the 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?

Output schema exists so return shape need not be explained, annotations cover the safety profile, and the description supplies the one non-obvious fact an agent needs: that this is the ambient project context for the rest of the session.

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?

Zero parameters, so per the baseline there is nothing for the description to disambiguate. Schema coverage is 100% and no parameter documentation is needed.

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 resource (the active project) and its scope: it is the project every other tool reports on. This distinguishes it from list_projects (enumerate) and select_project (mutate the selection), which an agent can tell apart without opening a 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?

Explicitly gives the trigger condition: call when unsure which project the conversation's numbers refer to. It does not mention select_project as the alternative for changing that project, so the when-not side is left implicit, but the positive guidance is clear.

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

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

Annotations cover read-only/open-world, but the description adds substantial context beyond them: the systematic undercount by design, the two senses of 'aiTraffic', the 0-1 rate semantics for engagementRate and ctr, and — critically — that a disconnected integration returns zeros and empty lists that look like a real zero-traffic finding. That is exactly the kind of behavioral caveat an agent needs.

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

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

Front-loaded and information-dense, but the middle section drifts into a lengthy comparison with Search Console and the aiTraffic field that could be compressed. Every point is relevant, yet the prose is essay-like for a tool definition and dilutes the actionable guidance.

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

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

With an output schema present, the description needn't explain return shapes; it instead supplies the integration-connectivity caveat, the interpretation guidance, and the axis semantics. Nothing an agent needs to call or interpret this tool correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: `by` ranks rather than totals and returns strongest entries rather than a full walkable list, and `assistant` narrows any of the three axes. The assistant referrer matching (openai→chatgpt) is documented in the schema, so the description doesn't need to repeat it.

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 and resource — Google Analytics sessions attributed to AI assistants — with count, engagement, and key events. It explicitly distinguishes itself from the visibility metrics (Search Console, get_ai_traffic vs. the aiTraffic field on a prompt), so an agent can separate it from siblings without opening any 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 names the question this tool answers ('is any of this visibility turning into visits'), explains when to use `by` versus totalling, and routes the agent to get_integrations_status before reporting zeros. It also states the two important exclusions: it is not a visibility counter and it doesn't capture direct-typed traffic.

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=true, so safety is covered; the description adds the non-obvious async behavior that each URL's `analysis` stays null until that URL's own check completes, i.e. partial results are expected. That is meaningful disclosure beyond the annotations, though rate limits or failure modes aren't mentioned.

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 sentences, front-loaded with what the call returns and then the polling condition; every clause carries information and nothing is 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?

An output schema exists, so return structure needn't be explained, yet the description still orients the agent on shape (URLs, nine signals) and on the asynchronous completion semantics. For a single-parameter read tool this is complete.

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

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

Schema description coverage is 100% for the single auditId parameter and the schema states it is the id 'as create_audit reports it'. The description adds no further syntax or format detail beyond that baseline, so 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?

States a specific verb and resource ('One audit in full') and enumerates what is returned: every audited URL plus nine content signals. It is clearly differentiated from create_audit (the producer) and get_audit_usage (quota) among the siblings.

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

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

Gives explicit lifecycle guidance — call after create_audit and keep calling until `status` is no longer `pending` — which is exactly the polling contract an agent needs. It stops short of naming/contrasting sibling readers such as get_audit_usage, so it is strong context rather than full alternative 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 cover readOnly and openWorld. The description adds that this reflects the same quota create_audit checks, which is meaningful context for an agent reasoning about audit limits. It does not describe rate limits or auth constraints, so it stops short of 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?

Two sentences, front-loaded with what is returned, followed by the projectId decision rule. No waste.

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

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

An output schema exists, so return-value detail is not required. For a single-optional-parameter, read-only quota tool, the description covers purpose, the parameter decision, and the create_audit relationship. It could note whether the quota is per plan or per key, but is otherwise complete.

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

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

Schema coverage is 100%, so the schema already documents projectId thoroughly (including a pointer to get_active_project). The description paraphrases the same semantics, adding marginal value. 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?

States a specific verb (reads/reports) and resource (monthly audit URL quota) with concrete output: total, used, and remaining. It also frames the relationship to create_audit, making it distinguishable from siblings.

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

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

Explicitly describes when to pass projectId (to read the quota billed to a project's workspace) versus omitting it (for the API key holder's own plan). Ties the parameter to a concrete decision, leaving little 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the no-side-effect profile is partly given. The description still adds value by asserting it performs the identical validation create_brand_analysis_run uses and returns the reason for unavailability, which is behavior the annotations alone don't convey.

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

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

A single sentence that front-loads the core purpose (whether a run would start right now) and appends the reason/no-side-effect qualifiers with no wasted text.

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 100% schema coverage on zero params and an output schema present, return values need not be explained. The description covers what the tool does and its relationship to the create tool; only minor gaps remain (e.g., no note on which project context is required).

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 are zero parameters, so per the baseline this scores 4. The description correctly implies the check is scoped to the 'active project' (no argument needed), which is useful context even though no parameter semantics exist to explain.

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 check (brand analysis run availability) for a specific resource (the active project) and explicitly ties it to the sibling tool create_brand_analysis_run, so an agent can distinguish it from create_brand_analysis_run and get_brand_analysis_run without opening a 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 phrase 'the same check that tool runs itself, without starting anything' clearly implies this is a preflight to run before create_brand_analysis_run. It names the alternative and its relationship, but doesn't explicitly state when NOT to use it or mention other siblings like get_brand_analysis_run.

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 cover read-only and open-world, so the safety bar is lower. The description adds real behavioral context the annotations cannot: gaps is empty and sentiment is null until status becomes ready, and error is set on failure. That directly shapes how an agent interprets results, though it doesn't discuss rate limits or pagination.

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-loaded with what the run contains and followed by the calling condition. Every clause carries information; nothing is padded.

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

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

With an output schema present, the description needn't enumerate return fields, yet it still previews the key ones (gaps, evidence, sentiment) and warns about their pre-ready states. Nothing needed to invoke or interpret the call 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?

There is a single runId parameter at 100% schema description coverage, and the schema already explains it comes from create_brand_analysis_run. The description adds no further parameter detail, 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 names the specific resource (one brand analysis run) and enumerates its contents: gaps, ranking evidence per gap, and sentiment. This clearly distinguishes it from the sibling create_brand_analysis_run, which produces rather than reads a run.

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 sequencing — 'Call it after create_brand_analysis_run until status is ready' — which tells the agent exactly when this tool is the right call. It stops short of naming alternative retrieval tools or when not to use it, but the polling condition is a clear usage context.

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

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

Annotations already declare readOnlyHint and openWorldHint, but the description adds real behavioral context beyond them: the brief has a status lifecycle (processing/ready/error) and returns near-empty data mid-processing, and it discloses that this tool does not write or publish the article. It stops short of richer operational detail (pagination, rate limits, size of payload).

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 return contents are correctly front-loaded, but the definition is long: the middle paragraph about PromptEye's measure/generate loop and the app-side writing workflow is largely product background that an agent does not need to invoke a read. Core instructions are buried in a wall of prose.

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 and safety annotations already present, the definition still covers everything an agent needs: what is returned, the polling/status semantics, and how it relates to create_content_brief. Nothing required to call it correctly is missing.

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

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

Schema description coverage is 100%, and the single briefId parameter is already documented as coming from create_content_brief. The description adds no syntax or format detail beyond the schema, so the baseline 3 for high coverage applies.

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

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

The first sentence names a specific verb (read) and resource (one content brief) and enumerates exactly what the payload contains: title, H2/H3 outline with notes and FAQ questions, fan-out phrases, and standalone-article phrases. It is clearly distinguishable from the sibling create_content_brief, which it explicitly contrasts ('orders one' vs 'reads it').

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

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

It states precisely when to call it: 'Call this after create_content_brief until `status` is `ready` or `error`', and warns that everything but the prompt is empty while the brief is `processing`. This gives both the trigger condition and the polling loop, leaving nothing 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?

Annotations only declare readOnly/openWorld, so the description carries the real behavioral load: the 4 000-request read cap, the four fixed assessments and their ok/warning/critical scoring (with `unknown` only for response time), the up-to-20 issues with an explicit worst-first ordering rule (5xx > 4xx > 3xx, then most frequent, then most recent), and the zero/empty-list failure mode for disconnected integrations.

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 purpose and the get_integrations_status caveat are well front-loaded and the ordering rules earn their space, but the description is four dense paragraphs and repeats the kind mapping twice ('`kind=ai` is the assistants; `kind=seo` is classic search engines' restating the earlier definition). Trimming that redundancy would tighten it without losing meaning.

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

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

An output schema exists, so return values need not be explained, and the description still covers the things the schema cannot: how scores are derived, how issues are ranked, sampling limits, and the misleading-zero failure mode with its recovery path. Nothing an agent needs to call and interpret this tool 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 is 3, but the description adds meaning the schema does not: why the 31-day window matters (only the newest 4 000 requests are read, so narrow the period rather than trust a partial read) and why `kind` is never combinable. It does not add further detail on `vendor` or the date defaults beyond what the schema already documents.

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 transformation (list_bot_visits requests for one `kind` turned into a verdict by the API) and names what the verdict contains: error/redirect counts, response speed, and worst problems. It explicitly distinguishes itself from adjacent siblings (list_bot_visits as the raw source, list_prompts/list_competitors as being named in an answer, list_sources as citation, get_ai_traffic as arrivals).

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 when-to-use routing (`kind=ai` for assistants, `kind=seo` for search engines, never combined), a sampling caveat (only the newest 4 000 requests are read, so narrow the period on a busy project), and a hard precondition: call get_integrations_status before reporting a zero or empty list, because an unconnected integration answers with zeros.

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 supply readOnlyHint and openWorldHint. The description adds a high-value behavioral fact beyond them: an unbound project returns zeros and empty lists that mimic a site with no traffic, and the caller should report which of the two integrations was empty. This is exactly the kind of context annotations cannot 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?

Front-loads purpose, then usage, then the false-zero caveat, which is well ordered. It runs slightly long and reiterates the 'call before reporting a zero' point, but nearly every sentence carries distinct guidance.

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

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

An output schema exists, so return-value explanation is not required, yet the description still flags the misleading zero/empty-list shape. Combined with the routing to get_integrations_status and the sync-status mention, an agent has everything needed to call and interpret it.

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

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

The tool takes no parameters, so per the rubric the baseline is 4. There is no argument syntax for the description to clarify, and it correctly focuses on output interpretation instead.

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 and resource: it reports whether Search Console and Google Analytics are bound to the active project and how their last sync went. It also explicitly distinguishes itself from get_integrations_status, which covers the bot tracker and sitemap instead. An agent can route between the two without opening either 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?

Gives explicit triggers ('when a Google figure looks wrong or empty', 'before promising a report built on one') and names the sibling alternative with the condition that selects it. It also warns to call this before reporting a zero as a finding.

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 cover readOnlyHint/openWorldHint; the description adds real behavioral semantics: what `connected: false` means versus `reason: sync_failing`, that the figures in downstream tools would be stale, and that Google/sitemap siblings explain the failure. It also discloses scope limits (no CMS integration; WordPress/Laravel are collector install paths reported under `botLogs`), which preempts a plausible misreading.

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?

Front-loads the one-sentence purpose, then the routing rule, then field semantics, then edge-case exclusions — a sensible ordering. It runs a bit long, and the final WordPress/Laravel sentence is the softest, but each sentence carries a distinct disambiguating fact and none is redundant.

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

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

With an output schema present the description needn't restate return structure, yet it still explains the semantics of the two output signals an agent is most likely to misread. Combined with the sibling routing and the explicit scope exclusions, an agent has everything needed to call this tool correctly and interpret it.

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

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

The tool takes zero parameters, so the baseline is 4; there is no parameter syntax for the description to add. The description instead clarifies the implicit 'active project' scope, which is the only input-like thing that matters here.

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 and resource — reports whether Search Console, Google Analytics, the bot tracker and the sitemap are connected to the active project — and explicitly distinguishes itself from the traffic/reporting siblings by describing itself as a single connectivity check. An agent can tell at a glance this is a precondition/diagnostic tool, not a data 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?

Gives an explicit when-to-call rule ('call it before reporting a zero or an empty list from get_search_performance, get_ai_traffic, list_bot_visits, count_bot_visits or list_crawls') and explains the failure mode it prevents. It names four concrete alternative tools and the exact condition that selects this one, leaving nothing 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?

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds genuinely new behavioral context: that every artifact PromptEye writes for the project reads this first, which signals a shared dependency an agent should be aware of. It doesn't discuss auth or freshness of the underlying data, so it is not exhaustive.

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 resource definition followed by the reason to care. The closing phrase 'worth knowing what a brand is being judged against' restates the opening clause about measuring against the brand, a minor redundancy, but nothing is padded.

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

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

With an output schema present, the description needn't explain returns, and the readOnly annotation covers safety. It is complete for a simple read tool, with the only soft gap being that it never says which project's knowledge base is returned (presumably the active one, given select_project/get_active_project 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-parameter tool applies. It correctly avoids inventing parameter talk and instead spends its words on what the resource is.

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 specifies the exact resource ('the description of the brand the project measures against') and even its content ('what the company sells and to whom'), so the agent knows precisely what comes back. It does not name the obvious sibling update_knowledge_base, relying on the get_/update_ naming convention to differentiate, which is clear enough but not 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 a clear usage context — read this before trusting a prompt or competitor judgement — which tells the agent why and when to call it. It stops short of naming alternatives or stating exclusions, so it is strong context rather than full routing guidance.

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

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

Annotations only cover readOnlyHint/openWorldHint, so the description carries the behavioral load — and it does: null vs 0 semantics for aiTraffic, the 50-search reporting floor, the fact a failed refresh keeps the prior figure and date, the sign convention for changes, and the warning that a hand-set businessPriority is indistinguishable from the computed one. This is well beyond what the annotations or schema disclose.

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?

Front-loaded with usage before the metric reference, and each metric paragraph states a concrete rule rather than padding. It is nonetheless long, and with an output schema present some field-by-field prose is arguably redundant, keeping it off 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?

For a measurement-heavy read tool with three nuanced metrics, the description supplies the interval semantics, the null/zero distinction, the measurement timestamp behavior and the banding thresholds — everything an agent needs to interpret a call. 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%, including the promptId lookup hint and the startDate/endDate defaults and 366-day constraint, so the schema does all the work. The description adds no input-parameter meaning of its own, making the baseline 3 correct.

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

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

Opens with a specific verb and resource ('One prompt of the active project') and immediately narrows scope ('with its visibility broken down per assistant — only the assistants that actually answered are listed'). An agent can distinguish this from list_prompts and from get_ai_traffic without opening any 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?

Explicitly states the situation that selects it ('Call this to see which assistant is carrying a prompt and which is dropping the brand from it') and routes to a sibling when the brand is weak ('create_content_brief starts an article aimed at this prompt'). It also fences off the closest-sounding sibling by contrasting with get_ai_traffic. No explicit when-not, but context is clear.

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

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

With readOnlyHint and openWorldHint already declared, the description adds meaningful value by stating it schedules nothing and returns an explanation when unavailable — the key behavioral trait for a check tool. It does not cover rate limits or latency, so it falls short of 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?

One dense sentence that front-loads the answer (whether a run would be scheduled) and closes with the key differentiator vs. generate_prompt_suggestions. Nearly no waste, though the em-dash aside makes it slightly heavy for a mobile read.

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

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

An output schema exists, so return structure needn't be described; the description still usefully explains the semantic of the return (availability plus the reason when not). For a one-parameter read-only check, nothing an agent needs is missing.

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

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

Schema coverage is 100% and the single groupId parameter is fully documented in-schema, so baseline is 3. The description adds only the scoping phrase 'of the active project,' no new format or constraint details 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 a concrete operation — a pre-flight availability check for generate_prompt_suggestions on one prompt group — and explicitly distinguishes itself from that sibling by noting it performs the same check 'without scheduling anything.' An agent can select it correctly without opening either 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 clearly frames the use case: determine whether generate_prompt_suggestions would schedule a run right now and, if not, why. The alternative (calling generate_prompt_suggestions itself) is named, giving strong implied routing, though it never states an explicit call-order rule like 'run this before generating.'

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=true, so the safety profile is covered. The description adds genuinely useful state semantics — a `processing` report returns no score yet — which an agent needs to interpret results, though it says nothing about latency, caching, or eventual consistency beyond that.

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

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

Front-loaded with the payload contents, then the usage condition. The long enumeration of returned fields is informative rather than filler, though it partly duplicates the output schema, which makes it slightly longer than strictly necessary.

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?

Covers purpose, triggering workflow, and the processing-state caveat. Since an output schema exists, return values needn't be described and their enumeration is a minor redundancy; nothing critical 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% for the single reportId parameter, and the description adds nothing about its format, source, or validity beyond what the schema already states ('as create_report or list_reports reports it'). Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb+resource ('read one report in full') and enumerates the concrete payload the agent receives (score, industry, prompts, competitors, assistant answers, sources, contact requests). This clearly separates it from list_reports and create_report among siblings.

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

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

Explicitly says to call it after create_report to check completion and read findings, and notes that a `processing` report carries no score yet. It does not name a competing alternative or state when-not to use it, but the workflow position 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?

Beyond the readOnlyHint/openWorldHint annotations, it discloses the critical security constraint (the PromptEye API key must never be placed in the snippet, since the public call carries no key and is browser-safe) and explains the data semantics of leadStatus, contactCount, and the one-off (non-tracking) nature of the report.

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 deliverable is front-loaded in the first sentence, but the middle paragraph is a lengthy digression on PromptEye's white-label lead-magnet business model that is not strictly needed to call the tool, making the overall definition bloated.

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-param, read-only integration helper it covers everything an agent needs: when to invoke, what it returns, how to present the answer, the meaning of the agency id, and the security caveat about the API key. The presence of an output schema makes the extra return-value prose supplementary rather than required.

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 takes zero parameters, so the baseline is 4. The description usefully characterizes the returned payload (agency id, endpoint, example body, cURL, typed request) and explains what the agency id actually is, adding meaning even though no parameters exist to document.

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

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

The opening sentence names the concrete deliverables (agency id, endpoint, example body, cURL line, typed request), which clearly distinguishes this as an integration-documentation tool from siblings like create_report or get_report. It is specific about the resource but never explicitly contrasts itself with those siblings.

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

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

It gives explicit trigger conditions: 'Call this whenever the question is how to set up, configure or integrate public reports, what the agency id is or where to find it, or what to hand a developer.' It even prescribes the response format ('hand the answer over as the example, rather than describing it'), leaving nothing 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?

Annotations already declare readOnlyHint/openWorldHint, yet the description adds the critical behavioral trait that an unconnected integration returns zeros and empty lists that read like a site nobody visits, plus the guidance to check get_integrations_status first. It also discloses that AI traffic undercounts by design and how ctr/position are scaled.

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?

Strongly front-loaded with the core purpose and the `by` mechanics before the explanatory material. It is long and the AI-traffic and 'two senses of the phrase' passages drift toward explaining neighboring tools, but most sentences carry disambiguating value.

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

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

An output schema exists, so return values need not be detailed, and the description covers the remaining gaps: parameter behavior, metric scales, the integration-not-connected failure mode, and how this metric differs from adjacent tools. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real interpretation: `by` ranks rather than totals and `limit` controls how far down the ranking you see. It does not add anything for startDate/endDate beyond what the schema states, so it falls short of the top band.

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

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

The opening states a specific verb and resource (reading clicks, impressions, CTR and average position for the active project's site) and scopes it to ordinary Google results. The description actively distinguishes this from sibling tools, naming visibility counts and AI traffic as answering different questions.

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 conditions: pass `by=query` for phrases and `by=page` for landing pages, raise `limit` to see further down, and call `get_integrations_status` before reporting a zero or empty list. It also contrasts this metric against get_ai_traffic and visibility, which is strong routing guidance.

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

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

Annotations already declare readOnlyHint and openWorldHint, yet the description adds substantial non-structured behavior: `sitemap` is null when nothing is connected (missing integration vs. empty site), `active=false` means the address dropped out but bots may still request it, and results are capped at 5 000 addresses. That is meaningful operational context beyond the annotations.

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

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

Front-loaded with the primary scope, then the comparison, then edge cases and the pagination cap; nothing is redundant. The metaphorical phrasing ('what the site says it wants read', 'published into silence') is flavor rather than waste, but it costs a bit of tightness.

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

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

With an output schema present, the description doesn't need to enumerate return values, yet it clarifies the key ones (path form, active semantics, null sitemap). Combined with annotations covering the safety profile and full schema coverage, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description nonetheless explains the semantics of the `active` filter ('dropped out of the sitemap while bots may still be asking for it') and the pagination ceiling that bounds `limit`/`cursor` usage, adding value over the schema text.

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+resource with scope: the sitemap connected to the active project, its last sync status, and the addresses it found. It also explicitly contrasts its `path` values with list_crawls, so an agent can distinguish it from that sibling without opening either 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?

Gives clear comparative context against list_crawls ('an address here with no crawl row is a page published into silence') and states the address cap ('The first 5 000 addresses can be paged to'), plus where sitemaps get connected. It lacks an explicit when-to-prefer-this-vs-alternative rule, 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 and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful lifecycle behavior beyond that: `pillar` is null and `clusters` empty until generation completes, and `errorMessage` is set on failure. It stops short of noting rate limits or how long readiness typically takes, so it is strong but not exhaustive.

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: the first front-loads what the tool returns, the second front-loads the usage trigger. Zero filler and no restatement of the title or name.

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

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

An output schema exists, yet the description still supplies the state semantics an agent actually needs (empty-until-ready, error sentinel) rather than duplicating field lists. Combined with the 100%-covered single param and read-only annotations, nothing needed to call this correctly is missing.

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

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

Schema coverage is 100% and the single parameter is fully documented in the schema itself, including provenance ('as create_topical_map or list_topical_maps reports it'). The description adds no syntax or format detail beyond that, so baseline 3 is correct.

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

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

Opens with a specific verb+resource+scope: 'One map in full: its pillar page and every cluster article, grouped by category.' This distinguishes it from list_topical_maps (which enumerates maps) and from the mutation siblings create/regenerate, so an agent can route correctly without opening 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?

Explicitly states when to call it ('after create_topical_map until status is ready') and names the alternative condition — once ready, stop polling. The sequencing dependency and the stop condition are both spelled out, leaving nothing 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?

With readOnlyHint/openWorldHint already covering the safety profile, the description adds substantial non-obvious behavior: only the newest 4 000 requests are searched so filters can return short, `verified` is User-Agent-derived and unfilterable, counts cannot be split by it, and an unconnected integration returns zeros indistinguishable from no traffic. These are exactly the traits an annotation cannot express.

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

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

Front-loaded with the purpose, then usage, then caveats and the integration-status trap — a sensible order. It is long (four dense paragraphs) but nearly every sentence carries a distinct warning; only the re-explanation of kind is arguably duplicative of 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?

An output schema exists, so return values need not be described. For a 9-parameter, open-world read tool the description covers the query scope, the paging/aggregation pitfall, the verification caveat, and the integration-not-connected ambiguity — nothing an agent needs to call or report it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3; the description still adds genuine meaning the schema lacks — the vendor vs. `assistant`-of-get_ai_traffic distinction and the 31-day start/end constraint framing ('read a month at a time, not a year'). It restates kind=ai/seo, which is redundant with the enum description, keeping it below 5.

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 and resource ('the individual requests AI assistants and search engines made to the active project's site, newest first') and immediately enumerates the fields returned. It also distinguishes itself from several siblings by name (count_bot_visits, list_prompts, list_competitors, list_sources, get_ai_traffic), so an agent can route correctly without opening a 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?

Explicit when-to-use ('call it to show what actually happened, or to see what a bot got when a page moved'), explicit when-not ('For totals call count_bot_visits instead'), and a concrete precondition ('Call get_integrations_status before reporting a zero or an empty list as a finding'). Alternatives and the failure mode of the wrong choice are both spelled out.

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. The description adds meaningful domain behavior: two-level hierarchy, parentId semantics, and source values ai/manual. It does not cover auth or rate limits, but with annotations covering safety, this is useful 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?

A single front-loaded sentence that conveys hierarchy depth, parent linkage, and source provenance without waste.

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

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

For a zero-param read-only list with an output schema, the description supplies the key domain context needed to interpret results. It omits pagination or active-project prerequisite, but those are minor given the simple contract.

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 are zero input parameters, so the baseline is 4. The description appropriately does not invent 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?

Names the resource and scope (every category of the active project, two levels deep), but does not include an explicit verb and does not differentiate from siblings like create_category or list_prompts.

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 when-to-use or when-not-to-use guidance; the agent must infer that this is the read operation for categories. No alternative tool is mentioned.

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=true, covering the safety profile. The description adds genuine domain context — that the list is scoped to the active project and that unexcluded names may include resellers, marketplaces and directories — but it discloses nothing about the returned shape or pagination.

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

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

The first sentence is well front-loaded, but the second paragraph ('Excluding a brand drops it from competitor rankings and share-of-voice calculations across historical data') describes the effect of the mutation sibling, not this read tool, which is tangential and slightly misleading placement.

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 need no explanation, and the tool has no parameters. Still, a read tool sitting next to set_competitor_exclusions should route the agent between them, and the description spends its closing line on the write-side behavior instead.

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 are zero parameters, so the baseline is 4. The description correctly signals project scoping ('the active project'), implying selection happens through select_project rather than through this tool's arguments.

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 identifies the resource precisely — the brands kept out of competitor rankings for the active project — and names the domain (competitor exclusions). It is stated as a noun phrase rather than a verb, so it leans on the title's 'List' to establish the read action, but an agent can still tell it apart from list_competitors.

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 explains what exclusions are and why they exist, which implies when to consult this list, but it never states when to call this versus set_competitor_exclusions (the obvious sibling for changing them). No explicit when-not or alternative routing is provided.

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 give readOnlyHint and openWorldHint; the description carries far more: ranking is cut to strongest-by-visibility so re-sorting is not equivalent to share-of-voice ranking, changes are sign-normalized (positive = improvement, including the lower-position-number inversion), metrics are null until measured, and ownBrand marks the project's brand in the results.

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?

Front-loaded with the core purpose, then grouped by concern (ordering, metric definitions, filters, workaround). It is long and dense, and the metric exposition (shareOfVoice vs citedAnswers vs citationShare) borders on reference documentation, but nearly every sentence prevents a concrete misinterpretation.

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 an 8-parameter, zero-required, open-world analytical tool with an output schema, this covers the ordering logic, metric semantics, filter exclusivity, and cross-tool workflow. An agent can call it correctly and interpret the result without further probing.

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 would be 3, but the description adds semantics the schema does not contain: that `limit` matters because the ranking is truncated rather than exhaustive, that `model` distinguishes a universally dominant brand from a single-assistant one, and the hard constraint that at most one of promptId/groupId/categoryId(+subcategoryId) may be supplied since combining them fails.

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

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

Opens with a precise verb+resource+scope: 'Every brand the assistants named on the active project's prompts, measured the same way the project's own brand is and ranked by visibility, then by average position.' It is unmistakably a competitor-brand ranking and cannot be confused with siblings like list_prompts or list_sources, both of which it explicitly references.

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?

States the questions it answers ('who are we losing to', how a market splits), names the narrowing filters and their exclusivity rule, and pre-empts a likely misuse case by explaining that no single call answers 'which prompts does competitor X outrank us on' — use list_prompts then call this per promptId. Explicit when, when-not, and alternatives.

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

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

Annotations cover only readOnly and openWorld; the description adds substantial non-obvious behavior beyond them: all-time coverage, ordering by last visit, the 3 000-row scan cap, empty results when integration is disconnected, and how a missing row should be read. 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?

Front-loaded with the core output shape, then caveats and routing. It is dense and somewhat long, with mild redundancy ('Coverage rather than volume' echoed later) and an expansive final paragraph, but most sentences carry distinct 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?

Output schema exists so return values need no explanation, yet the description still orients on columns and status semantics. For a 6-parameter, integration-dependent read tool, nothing an agent needs to call and interpret it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes further by clarifying that path returns all rows for that page, that vendor is not the assistant of get_ai_traffic, and that kind=ai/seo select bot families. It adds real meaning over the schema wording.

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 concrete verb+resource with the exact row grain ('one row per path and bot') and the fields returned (first/last visit, count, last status). It explicitly distinguishes itself from list_bot_visits (all-time vs. period) and from sibling measurements like list_prompts, list_sources and get_ai_traffic.

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

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

Gives explicit when/when-not: call get_integrations_status before reporting zeros/empties as a finding, and interpret sub-2xx lastStatusCode as worse than silence. Also states the 3 000-row search limit and the path exception, which tells the agent when this tool is trustworthy.

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 safety profile is covered. The description adds meaningful non-annotation context: this is product documentation rather than the user's data, an index URL is available, and every article has a user-facing link that should be shared in the answer.

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 instruction is front-loaded (what the tool is, then when to call it, then the workflow and caveats), and every clause carries routing information. It is on the long side, but the length is driven by genuinely useful examples 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?

An output schema exists, so return values need no explanation, and the description still covers the parts the schema cannot: source location, ordering versus read_help_article, scope boundaries against sibling data tools, and what to do with the result.

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 takes no parameters at all, so there is nothing for the schema or description to disambiguate; baseline for a parameterless tool is 4.

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?

Specific verb+resource: lists PromptEye's own help articles, with the exact source URLs given. It is clearly distinguished from the sibling read_help_article, which it names as the follow-up step.

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

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

Explicit when-to-use ('Call this FIRST whenever the user asks how something in PromptEye works...'), concrete trigger examples (missing emails, unscored reports), and an explicit exclusion ('for their visibility, prompts or competitors use the other tools'). The instruction not to answer from memory and the read-then-answer workflow leave nothing 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?

Adds ordering, per-project access level, root-entity context, and identity pitfalls ('do not call them duplicates based only on similar brand names') beyond readOnly/openWorld annotations. Also gives sequencing and disambiguation behavior. Annotations align; 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?

Front-loads scope and ordering, then usage sequence and disambiguation. It is somewhat long and repeats select_project, but most sentences carry actionable guidance, so minor trim possible.

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?

Output schema exists, so return fields need not be explained; annotations cover safety. Description supplies sequencing, scoping, and identity context needed to call and interpret this list tool correctly. Complete.

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

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

Schema coverage is 100% and the single optional workspaceId is fully documented there. The description does not add syntax or format details for workspaceId, so it meets the baseline 3 for high-coverage schemas.

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+resource (list projects), scope (every project the API key reaches), ordering (newest first), and access metadata. It defines a project and positions it as root, distinguishing it from select_project and downstream tools. An agent can identify it without opening 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?

Explicitly says 'Call this first, then select_project, before asking about visibility, competitors, prompts or sources,' giving both sequence and alternatives. Adds disambiguation instructions for similar brand names and when to ask the user. No when-not needed.

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

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

Beyond the thin readOnlyHint/openWorldHint annotations, the description supplies genuinely non-obvious semantics: change values are signed so positive always means improvement, positive average-position change means the brand was named earlier (lower number), and aiTrafficTotal is null when no measured prompt exists while paused prompts contribute nothing. These are behavioral facts an agent cannot derive from 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?

Purpose and routing are front-loaded, but the definition is long and mixes three concerns — routing, output-field semantics, and sign conventions — in one block. Since an output schema already exists, the extended explanation of aiTrafficTotal and change signs arguably exceeds what this field needs to do, making it denser than necessary.

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 annotations covering the safety profile, the description only needs to add routing and interpretation, which it does. It is nearly complete; the only soft spot is that parameter-level behavior (pagination, date span limits) is left entirely to the schema.

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

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

Schema description coverage is 100%, so the schema already documents limit, cursor, startDate and endDate. The description's 'over the period' phrasing loosely ties to the date parameters but adds no format, default, or pagination guidance beyond the schema, so the baseline of 3 applies.

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

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

The description clearly establishes the resource (the active project's prompt groups) and gives concrete examples of what a group is (comparison queries, problem queries, brand queries) plus the visibility-over-period payload. It never uses a plain 'List...' verb, but the intent is unambiguous and it is distinguishable from list_prompts by framing groups as 'the unit a strategy is judged by'.

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 routes the agent: use a group id to narrow list_prompts, use upsert_prompt_group to rename/describe/reorder, and delete_prompt_group to remove an empty one. It also explains the edge case that ungrouped prompts have no row here. No explicit 'when not to use this tool' statement, but the surrounding workflow is well covered.

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