Howseen

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

Annotations already declare this is a non-read-only, non-destructive, open-world write; the description adds real behavioral context beyond them – URL-to-domain resolution, the quota constraint, and the preview/confirm two-phase flow. It stops short of describing the response or what happens when resolution fails.

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

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

Two tight, front-loaded sentences with no filler; the core action leads and the workflow note follows. Slightly telegraphic phrasing ("confirm: true applies") costs a point on readability.

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 low-complexity write tool with a fully documented schema and no output schema, the description covers input forms, quota, and the confirm workflow. Only failure/return behavior is left unspecified, which is a minor gap.

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 all three parameters including the exact preview/confirm semantics. The description mainly restates the name-or-URL input already in the schema, adding only the "resolved to name + domain" detail. 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 action (track/add) and resource (a competitor), with the accepted input forms spelled out (name or website URL). It is easily distinguished from get_competitors, list_brands, and remove_competitor, though it does not name any sibling explicitly.

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

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

"Preview first; confirm: true applies" gives a clear two-step workflow, and the quota mention signals a precondition for use. It does not, however, say when not to use it or name an alternative path when the quota is exhausted.

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 annotations only declaring the safety profile, the description adds real behavioral detail: the batch is atomic (the whole list is refused on quota overflow), re-adding an archived prompt restores it rather than duplicating, and nothing changes until confirm: true follows an approved preview. These are non-obvious traits an agent could not infer from readOnlyHint=false/destructiveHint=false.

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

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

Three short sentences, front-loaded with the core action, then the quota constraint and restore behavior, closing with the preview/confirm workflow. No filler or repetition.

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

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

For a mutation tool with no output schema, full schema coverage and a clear safety annotation set, the description supplies everything needed: quota failure mode, upsert/restore semantics, and the required preview-then-confirm sequence.

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 brand, topic, confirm and prompts are already documented in the schema. The description's 'Preview first; confirm: true applies' reinforces the confirm parameter but adds no syntax or format detail beyond it, so the baseline 3 applies.

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

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

States a specific verb and resource ('Track new buyer questions (prompts) for the brand') and narrows the scope with 'new', implicitly separating it from list_prompts, suggest_prompts and archive_prompts. An agent can tell this is the creation path without opening the schema.

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

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

Gives concrete usage guidance: preview first, then set confirm: true to apply. It also states the precondition that the whole list is refused when it would exceed the plan's prompt quota. It stops short of naming the sibling alternatives (suggest_prompts, archive_prompts) that a caller might confuse this with.

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

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

Goes well beyond the annotations (destructiveHint=true, readOnlyHint=false) by disclosing exactly what is destroyed versus preserved: scanning stops and quota is freed, but history is retained, the prompt stays visible as archived, and it can be restored. It also discloses the preview/confirm gating, which is the key behavioral nuance for a destructive 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?

Dense and front-loaded: the effect and its consequences come before the procedural instruction, and no sentence is filler. The telegraphic style ('Preview first; confirm: true applies') is compact to the point of slight ambiguity, but it stays readable.

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

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

With no output schema and 100% schema coverage on parameters, the description supplies what is missing: reversibility, retained history, quota effect, and the preview-before-apply protocol. It omits edge cases such as behavior for unknown prompt texts or already-archived prompts, but the core call path is fully covered.

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 brand, confirm, and prompts are already documented in the schema. The description's 'confirm: true applies' reinforces the confirm semantics but adds no syntax or constraint detail beyond the schema; baseline 3 is appropriate.

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

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

States a specific verb and resource (archive prompts) and immediately describes the effect: prompts stop being scanned, quota is freed, history is kept, and they remain listed as archived and restorable. The reversibility phrasing implicitly separates it from remove_prompts, though no sibling is named explicitly.

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

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

Gives an explicit two-step workflow: preview first, then apply with confirm: true. It does not state when to choose archive over remove_prompts or what prerequisites apply (e.g. quota limits), so it stops short of full alternative-routing guidance.

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

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

Annotations already flag a non-read-only, non-destructive write. The description adds genuinely useful behavior beyond that: the link is public and frozen (immutable snapshot), carries agency branding, and requires a preview-then-confirm sequence. It stops short of stating permissions or rate limits, so not a 5.

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

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

