Mentionry

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

With no annotations, the description carries the burden and it adds useful behavior: results are classified by winnability and rationale, and competitors are explicitly excluded from their own results. The read-only nature is implied by 'Find', though side effects, auth, and rate limits are not addressed.

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 tightly worded sentences front-load the core function and then add an important edge-case rule. No filler or redundancy; every clause 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 two simple parameters, the main invocation is inferable, and the winnability classification gives some sense of return content. However, with no output schema, the description does not specify the output shape or define 'realistically winnable', and it omits usage context relative to sibling 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 50%: only competitors has a schema description, and the description maps 'you' to the domain parameter. It clarifies that competitors are the source of gap analysis, but it adds no format, example, or requirement details for domain beyond what the schema already provides.

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

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

Description uses a specific verb ('Find') and names the exact resource: pages linking to competitors but not to the user's domain. It also describes the unique output classification (winnable and why), which separates it from siblings like discover_competitors and find_prospects.

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 is given on when to use this tool versus alternatives such as discover_competitors or find_prospects. The description implies a backlink-gap use case but never states prerequisites, exclusions, or which sibling to choose instead.

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

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

Annotations already declare non-destructive, idempotent, non-read-only, so the bar is lower; the description still adds real context by warning that running work may incur provider cost and that cancellation doesn't guarantee refund or rollback. That is exactly the side-effect information the 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?

Two short sentences with zero filler, with the primary action stated first and the caveat second. 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?

The description covers the crucial caveat for a mutation tool with no output schema, but leaves the parameters and the practical workflow (check status, what state the job ends in) undocumented. Adequate but with clear gaps.

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

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

Schema description coverage is 0% for two parameters, and the description never mentions jobId or workspace, including the UUID pattern or why a workspace scope exists. The agent gets no semantic help beyond the bare 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 ('Cancel a queued job') and narrows the scope to queued work, which distinguishes it from read_preparation_job and read_preparation_actions. It does not name any sibling explicitly, so differentiation relies on the agent inferring the queued-vs-running 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?

The word 'queued' implies the applicable state, but nothing tells the agent what to do when the job is already running, nor points to read_preparation_job to check status first. 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?

With no annotations, the description bears the full burden. It discloses useful behavioral content: step-by-step behavior, returned data, billed vendor steps, and current blockers. However, it does not explicitly state side effects (e.g., whether this tool is read-only or can trigger agent execution), which is a meaningful gap for an agent inspection tool.

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

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

All information is packed into one front-loaded sentence, with the primary purpose first and supporting output details after. It is somewhat dense, but every clause adds distinct information.

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

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

For a single-parameter, no-output-schema tool, the description covers purpose, needed input, expected return content, cost-relevant steps, and run blockers. It only lacks explicit usage direction and side-effect clarification.

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

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

The schema already documents agent_id as 'From list_agents,' and the description adds the context that these are values needed for run_agent. That is helpful but not substantial; with 100% schema coverage the baseline of 3 is appropriate.

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

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

The description names the resource ('one agent') and the specific behavior ('what it does, step by step, and what it needs'), with concrete output categories. It is clearly distinct from siblings like list_agents (all agents) and run_agent (executes the agent).

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

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

It implies a pre-run inspection use case by mentioning 'the values you must pass to run_agent' and blockers, but it never explicitly says when to prefer describe_agent over list_agents or run_agent. No alternatives or exclusions are named.

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

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

With no annotations, the description carries the disclosure burden. It clearly says results include evidence for each candidate and warns that wrong suggestions can be recognized rather than blindly trusted. This goes beyond the schema and gives agents a useful expectation of output quality and intent.

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

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

Two tight sentences with no filler. The core purpose is front-loaded, and the second sentence adds return-value context that helps the agent interpret results. Every phrase 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?

The tool has only two simple parameters and no output schema, so the description covers the essential contract: what gets discovered, from which signals, and that candidates come with evidence. It could say a bit more about what evidence looks like, but it is sufficient for safe 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 coverage is 50%: the keywords parameter is described there and in the tool description, but the domain parameter is only implied by 'this one'. The phrase 'sharpens the search half' adds meaningful context for keywords, but the main domain parameter still relies on inference from the tool name.

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 ('Find') and a clear resource ('domains competing with this one'), and it specifies the two methods used ('search results and link profile overlap'). This distinguishes competitor discovery from sibling tools like find_prospects or backlink_gap without needing to inspect 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?

The description implies when to use the tool by framing it around competitor overlap and evidence, but it does not explicitly state when not to use it or name alternatives. A note that this is for competitor discovery rather than prospecting, qualification, or gap analysis would improve 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 declare idempotentHint=true and destructiveHint=false, so the bar is lowered; the description still adds real value by stating the required expectedVersion/idempotencyKey contract and by clarifying that artifacts are not deleted, only future preparation blocked, and that in-flight work and applied evidence are untouched. It omits failure modes (version conflict behavior, error shape).

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 and its non-destructive guarantee, then requirements, then the exclusion. 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?

No output schema and no annotations gap, so scope and side effects are reasonably covered, but a mutation tool with three required parameters and zero schema descriptions leaves the agent guessing about actionId sourcing and expectedVersion acquisition. Adequate but with a clear 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 0% across 5 parameters, so the description must carry the load, yet it only mentions expectedVersion and idempotencyKey and only as requirements, not formats or meanings. actionId (the primary identifier), reason, and workspace are never explained anywhere.

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 (dismiss) plus the resource class ('suggested/reviewed/prepared work'), and explicitly says no artifacts are deleted, which separates it from a delete tool. It does not name the sibling it should be picked over (e.g., review_preparation_action, cancel_preparation_job, restore_preparation_action), and the title's 'page suggestion' framing is slightly at odds with the body's 'prepared work' wording.

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 through the exclusions: 'prevents future automatic preparation; does not undo already running work or applied evidence.' That effectively tells the agent not to use this when work is running, but it never names the alternative tool (cancel_preparation_job) or states prerequisites or when review/restore is the better call.

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

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

With no annotations provided, the description carries the full burden and does well: it discloses that the tool returns the subject and body, performs no sending, and that sending happens later from the user's mailbox. This is important behavioral context that an agent needs before invoking the tool.

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

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

Three short, purposeful sentences: the action comes first, then the output and non-sending behavior, then the requirement. Every sentence earns its place and the structure is front-loaded.

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

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

Since there is no output schema, the description correctly explains the return value (subject and body) and the non-sending behavior. It leaves 'page_title' and 'sender_name' semantically unexplained, but those are optional and the core invocation path is well-covered by the description and required parameters.

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

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

Schema coverage is 67%, so the schema already documents most parameters. The description reinforces the meaning of 'hook' as the reason the prospect would link and 'prospect_url' as the target page, but it adds no new meaning for the undocumented optional params 'page_title' and 'sender_name'. 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 uses a specific verb ('Write') and clearly identifies the resource and result: one outreach email for one prospect, returned as subject and body. It is clearly distinguishable from sibling discovery and verification tools, despite not naming them explicitly.

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

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

