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

The description goes well beyond the annotations. It discloses that hand-written prompts skip demand/duplicate/fit checks, can duplicate existing prompts, carry no demand/priority/purchase intent/fit until PromptEye computes them, may sit at 0% visibility, and count against the workspace plan. It also explains group-by-name behavior (created vs reused). This is rich behavioral context that annotations alone do not provide.

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

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

The description is longer than average, but every section earns its place: the warning is front-loaded, the alternative is named early, the consequences are concrete, and the usage conditions are explicit. It is structured with clear paragraphs and bolded emphasis. Slightly verbose in the middle section, but not 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?

For a mutation tool with no output schema, the description is complete: it explains the operation, the caveats, the group behavior, the plan impact, and the exact conditions for use. An agent has everything needed to decide whether to call it and what to expect. The absence of an output schema is compensated by the detailed behavioral disclosure.

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 both parameters thoroughly. The description adds value by explaining the consequences of the confirmBypassPromptIntelligence flag (acknowledgement of skipping checks) and the groupName behavior (created/reused, no separate step). It reinforces the schema's meaning without repeating it verbatim, though the schema already carries most of the semantic weight.

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

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

The description states a specific verb and resource ('Tracks prompts written by hand in the active project, in one call') and immediately distinguishes it from the recommended alternative, list_prompt_suggestions. It clearly identifies what the tool does and what it is not, making sibling differentiation 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?

The description gives explicit when-to-use guidance: only when the user has prompts of their own that must be tracked verbatim (e.g., migrating from another tool or a client insists), and says to ask the user when unsure. It also names the alternative (list_prompt_suggestions) and the condition for using it instead, providing clear exclusions.

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

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

The description discloses key behavioral traits beyond the annotations: it is read-only (consistent with readOnlyHint=true), it returns ranked results not paged (with no cursor), it has a 'partial' flag indicating truncated counts, and it warns about User-Agent spoofing (bot IDs are free text, counts are upper bounds). It also explains the semantics of status codes and the difference between kind=ai and kind=seo. This goes far beyond the annotations and is essential for correct usage.

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 long but every sentence carries weight. It opens with the core purpose, then systematically covers groupBy semantics, pagination behavior, spoofing caveats, and differentiation from related tools. It uses paragraphs and bullet-like formatting for readability. No redundant phrases; each sentence either informs or directs the 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?

Given the tool's complexity (9 parameters, 5 groupBy modes, status patterns, multiple related tools), the description is remarkably complete. It explains return structure (ranked, partial flag), the meaning of counts (upper bounds due to spoofing), and the practical significance of failures. Since there is no output schema, this description fully compensates by explaining what the agent should expect and how to interpret results.

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?

Although the schema already covers all parameters (100% coverage), the description adds substantial meaning: it elaborates on the groupBy enum values ('bot', 'path', 'status', 'day', 'category') with concrete interpretations, explains the 31-day date window, clarifies that vendor is not the same as get_ai_traffic's assistant, and provides examples of botId values. It also warns about the spoofing issue affecting count accuracy. This is far beyond the schema's per-parameter descriptions.

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

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

The description opens with a precise statement: 'The same requests as list_bot_visits, counted by the API rather than listed.' This clearly identifies the verb (count), the resource (bot visits), and differentiates it from its listing sibling. It also explains the groupBy options and their meanings, leaving no ambiguity about what the tool does.

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 contrasts with list_bot_visits ('counted by the API rather than listed') and names alternative tools (list_prompts, list_competitors, list_sources, get_ai_traffic) to clarify when not to use this tool. It also provides a concrete recommendation: 'botId=chatgpt-user with groupBy=path is the sharpest reading here.' This is actionable guidance an agent can follow.

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 indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description adds significant behavioral context: creating a project counts against the workspace plan, implies a state change (becoming the active project), and warns that duplicate creation is refused. It also explains the effects on subsequent tools (they report on the active project).

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 moderately detailed but includes a lengthy aside about PromptEye's prompt generation, which is tangential to creating a project. While this provides context, it dilutes the main purpose. The key points are front-loaded, but the middle section could be trimmed for conciseness.

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

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

Given the tool's complexity (8 parameters, 3 required), the description covers the essential context: what a project is, the one-brand-one-market rule, the active project implication, and mention of prompt suggestions. Since there is no output schema, the description doesn't need to explain return values, but it does hint at the project becoming active.

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

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

Schema description coverage is 100%, so the schema already documents all 8 parameters. The description adds a little beyond schema, such as emphasizing the 'brand' parameter's matching to how assistants write answers and the 'excludedCompetitors' rationale. However, the added value is modest since the schema already covers parameter meaning well.

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

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

The description clearly identifies the tool's purpose: 'Starts tracking one brand in one market' and explains how a project is the foundational unit. It distinguishes itself from related tools by emphasizing the project creation aspect and references creating 'a second project for a brand and market already tracked is refused,' which differentiates it from list_projects and select_project.

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

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

The description provides clear guidance on when to use the tool: create a project before tracking prompts and competitors, and check list_projects first to avoid duplicates. It also implies when not to use it (when project already exists) but does not explicitly compare with alternatives like add_prompts or list_prompt_suggestions.

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 boolean annotations, the description discloses the public no-API-key endpoint, account quota spending, attribution to the configured account, the async 'processing with no score' result, and the cached resent behavior for repeats. None of this contradicts the annotations; it substantially enriches them.

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

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

The first sentence front-loads the action, and the later paragraphs are logically organized into product context, operational/auth behavior, and caching/async behavior. Some background sentences about white-labeling and the sales pipeline are useful but could be tightened without losing essential call 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 no output schema, the description supplies the critical return behavior: a new report returns as processing with no score, results land minutes later, and get_report should be used to read them. It also covers auth, quota, and repeated-call semantics, making the tool safe to invoke correctly with the two required parameters.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters. The description mainly restates or contextualizes them (e.g. website matching for cache, email as prospect address) rather than adding new parameter-level meaning beyond a baseline.

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

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

The description opens with a concrete verb and object: it generates a public visibility report and emails it to a given address. It also names what the report contains and explicitly contrasts itself with get_report_integration, so an agent can tell it apart from siblings without opening schemas.

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 routing instructions: use get_report_integration to wire the form, and read finished results with get_report rather than expecting scores immediately. It also clarifies that this is a one-off lead-magnet sample and not a tracking tool, and describes the 30-day cache/resend behavior on repeat calls.

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

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