Two sentences, front-loaded with the verb+deliverable, followed by the critical confirm workflow. Dense but every clause carries information; a minor trim of the parenthetical contents list would make it tighter.

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-param write with 100% schema coverage and no output schema, the description covers purpose, scope, and the preview/confirm contract well. Its only gap is not describing what a preview returns versus the final link, which an agent might want to know.

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 every parameter including the date range, brand, engine, lang enum, and confirm toggle is already documented. The description reinforces the confirm semantics but adds no syntax or format detail beyond what the schema provides, fitting the baseline-3 case.

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 (Create) plus resource (share report) and enumerates the report contents (visibility, competitors, top prompts, recommendations). The 'like the dashboard Share button' analogy and 'public, frozen link' scope make the deliverable unambiguous, and no sibling tool overlaps.

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 workflow guidance: 'Preview first; confirm: true creates the link,' which tells the agent the two-phase invocation pattern and the guardrail before committing. It does not name a competing sibling to avoid, but none exists here, so context is clear without 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 declare destructiveHint=true, but the description goes well beyond them: what actually happens (moved to Trash, restorable with restore_article), a side effect worth knowing ('its topic is not planned again'), and a key limitation ('a post already live on the client's own CMS ... is NOT removed from the CMS'). It also discloses that the first call is non-mutating and returns a preview.

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

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

Two dense sentences, front-loaded with the core action and its reversibility, then the CMS caveat, then the confirm workflow. Slightly long and colon-heavy, but nearly every clause carries an actionable constraint.

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 destructive 3-param tool with no output schema, the description covers the mutation's effect, reversibility path, side effects, the CMS edge case, and the required confirm sequence. Nothing an agent needs to call it safely is missing.

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

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

Schema coverage is 100%, so baseline is 3; the description adds genuine interaction semantics on top by prescribing the confirm=false-then-true sequence and noting the preview content ('the preview says where it stays live'), which the schema only states abstractly. It does not add anything for brand or article_id 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?

States a specific verb+resource ('Move an article ... to the Trash') and immediately scopes it: soft-delete that is restorable, not CMS removal. Explicitly names the sibling restore_article and distinguishes CMS-hosted posts from the deletion behaviour, so an agent can separate it from publish_article/archive_prompts 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?

Gives an explicit two-step protocol ('Always call WITHOUT confirm first and show the preview ... call again with confirm: true only after they approve') plus the undo route (restore_article, Trash UI). When-to-use and when-not-to-proceed are both spelled out, which is unusual and valuable for a destructive 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 destructiveHint=false and idempotentHint=true, so safety is partly covered. The description adds real value beyond them: the target state (Archived), dashboard reversibility, and the preview-vs-apply two-step behavior – none of which the annotations convey.

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

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

Two sentences, zero waste, effect front-loaded before the preview/confirm instruction. 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?

For a reversible mutation tool with full schema coverage and no output schema, the description supplies everything an agent needs: what changes, where it goes, reversibility, and the required confirm workflow. No significant 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?

Schema description coverage is 100%, so all three parameters (brand, confirm, action_id) are already documented, including where each id comes from. The description's 'confirm: true applies' merely restates the schema, adding no syntax or edge-case detail, so the baseline 3 applies.

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

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

States a specific verb+resource ('Dismiss an action-plan item') and immediately describes the concrete effect (moved to Archived, out of next best actions). This clearly separates it from the sibling mark_action_done, which handles the opposite user intent.

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

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

Gives clear context for when to use it ('item the user does not want to do') and an explicit operational protocol: 'Preview first; confirm: true applies.' No alternative tool is named explicitly, but the intent-based routing is unambiguous.

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

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

Annotations only cover readOnly/openWorld/destructive; the description adds the material behavior an agent cannot get from them: the two-phase preview-then-confirm flow, the guarantee that nothing is published, the fact that a write consumes the plan's article allowance, and the ~1 minute duration of a confirmed write.

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

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

Four dense clauses with the purpose front-loaded, the pipeline parenthetical clarifying what 'quality pipeline' means, and the safety-critical preview/confirm rule spotlighted at the end. No filler sentences.

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 still conveys the essential result semantics (a non-published draft, preview vs. persisted write, quota cost, latency). It does not explain what the preview response looks like or whether a preview leaves any artifact behind, which is the only real gap for a 3-parameter tool with full schema coverage.

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 question, brand and confirm are all already documented in the schema, including the preview semantics of confirm. The description reinforces the confirm gating and the single-brand default for brand, but adds no syntax or format detail beyond the schema — baseline 3 applies.

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

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

States a specific verb and resource ('Write a DRAFT article answering one buyer question') plus the scope constraint that it never publishes, which cleanly separates it from publish_article, refresh_article and delete_article in the sibling list. An agent can tell what this tool produces without opening the schema.

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

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

Gives an explicit operating sequence: 'Preview first; confirm: true writes it', which tells the agent exactly how to invoke it safely. It implicitly routes publishing elsewhere ('Never publishes') but never names publish_article as the alternative, so the exclusion is inferred rather than stated.

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

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

Annotations already cover read-only safety, and the description adds useful behavioral context beyond them: the action types (off-page listing and content answers), the 20/80 ranking logic, and that steps are included. It does not disclose return format details, but no 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 a single, front-loaded sentence that packs purpose, action types, ranking, and output detail without filler. It is efficient, though slightly dense with parentheticals and could be marginally clearer.

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 tool with 100% schema coverage and safety annotations, the description adequately explains the returned content. However, with no output schema and many similar siblings, it should more explicitly help the agent choose this tool and understand the return structure.

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 fully documents all six parameters. The description adds no parameter-specific syntax, defaults, or filtering behavior beyond what the schema already states, making the baseline of 3 appropriate.

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

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

The description clearly states the resource: prioritized actions to raise AI visibility, with off-page and content types and 20/80 ranking. It does not name a sibling tool as an alternative or explicitly contrast with get_easiest_wins or get_prompt_gaps, so it falls short of a 5.

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

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

There is no guidance on when to use this tool versus the many similar siblings such as get_easiest_wins or get_prompt_gaps. The phrase 'like the dashboard Action plan' implies a dashboard-equivalent use case but does not provide explicit when/when-not 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety and scope are covered. The description adds a useful conditional note that impressions and clicks are only returned when Search Console or Bing is connected, which is real behavioral context beyond the annotations. It does not, however, discuss pagination behavior or default date handling.

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 packs the relevant output fields without wasted words. The noun-phrase structure is slightly less clear than a full declarative sentence, but it is efficient and appropriately sized.

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

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

For a read-only retrieval tool with no output schema, the description enumerates the primary return fields and notes the conditional availability of impression/click data. This gives the agent enough to understand what comes back, though it omits pagination behavior and any hint about sorting or result ordering.

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 each of the five parameters is fully documented in the input schema. The description adds no additional meaning about the date range, brand selection, or pagination parameters, leaving the baseline score of 3 appropriate.

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

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

The description specifies the resource (articles written for the brand) and the key data fields returned (status, GEO score, published URL, indexing status, impressions, clicks), making the tool's function clear. However, it is a noun phrase without an explicit verb like 'retrieves' or 'lists', and it does not differentiate itself from the sibling list_articles, so it stops short of a 5.

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

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

No when-to-use guidance is provided. The description never mentions when this tool should be chosen over list_articles, get_visibility, or other siblings, nor does it note any prerequisites or exclusions. The agent is left to infer usage entirely from the tool name and data fields.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real behavioral value by describing the comparison window and default behavior ('last two completed scans' / default previous scan), plus the causal attribution content, which goes 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?

One dense sentence that is front-loaded with the core purpose and then enumerates return contents; every clause carries information, though the parenthetical cause clause makes it slightly heavy for a single sentence.

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

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

With no output schema, the description usefully enumerates what comes back (gains/losses, deltas, competitors, causes), which compensates well. It stops short of describing pagination or response structure, but nothing needed to call the tool correctly is missing.

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

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

Schema description coverage is 100%, so all three params (brand, since, engine) are already documented in the schema. The description reinforces the date-comparison semantics ('since a date') and the per-engine breakdown but adds no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb+resource with scope: 'What changed between the last two completed scans (or since a date)', then enumerates the exact outputs (prompts gained/lost, visibility delta per engine, newly named competitors, likely causes). An agent can distinguish this from get_visibility and get_prompt_gaps without opening a schema.

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

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

Gives clear context for when to use it — comparison between the last two completed scans, or against a supplied date — but names no alternatives or exclusions (e.g., when to prefer get_visibility or get_prompt_gaps instead).

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, destructiveHint=false and closedWorld, so the safety profile is covered. The description adds value by disclosing the metric set and the overall/per-engine aggregation dimension, but says nothing about pagination, rate limits, or what happens when competitor data is sparse.

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

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

A single sentence with zero filler, front-loaded with the verb and scope, then the metric list. Every clause carries information an agent needs.

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 usefully enumerates the returned metrics and the per-engine breakdown, which is the main thing an agent would otherwise lack. It is close to complete, though the absence of any indication of competitor-list sourcing (e.g. via add_competitor/remove_competitor) leaves a small gap.

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 all four parameters (from, to, brand, engine) already carry documented semantics and defaults. The description adds no syntax, date-range, or brand-resolution detail beyond the schema, so baseline 3 applies.

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

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

Names a clear verb (compare) and resource (competitors) and enumerates the exact metrics returned: visibility %, share of voice, average position, sentiment, overall and per engine. It implicitly separates itself from the sibling get_visibility by framing the output as a comparison against competitors, but it never names or contrasts with that sibling explicitly.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as get_visibility (brand-only) or get_top_sources. The comparative framing implies the use case, but the agent is left to infer when this tool is preferable to the other reporting tools.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds useful output composition details (ranking by lost-answer frequency, matching action-plan item) but does not disclose any additional behavioral traits such as authentication needs, rate limits, or side effects.

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, both dense and purposeful. The first front-loads what is returned and how it is ranked; the second justifies the tool's value. There is no filler or repetition.

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

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

With no output schema, the description adequately explains the return values: third-party sites/pages, their ranking basis, and the associated action-plan item. All seven parameters are fully documented in the schema, and annotations cover safety, so nothing critical is missing for an agent to call this correctly.

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

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

Schema description coverage is 100%, so the schema already fully documents all seven optional parameters (date range, brand, language, limit, offset, engine). The description adds no parameter-level meaning beyond what the schema provides, making the baseline 3 appropriate.

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

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

States a specific resource — third-party sites and pages cited in answers the brand loses — and a precise scope condition (competitor named, brand not). This distinguishes it from a generic top-sources tool and tells the agent exactly what domain the result covers.

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

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

Provides clear context for when to use it: finding the shortest path back into lost answers by getting listed on the cited sites. It does not, however, name alternative tools (e.g., get_top_sources or get_action_plan) or state when not to use it, so it falls short of explicit when/when-not 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 this a safe, closed-world read, so the safety burden is lifted. The description goes beyond them by disclosing the sort behavior (search volume when a cached figure exists, then count of competitors named) and the shape of each row, which is genuine behavioral context an agent cannot get from 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 with no filler; the core filter definition is front-loaded and the sorting rule is secondary, matching its importance. 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, and the description compensates well by describing row contents (prompts, named competitors, cited domains) and ordering. It omits only the default time window and pagination behavior, which are already covered by the parameter schema, so the gaps are minor.

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 from, to, brand, limit, engine, and offset are fully documented in the schema itself. The description adds nothing parameter-specific (no mention of date scoping, engine filter, or pagination semantics), so the baseline 3 is correct.

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

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

The description defines a precise, verifiable data set: tracked prompts where the AI names at least one competitor but not the brand, per engine, with competitors and cited domains included. That definition alone separates it from siblings like get_visibility, get_easiest_wins, and search_responses without the agent opening any schema.

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

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

"Start here to see what to win back" implies a use case and even a priority ordering among tools, which is more than nothing. But it names no alternatives and states no exclusion or prerequisite conditions (e.g. when to use get_easiest_wins or get_visibility instead), leaving the choice to inference.

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

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

Annotations already declare readOnlyHint, destructiveHint, and openWorldHint, covering the safety profile. The description adds conceptual context about what the data represents (cited domains and URLs) but does not disclose return format, pagination behavior, or rate limits, so it is adequate but not rich.

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 with zero waste: the first front-loads the returned data, and the second gives the actionable use case. Every sentence earns its place.

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

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

No output schema exists, so the description should summarize return values, which it does at a high level (domains and URLs, ranked by citations). It omits pagination and default limits, but those are covered in the schema, leaving the definition largely complete for a read-only analytics tool.

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

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

Schema description coverage is 100%, so the schema fully documents all six parameters. The description mentions "overall and per engine" implicitly touching the engine filter, but adds no syntax or default details beyond what the schema provides, matching the baseline of 3.

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

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

The description clearly identifies the resource as the domains and URLs most cited by AI engines for buyer questions, and specifies scope (overall and per engine). It does not explicitly distinguish itself from sibling analytics tools like get_visibility or get_prompt_gaps, so it falls short of a 5.

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

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

"Use it to find where the brand should get listed or mentioned" gives a concrete when-to-use scenario. There are no exclusions or named alternatives, but the intended context is clear.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false). The description goes beyond them by disclosing that the call surfaces API key permissions and rate limits, which is behavioral context an agent can't infer from annotations alone. It doesn't mention auth requirements or caching, but with annotations carrying safety that gap is minor.

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

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