The description gives clear context: use this when you need to draft a single outreach email with a personalized reason. It also provides an important exclusion ('sends nothing') and a prerequisite ('paid Mentionry plan'), which helps the agent decide when and whether to invoke it.

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

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

With no annotations, the description carries the behavioral burden. It discloses that the tool searches the open web and returns each kept result with a reason, which is useful. However, it does not mention result limits, latency, data-source caveats, or how the plausibility filtering works.

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

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

The description is two sentences with no filler. The core action and result format are front-loaded, and every phrase contributes meaning: what it searches, what types of pages it targets, and what it returns.

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 five parameters, no annotations, and no output schema, but the description only covers the general purpose and one output behavior. Optional parameter semantics and usage boundaries versus sibling tools are missing, making the definition incomplete for confident invocation beyond the required domain.

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

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

Schema description coverage is only 40%, and the description does little to compensate for the undocumented parameters. 'domain' maps to 'this site' and 'subject' loosely relates to topic/audience/keywords, but audience, keywords, and description are not explained at all, leaving their semantics unclear.

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: 'Search the open web for pages that would plausibly link to this site.' It further specifies the types of pages (resource pages, roundups, listicles, directories), which clearly differentiates it from siblings like discover_competitors or backlink_gap.

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 intended use is implied: use this when you want link-building prospects for a given site. However, there is no explicit when-to-use or when-not-to-use guidance, and no alternative sibling tools are mentioned, so the agent must infer the selection context.

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

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

With no annotations provided, the description carries the full burden of disclosing behavior. It does explain what the response includes, especially the useful 'whether it would run as it stands' readiness indicator. However, it does not explicitly state that the operation is read-only, nor does it mention permissions, rate limits, or response shape beyond field names.

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

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

The description is two sentences with no filler. The first sentence front-loads the tool's purpose and output fields, and the second sentence adds a concise, actionable next step. Every word 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 zero-parameter list operation, the description covers the key returned fields and suggests the next logical call. It is sufficient for an agent to invoke the tool correctly, though it omits potential details like ordering, pagination, or exact output schema, which would matter if the response were complex.

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

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

The tool takes no parameters, so there is nothing to document. The baseline of 4 applies because the description does not need to compensate for missing 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?

The description clearly states that the tool lists agents on the account and enumerates the returned attributes: name, step count, runnability, and last modification time. It is distinguishable from describe_agent by positioning that as a follow-up, but it does not explicitly contrast with other list tools such as list_connections or list_documents.

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

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

The description gives a concrete usage flow: call list_agents to get an overview, then call describe_agent to learn requirements before running an agent. It implies this tool is for surveying agents and checking run-readiness, though it does not state explicit exclusions or alternatives like run_agent.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered elsewhere. The description contributes only the filtering semantics ('owned active'), leaving unstated whether pagination is needed, what the result shape is, or how the 'active' filter is determined.

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 or redundancy. It is efficient, though its brevity borders on under-specification given seven undocumented parameters.

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 seven parameters, weak schema coverage, and no output schema, the description should explain what a returned workspace record contains and how the ambiguous params (url, days, direction) apply to a listing call. Neither is addressed, leaving real ambiguity about how to invoke it correctly.

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

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

Schema description coverage is only 29% — url, area, days, limit, offset, and direction have no descriptions at all, and several (url, days, direction) look unrelated to a plain workspace listing. The description names no parameters and gives no hints about defaults, ranges, or how url/area/days interact with workspace selection, so the coverage gap is left unmitigated.

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 brand workspaces) plus meaningful scope qualifiers ('owned', 'active'), which separates it from list_agents, list_connections, and list_documents. It does not explicitly name a sibling alternative, but the resource noun alone is discriminating enough.

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?

'For subsequent reads' implies the intended workflow: call this first to obtain workspace IDs that later read tools consume. However, there is no explicit when-not guidance, no mention of what to do if the list is empty or if the desired workspace is unowned/inactive, and no named alternative.

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

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

With no annotations, the description carries the behavioral disclosure burden. It explains what the tool returns—connected external integrations and their allowed permissions—and implies a non-mutating lookup. It does not explicitly state read-only behavior, but nothing about the description suggests side effects.

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

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

Two sentences carry the full message: what the tool does and when to call it. The core purpose is front-loaded, and there is no filler.

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

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

For a parameterless list tool with no output schema, the description sufficiently explains what the tool returns and when it should be used. It does not specify the exact response shape, but the agent knows enough to invoke it correctly.

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

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

The tool has zero parameters, so the baseline for parameter semantics is 4. The description adds no parameter-related confusion, and the schema already documents the empty input contract.

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

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

The description clearly identifies the resource ('outside tools this account has connected') and the implied listing/read action. The phrase 'outside tools' distinguishes it from sibling tools like list_agents and list_documents.

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

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

The description gives an explicit trigger: call before offering to file, post, or draft anything, so the agent can report what is actually available. It does not mention alternatives or when-not-to-use cases, so it stops just short of a top score.

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

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

With no annotations, the description carries full behavioral disclosure. It states that the tool returns metadata only and not text, and that ids are meant for read_document. However, it leaves 'how long it is' ambiguous (characters, words, pages?) and says nothing about pagination, ordering, or limits, which is a noticeable gap for an unannotated tool.

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

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

Two sentences with no filler: the first states the main purpose with specific output fields, and the second provides a useful routing hint. The most important information is front-loaded, and every sentence contributes value.

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

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

For a no-parameter list tool without an output schema, the description covers the essential output fields and points to read_document for content retrieval. Minor omissions exist, such as the exact definition of 'length' and any list ordering/limits, but the tool is simple enough that an agent can invoke it correctly.

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

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

The input schema has zero parameters and schema description coverage is effectively 100%, so there is no parameter documentation burden. The description adds no parameter-specific info, but it clarifies the output id's role with read_document. The no-parameters case warrants the baseline score of 4.

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

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

The description uses a specific verb ('list') and a clear resource ('documents your agents have produced') and enumerates the returned fields: name, author agent, length, and version count. It also differentiates from read_document by noting that text requires a separate call, making the tool's role unambiguous among its siblings.

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

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

The description explicitly routes text retrieval to read_document ('Pass an id to read_document for the text'), which tells the agent when not to use this tool. It implies the tool is for metadata overviews, though it doesn't explicitly state 'use this when you need document metadata.' The context is clear and actionable.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose useful traits beyond schema: result ordering ('newest first'), that items carry addresses, and that the call is 'Free.' It omits pagination, result limits, and any auth/scope requirements, which matters for a list endpoint.

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 terse sentences, zero filler, with scope and ordering front-loaded and the cost note tacked on at the end. Every fragment 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 zero-parameter list tool with no annotations and no output schema, the description adequately conveys what is returned (pictures and clips with their addresses) and in what order. The only meaningful gap is absent pagination/limit behavior, which is a minor omission at this complexity level.

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

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

