PingAura

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

Annotations already declare this is a non-read-only, non-destructive, closed-world write, so the safety profile is covered. The description adds genuinely useful context beyond that: the attestation is stored 'against the credential owner,' clarifying accountability and attribution. It does not say whether the call is idempotent, what happens if the page was already acknowledged, or what a failure looks like.

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

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

Two short sentences, front-loaded with the action and followed by the consequence. Minor redundancy: 'a person has checked' and 'someone has actually read the page' restate the same idea, so the second sentence slightly repeats rather than extending.

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 with annotations covering safety and no output schema, the description supplies what matters: that this is a manual attestation, that it applies to pages missed by the automated check, and that it is recorded against the credential owner. Nothing an agent needs in order 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?

Only one parameter and the schema documents it fully ('Hosted page ID', uuid format), so the schema carries the load. The description adds nothing about the parameter itself and does not, for example, explain how to obtain a page_id (presumably from list-hosted-pages or get-hosted-page). Baseline 3 applies at 100% schema coverage.

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 ('Record') and resource ('that a person has checked a hosted page'), plus a distinguishing condition: the page 'the automated fact check never read.' An agent can tell this is a manual attestation rather than an automated result. It does not, however, name any of the nearby hosted-page siblings (reject-hosted-page, request-hosted-page-regeneration), so sibling differentiation is only implicit.

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

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

The phrase 'a hosted page that the automated fact check never read' implies the triggering condition, but there is no explicit statement of when to call this versus reject-hosted-page or request-hosted-page-regeneration, and no prerequisites such as needing the page to be in a particular state. Usage is inferable, not 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 it is a non-destructive write with openWorldHint=false, so the safety profile is covered. The description adds genuine value beyond that by disclosing duplicate handling — existing entries keep their display name and aliases — and by naming the already_tracked response key, 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 sentences, both front-loaded and earning their place: the first states the action, the second states the edge-case behavior the agent would otherwise guess wrong about. No filler.

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

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

For a simple two-parameter write with no output schema, the definition covers the action and the one non-obvious outcome (already_tracked). It stops short of saying what happens to newly added domains, whether they are verified synchronously, or any quota implications of bulk adding.

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 documented, establishing the baseline of 3. The description adds no new detail about domain_id (e.g., that it must reference an existing tracked domain) or about the comma-separated format or limits on competitor_domains.

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

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

The description uses a specific verb and resource ('Add competitor domains to tracking'), which is enough to distinguish it from the read-only list-competitors and the delete/update siblings. It doesn't explicitly name those siblings, which keeps it 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?

It explains what happens when a domain is already tracked, which implicitly signals this is a batch-add rather than an edit path, but it never tells the agent when to prefer add-competitor over update-competitor or what precondition domain_id must satisfy. Usage is implied 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?

The annotations mark this as destructive, but the description adds important nuance beyond that: the article leaves lists, gets a new archived-<id> slug, frees the old slug, and retains its content. This gives the agent a clear picture of what 'destructive' actually means 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?

The description is short, front-loaded with the action, and every sentence adds useful information about effects. There is no redundant or filler text.

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

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

For a simple one-parameter mutation with annotations covering safety, the description explains the key side effects well. It does not mention return behavior, idempotency, or what happens if the article is already archived, but those are minor gaps given the tool's simplicity.

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

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

The schema has 100% description coverage for the single required article_id parameter, including its uuid format. The description does not add meaning beyond the schema, so the baseline score of 3 applies.

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

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

The description names a specific verb and resource ('Archive an article') and immediately clarifies the operational effect: removal from article lists, slug replacement, and content retention. That is enough for an agent to distinguish this from sibling operations like update-article or publish-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?

There is no explicit 'use this when' or 'do not use this when' guidance, and no sibling alternative is named. However, the stated effects imply appropriate scenarios, such as hiding an article from lists while keeping its content or freeing its slug for reuse.

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

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

Adds substantive behavior beyond the annotations: past scores and answers are retained, quota impact stops, future visibility runs skip it, and restore-prompt reverses it. This usefully tempers the destructiveHint=true flag by making clear the mutation is reversible and non-data-destroying, without contradicting it.

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 clauses, front-loaded with the action and its consequences. The trailing fragment "It keeps its topic" is terse to the point of ambiguity but does not bloat the description.

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

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

For a one-parameter, no-output-schema mutation, the description covers effects, retention, and reversibility well. Minor gaps: no statement of what happens when archiving an already-archived prompt (idempotency) or what the call returns.

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?

Single parameter with 100% schema description coverage, so the schema already carries the semantics. The description adds nothing about prompt_id (format, whether it must be an existing/active prompt), 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?

States a specific verb and resource ("Archive a prompt") and immediately distinguishes the operation from its inverse by naming restore-prompt. An agent can tell this apart from restore-prompt and from topic-management siblings without opening any schema.

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

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

Gives clear usage context: archiving removes the prompt from future visibility runs and quota counting, which is the condition under which you would choose it over simply leaving the prompt active. It names restore-prompt as the reversal path but never states an explicit exclusion (e.g., when to prefer removing a prompt from a topic 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 only cover the safety profile (readOnly, non-destructive, closed-world), and the description adds substantial behavior on top: cell scoring mirrors the Visibility page, runs are returned oldest first, the 40-cell ceiling, which inputs are rejected (unknown slice key, foreign topic_id, >4 runs), and the meaning of scopeTooSmall, noAnswers, notes/noteText, competitorsOmitted, and competitorSlice. That is exactly the extra context the annotations do not supply.

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?

Nearly every clause carries real information, and the hard limits come first. But it is delivered as one dense run-on paragraph mixing input rules, output semantics, competitor behavior, and error flags with no separation, which makes it slow to parse and pushes key operational facts into the middle.

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 5-parameter read tool with no output schema, the description covers everything an agent needs: valid input shapes, defaults, ordering, result layout, numeric ranges for AuraScore/Mention Rate/Share of Voice, and the degenerate cases (scopeTooSmall, noAnswers, scoring-rule notes). Nothing essential is left to guess.

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 3 is the baseline, but the description goes well beyond it: it explains that a run is a run id or a YYYY-MM-DD day resolved to that day's latest completed run in time_zone, that prompt_type values map to Branded/Non-branded/Competitor-branded with a non_branded default, that filters need keys and value slugs from list-prompt-filters, and that include_competitors covers the first slice, top 30 by the newest run's Rank.

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 gives a specific verb plus resource ('Compare 2-4 visibility runs across 1-20 slices in one table') and pins down the output shape (rows = slices, column groups = runs). It never mentions the nearby siblings (get-visibility-score, get-visibility-summary, list-visibility-runs), so the agent must infer on its own that this is the multi-run comparison tool rather than the single-score 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?

Hard boundaries are stated clearly (2-4 runs, 1-20 slices, 40-cell cap, >4 runs rejected), which implicitly tells the agent when the call is valid. But there is no explicit when-to-use/when-not guidance and no routing to alternatives such as list-visibility-runs for discovering run ids or get-visibility-summary for a single run, so usage is implied rather than directed.

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

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

Adds substantial context beyond the annotations: side effects (joining the visibility run, consuming quota), two named failure modes (quota exceeded, duplicate prompt text), and the draft/active distinction. It stops short of describing what is returned (no output schema exists) or any auth constraints, which keeps it out of 5 territory.

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 sentences with no filler; the core action and scope lead, followed by the quota/dedup rules. Slightly compressed phrasing ('counts toward the prompt quota, so creation is refused at the quota') asks the reader to unpack a causal chain that could be stated more directly.

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 write tool with a nested filters object and no output schema, the description covers purpose, side effects, and rejection conditions well. The main gap is the return payload — an agent gets no hint about whether the created prompt ID or the auto-created topic is handed back.

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

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

With 100% schema description coverage, the schema already explains every parameter including the filters object and the status enum. The description adds no parameter-level meaning beyond noting that topic auto-creation happens, 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 ('Create a visibility prompt') plus the domain scope, and defines the domain-specific term ('the question PingAura asks AI engines on each run') so an agent unfamiliar with the concept still understands it. This clearly separates it from create-prompt-topic, archive-prompt, and update-prompt-filters.

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 usable conditional guidance: active prompts join the next run and count toward quota while drafts do neither, and the call is refused at quota or on duplicate text. It also implicitly routes topic creation here ('The topic is created if it does not exist'), though it never names an explicit alternative tool the way a 5 would.

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=false, destructiveHint=false, openWorldHint=false), so the bar is lower. The description earns credit by adding behavior beyond annotations: the topic is created empty (no prompts attached) and names are unique per domain case-insensitively, which lets an agent predict duplicate-name failures. It stops short of stating the actual error or conflict response.

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

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