Two sentences, front-loaded with the returned data set followed by a usage directive. The parenthetical quota list is dense but each item earns its place by telling the agent what data is available; only the run-on listing 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?

No output schema exists, so the description correctly carries the burden of describing return contents (quotas, scan estimate, key permissions, rate limits). Combined with the fully-specified single parameter and safety annotations, an agent has enough to call this correctly; only auth/error behavior is unstated.

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

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

Schema description coverage is 100% and the single 'brand' parameter is fully documented in the schema (brand id/name/domain, optional for single-brand accounts). The description adds nothing about the parameter, so the baseline of 3 applies.

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

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

The description states a specific resource ('plan usage') and enumerates exactly what it contains: quotas used and left for prompts/competitors/articles/manual scans, next scan estimate, API key permissions and rate limits. This is unmistakably distinct from siblings like get_visibility or list_brands, which operate on brands and content rather than account state.

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?

'Call it before planning changes' gives explicit when-to-use guidance. No alternatives are named, but this tool has no overlapping sibling (none of the other 27 tools reports account/plan state), so there is little risk of misselection.

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

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

Annotations already establish a safe, non-destructive, closed read. The description adds real value on top of that by disclosing the return shape: per-engine breakdown, competitor share-of-voice comparison, and a trend series with one point per scan, which tells the agent the granularity of the time series. It does not discuss limits or empty-data behavior, so not a 5.

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

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