The tool takes zero parameters, so the baseline is 4. The description adds no parameter details because none exist, and schema description coverage is reported at 100%; nothing further is required here.

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

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

The description names a specific resource and scope ('pictures and clips already generated on this account'), which clearly separates it from generate_image/generate_video (creation) and from list_documents/list_agents (other resource types). The listing verb is only implied by the title rather than stated in the description, so it falls just short of a clean verb+resource statement.

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

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

Usage is implied – an agent can reasonably infer you call this to enumerate previously generated media – and 'Free.' hints at a cost condition. However, there is no explicit when-to-use/when-not guidance and no comparison to any alternative retrieval path.

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 (readOnly=false, openWorld=true, idempotent=true), the description discloses the concrete side effects an agent needs: it consumes one draft, may incur up to $0.02 of provider spend within the existing budget, and does not publish or send. It does not explain whether the call returns an asynchronous job handle, which is the main remaining behavioral gap.

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 purpose, then cost/side effects, then preconditions, then the negative boundary. No filler or repetition; each sentence carries distinct information.

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

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

For a non-read-only tool with no output schema, the description covers purpose, cost, side effects, idempotency requirement, and scope boundary – enough to invoke it safely. The missing piece is what the call returns (e.g., a preparation job id to poll via read_preparation_job), which an agent would still have to infer.

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 only 33% – only idempotencyKey is documented in the schema. The description compensates partially by clarifying that the actionId must refer to a "saved mapped action" and that an idempotency key is mandatory, but it says nothing about the optional workspace parameter, leaving a third of the inputs unexplained.

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?

"Queue a source-grounded draft for one saved mapped action" names a specific verb and resource, distinguishing it from read-only siblings like read_prepared_page_changes and read_preparation_action. It does not explicitly name a sibling it replaces or supersedes, which keeps it below 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 gives a clear precondition (requires an idempotency key) and an explicit boundary ("Does not publish or send"), which tells the agent this is a preparation step, not a deployment. It stops short of naming alternatives such as cancel_preparation_job or read_prepared_page_changes for inspecting results.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It states that the tool uses live search data, returns a verdict with measured signals and the honest case against, and is the same free diagnostic as the dashboard. This gives a clear picture of the tool's behavior and output without relying on structured metadata.

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, each earning its place: the first states the core purpose, the second describes the output, and the third provides useful expectation-setting. No redundant or filler language is present.

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 diagnostic tool with no output schema, the description is complete. It covers the purpose, data source, output shape, and the likely outcome, giving an agent enough context to invoke the tool appropriately and interpret its result.

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

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

The input schema already fully documents the single parameter with a descriptive example ('mentionry.com'), so schema coverage is 100%. The description adds no additional parameter-level meaning, which keeps this at the baseline of 3.

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

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

The description opens with a specific verb and resource: 'Judge whether a domain is worth running link building for at all'. It clearly distinguishes the tool from sibling tools like find_prospects or backlink_gap by focusing on the qualification verdict rather than prospect discovery or gap analysis.

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 clearly frames when to use the tool—before investing in link building for a domain—and sets expectations by noting that many sites will not be worth pursuing. It does not explicitly name alternative sibling tools or state when not to use it, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered elsewhere. The description adds no behavioral context beyond the annotations — nothing about pagination (limit/offset), time-window semantics (days), or the meaning of the 'direction' and 'area' filters.

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

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

It is a single compact sentence with no filler, but the brevity comes at the cost of substance — it is a noun phrase rather than a usable instruction, so being short is not fully 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?

With 7 parameters, 0 required, low schema coverage, and no output schema, the description needs to carry substantial weight on both inputs and return shape. It instead gives a one-line payload summary that leaves most parameter meaning and the response structure 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 description coverage is only 29% across 7 parameters; only url and workspace carry descriptions, and neither is explained in the description text. The enum 'direction' (in/out/both) and 'area' (SEO/GEO/both) are entirely opaque, and the description does not compensate for those gaps.

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 phrase 'Prioritized page actions with evidence, implementation steps, confidence, limits and outcome verification' describes the payload content but never states an action verb or scope. Read against siblings like read_page_insights and read_preparation_actions, which sound very similar, an agent cannot tell what makes this one distinct.

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 call this versus read_page_insights, read_preparation_actions, or read_preparation_action. No prerequisites, exclusions, or alternatives are named.

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, idempotent, non-destructive and closed-world, so safety is covered. The description adds one genuinely useful trait beyond that — the call incurs no provider spending — but says nothing about pagination, result size, or how the seven filters narrow the output.

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 and no redundancy. It is efficient, though the density of unexplained jargon slightly hurts immediate comprehension.

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

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

Seven parameters with 0 required, low schema coverage and no output schema place the burden squarely on the description, which neither explains parameter effects nor sketches the return shape. For a discovery tool this leaves the agent guessing what it will actually get 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 only 29%, so the description must carry the burden of explaining url, area, days, limit, offset, direction and workspace. It mentions none of them; the phrases "saved resources" and "sample workflow" are too vague to imply how url or area scope the response.

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?

"Discover saved resources, plan coverage, shared collection ceilings, protocol links and sample workflow" gives a verb and a list of resource categories, so the agent knows this is a capability/quota introspection tool. But the enumerated items are opaque business jargon ("shared collection ceilings", "protocol links") and the description never ties them back to the tool's name-level concept of agent capabilities and allowances, nor distinguishes it from siblings like describe_agent or list_agents.

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 only usable cue is "without provider spending," which implies a cost-free pre-flight check, but there is no explicit when-to-use or when-not-to-use guidance. Nothing tells the agent why it would pick this over describe_agent, list_agents, or list_brand_workspaces.

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, idempotentHint, destructiveHint=false, and openWorldHint=false, so safety is covered. The description earns some credit for adding that the data is 'saved' and involves 'no paid collection' — a real cost/behavior signal not in the annotations — but it says nothing about freshness, scope of the overview, or what happens when nothing is saved.

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

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

It is two clauses with zero waste, but it reads as telegraphic note-taking rather than a front-loaded statement of purpose. The most useful information (that this reads saved data) is not stated first or in a complete sentence.

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

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

Given the read-only annotations, no output schema, and flat parameter structure, the essentials for a safe read are covered; the description is not grossly inadequate. But with 0 required params and unclear paging/filter semantics across 7 fields, an agent still has gaps about what a default 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?

Seven parameters with only 29% schema description coverage, and the description explains none of them. The url and workspace fields have schema text, but area, direction, days, limit, and offset are left for the agent to infer from names and enum values alone — notably no explanation of how 'area' (SEO/GEO/both) or 'direction' change the returned 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?