Annotations declare readOnlyHint and openWorldHint, which are useful. The description goes beyond annotations by clarifying the subtle timing semantics of nextScanAt: it indicates when the run starts, not when data is complete, and warns that figures arrive gradually. This is valuable behavioral context that prevents misinterpretation. Not a 5 because it doesn't mention any rate limits or response format, but it's strong.

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

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

The description is two paragraphs: the first is an efficient summary of what is returned and when to use it, front-loading the purpose. The second paragraph clarifies a critical nuance about timing. No wasted words, and each sentence adds value. It's appropriately sized for the complexity of the timing caveat.

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

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

For a zero-parameter tool with annotations covering safety and open-world assumptions, the description is complete. It explains the key caveat about nextScanAt, which is the main potential source of confusion. The absence of an output schema is compensated by the description listing the key fields (plan, prompt count, assistants, next run start). Nothing critical is missing.

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

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

The tool has zero parameters, so there is nothing for the description to explain. The baseline for 0 parameters is 4, and the description doesn't add any parameter-specific information beyond that. Since there are no parameters, this is appropriate.

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

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

The description clearly states what the tool does: it returns information about the configured PromptEye API key, including plan, prompt counts, assistants, and next run time. It uses specific verbs ('diagnose a key', 'check whether a plan covers a feature') and distinguishes it from siblings by focusing on account-level configuration, not operational data like traffic or reports.

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

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

Explicitly states when to use this tool: 'Call this to diagnose a key, to check whether a plan covers a feature before promising it, or to answer when fresh figures will arrive.' It prescribes three concrete scenarios, effectively distinguishing from siblings that might query specific resources. It doesn't explicitly name alternative tools, but the scenarios are specific enough to guide the agent.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds context beyond annotations by defining the active project as the one every other tool reports on, clarifying what the returned value represents without contradicting the annotations.

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

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

Two sentences each carry distinct value: the first defines the resource, the second gives the exact call condition. No filler, front-loaded with the core 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?

For a read-only, zero-parameter tool without an output schema, the description covers the essential context: what the active project is and when to use this call. It does not spell out the response shape, but the name and title imply the project object is returned, and the annotations handle the safety profile.

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

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

The tool has zero parameters and an empty schema, so there is no parameter burden for the description. Per the rubric, zero parameters warrants a baseline of 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?

The description makes clear that this tool retrieves the project that all other tools are currently reporting on, which is specific and contextually distinct from siblings like list_projects and select_project. The verb is only implicit in the tool name and title, but the resource and scope are unambiguous.

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

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

The description explicitly instructs when to call it: 'Call this when unsure which project the numbers in this conversation refer to.' This is a direct, actionable usage guideline that distinguishes it from alternatives by function.

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 description doesn't need to repeat those. However, it adds valuable behavioral context beyond annotations: it explains the undercounting by design (assistants without links, direct traffic), the distinction between visibility and sessions, and the zeros-with-no-binding behavior. It could mention pagination or return format, but the read-only and open-world safety is already covered, so a 4 is justified.

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

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

The description is well-structured with clear paragraphs, front-loading the primary purpose and key parameters. It is slightly verbose in the alternative guidance section (Search Console details), but every sentence earns its place by clarifying important distinctions. It could be trimmed slightly without losing value, hence a 4 rather than 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?

Given the tool's complexity (5 optional params, no output schema), the description fully compensates: it reveals the semantic difference from aiTraffic, explains zero-return cases and the prerequisite check, and even covers date range behavior implicitly through schema. It is complete for an agent to call it correctly, with no critical missing information.

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?

Despite 100% schema coverage, the description adds substantial value: it explains the purpose of 'by' (rank vs total), that 'assistant' narrows any of the three, and gives key examples of matching (openai matches chatgpt). The schema does not explain the practical effects of `by` on the response shape or provide these aliases, so the description goes far beyond what the schema alone provides.

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

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

The description states a specific verb ('read'), a resource ('visits from AI assistants'), and the exact metrics (count, engagement, key events), and clearly differentiates it from Google Search Console and other analytics. It even clarifies the two senses of 'aiTraffic' vs this tool, leaving no ambiguity for the agent.

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 explains when to use it ('this is the tool for 'is any of this visibility turning into visits'') and contrasts with Google Search Console and other tools. It also instructs to call get_google_status before reporting a zero as a finding, providing clear context and exclusions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds valuable behavioral context: a project with nothing bound answers with zeros and empty lists, which reads exactly like a site nobody visits. This is a non-obvious behavioral trait that helps the agent interpret results correctly. It doesn't describe the exact return format, but with no output schema and zero parameters, the description carries the burden well.

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

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

The description is two sentences, front-loaded with the core purpose, and every sentence earns its place. The first sentence states what it does; the second explains when to use it and the critical interpretation pitfall. No wasted words.

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

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

For a zero-parameter, read-only tool with no output schema, the description is complete. It explains what the tool checks, when to call it, and how to interpret the zero/empty-list case. The agent has everything it needs to invoke and interpret the tool correctly.

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

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

The tool has zero parameters, so the schema provides no parameter semantics. The description compensates by explaining what the tool reports (binding status and last sync for two integrations). A baseline of 4 is appropriate for a zero-parameter tool where the description clarifies the tool's output semantics.

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

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

The description clearly states the tool's purpose: checking whether Search Console and Google Analytics are bound to the active project and how their last sync went. It uses specific verbs and resources, and it distinguishes itself from siblings like get_search_performance and get_ai_traffic by focusing on integration binding status rather than metrics.

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

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

The description gives explicit when-to-use guidance: call this when a Google figure looks wrong or empty, or before promising a report built on one. It also explains the critical pitfall of confusing an unbound integration with a site that has no traffic, and instructs the agent to call this before reporting a zero as a finding. This is strong usage guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds behavioral context by explaining that this is a foundational read used before evaluating other content, which goes beyond the annotations. It does not contradict them and provides useful context about the tool's role.

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

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

The description is two sentences with no waste. The first sentence states the core purpose and content, and the second explains why it matters. The most important information is front-loaded, and every clause earns its place.

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

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