A single dense sentence that front-loads 'Headline AI visibility of a brand' and then enumerates the metrics. It is appropriately sized for a no-parameter-required read tool; the only soft spot is that the metric list reads like a return-value enumeration rather than an action statement.

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 explaining what comes back and does so adequately, listing the metric families and the trend granularity. It is thin on how defaults resolve when brand or dates are omitted, but that is largely covered by the schema's own defaults.

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

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

Schema description coverage is 100%, so the baseline is 3. The description only obliquely touches parameters ('per engine', 'over the period') and adds no format, defaulting, or brand-resolution detail beyond what the schema already states for to/from/brand/engine.

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 resource precisely: headline AI visibility metrics for a brand (share of answers, share of voice, average position, sentiment, per engine, trend). That is specific enough to separate it from get_competitors, get_top_sources, and get_changes. It never states an explicit verb or names a sibling, so it stops short of a 5.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternative tools such as search_responses or get_article_performance. The word 'Headline' faintly implies a summary-level call, but the agent is left to infer entirely when this tool is the right choice versus its many siblings.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered. The description adds some value by disclosing that the result set spans drafts, scheduled and published articles with their status, which tells the agent it's a broad read — but it says nothing about pagination behavior or result ordering, which the schema only partially covers.

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

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

A single sentence with no filler, and the content-related clause (states and fields) is front-loaded. It loses a point for being a noun fragment with no verb, which makes it slightly less directive than it could be, but nothing is wasted.

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 usefully compensates by naming the fields returned (status, target question, GEO score, published URL). Combined with annotations that cover the safety profile, an agent has enough to call this correctly; only pagination/ordering behavior is left implicit.

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 all five parameters (brand, from, to, limit, offset) are already documented in the schema, including defaults and max values. The description adds no additional parameter semantics beyond what's in the structured fields, so the baseline 3 applies.

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

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