The fragment 'Saved brand coverage and next SEO/GEO actions' names the resource (brand overview) and its content, but is not a verb+resource statement and never says plainly that it reads a stored overview. It also fails to distinguish itself from nearby siblings such as read_brand_results, read_visibility, or read_site.

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 paid collection' implicitly tells the agent this returns already-saved data and won't trigger a spend, which hints at when to prefer it. However, it names no alternative tool and gives no explicit condition for choosing this over read_brand_results or read_visibility.

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 read-only, idempotent, closed-world, and non-destructive behavior. The description adds that results include 'explicit denominator and sample limits', which hints at data scope, but these terms are vague and not explained. No return format or pagination behavior is described.

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 compact phrase with no fluff, but it is too terse to be structurally helpful. It front-loads the core resource but omits necessary qualifiers about usage and behavior.

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

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

With seven parameters, low schema coverage, no output schema, and only basic safety annotations, the description is incomplete for correct invocation. An agent lacks guidance on temporal scoping, filtering, pagination, or what the saved results actually contain.

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

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

Schema description coverage is only 29%; only 'url' and 'workspace' are documented in the schema. The description does not mention parameters like area, days, limit, offset, or direction, nor does it clarify how '30-day' relates to the days parameter. An agent must rely on sparse schema metadata for critical controls.

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 resource ('answer-engine visibility and competitors') and notes it is saved and 30-day scoped. However, it does not distinguish this tool from near-siblings such as read_brand_overview or read_visibility, so an agent cannot confidently select it over those without opening schemas.

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

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

There is no explicit guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. The only implied context is that results are 'saved' and '30-day', which leaves selection largely to inference.

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

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

With no annotations, the description carries the full burden. It discloses version resolution ('Returns the newest version unless an older one is asked for') and the returned payload components. It does not mention failure modes or permissions, but for a read operation this is a minor gap.

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

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

Two tight sentences front-load the core purpose and then add the version detail. Every clause contributes meaningful information with no redundant 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 read tool with no output schema, the description sufficiently covers the returned content and versioning, and the schema fully documents parameters. Minor omissions such as not-found behavior keep it just short of complete.

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

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

Schema description coverage is 100%, so document_id and version are already explained. The description mostly restates the version behavior already in the schema and adds no significant new parameter-level meaning.

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

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

The description clearly identifies the resource ('one document your agent wrote'), the kind of output (text plus agent, step, and values), and the version behavior. This differentiates it from siblings like list_documents and read_site.

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 rather than explicit: an agent can infer this is for retrieving document content, but no alternatives or when-not-to-use conditions are named. There is no guidance distinguishing it from list_documents or other document-related 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?

Goes well beyond the annotations (which already declare read-only/idempotent) by disclosing the seven-day window, the 200 question/engine/region/persona group scan cap per brand, and the 30 pending / 30 reviewed item cap. It also explains the non-obvious semantics of triage.unchangedSinceReview and why the current run stays reviewed=false.

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

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

Claims and limits are front-loaded in the first sentence and the follow-up fragments each carry distinct constraints with little filler. Structure is telegraphic (subject-less fragments like 'Last seven days; at most 200 ... groups scanned per brand'), which costs some readability but no sentence is wasted.

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

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

With no output schema, the description does the work of listing returned fields and triage state/version, plus the scan and item caps, which is enough to call it correctly. Pagination/total-count behavior for offset/limit is the main omission.

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

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

Schema description coverage is only 25% (only workspace is documented), so the description should compensate for days, limit and offset, and it does not – the limit/offset pagination behavior and the interaction between the 1-7 `days` range and the stated 'last seven days' are unaddressed. The stated caps (30 pending/30 reviewed) also don't map cleanly onto the limit default of 25 with a max of 100.

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: latest saved answer executions needing owned-brand attribution review, and enumerates what each item carries (engine, region/date, competing brands, excerpt, citations, review task). An agent can distinguish this read from review_answer_evidence/restore_answer_evidence, though those siblings are only referenced generically as 'dedicated review/restore tools'.

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

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

Explicitly directs the agent to triage.needsReview for fresh tasks, flags that changed or unverified prior reviews need rechecking, and states that state changes belong to the dedicated review/restore tools rather than here. It also excludes comparison, provider calls and publication. Clear context and exclusions, only the sibling names themselves are left implicit.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior, so the description's added caveats are the valuable part: the 14-checks/90-days scope, explicit unknown gaps, and warnings that URL switching is not proven cannibalization and overlap is not business-rival inference. It also clarifies that no refresh or provider calls occur, which meaningfully sets expectations beyond the annotations.

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

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

The description is short and front-loads the data scope, but the dense phrasing ('complete-link SERP-overlap groups', 'dated compatible rank movement') reduces readability. It avoids waste, though several terms require interpretation before an agent can act.

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 does not explain the seven input parameters or return shape. It gives useful scope and caveats, but for an evidence-reading tool with low schema coverage, it leaves too much unexplained for reliable 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 coverage is only 29%, with only url and workspace described in the schema, so the description needed to compensate for area, days, limit, offset, and direction. It does not mention any parameter semantics, leaving most of the seven inputs undocumented.

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 lists the evidence included (saved rank observations, database suggestions, SERP-overlap groups), which conveys the resource, but it is jargon-heavy and never states a clear verb or a plain-language summary of what the tool returns. It distinguishes itself from refresh/provider tools via 'No refresh or provider calls,' but not clearly from siblings like read_search_rank_history or read_page_keywords.

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 guidance on when to use this tool versus alternatives such as read_search_rank_history, read_page_keywords, or read_visibility. The negative caveats ('URL switching is not proven cannibalization', 'not business-rival or complete-gap inference') help prevent misuse but do not route the agent to the right tool.

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

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

Annotations already declare this as a read-only, idempotent, non-destructive operation. The description adds useful context that links are sampled and include anchor text and nofollow evidence, but it does not explain sampling behavior, pagination, limits, or what the response 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?

It is a single short sentence with no filler, so it is concise. However, it is an incomplete fragment rather than a front-loaded definition, and the extreme brevity leaves important invocation details unstated.

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 seven-parameter tool with low schema description coverage and no output schema, the description is too thin. It does not explain parameter meanings, filtering behavior, pagination, or how the sampled results should be interpreted.

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

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

Schema description coverage is only 29% across seven parameters, so the description needs to compensate for undocumented fields like area, days, limit, offset, and workspace. It only indirectly references direction through 'incoming/outgoing' and says nothing about the required URL or the other filters.

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

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

The description identifies the resource as incoming/outgoing page links with anchor text and nofollow evidence, which is specific data. However, it is a noun phrase rather than a clear verb+resource statement and does not distinguish this from sibling tools such as list_connections.

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 indication of when to use this tool instead of list_connections, verify_links, backlink_gap, or other connection-related siblings. The description provides no usage context, 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 declare readOnlyHint=true, openWorldHint=false, idempotentHint=true, and destructiveHint=false. The description adds useful operational context by saying the data is 'saved' and consists of declarations/public HTML observations, and reiterates that it never fetches a page or starts work, clarifying that it reads persisted evidence rather than live pages.

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 core action and followed by a tightly scoped exclusion. There is no redundant phrasing and every sentence adds useful information.

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

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