Two short sentences, zero filler, with the action and scope front-loaded and the uniqueness constraint following. Nothing could be removed without losing meaning.

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

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

For a simple two-parameter create tool with full annotation coverage this is close, but there is no output schema and the description never says what comes back — notably whether the new topic's ID is returned, which an agent would need to chain into create-prompt or move-prompt-to-topic.

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 real semantics on top by specifying that 'name' is unique within a domain and compared case-insensitively, and that 'domain_id' scopes the topic to exactly one domain. That is more than the schema's bare 'Topic name' / 'Domain ID' labels.

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 ('Create an empty prompt topic') scoped to 'one domain,' which distinguishes it from create-prompt (which presumably attaches a prompt). It does not explicitly differentiate from update-prompt-topic or list-prompt-topics, but the create semantics 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?

Usage is only implied: the 'empty' qualifier and the per-domain uniqueness rule hint at when this is the right call (bootstrapping a grouping before adding prompts), but no alternative is named and no prerequisite or when-not condition is stated. An agent must infer the workflow from 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 flag destructiveHint=true, so the description's job is to define the blast radius, and it does precisely that: past results survive in completed runs, future runs stop scoring, and domain prompts are relabelled. This is exactly the context an agent needs before committing an irreversible-looking action.

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, action first and consequences second, with zero filler. Every clause conveys distinct information about the operation's effect.

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

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

For a one-parameter destructive tool with a full safety annotation set and no output schema, the description covers the important unknowns (retention and downstream relabelling). It stops short of stating the return value or idempotency behavior for repeated calls.

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

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

Schema coverage is 100% for the single competitor_id UUID parameter, so the schema carries the definition and baseline 3 applies. The description adds nothing about the identifier, such as where to obtain a valid one or whether an unknown ID errors.

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?

"Stop tracking a competitor on its domain" is a specific verb plus resource and corrects the natural assumption that a delete destroys data. It does not contrast itself with update-competitor or add-competitor, so the agent must infer the boundary from names alone.

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 consequence clause implies when this is appropriate (permanently stop scoring a domain), but there is no explicit "use this when / use update-competitor instead when" routing and no preconditions such as needing the ID from list-competitors. Usage is inferable 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 declare destructiveHint=true, so the description's job is to add operational context. It does so usefully by disclosing that archived prompts still occupy a topic, a non-obvious constraint that would otherwise cause failed deletes.

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 action and immediately followed by the blocking condition. The clause after the colon clarifies rather than repeats, so 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?

For a two-parameter destructive tool with annotations covering safety, this is nearly complete. The main gap is that it doesn't explicitly say the deletion is irreversible or what happens on success, though destructiveHint carries most of that burden.

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 both UUID parameters are documented in the schema. The description adds no parameter-level detail beyond what the schema already provides, which is the expected 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?

States a specific verb and resource: 'Delete a prompt topic.' The resource name itself separates it from archive-prompt, restore-prompt, and update-prompt-topic, but it does not explicitly contrast with those siblings.

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

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

Gives a concrete precondition for use: the topic must be empty of prompts, archived ones included. It does not name the alternative workflow (e.g., move or archive prompts first), so the routing guidance is clear but not exhaustive.

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 agent knows this mutates state. The description adds useful gate context (decisions block page approval) but never says whether a recorded disposition is final, overwritable, or what it destroys — the key question for a destructive-hinted call.

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 action, then the workflow constraint, then the dependency. No filler and no repetition 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 three-parameter mutation tool with no output schema, it covers purpose, gating rule and index source adequately. It stops short of describing the resulting page state or whether re-deciding is permitted, which matters for a destructive-flagged 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?

Schema coverage is 100%, so the baseline is 3, but the description adds provenance the schema lacks: claim indexes come from get-hosted-page, telling the agent where to obtain claim_index rather than guessing. It does not elaborate on disposition semantics beyond the enum, which the schema already documents.

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

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

States a specific verb and resource: record a decision about one flagged claim on a hosted page. It is unambiguously distinct from get-hosted-page (which supplies indexes) and from reject-hosted-page, which the description implicitly contrasts by scoping the action to a single claim.

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 trigger conditions and a workflow prerequisite: every flagged claim must be decided before the page can be approved, and indexes come from get-hosted-page. It does not state whether the disposition can be changed later or how it relates to whole-page rejection, so 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.

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false; the trailing 'Read only.' merely restates readOnlyHint. It does add value by enumerating the returned fields, which the agent otherwise wouldn't know since there's no output schema. No mention of permission requirements, error behavior, or what happens when no active subscription 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?

A single front-loaded sentence delivers the resource and returned fields with no waste. The appended 'Read only.' is redundant with readOnlyHint and is the one component that doesn't earn 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 carries the burden of describing return values, and it does so by naming the five fields returned. That is sufficient for a zero-parameter read tool; only edge-case behaviour (no subscription, missing slug) is left 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. The description correctly signals the no-argument nature by describing the response rather than any inputs.

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

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