The description names the resource (articles written for the brand) and enumerates the states covered (drafts, scheduled, published) plus the fields carried back (status, target question, GEO score, published URL). It's clear what the tool returns, but it never explicitly frames itself as a listing/query operation nor differentiates itself from siblings like get_article_performance.

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?

There is no when-to-use guidance, no exclusions, and no mention of alternatives such as get_article_performance for metrics or draft_article for creating content. The agent must infer usage purely from the tool name.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely new context: the payload contents (id, name, domain) and the recommended call-first sequencing, which matters since there is no output schema.

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

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

Two short sentences, with the resource and returned fields front-loaded and the usage hint second. No filler or restatement of the title.

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

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

For a zero-parameter list tool, the description covers what it returns and when to call it, compensating for the absent output schema. Minor omissions (empty-account behavior, ordering) are inconsequential here.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No misleading parameter claims are made.

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

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

States a specific verb ('List') plus the resource ('brands (websites) tracked in this Howseen account') and even enumerates the returned fields (id, name, domain). No sibling tool lists brands, so an agent can route unambiguously.

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?

'Call this first when the account may have several brands' gives a concrete ordering/trigger condition rather than generic boilerplate. It does not name an alternative tool to use instead, but no sibling offers overlapping functionality.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds value by naming the metric payload (visibility, share of voice, position, cited brands/domains), but says nothing about pagination behavior, defaults, or auth/brand requirements beyond what the schema states.

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

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