Given no parameters, no output schema, and annotations covering safety, the description is complete. It explains what the tool returns (brand description) and its significance in the workflow, so an agent can confidently decide when and how to use 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 has zero parameters, so the schema already covers 100% of semantics vacuously. Per the rubric, a baseline of 4 is appropriate for 0-parameter tools, and the description does not need to explain parameter details. It adds no redundant information.

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

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

The description clearly states the tool retrieves the brand description that the project measures against, specifying what it contains ('what the company sells and to whom'). This is a specific verb+resource with a clear scope, and it is distinct from sibling tools like get_account or get_active_project, which target different entities.

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

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

The description implies usage context by stating that everything PromptEye writes reads this first, and suggests consulting it before trusting prompts or competitors. However, it does not explicitly contrast with alternatives or state when not to use it, though the read-only, parameterless nature makes such guidance less critical.

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 readOnly/openWorld annotations, the description richly explains response semantics: signed changes, null-until-measured metrics, aiTraffic being a prompt property rather than a session count, and businessPriority's hand-set override. These are behavioral details an agent could not infer from the schema or annotations.

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

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

The description is longer than average but each paragraph addresses a distinct concern: purpose, sign conventions, metric definitions, and priority semantics. It is front-loaded with the primary use case, though some of the metric explanations could be tightened without losing 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?

With no output schema, the description carries the burden of documenting return metrics, and it does so thoroughly: visibility, reachIndex, averagePosition, aiTraffic, and businessPriority are all explained with null behavior and edge cases. The tool is adequately specified for an agent to invoke and interpret correctly.

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

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

Schema description coverage is 100%, and the schema already documents promptId, startDate, and endDate with patterns, defaults, and constraints. The description adds no parameter-level details beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool reads one prompt of the active project and lists visibility per assistant, which distinguishes it from sibling list tools. It also explicitly contrasts its aiTraffic meaning with get_ai_traffic, reinforcing the tool's specific scope.

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

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

The description gives a concrete call-to-action ('Call this to see which assistant is carrying a prompt...') and explicitly excludes get_ai_traffic as a different measurement. It does not exhaustively contrast with list_prompts or update_prompt, but the intended use case 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 already indicate readOnlyHint=true and openWorldHint=true, so the read-only nature is covered. The description adds valuable behavioral context: it reveals that a report can be in a 'processing' state and that no score is available until it finishes, which the agent wouldn't know from annotations alone. This goes beyond the schema and annotations.

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

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

The description is concise and front-loaded with the report contents in the first sentence, then provides usage guidance in the second paragraph. It avoids unnecessary details and is easy to scan. The only minor inefficiency is the long list in the first sentence, but it's still readable and purposeful.

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

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

For a single-parameter read tool with no output schema, the description covers what the report contains, how to invoke it after creation, and the processing state caveat. It doesn't mention error handling or rate limits, but these are not critical for this simple read operation. The information provided is sufficient for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, so the reportId parameter is already well-documented as the ID from create_report or list_reports. The description does not add extra parameter meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool reads one full public report and enumerates its contents (score, industry, demand, prompts, competitors, answers, sources, contact requests). It distinguishes itself from siblings like list_reports (which lists) and create_report (which creates) by focusing on the full detail retrieval.

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

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

The description explicitly tells the agent to call this after create_report to check if the report finished and to read its findings. It also warns that a report still processing carries no score, which is practical guidance. While it doesn't explicitly mention alternatives like list_reports for summaries, the context makes the appropriate usage clear.

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

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

Annotations already include readOnlyHint=true and openWorldHint=true, so the read-only nature is covered. The description adds rich behavioral context: explains the public report as a lead magnet, one-off sample, non-tracking nature, and why the snippet is browser-safe (no API key). This goes beyond the annotations and is highly useful for the agent to understand the tool's role.

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 longer than typical but every sentence adds value: it starts with what the tool returns, then explains the business context, then usage guidance. It is front-loaded with the core purpose. While it could be tightened slightly, it is not bloated and the structure aids comprehension.

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

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

For a tool with no parameters and no output schema, the description is fully complete. It explains what the output contains (integration example), the context of public reports, when to call, and security implications. Nothing an agent needs to correctly invoke or interpret the 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?

The tool has zero parameters and schema coverage is 100%, so there is nothing for the description to clarify about parameters. The baseline for 0 params is 4, and the description doesn't need to add parameter details. It does explain the output (integration example), which is relevant but not parameter-specific.

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

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

The description clearly states the tool provides integration details for posting forms to public reports, including agency id, endpoint, example body, cURL, and request. It explicitly differentiates from siblings by stating 'Call this whenever the question is how to set up, configure or integrate public reports' – distinct from get_report or create_report.

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

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

Provides explicit when-to-use guidance: '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 also tells the agent to hand over the answer as an example rather than describing it. Clear and actionable.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds meaningful behavioral context beyond that: unbound integrations return zeros and empty lists indistinguishable from a site nobody visits, CTR is a 0-1 rate, position counts from 1 (lower is better), and AI traffic undercounts by design. It also discloses the daily timeline behind the totals. The only minor gap is not describing the exact response shape, but with no output schema and rich behavioral caveats, the description carries its burden well.

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 long but every sentence earns its place: the first sentence states the core function, the second explains the ranking mode, and the remaining sentences carry critical caveats about interpretation and integration state. It is front-loaded with the essential purpose and uses paragraph breaks to separate concerns. It could be tightened slightly, but the density of useful guidance justifies the length.

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

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

For a read-only analytics tool with 4 optional parameters, 100% schema coverage, and no output schema, the description covers everything an agent needs: what the numbers mean, how to interpret them, when to distrust them, how to disambiguate from siblings, and what to do before reporting a zero. The integration-bound caveat is exactly the kind of contextual trap that would otherwise cause false findings.

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 adds real value beyond the schema: it explains that `by` changes the aggregation from totals to a ranking, that `limit` is ignored without `by`, and that a ranking answers with the strongest entries rather than a walkable list. It also clarifies the date-range semantics indirectly by noting the daily timeline. This exceeds the baseline but doesn't fully document every parameter interaction (e.g., endDate/startDate defaults are already 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?