States a specific verb (get) and a precise resource (the connected workspace's account info), then enumerates exactly which fields come back: name, slug, creation date, subscription status and billing period. No sibling tool covers this resource, so the agent can distinguish it from the long list of get-*/list-* tools immediately.

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

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

Usage is only implied: an agent infers this is the tool to call for workspace/account metadata because no sibling overlaps. There is no explicit when-to-use statement, no preconditions (e.g. auth/scope needed), and no named alternative. Adequate but leaves the agent to reason 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 adds meaningful value beyond the annotations by enumerating exactly what the response contains: title, slug, status, keywords, Markdown body, meta description, summary, word count, and publication location. Since there is no output schema, this return-content disclosure is important. 'Read only' merely restates the readOnlyHint annotation and adds little, but the field list carries the 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 definition is a single front-loaded sentence that immediately states the core action. The field enumeration is somewhat long but earns its place by compensating for the absence of an output 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 simple read-only, single-parameter tool with clear annotations, the description is largely complete. It compensates for the missing output schema by naming the returned fields, though it does not mention error behavior such as an invalid or missing article_id.

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

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

There is one required parameter, article_id, with 100% schema description coverage. The schema already identifies it as the Article ID, and the description does not add format or usage detail beyond that. Baseline 3 is appropriate when the schema fully documents the only 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 states a specific verb ('Get') and resource ('one article in full'), making the tool's purpose immediately clear. It implicitly distinguishes itself from list-articles by emphasizing a single article and a full field set, though it does not name the 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?

Usage is implied by 'Get one article in full,' which suggests retrieving a single record versus listing. However, there is no explicit guidance on when to use this tool instead of list-articles, nor any stated prerequisites or 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 cover the safety profile (readOnlyHint true, openWorldHint false, destructiveHint false), so the bar is lower. The description adds genuinely non-structured context: results are scoped to a single audit and are pre-sorted by impact, and each returned record carries severity, category and an issue_fingerprint. It does not mention pagination behavior or what happens with an empty/invalid audit.

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, both earning their place: the first establishes scope and sort order, the second establishes the return record shape and links to the downstream mutation tool. 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?

There is no output schema, and the description partially compensates by naming the fields present on each issue and the ordering, which is what an agent needs to chain into update-issue-status. It stops short of covering pagination limits or how filtering interacts with 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% with enums on category and severity, so the schema does the heavy lifting. The description only alludes to severity and category as output field concepts rather than explaining them as filters, and says nothing about the limit/paging parameter. 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 ('Get the issues found in one site audit') plus an ordering guarantee ('highest impact first'), which is far more than a restatement of the name. It does not explicitly distinguish itself from siblings like list-site-audits or get-site-health-summary, but the resource is narrow enough that confusion is unlikely.

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

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

Usage is only implied: an agent can infer this belongs after run-site-audit or list-site-audits, and the mention of issue_fingerprint feeding update-issue-status is a helpful workflow pointer. However, there is no explicit when-to-use, when-not-to-use, or named alternative such as get-site-health-summary for aggregated views.

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 useful content context (which fields come back) and the resource comparison, but says nothing about behavior on an unknown/nonexistent domain_id or response size.

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 filler, with the payload contents and the alternative-view note front-loaded. 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?

With no output schema, the description at least names the notable returned fields, and the read-only nature is covered by annotations. Complete enough for a one-parameter lookup, though error/missing-resource behavior is unaddressed.

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

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

Schema coverage is 100% for the single required domain_id parameter, so the schema already carries the semantics. The description adds no format, sourcing, or lookup guidance beyond what the schema states, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Get full details for a specific domain') and enumerates the payload contents (icon_url, brand_aliases, sitemap scan state). It does not explicitly name list_domains as the collection counterpart, so sibling differentiation is only implied by 'a specific domain'.

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 a routing hint by contrasting this tool with the lighter pingaura://domains/{domainId} resource view of the same domain, which tells the agent when the heavier call is warranted. It gives no explicit exclusions or error conditions.

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 real value by disclosing the shape of the payload — body, supporting evidence, and fact-check-flagged claims — which the annotations cannot convey. It omits not-found/error behavior and permission requirements.

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 front-loaded sentence with a verb, a resource, and a payload summary; no filler and nothing trailing that an agent must wade through.

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 one required parameter, full schema coverage, and no output schema, the description usefully compensates by describing what is returned. The only gap is that it doesn't tell the agent how to obtain a page_id or what happens for an unknown ID.

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

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

Schema description coverage is 100% for the single page_id parameter, so the baseline is 3. The description does not add anything about the parameter beyond the schema — notably it never says the UUID comes from list-hosted-pages, which would have been the useful addition.

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 ("Get one hosted page") and enumerates what the record contains (body, evidence, flagged claims), which clearly separates it from list-hosted-pages and from the other get-* tools. It stops short of naming the sibling to use for discovery, so it is clear but not maximally differentiated.

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 singular "one hosted page" implies a fetch-by-ID lookup versus a list operation, but the description never states when to use this instead of list-hosted-pages, nor where a valid page_id comes from. Usage is inferable 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 declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds that the record is scoped to the domain's connected account and lists the returned metadata, but says nothing about the no-account-connected case or any error behavior — useful but not rich context.

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

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

A single front-loaded sentence that identifies the resource and then enumerates the fields, with no filler. Nothing could be removed without losing information.

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

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

There is no output schema, so naming the returned fields (id, name, currency, timezone, preview URL) is exactly the right compensation for a one-parameter read. Only the missing edge-case behavior (no ads account for the domain) keeps it from full marks.

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

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

Schema description coverage is 100% and the single parameter is documented in the schema, so the baseline is 3. The phrase 'connected to a domain' hints that domain_id selects the owning domain, but it adds no format, lookup, or failure semantics beyond what the schema already states.

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

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

Specific verb ('Get') plus precise resource ('account-level metadata for the ChatGPT Ads account connected to a domain') and an enumeration of returned fields. It is clearly distinguishable from the list-openai-ads-campaigns / ad-group siblings, though it never explicitly contrasts with the similarly named get-account-info.

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

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

Usage is only implied: the caller needs the ChatGPT Ads account record for a domain. No when-to-use/when-not guidance and no mention of the closest alternative (get-account-info) or of what happens if no ads account is connected to the domain.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the metric vocabulary and the grain behavior of aggregation_level (one row per campaign/ad group/ad), but says nothing about row limits, pagination, or what identifiers accompany each row — moderate added value over the annotations, 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 dense sentences with no filler; the core capability and metric set are front-loaded, and the grain caveat follows immediately. Nothing is repeated redundantly with the title.

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

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

For a 7-parameter read tool with no output schema, the description lists the metrics but not the shape of returned rows (which dimension keys appear per grain, whether limit truncates, how sort interacts with grain). Adequate to call the tool, but incomplete about what comes back.

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 7 parameters (including enum values and defaults for aggregation_level and time_granularity) are already documented. The description only re-mentions the metric names and the effect of aggregation_level, adding little syntax or semantics the schema lacks — 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 ('Get account-level insights') and enumerates the metrics returned (spend, impressions, clicks, CTR, CPC, CPM) plus the date-range scoping. It stops short of explicitly distinguishing itself from the sibling insights tools (get-openai-ads-campaign-insights, get-openai-ads-ad-group-insights), and in fact hints that this tool can produce campaign/ad-group rows, which muddies rather than sharpens the boundary.

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

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

Usage is only implied: the agent can infer this is the account-rollup variant, and the second sentence explains that aggregation_level changes the row grain. But there is no explicit 'use this instead of X when Y', no mention of the default grain's relationship to the per-entity insights siblings, and no stated 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?

The annotations already establish that this is a read-only, non-destructive operation in a closed world. The description adds that the response includes the ad creative, which is useful return-content context, but it does not address not-found behavior, permissions, or other operational details.

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

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

A single, front-loaded sentence with no filler. Every element ('single', 'by ID', 'including creative') contributes 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 simple two-parameter read tool with full schema coverage and annotations covering the safety profile, the description is nearly complete. It states the resource, lookup key, and a notable return attribute; only edge-case behavior such as missing IDs is omitted.

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%: both required parameters (domain_id and ad_id) are documented in the schema. The description reinforces that lookup is by ad ID but adds no format, constraints, or domain-scoping detail beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description gives a specific verb and resource ('Get a single ChatGPT Ads ad by ID') and adds that the creative is included. The word 'single' implicitly contrasts with the sibling list-openai-ads-ads, and 'including creative' suggests it returns more than the insights siblings, but 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?

The 'by ID' phrasing implies this is for fetching an already-known ad rather than listing or analyzing ads, but there is no explicit statement of when to use this versus list-openai-ads-ads or get-openai-ads-ad-insights, and no exclusions are given.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered elsewhere. The description adds nothing beyond that — no error behavior for a missing ID, no note on what happens with an ad group in another domain, no auth or scoping notes.

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 front-loaded sentence with no filler, which is appropriate for a simple lookup. It is perhaps too terse to earn credit for structure that anticipates 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?

There is no output schema, so the description should describe what a returned ad group looks like, but it does not. For a fetch tool with two required parameters and no return-value documentation anywhere, this leaves a significant 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 both domain_id and ad_group_id are documented in the schema. The description only echoes the ID lookup, adding no format, scoping, or relationship detail beyond the schema.

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

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

States a specific verb and resource ('Get a single ChatGPT Ads ad group by ID'), which is clear on its own. However, it never distinguishes itself from the closely named siblings like list-openai-ads-ad-groups or get-openai-ads-ad-group-insights, so an agent must infer the difference.

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 single-fetch tool versus the list endpoint or the insights variant. The reader gets no context, exclusions, or alternatives; usage is only implied by 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, openWorldHint=false, so the safety profile is fully covered and the description doesn't repeat it. It adds the date-range scoping context, but says nothing about row shape, defaults, or how the grain/granularity controls change what comes back — for an analytics read tool that is the most decision-relevant behavior and it is left to the schema.

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

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

One short sentence, front-loaded with the verb and the scoping constraint, with zero filler. It is efficient but arguably under-built for an 8-parameter analytics tool rather than genuinely tight.

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

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

There is no output schema, so the description carries some burden for describing what comes back, yet it doesn't mention that results default to a single ad_group rollup row unless aggregation_level or time_granularity is changed. Combined with no sibling routing, this leaves real gaps for an 8-parameter tool, even though the schema itself is fully documented.

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 aggregation_level and time_granularity are already documented in the schema. The description adds nothing beyond the required-parameter set it implies, which is the expected 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?

States a specific verb (Get insights) and resource (ad group) with a clear scope qualifier (single ad group, date range). The word 'single' implicitly contrasts with the account/campaign/ad siblings, but it never names them, so an agent must infer the distinction.

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 or when-not guidance. An agent picking among get-openai-ads-account-insights, campaign-insights, ad-insights, and this tool gets only the prepositional scope difference in the name; the description never says to choose this one when you already have an ad_group_id, or to fall back to campaign-level otherwise.

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 closed-world, so the safety profile is covered. The description adds the date-range and single-ad scoping constraint, but says nothing about pagination, default limits, or what the rollup vs daily grain produces.

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 well-formed sentence with the resource and scoping constraint front-loaded and zero filler. Nothing could be cut.

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 rich schema coverage, annotations, and no output schema, the description covers what's needed to invoke correctly. The only mild gap is not indicating what insight rows/metrics are returned, though the sort field examples hint at the metric set.

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 7 params (including sort directives and time_granularity) are already documented in the schema. The description adds no meaning beyond that, 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 a specific verb (get insights) and resource (a single ad), and its scoping language distinguishes it from the campaign- and ad-group-level insight siblings. It stops short of naming those alternatives explicitly, so it's clear but not fully differentiated.

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

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

The phrase 'scoped to a single ad' implies this is the per-ad drill-down versus the campaign/ad-group variants, but there's no explicit when-to-use or when-not guidance. An agent must infer the choice from sibling names.

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 beyond them by enumerating the returned fields (budget, schedule, status, targeting), which matters because no output schema exists.

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

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

A single sentence with zero filler, front-loaded with the verb and resource and ending on the useful payload list. Nothing could be removed without losing information.

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

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

With annotations covering safety and the description listing the payload fields in lieu of an output schema, an agent has what it needs to call this correctly. The main omission is any statement of how it relates to the sibling list/insights tools.

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 domain_id and campaign_id are already documented in the schema. The description's 'by ID' reinforces the lookup key but adds no format, scoping, or error behavior 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 ('Get a single ChatGPT Ads campaign by ID') and enumerates the payload (budget, schedule, status, targeting). The word 'single' plus 'by ID' implicitly separates it from list-openai-ads-campaigns and get-openai-ads-campaign-insights, but neither sibling is named.

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

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

Usage is only implied: the agent must infer that this is the right call when it already holds a campaign_id. There is no explicit statement of when to prefer list-openai-ads-campaigns or get-openai-ads-campaign-insights, and no prerequisites (e.g. that domain_id must be resolved first) are mentioned.

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

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

The annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is clear. The description adds that aggregation_level changes the row grain to one row per ad group or ad, which is useful behavioral context. It does not explain pagination, default row behavior beyond the schema, or output metric shape, so it remains moderate.

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 tight sentences with the campaign/date-range scope front-loaded. The second sentence adds only relevant row-grain context about aggregation_level, 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?

The tool has 8 parameters, 4 required, and no output schema. The description covers scope and aggregation grain, and the schema richly documents parameters. However, with no output schema, the description does not describe what insight metrics or response structure the agent should expect, leaving a meaningful completeness 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%, including detailed descriptions for since, until, limit, sort, time_granularity, and aggregation_level. The description mentions aggregation_level behavior, but the schema already documents that parameter and the enum values. The baseline of 3 is appropriate because the schema carries most parameter semantics.

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

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

The description states a specific verb and resource: get insights scoped to a single campaign over a date range. It also clarifies row grain via aggregation_level, helping distinguish campaign-level retrieval from broader account or ad-group retrieval. It does not explicitly name sibling tools like get-openai-ads-account-insights or get-openai-ads-ad-group-insights, so it stops short of full sibling differentiation.

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

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

The phrase 'scoped to a single campaign' implies when this tool is appropriate, and the aggregation_level note implies that ad-group/ad rows can be obtained without switching tools. However, there is no explicit when-to-use guidance, no exclusions, and no named alternative for account-level or dedicated ad-group/ad-level insight retrieval.

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 non-destructive, so the safety profile is covered. The description still adds real behavior: that results are paged, that `total` is the full match count while a single page is not the full set, and that non_branded counts unclassified prompts toward the headline — non-obvious semantics worth stating.

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

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

Three tight sentences, each carrying distinct load: purpose, classification semantics, and pagination contract. The pagination caveat is stated in the same breath as the mechanism, not buried.

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 takes on return-value explanation and does so for the paging envelope and the prompt_type field. It stops short of describing the visibility_score field or row shape more broadly, but that is a minor gap for a read-only list 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 coverage is 100%, so the baseline is 3; the description goes beyond by explaining the prompt_type taxonomy and how unclassified folds into non_branded, which directly affects filter results. It does not add syntax detail for `attributes` or `order`, which the schema already handles.

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 ('Get visibility scores for tracked prompts/queries'), which distinguishes it from the aggregate siblings get-visibility-score and get-visibility-summary by implying per-prompt rows. It never names those siblings explicitly, so the differentiation is inferential rather than stated.

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 prompt_type and paging notes give useful context for how to consume results, but there is no explicit 'use this when… / use get-visibility-summary instead' guidance. An agent must infer from the sibling names which endpoint serves the aggregate versus the per-prompt view.

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 a closed-world scope, so safety is covered. The description adds genuine behavioral context beyond that: it discloses the return shape (used, limit, remaining per quota) and the important edge case that a null limit means unlimited, which prevents an agent from misreading null as zero or missing data.

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

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

Two tight sentences: the payload-shape statement comes first, followed by the null-limit caveat. Every clause earns its place — the quota enumerations and the billing-period note all carry information an agent needs to interpret the response.

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 nearly complete: it names the returned fields, the quota categories and the null semantics. It stops short of noting freshness/caching or whether an unsubscribed account errors versus returns zeros, but those are minor gaps for an otherwise self-explanatory read.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. The parenthetical definitions of each quota type (e.g. articles counted for 'this billing period') are a bonus, though they describe outputs rather than inputs.

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

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

States a specific verb ('Get') and resource ('quota usage') and then enumerates the exact quotas covered (prompts, articles, site audits, chat messages), so an agent knows precisely what this returns. No sibling tool overlaps this account-level quota read, and the description makes that scope 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?

Usage is only implied: the description makes clear it's a quota/billing-period inspection call, but never states when an agent should reach for it (e.g. before creating prompts or articles to check headroom) or what alternative to use for related billing data. Adequate but with no explicit when-to-use guidance or 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 destructiveHint=false, so safety is covered. The description adds genuinely useful behaviour beyond that: which severity buckets always appear (critical/high/medium/low, zero when none) and that the aggregate spans the 5 most recent completed audits, which explains freshness and shape. It stops short of noting caching or how the window is recalculated.

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

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

Two sentences, front-loaded with what is returned and the aggregation window, then a pointer to the raw-data resource. Every clause carries information; nothing is padding.

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

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

No output schema exists, so the description has to describe the return value, and it does: total counts plus a fixed four-bucket severity breakdown. For a one-param read tool with annotative safety coverage, that is nearly sufficient; only freshness/refresh semantics and multi-domain behaviour are left unspecified.

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

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

There is a single parameter and schema description coverage is 100%, so the schema already documents domain_id as a UUID domain identifier. The description only restates the domain scoping ('for a domain') without adding format, defaulting, or error behaviour. With one fully documented param, 3 is the appropriate 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?

States a specific verb and resource: a computed health aggregate for a domain, with total issue counts and a per-severity breakdown. It also names the aggregation window (5 most recent completed audits), so an agent knows this is a roll-up rather than a raw listing. It never names a sibling like get-audit-issues or list-site-audits to sharpen the boundary, so it lands at 4.

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

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

Usage is implied by the phrase 'computed aggregate' versus the pointer to pingaura://domains/{domainId}/health for raw audit metadata, which suggests when to look elsewhere. There is no explicit when-to-use / when-not-to-use statement and no mention of get-audit-issues as the per-issue alternative, so the agent must infer the 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 establish read-only, non-destructive, closed-world behavior, and the description adds substantial context on top: figures are backed by the same selection as the dashboard, score and share_of_voice are null when the scope has nothing to score, and scope.run_id is null for a date window. This is behavior 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 purpose and the get-prompt-scores exclusion are front-loaded, and the remaining sentences carry real information about return fields, defaults, and scope precedence. It is dense and long for a single paragraph, but almost nothing is filler.

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

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

For a 9-parameter tool with nested filters and no output schema, the description supplies the return-field mapping (score/coverage/share_of_voice/mentions/counts) and null-case semantics, which is exactly the missing piece. An agent has enough to call it correctly and interpret the response.

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 meaningfully extends it: the prompt_type taxonomy (non_branded excludes us and competitors, branded names only us, competitor_branded names a competitor) and the rule that each prompt belongs to exactly one segment are semantic content absent from the schema. Scope precedence and filters validation are partly duplicated from scheme descriptions, which keeps this short of a 5.

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

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

The opening sentence names a specific verb and resource ('get the exact visibility score') and enumerates the scope axes (prompt type, topic, filters, engine, run or date window). It also explicitly distinguishes itself from get-prompt-scores, stating that per-prompt scores do not average into the scoped figure.

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 scope resolution precedence is spelled out in full (run_id > run_date > latest_run > last `range` days with a 15d default), and the description routes agents to list-prompt-filters for valid filter keys and to compare-visibility-runs for run/slice comparisons. It even states a negative condition: filters with undeclared keys are rejected.

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 far beyond the readOnly/OpenWorld/Destructive hints, which already establish a safe read. It discloses non-branded vs branded vs competitor_branded scoring semantics, null-handling for older runs, the meaning of null geo in an engine entry (no data, not zero), what coverage counts, and default competitor trimming with competitors_omitted. That is exactly the context an agent needs to interpret the response.

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

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

Front-loads the purpose and return shape in one sentence, then spends the rest on field semantics. It is dense and a single paragraph where bullets could improve scanability, but nearly every sentence carries non-obvious information, particularly given the absent output 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?

With no output schema and only two parameters, the description must carry the response semantics, and it does: it enumerates the score families, null conditions for pre-split runs, per-engine null behavior, and coverage counting scope. An agent can interpret a returned object without further docs.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning: run_id provenance from list-visibility-runs and a fuller explanation of the detail default, including the 10-highest-plus-tracked-brand cap and competitors_omitted. Slightly redundant with the detail schema description but reinforces the cost tradeoff.

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 ('Get the visibility summary for a specific run') and names the return shape (scores, coverage %, engine breakdown, competitor comparison). It points to list-visibility-runs as the source of run_id, but does not explicitly distinguish this tool from get-visibility-score or compare-visibility-runs.

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?

Clearly tells the agent where run_id comes from (list-visibility-runs) and warns that detail 'full' returns every list and can be very large, giving a concrete case for choosing 'compact' vs 'full'. No explicit when-not or sibling alternative guidance beyond that.

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, destructiveHint=false, openWorldHint=false), yet the description still adds ordering behavior and a concrete inventory of returned fields versus the omitted body. Only 'Read only.' merely restates 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, front-loaded sentence carries scope, ordering, filter and return shape; the trailing 'Read only.' is redundant with readOnlyHint and is the only wasted clause.

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 compensates by enumerating the row fields and flagging that the body is excluded. It leaves unaddressed what happens when more than limit (max 50) articles exist, since there is no offset/cursor parameter.

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 three parameters are already documented. The description reinforces that domain_id scopes to a single domain and repeats the status enum values, but adds no new syntax or limits (e.g. that limit is capped at 50) 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 and resource (list articles), scopes it to one domain, declares ordering (newest first), and names the optional status filter. It is clearly distinguishable from get-article (single, full body) and the other list-* 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 status filter values and 'newest first' ordering make the intended browsing use case clear, and the note that rows exclude the body implicitly routes the agent to get-article when full content is needed. It stops short of explicitly naming that alternative or stating 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, destructiveHint=false and openWorldHint=false, so "Read only." adds nothing. The one piece of genuine added context is that display name and aliases govern which AI answers count as a mention — useful semantics, but nothing about unknown-domain behavior or result size/pagination.

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

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