The tool has no output schema and three undocumented optional parameters, so the description needs to do more than state the general resource. It does not explain what a 'deployment declaration' or 'public HTML observation' contains, how results are scoped by workspace/document/deployment, or what an agent receives.

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

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

There are three parameters with 0% schema description coverage, and the description provides no meaning for workspace, documentId, or deploymentId. It does not explain optionality, whether these are filters, or how the identifiers relate to the returned deployment evidence.

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: reading saved deployment declarations and public HTML observations. It also distinguishes itself from mutating/fresh-fetch siblings by stating it never fetches a page or starts work, though it does not explicitly contrast with nearby tools like record_page_deployment or read_website_pages.

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 'Never fetches a page or starts work' gives an implicit when-not condition and suggests this tool is for reading existing evidence only. However, it does not explicitly say when to choose this over record_page_deployment, prepare_page_changes, or read_website_pages, nor does it explain how the optional identifiers select scope.

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, idempotentHint=true, openWorldHint=false and destructiveHint=false, so safety is covered structurally. The description adds no behavioral context of its own — no indication of what 'SEO/GEO action plan' means operationally, whether results are cached/snapshot-based, or how the time window affects 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?

It is short with no filler, but it is a dangling noun phrase rather than a front-loaded statement of purpose, so brevity comes at the cost of clarity. Restructuring into a verb-led sentence would cost no extra length.

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

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

A 7-parameter aggregation tool with no output schema and undocumented pagination/filtering parameters needs substantially more description than one clause. The description does not tell the agent enough to invoke it correctly or to interpret the multi-section 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 description coverage is only 29% (url and workspace documented, area/days/limit/offset/direction not described beyond enums and bounds). With low coverage the description should compensate by explaining what area, direction and days control, but it says nothing about any 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 is a noun-phrase fragment ('One mapped page, keyword topics, SEO/GEO action plan and internal connections') that lists returned content but never states a verb or the action performed. An agent can infer it retrieves aggregated insights for one URL, but must guess that reading over alternatives like read_page_keywords or read_page_connections is the point.

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

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

There is no when-to-use context and no mention of the closely related siblings read_page_keywords, read_page_connections, read_search_console_performance or read_actionable_insights. Nothing tells the agent whether this is the aggregate view or how it differs from those narrower reads.

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, idempotent, and non-destructive behavior, so the description's value-add is the pagination caveat and the warning that results are incomplete. That is meaningful context beyond the annotations, though it doesn't say what happens with large offsets or how the lexical labels are derived.

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 scoping caveat front-loaded and no filler. It is efficient, though the phrasing 'with lexical topic labels' is the only clause that slightly clouds the core statement.

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

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

With no output schema, the description must carry the burden of what comes back, and it does say rows plus topic labels are returned. However, for a 7-parameter tool it leaves most filter semantics and pagination behavior unexplained, which is a real 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 only 29% across 7 parameters, and the description adds nothing per-parameter beyond the word 'paginated'. It does not explain 'area', 'days', 'direction', or how limit/offset interact, so the low-coverage gap is not compensated.

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 resource ('keyword rows for a mapped page') with lexical topic labels, which distinguishes it from siblings like read_page_connections or read_page_insights. It lacks an explicit verb, but 'All collected keyword rows' is unambiguous about what is returned.

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 sets a negative boundary ('not complete keyword discovery') and flags that results are paginated, which implies iteration, but it never names an alternative tool for full keyword discovery or explains when to prefer this versus other page reads. Usage is implied rather than prescribed.

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 readOnly, idempotent, non-destructive, and closed-world; the description adds that only persisted data is returned (no live provider call) and that history is cursor-paginated, which is meaningful behavioral context beyond the annotations. It stops short of describing auth/ownership failure modes.

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 core scope is front-loaded and the 'saved data only' constraint follows immediately. 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?

With no output schema, the description usefully enumerates what comes back (action, stateVersion, audit history), but it leaves all four parameters unexplained and says nothing about paging direction or limits, leaving meaningful gaps for a 4-param read 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 0%, so the description must carry the burden, but it names none of the four parameters. 'cursor-paginated audit history' only faintly gestures at `before`/`limit` and gives no semantics for `actionId` (the required key) or `workspace`.

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: reading a single owned mapped action plus its stateVersion and paginated audit history. The singular 'one owned mapped action' implicitly separates it from the sibling list tool read_preparation_actions and from read_preparation_job, 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?

'Saved data only; no provider work' tells the agent this is a snapshot read rather than a live fetch, but it never says when to prefer this over read_preparation_actions or read_prepared_page_changes, nor what prerequisites (ownership, mapping) are required.

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, idempotent, non-destructive behavior. The description adds useful context by saying the data is saved and that no provider work is triggered, though it does not discuss filtering scope or pagination behavior.

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

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

The description is two short sentences with little waste and the key read-only/no-provider-work constraint is front-loaded. The first sentence is a noun-phrase fragment rather than a full purpose statement, but it remains efficient.

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

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

For a tool with seven filter parameters, no output schema, and low schema-description coverage, the description leaves important invocation details unstated. It says what data is returned and one downstream use, but it does not explain filtering, pagination, or sibling selection.

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 only 29% across seven parameters, and the description does not explain url, area, days, limit, offset, direction, or workspace semantics. It mentions action IDs as outputs, not how to use the input filters, so it does not compensate for the schema gaps.

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

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

The description identifies the resource clearly: saved owned-page action IDs, source evidence, and preparation states. It is specific about contents, but it does not explicitly distinguish this plural listing tool from siblings like read_preparation_action or read_prepared_page_changes.

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 one concrete downstream usage: use an action ID with prepare_page_changes. It also clarifies that the read triggers no provider work, but it does not explain when to choose this tool over the singular action reader or the prepared-changes reader.

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, idempotent and non-destructive, so the safety profile is covered. The description still earns credit by adding a cost/side-effect guarantee the annotations do not express: it never schedules work and never calls paid providers. It omits what a 'status' actually contains, but with no output schema that gap is real.

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 sentence, front-loaded with the action and resource, with the non-obvious constraint appended. No filler and nothing repeated from annotations or 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?

A two-parameter tool with no output schema and no parameter documentation needs the description to explain what jobId identifies, how workspace scopes the lookup, and roughly what a status response contains. None of that is present, so an agent cannot call it confidently beyond guessing.

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

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