The description opens with a precise verb-resource pair: it reports clicks, impressions, CTR, and average position for the active project's site in ordinary Google results, with a daily timeline. It also distinguishes itself from get_ai_traffic by contrasting visibility (brand named) vs arrivals, and from get_google_status by noting the bound-integration prerequisite. This is a specific, differentiated purpose statement.

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

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

The description explicitly says when to use the `by` parameter (to rank instead of total), when to raise `limit`, and when NOT to report a zero: call get_google_status first to determine whether the integration is bound. It also warns that a rise here means people acting on answers, not brand mentions, and clarifies the two senses of aiTraffic versus get_ai_traffic. This is exemplary routing and exclusion guidance.

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

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

With readOnlyHint and openWorldHint already present, the description adds useful non-obvious behavior: sitemap can be null, active can be false for addresses that dropped out, and only the first 5,000 addresses are pageable. These details go beyond the annotations and help set expectations.

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

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

The description is four purposeful sentences/fragments, front-loaded with the main purpose and then adding distinct facts: comparison to list_crawls, null semantics, and paging. It is slightly dense, but every clause earns its place.

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

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

There is no output schema, so the description helps by covering the key returned concepts: path, active, null sitemap, and paging. It does not fully enumerate the sync-status fields or error cases, but an agent has enough to invoke the tool and interpret the important results.

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

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

The input schema already documents all three parameters with 100% coverage, so baseline is 3. The description adds interpretive value by explaining what active=false means in context, how path relates to list_crawls output, and the 5,000-address paging boundary.

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 title and description name a specific verb + resource: list the addresses in the connected sitemap. The description also clarifies the scope (active project) and the value proposition (what the site says it wants read), distinguishing it from crawl-focused siblings like list_crawls.

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

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

The description gives clear context for when this tool is relevant: inspecting the connected sitemap, comparing it to list_crawls output, and diagnosing a missing integration. It explicitly relates the data to list_crawls so an agent can choose between sitemap and crawl data, though it does not state a hard when-not to use it.

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

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

Annotations declare readOnlyHint=true and openWorldHint=true, and the description is fully consistent with them. It adds genuine behavioral context beyond the annotations: what it reads (account, project, brand description, prompts, pending suggestions, public reports), that it derives the next step from what is missing, and that it reports what must be done in the PromptEye app rather than here.

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 dense paragraph with the trigger conditions front-loaded. Each sentence earns its place: triggers, timing, what it reads, the output logic, and the app-vs-server caveat. Slightly long but all substantive.

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?

A complex tool that aggregates many resources with no output schema, but the description covers what it reads, how it decides the next step, and the app-vs-server distinction. Annotations cover the safety/open-world profile. Nothing an agent needs 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% — the sole optional projectId parameter is documented ('Report on this project instead of the active one, and make it active'). The description adds nothing about parameters, but with full schema coverage the baseline 3 is appropriate.

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

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

States a specific verb+resource ('call this when the user asks what they can do... where to begin, where they stand, or what to do next') and differentiates itself from the many list/read siblings by framing itself as a state-reader that produces a next step rather than a data dump.

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-to-use conditions (user asks about capabilities, where to begin, where they stand, next steps) and an explicit timing rule (at the start of a session before guessing). It also tells the agent this is preferable to enumerating all server capabilities, providing clear guidance on when NOT to fall back on generic listing.

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

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

Annotations already declare readOnlyHint and openWorldHint, and the description adds substantial behavioral detail beyond them: the 4,000-newest-request search window, under-reporting with rare filters, the unverifiable User-Agent problem, and the directive to present counts as upper bounds. There is no contradiction with the annotations.

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

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

The description is front-loaded with a one-sentence definition, then moves through use case, alternatives, conceptual framing, and caveats in a logical order. It is long, but every sentence earns its place given 9 parameters and several sibling tools to disambiguate.

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

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