Front-loaded with the operation and payload, three short sentences, no filler. The trailing "Read only." is redundant with annotations and is the only sentence not earning 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-parameter read tool with full annotation coverage, the description covers purpose, scoping and the returned fields, which is enough given there is no output schema. Missing only edge-case behavior (empty list, invalid domain id).

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?

Single parameter with 100% schema coverage, so the schema already fully documents it. "for one domain" reinforces the scope but adds no format or sourcing detail beyond the schema's uuid-typed "Domain ID".

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

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

Specific verb and resource ("List the competitor domains tracked for one domain") plus the exact fields returned (id, display name, aliases). It is clearly distinguishable from add-competitor/update-competitor/delete-competitor by the "List" framing, though it never names them explicitly.

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

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

"tracked for one domain" implies the tool is scoped to a single domain and is the read path versus the add/update/delete siblings, but the description never states when to use it over alternatives or any prerequisite (e.g., that the domain must already exist / the id comes from list-domains).

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 carry readOnlyHint=true, openWorldHint=false, destructiveHint=false, so the safety profile is covered; the description's 'Read only' is largely redundant but harmless. Its value-add is disclosing the shape of the response (the six returned fields), which is meaningful given no output schema exists. No pagination or result-size behavior is mentioned, keeping it below 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 primary action and the returned fields before the usage note. The field enumeration is long but earns its place since no output schema documents the response.

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 compensates by naming the returned fields, and the read-only nature is stated. Minor gaps: no mention of ordering, pagination, or behavior with zero domains tracked, which an agent might care about for a list 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 takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; the description does not waste space inventing parameter guidance.

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

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