Schema description coverage is 0%, so the description must carry both parameters. It says nothing about jobId (a UUID the agent must obtain somehow) or about the optional workspace scoping parameter. The agent is left to infer semantics entirely from types and patterns.

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 ('Read') and resource ('a saved preparation job status'), so an agent can distinguish this from cancel_preparation_job or prepare_page_changes. It stops short of naming any sibling or clarifying how it differs from read_preparation_action(s), which sit in the same family.

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: it reads an existing job, as opposed to scheduling one. There is no explicit 'use this when…' or any pointer to an alternative for starting or cancelling a job, even though cancel_preparation_job and prepare_page_changes are obvious neighbours.

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 this as read-only, idempotent, non-destructive, and closed-world, so the description only needs to add context. It does add meaningful behavior: historical review-only proposals are withheld and replaced with an intent-review task, and no generation, publishing, or provider requests occur.

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

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

The description is short and front-loads the main subject in the first sentence. Some sentences are terse and jargon-heavy, but there is no obvious 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?

This tool has seven parameters, low schema description coverage, and no output schema, so the description carries more burden. It gives useful read-only behavioral context but omits what the return shape looks like and how most filters or pagination behave.

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

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

Schema description coverage is only 29%, and the description compensates for very little. It adds some meaning for the URL parameter ('mapped URL' and 'eligible full artifact') but says nothing about area, days, limit, offset, or direction, leaving most filters undocumented in both places.

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

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

The description identifies a specific resource: saved source-grounded copy changes plus current eligibility, and the surrounding text distinguishes it from generation/publishing work. It lacks an explicit verb, relying on the tool name for the read action, but an agent can still infer the purpose.

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

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

The only usage-like instruction is 'Add a mapped URL for an eligible full artifact,' which is a parameter hint rather than a when-to-use rule. It does not explain when to choose this over prepare_page_changes, read_preparation_action, or other sibling 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 readOnly, idempotent, non-destructive, closed-world. The description adds real behavioral context beyond them: results are from cached/finalized data ('no refresh, provider call'), coverage is limited to plan-mapped pages, and figures carry no causal-lift interpretation. Only missing piece is pagination/return-shape behavior implied by limit/offset.

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 and the content (what rows, what samples) is front-loaded before the constraints. The telegraphic phrasing ('prior28day', 'Plan-limited mapped pages') costs some readability but nothing is wasted.

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

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

With no output schema the description must carry content detail, which it does reasonably well, but for a 7-parameter tool at 29% schema coverage it leaves parameter meaning and tool-selection guidance unaddressed. Adequate for what the data is, thin for how to call it.

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

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

Schema description coverage is only 29% across 7 parameters, so the description must compensate and does not. It mentions dimensions (query/page/country/device) but never ties them to area, direction, days, limit, or offset, leaving enum and paging semantics undocumented in both places.

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

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

Names the concrete resource: saved finalized query/page/country/device rows plus prior-28-day samples. It doesn't explicitly say 'read' (that lives in the title) and never names a sibling like read_search_rank_history or read_page_insights, but the 'saved, not live provider call' framing separates it from a live-fetch 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?

No when-to-use guidance and no alternative named, despite ~10 read_* siblings that could plausibly be chosen instead (read_page_insights, read_search_rank_history, read_visibility). The 'no refresh, provider call or causal lift claim' line is a constraint statement, not 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?

The description adds useful context beyond the read-only/idempotent annotations: the data is 'indexed database samples' rather than live results, and 'absent observations are unknown' rather than zeroes. That provenance caveat is exactly the kind of behavioral nuance annotations cannot convey, though pagination behavior is not described.

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 zero waste and the key data-provenance caveat front-loaded. Nothing in the description 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 seven-parameter query tool with no output schema and low schema description coverage, the description leaves major gaps: return shape, snapshot granularity, direction meaning, and how filters combine. The provenance caveat is useful but not enough to make the tool fully callable with confidence.

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 only 29%, so the description needs to compensate, but it explains only URL and market implicitly. It does not explain the critical 'direction' enum (in/out/both), the 'area' enum (SEO/GEO/both), or how 'days', 'limit', and 'offset' shape the query.

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

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

The description states a specific resource: saved keyword positions by snapshot, URL and market. It distinguishes the tool from live rank tracking with 'not a live rank campaign', which helps separate it from read_live_search_campaign, though it does not explicitly name that sibling.

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 'not a live rank campaign' implies this is for historical saved data rather than live campaign data, but it never names an alternative tool or gives an explicit condition for choosing one over the other. Usage is inferred rather than stated.

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

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

With no annotations, the description carries the burden. It discloses that the result is an interpretation ('what we think it is about'), implicitly signals a read-only operation via 'Read', and specifies the returned components. It could add caveats about freshness or edge cases, but it is reasonably transparent for a simple read tool.

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

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

Two sentences, front-loaded with purpose and output, followed by usage guidance. Every sentence adds value and there is no redundant 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 single-parameter tool with no output schema, the description covers the output shape, the read intent, and the workflow position. The main gap is parameter format guidance, but the overall context is sufficient for an agent to invoke the tool reasonably.

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

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

Schema description coverage is 0%, so the description must compensate. It only restates the concept of 'domain' without specifying format, examples, or whether to include protocol/subdomains. The property name 'domain' already conveys the basic meaning, so the description adds little 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 action ('Read a domain') and defines the deliverable: a description, audience, and target keywords. It also frames this as the foundational brief for sibling tools, which distinguishes it from tools like qualify_domain or read_document.

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 an explicit when-to-use directive: 'call it first when you do not already have one.' This clearly tells an agent the tool produces the shared input needed by other tools, making the intended workflow unmistakable.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does well by framing the operation as reading 'recorded answers' and returning measurements, which implies a read-only, side-effect-free operation. It also discloses what the grouping options produce (trend versus bucket comparisons), exceeding the minimal safety disclosure expected.

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, each earning its place: the first lists the metrics, the second explains grouping choices, and the third gives dashboard context. The description is front-loaded with the core function and contains 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 two-parameter read tool with no output schema, the description explains the return concept well by naming the metrics and grouping behavior. It doesn't specify the exact response shape or edge cases, but with simple parameters and no nested objects, that is a minor gap.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning by tying the dimension parameter to analytical intent ('find where a brand is weak') and explicitly mapping day to trend and the other dimensions to comparisons, going slightly beyond the schema's terse enum descriptions.

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

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

The description uses a specific verb 'read' and resource 'visibility' while enumerating exact metrics: visibility, share of voice, mean position, and competitor ranking. It clearly distinguishes this tool from sibling tools like read_document and discover_competitors by focusing on the account's own answer-engine measurements.

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

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

The description provides clear context by stating this is 'the data behind the dashboard's Answer Engine Insights' and gives explicit guidance on when to use each grouping: day for trends, and model/region/persona/prompt/topic for finding weak spots. It doesn't name when-not-to-use alternatives, but the context is strong and the sibling list shows no overlapping analytics 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, idempotentHint, and openWorldHint=false, so safety is covered. The description adds only that results are scoped to an 'entitled' saved website map, which is a small but real access/side constraint; it says nothing about what 'readiness' indicates, pagination behavior, or result shape.

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?