One dense, front-loaded sentence with no filler, delivering the resource and its returned metrics efficiently. Slightly list-heavy but every element 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?

With no output schema, the description usefully names the fields the tool returns, and the schema fully covers inputs. Given the read-only annotations and complete parameter coverage, an agent has enough to invoke it correctly, though pagination/ordering nuance is absent.

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 all six parameters (from/to, brand, limit, engine, offset) are fully documented in the schema itself. The description adds no parameter-level meaning, which is the expected baseline when the schema does the heavy lifting.

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

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

States the resource (buyer questions/prompts tracked for a brand) and enumerates the per-prompt metrics returned, which meaningfully separates it from siblings like get_visibility or get_prompt_gaps. However, it reads as a noun phrase rather than an explicit verb+resource statement, so it's clear but not maximally directive.

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

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

No indication of when to use this versus the many sibling list/get tools (list_brands, get_visibility, get_prompt_gaps, search_responses). The single-sentence description gives the agent no routing guidance or prerequisites.

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 non-destructive, idempotent write behavior, so the bar is lower. The description adds genuinely useful behavioral context: a preview mode exists and changes are only applied when confirm is true, which is the key safety trait for this mutation.

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 compact sentences with zero filler; the mutation action is stated first, followed by id provenance and the confirm rule. 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?

For a single-required-param mutation with no output schema, the description covers what changes, how to obtain the id, and the confirm safeguard. It does not describe what the preview returns, but with no output schema that is a minor omission.

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

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

Schema coverage is 100%, so baseline is 3. The description still adds value by naming the source tools for action_id and by explaining the preview/confirm interaction ('Preview first; confirm: true applies'), which the schema documents but the description reinforces in workflow terms.

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 ('Mark an action-plan item as done') and clarifies the resulting state ('same state as the dashboard Action plan'). It is clearly distinguishable from siblings like dismiss_action or delete_article.

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?

Tells the agent where the required id comes from ('Use the action id from get_action_plan or get_easiest_wins') and prescribes the workflow ('Preview first; confirm: true applies'). It does not address when not to use this tool versus dismiss_action, but the core context is explicit.

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

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

Annotations already flag mutating, destructive, and open-world behavior, but the description adds crucial workflow details: public exposure ('Goes live publicly'), preview-then-confirm behavior, the Autopilot ON prerequisite for scheduling, and that a successful publish returns the URL.

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

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

The description is a single, well-structured sentence that front-loads the core action and then layers in destination, timing, public visibility, and the confirm workflow. Every clause earns its place with no wasted words.

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

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

For a mutation tool with open-world and destructive annotations, the description covers the unique risks and workflow: public go-live, preview requirement, explicit confirmation, scheduling prerequisite, and return value. With no output schema, mentioning the returned URL is sufficient and nothing critical for correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents every parameter including confirm, platform, publish_at, article_id, and brand. The description reinforces the confirm workflow and mentions Autopilot ON for scheduling, but adds little syntactic or semantic detail beyond what the schema provides.

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

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

States a specific verb and resource ('Publish a written article') and names the source ('a draft from draft_article'), clearly distinguishing it from drafting or managing articles. Lists destinations and scope (now or scheduled), so an agent can identify the action without opening the schema.

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

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

Provides clear context: publish now or schedule (requires Autopilot ON), preview first, and set confirm: true only after approval. It implies the relationship to draft_article but does not explicitly state when not to use this tool versus alternatives like delete_article or refresh_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?

Annotations only give the generic readOnlyHint=false / destructiveHint=false / openWorldHint=true trio; the description adds real behavioral context: the same id/slug/question/date are preserved, the previous version is kept and restorable, published articles are diverted into a refreshed draft, quota implications, and an expected runtime of about a minute.

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

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

Front-loaded with the core action and its constraints, and every clause carries information (preservation, non-destruction, quota, workflow, timing). It is a dense single paragraph with several parentheses, so it is slightly heavy but not wasteful.

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

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