Even without an output schema, the description tells the agent what a result contains ('which bot, which path, what the site answered and how long it took'), how results are ordered, and what limits and caveats apply. Combined with the schema's detailed parameter descriptions, the agent has everything needed to call and interpret this tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents every parameter; the baseline is 3. The description adds meaning beyond the schema by explaining that summing pages yields a wrong total due to the 4,000-request cap and that counts cannot be split by verified status, plus it clarifies kind/vendor in the context of sibling tools.

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 exact resource ('individual requests AI assistants and search engines made to the active project's site'), specifies ordering ('newest first'), and lists what each record contains (bot, path, site answer, duration). It also clearly distinguishes this tool from siblings like count_bot_visits, list_prompts, list_sources, list_competitors, 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?

The description explicitly says when to call it ('this is the evidence layer') and when not to: 'For totals call count_bot_visits instead — paging through this to add requests up gives a wrong number.' It also names the neighboring measurement concepts it is not, with sibling tool names, leaving no ambiguity about selection.

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

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

The description claims to list 'every category', which implies exhaustiveness. However, the annotation openWorldHint=true indicates that the result set may be incomplete and should not be assumed exhaustive. This is a direct contradiction between the description and the annotation, warranting a score of 1.

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

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

The description is a single, front-loaded sentence that immediately states the scope ('Every category of the active project') and then adds the key details of depth and origin. No fluff or repetition; every word contributes.

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

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

For a parameterless list tool with no output schema, the description provides a high-level understanding of the return structure (two levels, subcategories, origin). It does not specify output format, but that is not required given the lack of an output schema. The description is sufficient for an agent to know what to expect when 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?

The tool has zero parameters and the schema description coverage is 100% (vacuously). Since there are no parameters to explain, the description does not need to compensate. The baseline for zero parameters is 4, and the description adds no extra parameter-related information, which is acceptable.

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

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

The description clearly states the verb 'list', the resource 'categories of the active project', and specifies the depth (two levels) and the inclusion of origin (proposed vs hand-written). This distinguishes it from sibling tools like list_projects or list_prompt_groups, which target different resources.

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

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

The description provides clear context by scoping to the active project, implying the tool is used when category structure is needed. It does not explicitly mention alternatives or exclusions, but the resource name makes the use case obvious against the sibling list.

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 read-only nature is covered. The description adds valuable context beyond annotations: exclusions apply to the active project and affect competitor rankings and share-of-voice calculations across historical data. It does not fully describe return format, but this is minor for a zero-parameter list tool.

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

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

The description is compact and front-loaded: the first sentence states exactly what the tool returns, and the following sentences explain why exclusions exist and the effect of excluding a brand. Every sentence earns its place without redundancy.

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

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

For a zero-parameter, read-only list tool, the description provides enough context to call it correctly: it returns excluded brands for the active project and explains the domain semantics. It does not describe output formatting, but the absence of an output schema is less critical here given the simplicity of the operation.

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

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

The input schema has zero parameters and 100% schema description coverage, so the parameter baseline is 4. The description reinforces this by confirming the tool operates on the active project context rather than requiring explicit arguments, which is the only parameter-related meaning an agent needs.

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 exact resource ('brands excluded from competitor rankings') and the action ('list') for the active project. It also distinguishes this from a general competitor list by explaining that excluded brands are the ones kept out of rankings, which separates it from siblings like 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?

The description gives clear context: assistants name many candidate competitors, and this tool lists the ones deliberately excluded from rankings. It implicitly tells an agent when to call it and contrasts with the write counterpart set_competitor_exclusions, though it does not explicitly name alternatives or state 'use this when...'.

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 the burden of behavioral disclosure, and it delivers thoroughly: sign conventions ('positive always means improvement... a positive change goes with a lower position number'), null-until-measured behavior, the ownBrand marker, and detailed metric semantics distinguishing shareOfVoice, visibility, and citations. This is far more than the annotations alone provide, and nothing contradicts the read-only/open-world hints.

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

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

The description is long, but it front-loads the purpose and use case in the opening sentences, then organizes the rest into metric semantics, sign conventions, and parameter guidance — every sentence carries decision-relevant content. It hovers near the upper bound of acceptable length and the metric explanations could be tightened slightly, but there is no filler.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does: it names the fields (shareOfVoice, visibility, reachIndex, averagePosition, citations, citationShare, ownBrand), their units and null states, and the ranking semantics. For a 4-parameter tool with no required parameters, an agent has everything needed to invoke it and interpret the result correctly.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds genuine lift: `limit` is explained as necessary because 'the ranking answers with the strongest brands rather than a list to walk to the end of,' and `model` is tied to a diagnostic goal (dominance everywhere vs a single assistant). Date parameters are left to the schema, which is acceptable since they are already fully documented.

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 statement — 'Every brand the assistants named on the active project's prompts, measured the same way the project's own brand is and ranked by share of voice' — and names concrete use cases ('who are we losing to', how a market splits between brands). The object (measured competitor brands) clearly distinguishes it from the sibling list_competitor_exclusions, which manages exclusion lists rather than market measurement.

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 frames when to call it: 'Call this for "who are we losing to" and for how a market splits between brands.' It also gives parameter-level usage advice — raise `limit` to see further down the ranking, use `model` to tell a brand that dominates everywhere from one that owns a single assistant. It stops short of naming an explicit alternative tool or a when-not-to condition, so it earns a 4 rather than 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?

Beyond the readOnlyHint and openWorldHint annotations, the description discloses key behaviors: pages never fetched are absent, the 3,000-row search limit unless a single path is specified, and the interpretation of lastStatusCode outside 2xx as worse than silence. It also clarifies that bot visits are machine fetches, not human reads. This adds substantial context beyond annotations.

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

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

The description is long but every sentence serves a purpose. It is front-loaded with the core output definition, then systematically covers exclusions, limits, and comparisons. The structure is logical and dense without redundancy, making it appropriately sized for the tool's complexity.

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

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

Given 6 parameters, no output schema, and many sibling tools, the description is remarkably complete. It describes the row format, pagination via cursor and limit, the 3,000-row restriction, and the conceptual distinction from related tools. Nothing an agent needs to correctly call and interpret the 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?

Although schema description coverage is 100%, the description enriches parameter understanding: it clarifies that `kind` distinguishes AI vs SEO bots, that `vendor` is not the same as `assistant` in get_ai_traffic, and that `path` must match get_sitemap's format. It also explains how `path` affects the search scope, adding semantic meaning not 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?

The description states precisely what the tool does: it returns one row per path and bot with first/last request timestamps, count, and last status. It also explicitly distinguishes itself from list_bot_visits by coverage scope, making its purpose unambiguous and clearly differentiated 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?

The description gives clear when-to-use and when-not-to-use guidance. It contrasts with list_bot_visits (period vs all-time), and explains how it differs from list_prompts, list_competitors, list_sources, and get_ai_traffic, providing explicit alternatives and the conceptual role of the tool.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds useful behavioral context beyond annotations: this tool is documentation access, not user data access, every article has a human-facing page, and the agent should provide that link in its 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 description is front-loaded with the key purpose and contains dense, relevant guidance. It is longer than necessary but every part earns its place by supporting routing decisions and downstream behavior.

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 having no output schema, the description gives enough context for correct invocation: what the tool lists, where the index is, how to choose an article, what to do next, and what to return to the user. No critical operational gap remains.

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

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

The tool has zero parameters, so the baseline is 4. The description does not need to explain parameters, and it appropriately focuses on selection and usage rather than input semantics.

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

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

The description states a specific verb and resource: list PromptEye's help articles. It also distinguishes itself from read_help_article by instructing the agent to list first, pick an article, then read it with the sibling 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?

Provides explicit when-to-use guidance: call this FIRST for product how-to questions, settings, features, configuration, or unexpected behavior. It also gives an exclusion: for user visibility, prompts, or competitors, use other tools, and it names the next step (read_help_article).

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

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

The description adds meaningful behavioral detail beyond the readOnlyHint and openWorldHint annotations: the result is scoped to the API key, ordered newest first, includes per-project access information, and lists the fields returned. The warning that similarly named projects with different labels are distinct is especially valuable for avoiding incorrect duplicate detection.

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

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

The description is dense but every sentence earns its place: scope, ordering, project definition, workflow placement, row contents, duplicate caveat, and disambiguation advice. It is front-loaded with the core behavior and then builds practical usage context without redundancy.

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

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

Given that there is no output schema, the description adequately covers the return shape and semantics: rows contain label, brand/name, domain, access, and project id. It also explains ordering, scope, and how to proceed to select_project, making the tool self-sufficient for correct invocation.

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

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

The tool has zero parameters and the schema description coverage is 100%, so the baseline is 4. The description correctly avoids inventing parameter details and the only contextual reference, the API key, is an authentication scope rather than a call parameter.

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

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

The description clearly states what list_projects does: it returns every project accessible to the API key, sorted newest first, and explains what a project is. It also distinguishes itself from select_project by establishing that listing comes first and selection follows.

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

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

The description gives explicit workflow guidance: 'Call this first, then select_project, before asking about visibility, competitors, prompts or sources.' It explains how to disambiguate projects and which identifier to use for selection. However, it does not explicitly cover when to prefer related alternatives like get_active_project or create_project, so it stops short of full exclusion guidance.

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

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

Annotations only provide readOnlyHint and openWorldHint. The description adds important behavioral semantics: groups are the strategy unit, ungrouped prompts are excluded, change signs are normalized so positive always means improvement, average-position improvement is inverted, and aiTrafficTotal excludes paused prompts. No contradiction with annotations.

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

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

Three focused paragraphs, front-loaded with the grouping definition and sibling distinction before metric clarifications. Every sentence adds necessary interpretive information with no filler.

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

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

Since there is no output schema, the description explains return semantics such as signed changes and aiTrafficTotal. However, it introduces 'visibility' without defining it and does not enumerate the expected response fields, leaving some ambiguity about row contents.

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

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

Schema description coverage is 100%, with defaults, bounds, formats, and pagination semantics already documented. The description does not add parameter-specific detail, but the baseline of 3 is appropriate when the schema carries the full 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: list prompt groups of the active project, with examples of group types. It also differentiates from list_prompts by noting ungrouped prompts have no row here and that a group id narrows 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?

Explicitly names the alternative tool and the relationship: use a group id to narrow list_prompts, and ungrouped prompts appear only in list_prompts with groupId null. This gives clear when-to-use and when-not-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?

Beyond the readOnly/openWorld annotations, it explains sign conventions (positive means improvement), null behavior until measured, that aiTraffic is a prompt property rather than a period measurement, and that hand-set businessPriority overrides the computed value. It also states that paused prompts are included and that the two priority values are not reported separately. No statement contradicts the annotations.

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

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

The description is front-loaded with the tool's purpose and organized into paragraphs by metric/behavior, making it scannable. It is long, but there is no output schema to carry the metric definitions, so the length is largely justified. A few turns of phrase ('questions the active project puts to the assistants') are more ornate than necessary, which keeps it from 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?

With no output schema, the description fully specifies the returned metrics (visibility, reachIndex, averagePosition, aiTraffic, businessPriority), their ranges, banding, null states, and sorting. It also covers edge behavior such as hand-set priority overriding computed values. Pagination and filters are already covered by the schema's parameter descriptions, so nothing needed for correct use 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 schema already documents limit, cursor, dates, groupId, and categoryId. The description adds no parameter-specific guidance; its field explanations concern return metrics, not inputs. Baseline 3 applies because the schema carries the parameter 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?

The description identifies the resource (the active project's prompts), the subject (the questions put to assistants), and the included metrics (visibility, period-over-period movement), so an agent can tell what the tool returns. It also contrasts itself with get_ai_traffic, preventing a likely mix-up. The title supplies the explicit 'list' verb, and the body adds scope and output specifics.

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 says this is 'where to look' for which questions carry the brand, giving a concrete use case. It also draws an explicit line against get_ai_traffic: that tool counts sessions that reached the site, while this one reports demand behind the question. Paused prompts and newest-first ordering add further selection context.

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

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

The annotations already indicate readOnlyHint=true and openWorldHint=true, so the description correctly aligns with these (no contradiction). It additionally clarifies that this tool only reads suggestions and that accepting suggestions is done in the app, preventing misuse. It also explains that aiTraffic is a property of the prompt, not a period measurement, which adds semantic clarity beyond annotations. A slight deduction because it doesn't exhaustively detail all behavioral edge cases, but it adds significant value.

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

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

The description is longer than typical but each paragraph earns its place by explaining key concepts (aiTraffic, relativeVolumeScore, purchaseIntentLevel, companyFitScore) that an agent would need to interpret results. It front-loads the primary purpose and usage recommendation in the first paragraph. It could be tighter by moving some definitions inline, but it is structured without redundancy and stays focused.

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

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

Given the output schema absence, the description compensates by defining all key output fields (aiTraffic, relativeVolumeScore, purchaseIntentLevel, companyFitScore) and their interpretations, which is critical for an agent to use the returned data. It covers filtering behavior and the read-only nature. Minor gaps exist, such as default behavior when groupId is omitted, but overall it provides sufficient context for correct invocation and interpretation.

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

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

The schema already covers the single parameter 'groupId' with a clear description. The tool description does not add further detail about the parameter's behavior (e.g., whether filtering is exact or partial, or what happens if omitted). Since schema coverage is 100%, a baseline of 3 is appropriate; the description doesn't need to compensate, but it also doesn't enhance parameter understanding beyond the schema.

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

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

The description clearly states the tool lists prompt suggestions for the active project, with a specific purpose: to identify prompts worth adding. It distinguishes itself by explaining it is the recommended way to add prompts and references demand-driven generation. However, it does not explicitly name a sibling that might be similar; it does mention get_ai_traffic as a distinct tool but not as a direct alternative, so differentiation is mostly clear but slightly indirect.

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

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

The description explicitly says to use this tool 'when asked what to monitor next, and before ever writing prompts by hand.' It also contrasts with get_ai_traffic, explaining what that tool reports versus this one, providing clear when-not-to-use guidance. This goes beyond generic context to give direct selection criteria.

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

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

The annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds behavioral detail beyond annotations: it specifies the ordering ('newest first'), the scope ('every report this key's account has generated'), and clarifies that reports are one-off samples (not tracking) until converted. This context helps the agent understand what the returned data represents, going beyond what annotations alone provide.

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

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

The description is excessively long for a list tool. It spends several sentences on the business model of public reports (white-label, lead magnet, branding) before explaining the actual fields. While the first sentence is front-loaded and concise, the rest is verbose and could be trimmed to the essential field meanings. An agent calling this tool only needs to know what it lists and what the fields mean; the marketing explanation is unnecessary. This reduces clarity and wastes tokens.

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

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

Given that there is no output schema, the description must convey the structure of the return. It does this by stating that each row carries the visibility score, whether the prospect asked to be contacted, whether the report is converted, and it mentions contactCount and leadStatus. It also explains the business context, which is useful for interpreting the data. It is not exhaustive (e.g., it doesn't list every field or pagination behavior), but for a read-only list with a cursor, it is sufficiently complete.

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

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

The input schema has 100% description coverage: limit and cursor are fully explained. The description does not add anything about these parameters themselves. It does add meaning about the returned fields (visibility score, contactCount, leadStatus, converted status), which helps interpret the output, but that is not parameter semantics. Since the schema fully covers the parameters, the baseline of 3 is appropriate.

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

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

The first sentence states exactly what the tool does: 'Every report this key's account has generated, newest first'. The resource (reports) and verb (list) are clear, and the ordering is specified. It also distinguishes this from siblings like get_report (single report) and list_projects (projects, not reports) by emphasizing 'public reports' and the lead-pipeline context. The description is unambiguous about the scope.

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 implicitly tells the agent when to use this tool by framing it as the 'agency's lead pipeline' and stating that 'Sorting the work by contactCount is how the interested leads are found.' This clearly indicates a use case: to examine leads and identify interested prospects. However, it does not explicitly name alternative tools or state when NOT to use this tool, 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?

With readOnlyHint already indicating a safe read operation, the description still adds substantial behavioral context: results are ranked by citation count, raising `limit` reveals further down the ranking, `model` narrows results to one assistant, and the meanings of citations, share, and ownDomain are explained. This goes well 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?

The description is front-loaded with a clear purpose, then provides semantics and usage guidance in a structured way. It is slightly wordy and uses decorative phrases like 'the domains describe one pie' and 'where the story about it is being written', but every paragraph carries meaningful content.

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

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

The description covers ranking behavior, output field semantics (citations, share, ownDomain), and the effect of parameters, while the schema handles date constraints and limits. Since there is no output schema, an explicit statement of the exact response shape would make this fully 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 baseline is 3, but the description adds real value by explaining the behavioral effect of `limit` and the analytical use of `model`. The date parameters are not expanded in prose, but their schema descriptions already cover defaults and inclusive ranges.

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 states a specific operation and resource: list the domains assistants cite, scoped to the active project's prompts and ranked by citation frequency. It also explains why to call it ('see which pages shape what the assistants say about the brand'), which distinguishes it from sibling listing tools like list_competitors 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?

The description explicitly says when to call the tool ('Call this to see...') and how to use `limit` and `model` to answer different questions, including distinguishing broadly trusted sources from single-assistant sources. It does not explicitly compare against sibling tools or give when-not-to-use guidance, 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 provide readOnlyHint=true and openWorldHint=true, but the description adds substantial behavioral context beyond that: it warns against concluding something is undocumented from partial excerpts, instructs the agent to say so if the corpus cannot be read or lacks an answer, and specifies answer language, citation, and not inventing behavior. This is rich, non-redundant transparency.

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 four sentences and roughly 100 words. While longer than some, every sentence earns its place: it gives the return value, the usage context, caution about partial sources, and response requirements. The structure is logical, though the length is slightly above the minimum needed for a zero-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?

For a zero-parameter, read-only tool with annotations already covering safety, the description is complete: it provides the exact data source, how to use it, what to do on failure, and response standards. No output schema exists, and the description sufficiently covers what the agent needs to call and use the tool correctly.

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

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

The tool has zero parameters, and schema coverage is 100% (empty schema). Per the rubric, the baseline for 0 parameters is 4. The description adds no parameter-specific semantics because there are none, but it also does not need to.

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

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

The description states a specific verb and resource: 'Returns the complete PromptEye Help corpus as one text file.' It clearly distinguishes itself from sibling tools like read_help_article, which presumably returns a single article, by emphasizing the complete corpus. The inclusion of the URL further anchors the scope.

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

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

The description explicitly says 'Use this as the source of truth for questions about how PromptEye works,' giving a clear trigger for when to invoke this tool. It also instructs to search and check relevant articles in the corpus before answering. However, it does not explicitly contrast with alternatives such as read_help_article or list_help_articles, leaving some inference to the agent.

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

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

Annotations already indicate readOnlyHint=true and openWorldHint=true. The description adds critical behavioral context: it explicitly frames the content as documentation to relay, not instructions to the agent, and warns against improvising beyond the article. This prevents the agent from treating the article as authoritative for its own actions, which is a nuanced behavioral disclosure.

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

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

The description is concise, with no filler, and front-loads the most important instruction (take the path from list_help_articles) early. It then clarifies the behavioral expectations in a clear, direct text block. Every sentence serves a purpose.

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

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

Given that the tool has one simple parameter and is read-only, the description is complete. It covers how to get the path, what to do with the content, and how to handle gaps in coverage. No additional information is needed for correct invocation.

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

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

The single parameter 'path' is fully documented in the schema with a clear example, so schema coverage is 100%. The description reinforces that the path comes from list_help_articles and provides a concrete example, which adds useful context for the agent on how to obtain the correct value. This goes slightly beyond the schema's basic description.

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

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

Clearly identifies the tool as reading a help article and returning its content in Markdown. It specifies the resource ('PromptEye help center') and the output format, and it is distinguishable from siblings like list_help_articles because it focuses on reading one article rather than listing them.

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

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

Provides explicit instructions on how to use the tool: take the path from list_help_articles, answer from the article's content, and point the user to the help center if the article doesn't cover the question. It also advises to mention when the article is insufficient rather than improvising.

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

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

The description states the tool changes which project is active and can switch projects mid-conversation, which is a state mutation. The annotation readOnlyHint=true claims the tool does not modify state, directly contradicting the described behavior. This is an annotation 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?

The description is three sentences with no wasted words. The core action is front-loaded, followed by necessary context about why this tool matters and when to call it again.

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

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

For a simple single-parameter selection tool, the description covers the main action, the effect on other tools, and usage timing. It omits return value or error behavior, but those are not critical given the tool's simplicity and lack of 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?

The schema fully documents the single projectId parameter, including its source from list_projects. The description does not add additional parameter-level meaning, but with 100% schema description coverage the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: it makes one project the active project. It also differentiates this tool from its siblings by explaining that all other tools operate on the active project and take no project argument, making its role as the state-setter unambiguous.

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

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

The description gives explicit usage timing: call it once before working with visibility, competitors, prompts, answers, or sources, and call it again to switch projects. It does not explicitly mention when not to use it or alternatives like get_active_project, but the guidance is clear enough.

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

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

The description goes beyond the annotations by detailing the side effect: excluded brands are dropped from competitor rankings, share of voice, and citations across all historical measurements. It also clarifies that the list is replaced wholesale, which is critical for a state-changing call. This does not contradict 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?

Two short paragraphs front-load the replacement semantics, then provide the key caveat and effect. Every sentence earns its place; there is no filler or repetition of the tool 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?

For a single-parameter write operation with no output schema, the description covers scope ('active project'), replacement behavior, side effects, input limits, optional aliases, and the empty-list case. Nothing essential is missing.

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

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

Schema coverage is 100%, so the schema already documents exclusions, aliases, maxItems, and empty-array behavior. The description reinforces 'up to 50' and 'optional alternative spellings/aliases,' but adds little meaning beyond the schema's own descriptions.

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

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

The description opens with 'Replaces the complete exclusion list for the active project with the one provided,' naming a specific verb, resource, and scope. It also links to list_competitor_exclusions, which distinguishes it from the read/add alternative in the sibling tool list.

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 says to read the current list with list_competitor_exclusions first if addition rather than replacement is desired, and states the empty-array behavior ('excludes nobody'). This gives an agent a clear decision rule for when to call this tool instead of the sibling.

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 annotations, the description adds the important partial-update behavior: 'Only provided fields are updated; omitted fields keep their current values.' It also discloses downstream effects on generated prompts, suggestions, and analyses, which is context an agent cannot infer from the schema or annotations alone. It does not cover auth, rate limits, or failure modes, but those are not required by the annotations and are minor for an update tool.

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

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

Two short paragraphs, front-loaded with the action and resource. The first sentence is immediately informative; the second adds real consequence; the third disambiguates patch semantics. There is no filler or repetition of schema contents.

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

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

For a 6-parameter patch-style update with complete schema and partial-update semantics in the description, the definition is largely sufficient: the agent knows what to send, what the effect is on generated content, and how omissions are handled. It does not describe the success return value or explicitly cover the empty-payload edge case, but no output schema exists and the no-op behavior follows from the stated semantics.

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: each of the six string properties already has an explanatory description and maxLength. The tool description adds a high-level grouping ('who buys it, where it sells, and what makes it distinct') and clarifies that fields are optional, but it does not add per-parameter detail beyond what the schema already provides.

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

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

The first sentence uses a specific verb ('Updates') and a concrete resource ('what the project knows about the brand'), and enumerates content dimensions ('who buys it, where it sells, and what makes it distinct'). This clearly separates it from read-only sibling get_knowledge_base and from update_project/update_prompt, so an agent can identify the correct tool without ambiguity.

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

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

The description provides clear context for when to use the tool: the knowledge base fields drive everything PromptEye generates, so keeping them accurate is the trigger. It also clarifies partial-update semantics. However, it does not explicitly name alternatives or state when not to use it (e.g., 'use get_knowledge_base to read, update_project for project settings'), so it stops at clear context rather than explicit routing.

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

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

Annotations already signal mutation (readOnlyHint=false), but the description adds significant beyond-annotation behavior: alternativeBrandNames and alternativeDomains are replaced as a whole, changing alternativeBrandNames triggers a rebuild of historical visibility metrics that may take up to an hour, and aggregate reads like list_competitors and list_prompt_groups may be temporarily unavailable. It even instructs warning the user beforehand. There is no contradiction with the annotations.

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

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

The description is front-loaded with the core purpose, then lists the changeable fields, and then uses two clearly separated note paragraphs for critical edge-case behavior. Every sentence carries meaningful information: no filler, no repetition of the title or schema, and the warnings are placed where they influence invocation decisions.

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

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

For a mutation tool with no output schema and five optional parameters, the description covers everything an agent needs: what can be changed, what cannot be changed and why, replacement behavior, side effects, duration, and downstream impact on sibling read tools. The absence of a return-value description is acceptable because no output schema exists and the focus is on invoking the mutation correctly.

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

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

Schema coverage is 100%, so the schema already documents each parameter. The description adds value by consolidating the replacement semantics for both array parameters and explaining the real-world consequence of changing alternativeBrandNames (rebuild and read unavailability). It also clarifies that brand name and market country are not parameters here at all, which helps agents understand the parameter boundary even though schema cannot express that.

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

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

The description opens with a specific verb and resource ('Correct what the active project tracks') and enumerates the exact fields that can be changed: display name, grouping label, primary domain, alternative brand spellings, and alternative domains. It also distinguishes itself from creating a new project by explicitly stating that brand and market country cannot be changed here because they define a separate project.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: it states that brand name and market country cannot be changed via this tool and that a different brand/market should be a separate project. It also explains that alternative lists are replaced wholesale, so callers must pass the complete list. This is clear routing against create_project and prevents misuse.

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

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

With only readOnlyHint=false and destructiveHint=false in annotations, the description carries the behavioral disclosure burden and handles it well. It explains capacity effects of pausing/resuming, history preservation on re-filing, and that businessPriority overrides computed priority while null returns control to PromptEye's computation. No annotation contradiction exists.

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

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

The description is front-loaded with the core purpose and uses concise note bullets for caveats. Every sentence carries information and there is no filler or unnecessary repetition of the input 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 7-parameter mutation tool with no output schema, the description covers the key lifecycle effects, constraints on text editing, history preservation, priority semantics, and an alternative workflow. The only omission is the response shape, but the action-oriented nature and rich input documentation make this acceptable.

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 each parameter. The description adds value beyond the schema by explaining the semantic consequences of businessPriority and the capacity implications of status changes, though it does not repeat every parameter interaction already covered by the schema.

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

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

The description opens with a specific verb and resource, 'Changes what happens to one prompt', and clearly enumerates the mutable dimensions: status, group/category filing, and priority. It distinguishes update_prompt from read/list/add siblings by stating it mutates an existing prompt rather than retrieving or creating 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?

The description explicitly states what the tool is for and gives a clear exclusion: the prompt text cannot be edited, with the alternative being to add a new prompt and pause the old one. This gives an agent enough context to choose update_prompt over add_prompts or other siblings.

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