Specific verb ('List') plus resource ('domains tracked in the connected PingAura workspace'), and it enumerates the attributes returned (id, name, verification status, industry, target geography, sitemap scan state). The line 'Every other domain tool takes one of these ids' distinguishes it from get-domain and other domain-scoped siblings 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?

'Every other domain tool takes one of these ids' implicitly tells the agent to call this first to obtain ids before using domain-scoped tools. It stops short of an explicit when-not or naming a specific alternative, but the usage context is clear enough to act on.

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 only a hint that results are tied to a review queue; it says nothing about pagination behavior, default limit of 25, default status of 'all', or whether the queue info is part of the payload.

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

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

A single short sentence with no filler, and the core resource is front-loaded. The trailing 'and the review queue they sit in' clause is slightly vague rather than wasteful, so it just misses 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 should clarify what a result looks like (page fields, queue grouping, pagination), and it only gestures at 'the review queue'. For a simple 3-parameter read tool this is adequate but leaves the agent guessing about the return shape and result volume.

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 status enum already carries detailed semantics (including the 'awaiting_review' alias and the absence of a 'rejected' status), so the schema does the heavy lifting. The description adds no extra meaning about domain_id, limit, or status beyond what the schema states.

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 verb ('List') and resource ('the pages written for a domain'), so the basic operation is clear, but it never distinguishes hosted pages from the very close sibling 'list-site-pages' (or 'list-articles'), and the phrase 'the review queue they sit in' is ambiguous about whether a queue object is returned or just a grouping.

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 choose this over list-site-pages, get-hosted-page, or the workflow siblings (reject-hosted-page, retire-hosted-page, request-hosted-page-regeneration). The agent must infer usage entirely from the name and the enum in the schema.

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 that returned records carry status and bidding config, which is useful since there is no output schema, but says nothing about page-size behavior, cursor semantics, or whether results are complete without paging.

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

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

A single front-loaded sentence with no filler; the resource, its parent scope, and the returned fields are all in the first clause set. 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?

For a read-only list tool with full schema coverage and no output schema, the description gives enough to call it correctly and hints at return contents. The only gap is that pagination and result-set behavior are left entirely to the schema.

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

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

Schema description coverage is 100%, so all six parameters are documented in the schema itself, and the description only restates the campaign scoping. No added meaning beyond the schema (e.g., expected ID formats or cursor reuse rules), 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 ('List ad groups') plus the scoping parent ('belonging to a ChatGPT Ads campaign') and the payload hints ('status and bidding config'). This distinguishes it in practice from list-openai-ads-ads and list-openai-ads-campaigns, though it never names those siblings 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?

No guidance on when to use this versus get-openai-ads-ad-group (single item) or list-openai-ads-ads (child ads), and no mention of pagination workflow despite two cursor parameters. Usage is only inferrable from the phrase 'belonging to a campaign'.

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 value beyond that by naming the returned fields (creative, status, review_status), which matters because there is no output schema. It says nothing about pagination or result volume, leaving that entirely to the schema.

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

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