With no output schema, the description still covers the preview behavior, confirmation requirement, state preservation, quota, and rough duration. An agent has everything needed to call this correctly in the right sequencing.

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 parameters are already documented. The description still adds value by explaining the preview-then-confirm protocol and the alternative identification path (article_id from list_articles vs. the target question), which the schema states only flatly.

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 (rewrite/refresh) and resource (a WRITTEN article) and scopes it precisely: 'with the brand's current profile after it changed'. It is immediately distinguishable from siblings like draft_article, publish_article, delete_article, and restore_article.

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

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

Gives an explicit trigger (after the profile changed), an explicit boundary (a published article is never overwritten), a cost rule (free once per article, otherwise article allowance), and the required workflow (preview first, then confirm: true). It also points to list_articles for the id.

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 flag destructiveHint=true, but the description adds two things they don't cover: the retention semantics ('Past results keep it') and the mandatory preview-then-confirm protocol. That is non-obvious behavior an agent would otherwise have to guess, so it clears the lowered bar for annotated tools.

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 compact clauses, front-loaded with the action and its effect, and no sentence is filler. The telegraphic fragment style ('confirm: true applies') is slightly cryptic, which holds it below a 5.

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

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

For a 3-param destructive tool with no output schema, it covers the action, retention behavior, and the safety protocol, which is most of what an agent needs. It omits edge cases such as an unknown competitor name, and the brand-scoping caveat is left entirely to the schema.

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

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

Schema description coverage is 100% and every parameter already carries a descriptive string, so the schema does the heavy lifting and baseline 3 applies. The description's 'by name or domain' and 'confirm: true applies' largely restate what the competitor and confirm schema entries already document.

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

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

States a specific verb+resource ('Stop tracking a competitor') with the accepted identifier forms ('by name or domain'), which maps cleanly onto the required parameter. It is trivially distinguishable from siblings add_competitor and get_competitors without opening any schema.

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

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

'Preview first; confirm: true applies' prescribes the exact call sequence for a destructive operation, which is real when-to-use guidance. It does not name an alternative or state exclusions (e.g., a tool for pausing instead), so it falls short of a 5.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing the retention rule (past scan results remain in history) and the preview-then-confirm gate, though the confirm mechanics largely restate the schema's own confirm description.

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

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

Three short sentences with zero filler, front-loaded with the primary action and its consequence before the sibling comparison and the confirmation gate. 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?

For a destructive, closed-world mutation with no output schema, the description covers what is removed, what is preserved (history), the safer alternative, and the preview/confirm sequence that must be honored. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so all three parameters (brand, confirm, prompts) are already documented with format and sourcing hints in the schema. The description only echoes the confirm behavior and adds no prompt-text format or batch-limit detail beyond what the schema states; baseline 3 applies.

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

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

States a specific verb and resource (stop tracking / remove from the prompt list) and immediately distinguishes the operation from its nearest sibling by noting that past scan results stay in history. An agent can tell this apart from archive_prompts or remove_competitor without opening any schema.

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

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

Names the alternative explicitly ('Prefer archive_prompts to keep them listed') and gives the operative condition that selects it. It also states the call sequence ('Preview first; confirm: true applies'), so the agent knows the required two-step flow rather than a single destructive call.

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

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false), the description discloses a rate limit (at most once per article every 24h), that the call reaches external services, and that confirm:true is what actually submits while omitting it yields a no-op preview. It does not cover error behavior or what happens on a rejected/duplicate submission.

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?

It is dense and front-loaded with the action and targets, and the critical safety rule (preview then confirm) lands at the end where it is memorable. The url explanation is somewhat restated from the schema, costing a little efficiency.

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

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

For a 4-parameter, single-required-param mutation tool with no output schema, the description covers rate limits, the preview/confirm contract, and the conditional url case. Return handling is not described, but the text notes Howseen records and tracks indexing, which is sufficient context.

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 all four parameters are already documented, and the description largely reinforces that (url conditional, brand optionality, confirm semantics). It adds little syntax or format detail beyond the schema, so baseline 3 applies.

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

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

The definition states a specific verb and resource (submit a published article for search-engine indexing) and names the concrete downstream targets (Google, Bing, IndexNow). An agent can immediately distinguish this from publishing or refreshing siblings.

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

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