Brevity here is under-specification rather than economy: a single noun phrase with no verb and no front-loaded action. Nothing is wasted, but nothing useful is delivered either.

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 and low schema coverage, the description should explain what is returned and how the filters interact. It does neither, so an agent cannot reliably invoke it without guessing.

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?

Seven parameters with only 29% schema description coverage means the description must carry meaning for url, area, days, limit, offset, and direction. It explains none of them; 'pages and readiness' gives no hint about how area, direction, or days alter the result, leaving most inputs undocumented anywhere.

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 fragment 'Pages and readiness in the entitled saved website map' never states a verb and never says what 'readiness' means, so the agent cannot tell whether this returns page records, a status report, or both. It also fails to distinguish itself from close siblings like read_site, read_page_keywords, and read_page_connections, which each name a concrete resource.

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 statement of when to call this versus read_site or read_page_insights, and no prerequisites beyond the implied 'entitled saved website map'. The agent must infer selection criteria entirely from the name and the sibling list.

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

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

Annotations already declare readOnly=false, idempotent=true, openWorld=true, and destructive=false. Beyond that, the description discloses the concrete side effect – one bounded public HTML fetch rather than a CMS write – which is genuinely useful context an agent cannot get from annotations. It does not say whether the check is synchronous or returns a job handle, leaving one behavioral gap.

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 tightly packed sentences with no filler; the affirmative scope comes first and the exclusion list follows immediately.

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

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

For a no-output-schema mutation with four required parameters, the description covers what is recorded, what side effect fires, and what the tool is not. The main missing piece is the outcome shape of the queued HTML check (async job id vs immediate result) and the relationship to read_page_deployments.

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 60%: reviewed, deployedAt, and idempotencyKey are documented in the schema, including the 90-day window and retry guidance. The description adds no parameter detail and leaves workspace and documentId undocumented anywhere beyond type and length, so it neither compensates nor regresses.

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: declaring that already-reviewed changes were applied to their mapped page. The second sentence further bounds the action by ruling out CMS publishing, paid research, and rank-lift proof, so an agent can distinguish this from prepare_page_changes or read_page_deployments.

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 prerequisite is clear from 'reviewed saved changes were applied' – the work must already be prepared and reviewed. The negative scoping ('not CMS publishing, paid research or proof of ranking lift') prevents misuse, but no sibling tool is named as the alternative for those adjacent tasks.

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 idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is largely structured. The description adds genuine value by stating the blast radius ('No provider work, content publication or outcome claim'), which tells the agent this is a bookkeeping-only mutation. However it omits the version-conflict behavior implied by expectedVersion, which is the main risk an agent needs to know about.

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

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

Two tight sentences with the action front-loaded and the scope disclaimer second. Nothing is padded, though the 'using stateVersion and idempotencyKey' clause actively introduces a naming error rather than 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 versioned, idempotency-keyed mutation with no output schema, the description leaves key gaps: what happens on a version mismatch, what state the run must be in, and what the caller receives. The mismatched parameter name further reduces confidence that the agent can invoke it correctly.

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

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

Schema description coverage is 0%, so the description must carry the load for four parameters, but it only nods at two and does so inaccurately: it says 'stateVersion' while the schema requires 'expectedVersion'. runId and workspace are never explained, and no semantics (dedupe key format, concurrency check, workspace scoping) are added over the raw schema.

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

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

The description names a specific verb ('Restore') and target ('a reviewed recorded run to the review queue'), which clearly separates it from the sibling read tools like read_latest_answer_reviews and the forward-looking review_answer_evidence. It stops short of explicitly naming the inverse operation it pairs with, but the intent is 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 agent must infer that this applies to a run that was already reviewed and needs to be placed back into the queue. No alternative (e.g. review_answer_evidence) is named and no precondition or when-not guidance is given, though the negative scope sentence does bound what the call will not trigger.

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 write, idempotent, non-destructive, and closed-world behavior. The description adds meaningful context beyond that: no immediate provider work/job submission, preservation of applied/prepared evidence or fallback to suggested, and different outcomes for scheduled preparation versus failed drafts. It still lacks permission or error details, but adds substantial behavioral value.

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

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

The description is front-loaded with the core action and remains compact across four sentences. Some state-transition language is dense, but there is little obvious 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?

This is a stateful mutation with five parameters, no output schema, and 0% schema description coverage. The description provides useful state outcomes and annotations cover safety, but it leaves parameter purpose, response shape, and error behavior under-explained.

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

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

Schema description coverage is 0% for five parameters. The description names expectedVersion and idempotencyKey but does not explain their meaning, and it says nothing about actionId, reason, or workspace. The schema supplies names, types, and patterns, but the description does not compensate for the missing semantic 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?

The description states a specific verb and object: 'Restore dismissed/archived work', and adds state outcomes. It is clear enough to distinguish this from dismiss_preparation_action, but it does not explicitly name sibling alternatives or clarify 'work' as a preparation action.

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 'Restore dismissed/archived work' and by state-specific notes about fresh suggestions and failed drafts. However, there is no explicit when-to-use/when-not-to-use guidance or comparison to siblings such as dismiss_preparation_action or read_preparation_action.

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 idempotency and non-destructiveness, and the description adds useful scope boundaries: it is not publishing or improving, new runs remain separate, and there is no provider work. It does not cover permission requirements or what happens on version conflicts, but it adds meaningful behavioral context beyond the annotations.

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

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

The description is short, front-loaded, and each sentence adds a distinct constraint: scope, required version/idempotency inputs, run isolation, and absence of provider work. The only weakness is that 'saved stateVersion' introduces ambiguity rather than precision.

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

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

For a mutation tool with four parameters, no output schema, and 0% schema description coverage, the description leaves important gaps. Workspace is undocumented, version-conflict behavior is unexplained, and runId is only implied, so an agent cannot fully understand parameter semantics from the description 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 0%, so the description must carry the load. It mentions 'saved stateVersion and idempotencyKey,' which loosely maps to expectedVersion and idempotencyKey, but the term 'stateVersion' does not match the schema's 'expectedVersion,' the optional workspace parameter is entirely unmentioned, and runId is only obliquely implied.

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: 'Mark one recorded answer run reviewed.' It also scopes the action by saying 'not published or improved,' which helps distinguish it from write-oriented siblings, but it does not explicitly name any alternative 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?

Usage is implied by 'Mark ... reviewed, not published or improved' and 'New runs remain separate,' suggesting this is the narrow review-only action. However, it never explicitly says when to use this versus siblings like read_latest_answer_reviews, restore_answer_evidence, or review_preparation_action.

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 the mutation is non-destructive and idempotent, so the bar is lower. The description adds real value by naming expectedVersion and idempotencyKey, implying optimistic-concurrency failure modes and retry safety, but it never says what a version conflict looks like or what state 'reviewed' transitions the action into.

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 core action and immediately followed by the scope constraint. Nothing is wasted, though the phrasing is dense enough that the identifiers are mentioned without explanation.

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

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