A single front-loaded sentence naming the action, the parent resource, and the returned fields. No filler, no repetition 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 read-only, 6-parameter list tool with full schema coverage and annotations, the description covers scope and the key returned fields. Missing only a note on pagination behavior and whether the list is bounded, which are minor given the cursor parameters are documented in the schema.

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

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

Schema description coverage is 100%, so every parameter (domain_id, ad_group_id, after, before, limit, order) is documented in the schema itself. The description only implies the ad_group_id scoping and adds no format, range, or capping detail. Baseline 3 is appropriate when the schema does all the work.

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

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

States a specific verb (List) and resource (ads) and scopes it to a ChatGPT Ads ad group, which separates it from get-openai-ads-ad (single) and list-openai-ads-ad-groups/campaigns. It does not explicitly name those siblings, so the differentiation is inferable rather than stated.

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 parent-scoped phrasing implies you call this when you have an ad_group_id and want its ads, but there is no explicit when-to-use/when-not guidance and no pointer to alternatives such as get-openai-ads-ad for a single ad. Usage is inferable from the description only.

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 the returned field set but says nothing about pagination behavior despite after/before cursors in the schema, nor about default ordering or result caps.

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 well-formed sentence with the resource and scope front-loaded and zero filler. Nothing could be removed without losing information.

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

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

With no output schema, the description usefully lists returned attributes, and the schema fully covers parameters. The remaining gap is pagination/ordering behavior, which an agent must infer from the cursor fields alone.

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 limit, order enum, and cursor parameters all documented in the schema itself. The description contributes no additional parameter meaning, 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 gives a specific verb and resource ('List campaigns') scoped to the connected ChatGPT Ads account, and enumerates the returned fields (status, schedule, budget, targeting). It is clearly distinct from get-openai-ads-campaign (singular) and list-openai-ads-ad-groups, though it never names those siblings 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?

Usage is implied by the plural 'List' verb and the account scoping, but there is no explicit when-to-use, when-not, or pointer to sibling listing tools such as list-openai-ads-ad-groups. An agent can infer the intent but gets no routing guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing the empty-result condition: `attributes` comes back empty when the plan excludes custom filters or the domain declares none — an important outcome an agent would otherwise misread as an error.

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

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

Three tight sentences: what is returned first, then how the output connects to get-prompt-scores, then the empty-state caveat. Every sentence carries information an agent needs, and nothing is repeated from the schema or annotations.

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

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

For a single-parameter read-only list tool with no output schema, the description covers return shape (key, label, value slug, label) and the empty-state edge case. Nothing essential is missing to invoke it correctly or interpret the result.

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

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

Schema coverage is 100% with the single domain_id parameter documented as a UUID, so the schema carries the burden. The description implies domain scoping ("the custom filters a domain declares") but adds no format or constraint 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 and resource ("List the custom filters a domain declares") and enumerates the returned shape: key, human label, and valid values as value slug plus label. The agent can tell this is a read-only metadata listing distinct from the sibling mutation tools set-prompt-filter-definitions and update-prompt-filters.

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 downstream context: get-prompt-scores filters `attributes` by these value slugs, which tells the agent when to call this first. It does not explicitly contrast with update-prompt-filters or set-prompt-filter-definitions, but the usage context 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?

The annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that results include ids and are sorted by name, but it does not mention pagination, permissions, error behavior, or whether results are scoped to existing domains.

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 with no filler. It efficiently communicates the verb, resource, domain scope, returned ids, and sort order.

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

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

For a simple one-parameter read-only list tool, the description covers scope and return shape sufficiently for an agent to invoke it. Because there is no output schema, stating that ids are returned and sorted by name is valuable; only minor details such as pagination or empty-result behavior are missing.

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

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

There is one parameter, domain_id, and schema description coverage is 100%, so the schema already documents it adequately. The description adds the domain-scoping context but no format or validation details beyond what the schema provides, making 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 states a specific verb (List), resource (prompt topics), scope (of a domain), and return detail (ids, sorted by name). It clearly distinguishes this read-only enumeration from siblings such as create-prompt-topic, update-prompt-topic, delete-prompt-topic, and move-prompt-to-topic.

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

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

The description implies this tool is used to retrieve prompt topics for a given domain, but it does not explicitly state when to use it versus alternatives like list-prompt-filters or list-domains. Usage is understandable from the context but lacks explicit exclusions 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 readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds real value beyond that by disclosing sort order and the exact fields each audit returns, though it says nothing about pagination or how limit interacts with ordering.

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 filler, with the resource and ordering front-loaded before the return-field summary. Every clause carries information an agent can use.

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, enumerating the returned fields (scores, PingAura, issue count, Lighthouse mobile/desktop, CWV status) is exactly the right compensation. Minor gap: no note on result paging or whether limit caps the newest-first window.

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 domain_id and limit are already documented in the schema. The description mentions 'for a domain' but adds no format, default, or range detail beyond structured fields, matching the baseline 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?

States a specific verb and resource ('List site health audits for a domain') plus ordering ('newest first') and per-audit scope ('one page'). The enumerated return fields make it obvious how this differs from get-audit-issues or get-site-health-summary.

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

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

Usage is implied by the name and description (browse audits for a domain), but there is no explicit when-to-use guidance and no named alternatives, even though siblings like get-audit-issues and run-site-audit sit adjacent in purpose.

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 real behavioral context beyond that: results are scoped to one domain, sorted by URL, and carry tracked status, issue count, three score fields and last audit time – important since no output schema exists.

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

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

A single dense sentence with the scope front-loaded and no filler. The tail-end field enumeration is long but each item conveys return-value information that is otherwise unavailable.

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 carries the burden of describing the return shape, and it does so thoroughly. It omits pagination semantics and what an empty result means, which matter for a cursor-based list 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 all four parameters are documented in the schema. The description only echoes the domain scoping and never mentions the page_type filter or the cursor/limit pagination, adding nothing 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?

A specific verb ('List') plus resource ('the pages discovered for a domain') and an explicit enumeration of returned attributes, which distinguishes it from listing hosted pages or domains. It never names a sibling explicitly, so an agent must infer the boundary itself.

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 says nothing about when to use this versus list-hosted-pages, list-site-audits, or get-audit-issues, nor about when a page_type filter is appropriate. Usage is only implied by the verb and resource.

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

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

Annotations already mark it read-only and non-destructive, and the description adds substantial behavior: result ordering, what engine_shortfall means, that one_per_day filters to completed runs only, and a real limitation (at most 500 newest runs scanned, so results can fall short of `limit`). That truncation caveat is exactly the kind of non-obvious trait an agent needs.

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

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

Front-loaded with purpose and ordering, then modes, then the caveat — a sensible progression. The single dense paragraph is slightly long and the engine_shortfall aside could be tighter, but every sentence carries information.

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

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

With no output schema, the description still conveys the return shape (a list of runs, each with the engines it queried and a `day` when one_per_day is used) and the engine_shortfall field's meaning. Combined with annotations, an agent has enough to call it and interpret results 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, but the description goes further by explaining the semantics of one_per_day (completed runs, that day's latest, the run the Visibility page shows, inclusion of `day`) and how it interacts with `limit`. It says less about `time_zone` and `limit` bounds than the schema already does.

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 visibility analysis runs for a domain') plus ordering ('newest first'). It also names two siblings (get-visibility-score, compare-visibility-runs) and how their ids relate, so an agent can separate it from those tools without reading 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?

Explains the two modes: a plain newest-first list versus one_per_day for completed-run-per-day retrieval matching the Visibility page, and points to the downstream tools that consume those ids. It gives clear context but never states an explicit exclusion or 'do not use this when' condition.

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

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

Annotations already mark this as a non-readonly, destructive mutation. The description adds valuable behavioral context: text, scores, and history are preserved, while topic-level scores change going forward. It does not cover permissions, reversibility, or error behavior, so it stops short of a 5.

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

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

The description is two tightly written sentences with no wasted words. The core operation and the key preservation/score behavior are front-loaded.

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

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

For a simple two-parameter mutation with full schema coverage and no output schema, the description covers the essential effect of the move and what remains unchanged. It leaves minor gaps around reversibility and failure modes, but nothing critical for invocation.

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

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