It gives a clear conditional for passing url (only when you publish on your own site from the API or feed) and prescribes a workflow: preview first, then confirm: true. It does not explicitly name an alternative tool or state when not to call it, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=true, so safety is covered. The description adds the meaningful preview-then-confirm workflow and the Trash origin, which is behavioral context not conveyed by the annotations alone.

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 compact sentences with zero filler, front-loading the core action and then the critical confirm workflow. 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?

No output schema exists, but the tool's behavior is simple and the annotations plus schema cover safety and parameters; the description closes the remaining gap by explaining the preview/confirm gate. Minor omission of any return-value or error context keeps it from a 5.

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 brand, confirm, and article_id are already fully documented in the schema, including confirm's preview/precedent semantics. The description only restates confirm: true and adds no parameter detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource (bring back an article from the Trash) and links it to the inverse operation by name (one deleted with delete_article). This distinguishes it clearly from siblings like delete_article and draft_article without needing their 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?

Gives a clear usage protocol: 'Preview first; confirm: true restores.' This tells the agent the required call sequence. It lacks explicit when-not or named alternatives, but the deletion/trash context implicitly scopes usage well.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds real behavior beyond them: preview changes nothing, confirm=true actually runs, and each call takes about 45 seconds. It also discloses the rate-limit/cadence constraint, which is exactly the kind of context annotations don't carry.

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

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

Front-loads the action, then packs constraints into a parenthetical and closes with the preview/confirm rule and timing. Dense but every clause earns its place; the nested parenthetical makes it slightly harder to parse than ideal.

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 2-parameter action tool with no output schema, the description covers action, constraints, timing, and the required confirmation flow. The one gap is that it doesn't say what the preview returns, though the absence of an output schema makes that a minor omission.

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 both parameters are already documented (baseline 3). The description still reinforces the semantics of 'confirm' by tying it to the preview step ('Preview first; confirm: true runs') and adds the cadence meaning of 'brand' scoping, giving modest value beyond the schema.

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

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

States a specific verb (scan) and resource (the brand's prompts on the AI engines now), and the scope is unambiguous. No sibling tool performs scanning, so an agent can identify this as the action-triggering tool without opening the schema.

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

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

Gives explicit when/when-not conditions: the once-per-cadence limit (72h, or 24h on Business), that prompts added since the last scan can be scanned alone, and that unfinished scans can be continued. The preview-then-confirm workflow is spelled out as the required procedure.

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, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuinely new context with no output schema present: it discloses the shape of returned records (excerpts around the mention, naming of brand and competitors, cited URLs) and that all filters are optional.

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 with no filler; the return-payload summary is front-loaded before the filter sentence. The second sentence is a dense list that could be tightened slightly, but nothing is wasted.

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 correctly compensates by describing the returned fields, and it covers the three filtering dimensions. Minor omissions remain — pagination behavior and the default-brand fallback are left to the schema — but nothing an agent needs to call it correctly is absent.

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 all eight parameters (including the comma-separated engine list and pagination fields) are already fully documented. The description names query, prompt, and engine but adds no format or syntax detail beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Read real AI answers collected for the brand') and then enumerates the payload (brand-mention excerpts, brand/competitor naming, cited URLs). This payload description distinguishes it from siblings like get_top_sources or get_visibility, which cover only sources or 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 second sentence describes the available filters (query, prompt, engine), which implies how to narrow results, but never states when to choose this tool over get_top_sources or get_visibility, nor any prerequisites or exclusions. Usage is inferable from the filter list rather than spelled out.

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

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

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description still adds meaningful context beyond them: the 20-calls-per-day rate limit and confirmation that the call is non-mutating and must be followed by add_prompts to persist anything.

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

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

Two tight sentences with zero waste; the content of the suggestions is front-loaded and the action/alternative and rate limit follow immediately.

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

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

For a simple read-only suggestion tool with full schema coverage and no output schema, the description tells the agent what it returns and how to act on it. It is essentially complete, with only minor gaps like ordering/pagination of 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?

Schema description coverage is 100%, so both parameters are already fully documented (brand resolution and count with min/max/default). The description adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

The title supplies the verb+resource ('Suggest prompts to track') and the description specifies exactly what the suggestions contain: real Hacker News buyer questions ranked by engagement plus AI suggestions for the category. It is clear, though the opening sentence describes the returned content rather than restating the action, so differentiation from siblings only emerges later.

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

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

It explicitly routes the agent: 'Returns suggestions only; use add_prompts to track some,' naming the alternative and the follow-up action. The when-to-use condition (buyer questions the brand does not track yet) is clear, but there is no explicit when-not guidance.

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