For a mutation tool with no output schema, the description covers the safety profile reasonably and rules out adjacent jobs, but leaves the three undocumented parameters and the post-call state ambiguous. An agent can invoke it without erroring, but cannot confidently construct reason/workspace values.

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

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

Schema description coverage is 0% across 5 parameters, so the description must compensate and it only touches two: expectedVersion and idempotencyKey, without explaining the sha256-hex format or the retry contract. actionId, reason, and workspace are entirely undocumented anywhere — an agent must guess that reason is optional free text and workspace is a scoping selector.

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 — 'Mark a suggestion reviewed' — and then scopes it with 'Task triage only, not copy approval, generation, publication or outcome verification,' which separates it from siblings like prepare_page_changes or dismiss_preparation_action. It is clear what the tool does, though it never explicitly names which sibling to use for the excluded cases.

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 exclusion list ('not copy approval, generation, publication or outcome verification') is explicit when-not guidance that most definitions lack. What's missing is the positive routing: it does not name dismiss_preparation_action or read_preparation_action as the alternatives for the cases it disclaims.

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

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

With no annotations, the description carries the full burden and does well: it discloses that output is an ordered step trace with per-step return values and timings, that a run is consumed from the included quota, and that provider calls draw on a shared collection allowance. Failure modes, async/sync behavior, and timeouts are left unstated, keeping it 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?

Four compact sentences, front-loaded with purpose and return behavior, then input construction, then cost/quota, then the plan prerequisite. No sentence is redundant and nothing is 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?

Since there is no output schema, the description must explain return values, and it does: ordered steps with results and durations. Quota and plan requirements are covered, which is important for a cost-bearing tool. Missing only error/limit-handling detail for a tool that consumes a metered resource.

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 further by telling the agent where input keys come from (describe_agent's `key` field) and implying inputs are a keyed object of the agent's declared inputs. The agent_id sourcing is already in the schema as list_agents, so the added value is real but modest.

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 ('Run one of your agents once') and immediately defines the return shape: per-step results, in order, with outputs and durations. This clearly separates it from sibling management tools like list_agents and describe_agent, which it references only as data sources.

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

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

Gives concrete prerequisites and the tool chain needed to invoke it: agent_id from list_agents, inputs keyed from describe_agent, one included run consumed, and a paid Mentionry plan required. It does not state when to avoid running an agent, but no true alternative execution tool exists among siblings, so context is effectively complete.

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

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

With no annotations provided, the description carries the full behavioral burden. It explains the live-profile check, the reported fields, and the important nuance that removed links appear as changes rather than remaining on the scoreboard. It does not cover errors, rate limits, or propagation delays, but the core behavior is clearly disclosed.

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 main action and output are front-loaded, and the second sentence adds a valuable behavioral detail that prevents misinterpretation of removed links.

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

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

For a tool with only two simple parameters and no output schema, the description provides everything an agent needs to invoke it correctly: what to supply, what the report contains, and how removed links are treated. No critical behavioral information is missing.

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

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

Schema coverage is 100%, so both parameters are already fully documented. The description adds only marginal parameter-level context by framing 'pitched' as the domains to check and 'domain' as your own domain, which mostly restates the schema. Baseline 3 is appropriate.

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

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

The description states a specific action ('Check a list of domains against your live backlink profile') and clearly defines the output: which domains now link, when the link first appeared, and whether it is still present. It distinguishes itself from backlink-related siblings like backlink_gap by focusing on verifying previously pitched domains rather than finding gaps or prospects.

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 clearly implies its context: verifying whether pitched domains have landed links in the live backlink profile. However, it does not explicitly name alternatives or state when not to use this tool, so it stops short of the highest tier of usage guidance.

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

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

With no annotations, the description carries the full burden and does reasonably well: it discloses the cost ('Spends one draft allowance'), the persistence side effect (filed in Documents), and the grounding dependency on a brand kit. It omits permission/auth requirements and what happens if the draft allowance is exhausted, which keeps it from 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 front-loaded sentences that each carry information: what is produced, how it is grounded, and where the result can go. No filler, though the clause about Outlook/Gmail rendering is parenthetical detail that could be trimmed.

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

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

For an 11-parameter generative tool with no annotations and no output schema, the description covers the output artifact and cost but says almost nothing about the inputs, so the agent cannot tell what a good 'brief' looks like or how sections/cta fields map to the rendered email. Adequate minimum viability, but with a clear parameter-semantics 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 only 18% (just title and images), and the description does not compensate by explaining the other nine parameters (goal, tone, notes, offer, audience, sections, cta_url, cta_text, preheader). 'From a brief' is the only hint at how the inputs are consumed, leaving the agent to infer the meaning and format of most fields.

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+resource (write an HTML marketing email) and specifies the technical rendering approach (tables and inline styles for Outlook/Gmail) plus the side effect (filed in Documents for preview). It is clearly distinguishable from siblings like write_landing_page and create_email_draft, which is explicitly framed as a downstream destination rather than the same action.

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

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

It states the grounding condition ('when a brand kit exists') and routes the agent to the correct downstream tools, noting that create_email_draft and app actions 'ask first'. It never states when NOT to use this tool (e.g., plain-text or non-marketing emails), so it stops short of full when/when-not coverage.

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

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

With no annotations, the description carries the full burden and does real work: it discloses the output format and destination, that the draft is private until publish_page, that it draws on the brand kit, and that it spends one draft allowance (a quota/cost signal). It omits permission requirements, overwrite behavior on title collision, and failure modes, so it falls short of fully transparent.

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 action is front-loaded and each sentence adds distinct information (output, brand grounding, image inputs, privacy/quota). Minor looseness in clauses like 'where the customer previews it' keeps it from being maximally 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?

For a 10-parameter mutation tool with no annotations and no output schema, the description covers output, privacy, quota, brand grounding, and image inputs, but leaves several parameters (offer, tone, cta_url, cta_text, audience) with no meaning anywhere and does not explain what 'starts from a brief' means relative to the title/goal fields.

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 50%: goal, notes, title, images, and sections are documented in the schema, while tone, offer, cta_url, cta_text, and audience are undocumented in both places. The description reinforces the images parameter's provenance ('/m/... addresses from generate_image') and the notion of a brief, but does not compensate for the unexplained CTA and audience fields.

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 (write) and resource (a complete, responsive landing page as HTML) with the destination (Documents) and the previewing party named. An agent can distinguish this from content-producing siblings like write_email_template or draft_pitch solely from the description.

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?

Conditional guidance is present: 'Grounded in the brand kit when one exists' and 'Pass the addresses of pictures you generated so the page uses them' tell the agent when certain inputs apply. It also routes the publish step to the sibling publish_page. However it does not state when this tool is preferred over other authoring tools or what preconditions must hold to call it.

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