Schema description coverage is 100%, so the prompt_id and topic_id parameters are already documented. The description confirms the conceptual roles of prompt and target topic but adds no format or validation detail beyond the schema.

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

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

The description states a specific verb and resource: move a prompt to another topic. It also adds the important scope constraint that the target must be in the same domain, which is enough to distinguish this from general prompt updates or topic updates.

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 use case is implied clearly by the operation itself, and the same-domain constraint is useful. However, it does not explicitly mention when to use this instead of update-prompt-topic or other prompt/topic management 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=false, destructiveHint=true and openWorldHint=true, so the safety profile is covered. The description earns credit by adding behavior beyond that: outbound CMS routing, the side effect of recording deployed_url for manual deployments, and the guaranteed local status/timestamp mutation in every case. It does not explain what the destructive aspect actually destroys (e.g., an existing live WP post being overwritten).

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 short sentences, front-loaded with the action and then ordered by the routing decision tree. Minor redundancy with the schema's own "Required when..." descriptions, but 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 return burden and largely discharges it by stating the resulting status and timestamp. It is still silent on the response payload shape, error behavior when routing fails, and the wp_status draft interaction, which leaves small gaps for a destructive, open-world 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 all four parameters are already documented, including the conditional conditions for target_provider and deployed_url. The description largely restates those conditions rather than adding new semantics, and it never addresses wp_status or how a "draft" WP post squares with the claim that local status is always set to "published". Baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource ("Publish an article") and immediately adds the distinguishing behavior: CMS auto-routing plus a local status transition to "published" with a timestamp. That is enough to separate it from update-article and archive-article, though those siblings are never named, so the contrast is inferred rather than stated.

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 three routing cases are laid out explicitly: exactly one integration means automatic routing, several means use target_provider, none means supply deployed_url. That is unusually clear conditional guidance. What is missing is any statement of when this tool is preferred over update-article (e.g., status-only changes) or any prerequisite/precondition.

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 destructiveHint=true, so the description doesn't need to prove this is a mutation; instead it adds real context the annotations can't express — the topic gets closed, discovery stops proposing the page, and an already-live page 'starts retiring'. It stops short of saying whether a rejection can be undone or what happens to an already-rejected page.

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

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

Two short sentences, zero filler, with the core action and its consequence front-loaded before the alternative is offered.

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, non-open-world mutation with a fully documented 2-param schema and no output schema, the description covers the key side effects and the main alternative. Reversibility and the reject-vs-retire distinction are the remaining holes.

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 both parameters are documented there (including that reason is recorded on the page and the gap). The description adds no syntax, format, or constraint 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 (reject) and resource (hosted page) plus the downstream effect on the topic, which is the distinguishing behavior. This lets an agent separate it from sibling mutations like retire-hosted-page or publish-article 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 a clear use condition ('so discovery will not propose it again') and explicitly names an alternative, request-hosted-page-regeneration, with the tradeoff ('keeps the topic and asks for a new version'). It omits the closest sibling, retire-hosted-page, so the agent gets no guidance on reject vs. retire.

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 flag destructiveHint=true; the description goes further by naming the actual destructive consequence — an already-live page begins retiring because a draft cannot be served — and the queue state of the topic. That is substantive context beyond the structured hints. It stops short of covering reversibility of the requested rewrite or the note's effect on scope.

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 clauses, front-loaded with the action, and each remaining sentence earns its place by disclosing a real side effect (queue retention, live-page retirement). 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 two-parameter mutation with a descriptive schema and destructive annotation, the description supplies the key operational fact an agent would otherwise miss: the live page gets retired. What it leaves out is comparative routing against sibling lifecycle tools and whether the regenerated draft replaces or forks the existing page.

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 both parameters are described there, so the baseline is 3. The description's 'carrying a note on what to change' only paraphrases the note field's own description and adds no format, length, or scope nuance. It does not compensate for anything the schema lacks, because the schema lacks nothing.

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

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

States a concrete verb+resource pair: 'Send a hosted page back to be written again, carrying a note on what to change.' Clear enough to act on without opening the schema. It does not name the nearby siblings (reject-hosted-page, retire-hosted-page, dispose-hosted-claim), so the differentiation burden is left implicit even though the verbs differ.

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

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

Usage is only implied: the page needs a rewrite, so request it. There is no explicit 'use this instead of reject-hosted-page when...' guidance despite several adjacent lifecycle tools. The stated collateral-effect (live page retiring) helps an agent judge consequences but does not route selection between alternatives.

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

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

Annotations already declare this is not read-only, not destructive, and not open-world. The description adds useful behavioral context beyond that: the restored prompt joins the next visibility run, and the operation is refused at prompt quota.

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

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

Two sentences, front-loaded with the core action and followed by the key constraint. Every sentence adds useful information with no wasted wording.

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

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

For a simple one-parameter mutation with annotations and no output schema, the description covers the essential behavior: restoring archived state, triggering a visibility run, and quota refusal. Minor edge cases, such as what happens when restoring an already-active prompt, are not 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?

There is only one required parameter, prompt_id, and the schema description coverage is 100%. The description does not add extra semantic detail about the parameter, 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 gives a specific verb and resource: restore an archived prompt to active. It also states the functional effect of joining the next visibility run, making it clearly distinct from archive-prompt and other prompt tools.

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

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

It clearly implies when to use the tool: when a prompt is archived and should become active again. It also gives an important when-not condition: the restore is refused when the workspace is at its prompt quota. It does not explicitly name alternative tools or recovery paths.

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 destructiveHint=true annotation, it discloses the exact HTTP outcomes (410 vs 301) that make this a deliberate removal rather than an accidental 404, and that the redirect target must already be live. The account-owner permission requirement is context the annotations do not 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?

Three tightly packed sentences: the action first, then the two behavioral branches, then the prerequisite. The 'answer engine' rationale justifies the 410 choice rather than padding.

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

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

For a destructive, no-output-schema mutation, it covers effect, permission, and both branches. It does not say whether retirement is reversible (republish?) or what happens to existing links, which is the only material 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%, and the schema already describes both page_id and redirect_to_slug, including the pattern constraint. The description only reinforces 'already live on the same domain', which the schema already states, so it adds little beyond the 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?

A concrete verb and resource ('Take a live page off the customer's domain') make the operation unambiguous. It does not name the nearest sibling (reject-hosted-page) or explain how it differs, so sibling differentiation depends on the agent inferring from names.

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 decision rule: no redirect = 410, redirect = 301 to an already-live page, plus the 'requires the account owner' prerequisite. It stops short of stating when NOT to use it versus reject-hosted-page or archiving.

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 discloses important behavior: each page consumes one site audit quota unit, oversized requests are refused, audits run in the background by fetching pages, and results are retrieved via list-site-audits. It does not cover permissions or immediate response details, but the quota and async behavior are valuable additions.

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 tight sentences. It front-loads the core action, then adds quota behavior, then explains asynchronous execution and result retrieval, with no redundant or wasted wording.

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 mutation-style operation, two parameters, and absence of an output schema, the description covers the key facts an agent needs: scope, quota consumption, refusal on overage, background execution, and where results appear. It could be slightly more complete by stating what the immediate queued response contains, but the essential behavior is present.

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 documented in the schema. The description clarifies that page_ids targets a specific subset and omitting them targets all tracked pages, but this largely mirrors the schema rather than adding new semantic detail.

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

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

The description uses a specific verb, 'Queue', with the precise resource, 'site health audit', and states the two scopes: a domain's tracked pages or specific page IDs. It also names the sibling tool where results appear, making it clearly distinguishable from list-site-audits and related audit tools.

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

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

It gives clear usage context: queue an audit for tracked pages or specific page IDs, note that quota is consumed, and directs the agent to list-site-audits for results. It does not explicitly state when not to use this tool or name alternatives for triggering audits, which keeps it from 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?

Goes well beyond destructiveHint=true by naming what is destroyed (anything omitted is removed), the refusal condition (filters still tagged on prompts), and the structural limits (5 filters, 50 values). These are the operational details an agent needs before a mutation that annotations cannot express.

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

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

Four tight sentences with no filler: the replacement semantics lead, followed by the refusal guard and then the numeric constraints. Every sentence contributes a distinct rule.

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, no-output-schema tool, the description covers destruction, guard rails, and format constraints well. The remaining gap is sibling disambiguation from update-prompt-filters, plus no indication of what is returned on success.

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

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

Schema coverage is already 100%, but the description restates the cardinality caps (5 filters, 50 values) and the key/slug character rules in prose, which helps the agent construct a valid payload without re-reading patterns. It omits any guidance on label fields, so it is not fully additive.

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?

"Replace the custom filters a domain declares" gives a specific verb (replace) and resource (custom filters), and the full-replacement semantics distinguish it from a read tool. However, it never mentions or contrasts with the sibling update-prompt-filters, which an agent must disambiguate against on its own.

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

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

Explicitly says to send the complete intended list rather than a patch, and points at list-prompt-filters as the source of the current state. It gives a clear usage context but offers no exclusion criterion versus update-prompt-filters.

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 disclose mutation, destructive, and open-world behavior, so the description is not the sole source of safety context. The description adds useful async and prerequisite context with 'Queue' and 'Required before...', but it does not explain what the destructive side effects are or what existing data may be affected.

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

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

Two short sentences, front-loaded with the action and followed by the prerequisite condition. There is no filler or redundant restatement.

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

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

For a one-parameter mutation tool, the description covers purpose and prerequisite but omits the consequences implied by destructiveHint=true. It also does not clarify how the queued scan is monitored or what happens after queuing, though the annotations carry some of that burden.

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

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

There is only one parameter, domain_id, and the schema provides 100% description coverage. The description's phrase 'for a domain' loosely maps to it, but adds no format or semantic detail beyond the schema.

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

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

The description uses a specific verb and resource: 'Queue a sitemap scan for a domain.' It also states the outcome ('discover and track pages') and distinguishes this setup step from the sibling 'run-site-audit' by naming the prerequisite condition.

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

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

It gives a clear usage condition: required before running a site audit when no pages exist yet. It does not cover when not to use the tool or mention other alternatives, but the primary routing guidance 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 declare destructiveHint=true and readOnlyHint=false, so safety is covered; the description then adds genuinely new semantics — that omitted fields are preserved and each supplied field overwrites its prior value, including the keywords array. It stops short of saying whether updates are reversible or what the response contains, 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?

Three short sentences, front-loaded with what can be changed, then the partial-update rule, then the scope exclusion. No filler and nothing repeated.

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-param mutation tool with full schema coverage and annotations carrying the destructive/read-write profile, the definition covers what can change, how omission is treated, and what is out of scope. Missing only return-value shape and per-operation preconditions (e.g. whether a published article can be reverted to draft).

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 every parameter is documented in the schema; the description's field list and the 'draft, ready or published' status values largely restate it. Only the overwrite-on-send semantics adds meaning beyond the schema, so the baseline 3 is right.

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 (Update) plus resource (article) and enumerates exactly which fields are mutable (title, slug, status, keywords, meta description, summary). It also carves out scope with 'The body is not editable here,' which separates it from article-content tools and from siblings like publish-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?

'Only the fields sent change; each one overwrites its old value' tells the agent this is a partial/PATCH-style update rather than a replacement, which is the key usage decision. It also signals an exclusion (body not editable) but does not name the alternative tool or state prerequisites such as required permissions or which article states can be updated.

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 as destructive and not read-only. The description adds useful behavioral context about how names affect mention counting and domain matching, but it does not state whether aliases are replaced or merged, nor what old values are lost.

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, front-loaded with the action and followed by the key semantic consequence. No filler or repetition.

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

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

Given a destructive update tool with three parameters and no output schema, the description explains purpose and mention-count impact but omits replacement behavior and confirmation that existing aliases may be overwritten. The annotations warn of destructiveness, but the description should say more about what destruction means 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: display names and aliases determine which answers count as competitor mentions, and domain matching depends on display name. It still does not describe the aliases parameter's replacement 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 uses a specific verb and resource: "Update a competitor display name or aliases." It clearly distinguishes updating from adding or deleting, but does not explicitly name sibling tools such as add-competitor or delete-competitor.

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 implies use when changing an existing competitor's name or aliases, but gives no explicit when-to-use guidance, prerequisites, or alternatives. The second sentence explains consequence rather than usage selection.

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

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

Annotations already declare readOnly=false and destructiveHint=true, so safety framing is covered. The description adds genuinely non-obvious behavior beyond that: the status change is scoped to the issue on that domain and applies across all audits rather than to a single audit instance, and the operation is reversible ('reopen'). It stops short of saying what happens to in-flight audits.

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, no filler, with the action front-loaded and the scoping caveat immediately after. Every clause carries information.

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

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

For a 3-parameter mutation with no output schema, the description covers action, target, and scope. The missing piece is how an agent should source the fingerprint (presumably from get-audit-issues), which would have closed the loop.

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 enum for status (open/done) is documented in the schema, so baseline is 3. The description adds modest semantic value by explaining that issue_fingerprint identifies the issue across audits, but it does not explain the interaction between domain_id and fingerprint (e.g., whether the same fingerprint can exist on multiple domains).

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 pair ('Mark a site health issue done or reopen it') and clarifies the entity model: status lives on the issue on that domain, keyed by fingerprint, spanning audits. That is enough to separate it from read-only siblings like get-audit-issues or get-site-health-summary, 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?

The two enumerated actions (done / reopen) imply when to call it, but there is no explicit guidance on prerequisites (where to obtain the issue_fingerprint) or when to prefer this over acknowledging or otherwise handling an issue. Usage is inferable 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?

Adds genuinely non-obvious behavior beyond the annotations: merge semantics (omitted keys keep their value), the "-" sentinel that clears a key, and that undeclared keys/values are rejected rather than silently dropped — a critical failure mode. The clearing behavior is consistent with destructiveHint=true, though the description never states that cleared values are unrecoverable or what permissions are required.

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

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

Three sentences, front-loaded with the action, then the merge/quirk semantics, then sibling routing. No restatement of the title or the schema, and every clause carries information the 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 only two parameters, no output schema and a nested object, the description covers the mutation contract, validation failure mode, and alternatives well enough to call it safely. The only gap is the success response shape, which it leaves unstated since there is no output schema to lean on.

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

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

Schema coverage is 100% with a nested filter map already documented, so the baseline is 3; the description earns above baseline by explaining the merge contract, the "-" clear convention, and that valid keys/values must come from list-prompt-filters. prompt_id itself is not elaborated, but it needs no elaboration.

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: "Set the custom filter values on an existing prompt." It then explicitly delimits itself from the confusable siblings by declaring prompt text immutable and naming move-prompt-to-topic, archive-prompt and restore-prompt as the tools for topic/status. An agent can pick this tool over those 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?

Gives the trigger condition (setting filters on an existing prompt) plus explicit routing for adjacent operations: topic changes go to move-prompt-to-topic, status changes to archive-prompt/restore-prompt. It also points at list-prompt-filters as the required source of valid keys and values, which is a real prerequisite for calling this correctly.

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

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

Annotations already declare destructiveHint=true and openWorldHint=false, so the safety profile is covered; the description adds real value by bounding the blast radius, stating that contained prompts and their scores are untouched. It stops short of saying whether the rename is reversible or whether the old name is retained anywhere.

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

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

Two short sentences, zero filler, with the action stated first and the side-effect caveat immediately after. Nothing is repetition of the title beyond the necessary verb+resource.

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

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

For a three-required-parameter mutation with full schema coverage and no output schema, the description covers the action and the scope of impact. It could go further by noting what a successful call returns or how name collisions are handled, but 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 description coverage is 100%, so all three parameters (domain_id, topic_id, name) are already documented with format and length constraints. The description adds no format, scoping or constraint detail beyond what the schema provides, which is the expected 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?

"Rename a prompt topic" gives a specific verb and resource, and the second sentence scopes the change to the name only. Against siblings like delete-prompt-topic, create-prompt-topic and move-prompt-to-topic the intent is inferable from the verb, 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?

The rename framing implies when to reach for this rather than create/delete/move, but there is no explicit when-to-use or when-not-to-use statement and no mention of prerequisites such as needing write access to the domain.

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