Hi, Moose AEO

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

Annotations already cover read-only/idempotent/closed-world, but the description adds real context: results come from the *latest crawl* (not a live crawl), carry the crawl date, and 'unknown' means the check failed to run rather than a coverage gap — a distinction that prevents a costly misinterpretation. It doesn't say whether a crawl is triggered or how stale results can be.

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

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

The core action and the result categories are front-loaded, and the closing 'unknown' clarification earns its sentence. The usage sentence slightly overlaps the opening scope statement, so it isn't perfectly lean.

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

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

With no output schema, the description correctly explains the return values (four verdicts, evidence URLs, crawl date). It leaves open what happens when a project has never been crawled, though the 'unknown' note partly covers that case.

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

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

Schema coverage is 100% and each parameter is documented there, including the parentTopic rationale and the 1–15 topic limit, so the description only reinforces 'one or more topics'. Baseline 3 applies since the schema carries the parameter burden.

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

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

States a specific verb and resource: check the latest crawl for pages that already cover given topics, returning a per-topic verdict. That is distinguishable from the visibility_* siblings (AI-answer visibility) and find_internal_links, though it never names those siblings explicitly to draw the line.

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

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

Gives an explicit trigger condition: 'Use it when the user asks whether their site already has something, and before proposing new content.' No when-not guidance or named alternatives are provided, 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 this is a non-read-only, open-world, non-idempotent, non-destructive creation operation. The description adds substantial behavioral context beyond that: render times, host-device blocking, hosting domains, preview handling, snippet delivery, and the still-rendering follow-up path.

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

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

The description is long but front-loaded: it starts with the output and required source, then moves through workflow, rendering time, snippet handling, and voice options. The 30-voice roster is lengthy but serves parameter selection; some operational details could still be compressed.

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 17 parameters, no output schema, and a complex asynchronous creation workflow, the description is complete enough to call correctly. It covers source requirements, defaults, rendering expectations, result handling, and the user-facing snippet workflow.

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

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

Although schema description coverage is already 100%, the description adds real meaning beyond the schema: it explains the three accepted source modes, states key defaults, maps settings-page choices onto parameters, and describes every voice persona rather than only listing enum names.

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: it creates a two-voice audio episode from article content, rendered as an MP3 with an embeddable HTML snippet. It also implicitly distinguishes the tool from get_audio_embed by positioning that sibling as a follow-up for still-rendering episodes.

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

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

It gives explicit branching guidance: offer the settings page once when voices, length, or player look are unspecified; use defaults if declined; map the pasted settings line onto parameters; and call get_audio_embed later if rendering is still in progress. It also names the accepted source modes, making the call conditions clear.

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

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

Goes well beyond the annotations: discloses a 1–3 minute runtime, the grounding sources (live search results, site crawl, brand guidelines, Brand Truth) which concretely explains openWorldHint=true, the return shape (markdown + structured fields + briefId), and an output-handling instruction. Annotations say nothing destructive and non-idempotent; the description's "creates a new brief" framing is consistent with that.

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

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

Front-loaded with the action and scope, then usage, latency, return value, and the downstream handle. Every sentence carries operational value — the runtime estimate and the "give the returned brief in full" instruction both change agent 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?

No output schema exists, yet the description states the return format and the briefId handoff; no annotations cover the long-running/grounded nature, which the description discloses. For a 5-param creation tool this leaves no significant gap for correct invocation.

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

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

Schema coverage is 100%, so project/topic/guidance/targetUrl/templateType are already fully documented, including the "treated as requirements" note. The description adds no syntax, format, or constraint detail beyond the schema, so the baseline of 3 applies.

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

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

Specific verb + resource ("Creates a search-informed content brief") with explicit scope ("for one project") and an enumeration of what the brief contains. It also distinguishes itself from create_draft by positioning the returned briefId as the handoff to 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?

"Use it when the user wants a brief for a page or article on their site" gives a clear triggering condition, and the briefId reference implies the create_content_brief → create_draft sequence. However, no explicit when-not condition or named alternative (e.g. list_briefs, refresh_content, create_key_points) is given for adjacent cases.

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

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

Annotations already declare it as a non-read-only, non-destructive, non-idempotent open-world write. The description adds material context beyond that: a one-to-three-minute latency expectation, the return shape (markdown draft plus draftId), and a directive on how to present the output. These are the exact things an agent cannot infer from the annotations.

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

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

Four sentences, front-loaded with the action and artifact, then input routing, then latency and return, then the output-handling directive. No filler and nothing repeated from structured fields verbatim beyond what the routing requires.

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

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

There is no output schema, and the description compensates by stating exactly what comes back (markdown draft plus draftId) and how to hand it to the user. Combined with the latency note and input routing, an agent has everything needed to invoke this correctly without a follow-up call.

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

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

Schema description coverage is 100%, so every parameter including the brief/briefId split, guidance, briefTitle and templateType is already documented in structured fields. The description's 'Pass the briefId returned by create_content_brief, or a brief written elsewhere as markdown' restates that schema guidance without adding format or constraint detail, so the baseline 3 applies.

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

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

States a specific verb and artifact ('Writes a publishable first draft in Hi, Moose from a content brief') and enumerates the grounding sources (brief, Brand Truth, brand guidelines, site crawl, polish pass). It is clearly distinguishable from create_content_brief (upstream) and create_featured_image (downstream), both named in the text.

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 routes the agent on which input to use: briefId from create_content_brief versus a markdown brief written elsewhere. It also names the downstream consumer of draftId and instructs 'Give the draft to the user in full.' No explicit when-not-to-use case is given, which keeps it at 4 rather than 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?

Adds substantial context beyond the annotations: grounding in content, Brand Truth and brand guidelines, an account-tier-dependent behavior (paid accounts research real search behaviour first), a latency expectation of one to two minutes, and an instruction to return the FAQs in full since there is no output schema. None of this is derivable from readOnlyHint/openWorldHint alone.

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

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

Front-loaded with what the tool produces, then prerequisites, then the ask-before-calling rule and timing. Dense but every clause carries information; only the grounding phrase ('content itself, Brand Truth and brand guidelines') borders on listy 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?

Covers everything an agent needs for a generative, non-idempotent write: required inputs and their provenance, preconditions, tier-dependent variation, expected duration, and what the returned artifact looks like. No output schema exists, but the description compensates by describing the deliverable and how to present it.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a real constraint the schema does not encode: the schema marks only 'project' as required, while the description states the source (url or draftId) is required and mutually exclusive. The 'guidance' parameter is left entirely to the schema.

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

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

States a specific verb and resource (writes a set of FAQs with answers) scoped to one piece of content, and names the brand-voice/grounding sources. It is clearly distinguishable from siblings like create_key_points or create_draft, and even states the deliverable (FAQPage schema markup ready to paste).

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 lists the two valid source modes (draftId of a saved draft, or a site URL) and names the tools that produce a draftId. It also gives a pre-call routing rule: if the user supplied neither, ask which draft or page before calling. That is when-to-use plus a genuine gate, not just implied context.

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

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

Annotations declare this is a non-read-only, open-world, non-idempotent write, and the description adds the context they cannot: it takes about a minute, it produces an image plus a PNG link, and the file is also saved on the host device. Latency and a host-side side effect are exactly the traits an agent needs before invoking.

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 what is produced and at what size, then how to supply the input, then duration and return. Nothing is repeated from the schema and every 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?

A write tool with five parameters and no output schema, and the description covers duration, the returned artifact, the PNG link, and the host-device copy — everything needed to call it and act on the result.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds a constraint the schema cannot express: title plus summary is only used 'when there is no draftId,' clarifying the schema's implicit either/or despite only project being required. It also notes the brand's saved style still applies when styleIntent is given.

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 ('Creates a featured (hero) image in Hi, Moose') plus concrete scope details — 1200x630, for social sharing and the page, in the brand's saved image style. An agent can distinguish this from create_draft or create_audio without opening a schema.

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

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

Gives explicit input alternatives — 'Pass the draftId returned by create_draft, or a title plus a short summary' — which is real routing guidance for a tool with a conditional required set. It does not state when this tool should be skipped or what it replaces, so it falls short of full when/when-not guidance.

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

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

Annotations already flag this as non-read-only and open-world, so the description focuses on what matters: that runs take about a minute and that the results should be surfaced to the user in full. It does not say whether the key points are persisted or what happens on regeneration, which is the main remaining 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?

Sentences are front-loaded with the core action, then source requirements, then timing and output handling. Slightly longer than strictly necessary but every sentence carries operational information.

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

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

With full schema coverage and no output schema, the description covers source resolution, grounding, latency, and output handling. Only persistence/return structure is left implicit, which is minor for this tool shape.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value by clarifying that url and draftId are alternatives and by instructing the agent to resolve a missing source with the user rather than guessing.

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 ('writes the key points of one piece of content') and defines what key points are (short quotable statements grounded in content, Brand Truth, and guidelines), which distinguishes it from sibling generators like create_faqs or create_content_brief.

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 requires a source and names both acceptable forms (draftId from create_draft/list_drafts, or a page URL), plus a concrete fallback: ask the user which draft or page if neither was given. This removes nearly all selection ambiguity.

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 that this is a read-only, idempotent, non-destructive operation. The description adds substantial behavioral context beyond annotations: crawl-date dependency, exclusion of already-linked pages, approximately one-minute latency, and instructions to return both lists in full.

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

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

The description is front-loaded with the tool's purpose and return shape, then proceeds through source requirements, crawl limitations, timing, and output handling. Despite its length, nearly every sentence carries operational value for correct invocation or result presentation.

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, but the description compensates by explaining the two returned lists, their anchor-text contents, and what is excluded. Combined with annotations and full schema coverage, an agent has enough information to invoke the tool correctly and present results appropriately.

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

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

Schema coverage is 100%, so the schema already documents the five parameters. The description still adds useful selection semantics by framing url, draftId, and content as alternative required sources and by noting that content is for pages not live yet. This goes beyond the raw field 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 begins with a specific verb and resource: 'Plans internal links for one piece of content.' It also distinguishes the exact outputs: outbound link suggestions and inbound link opportunities, each with anchor text, so an agent can tell what this tool uniquely provides.

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 states the source requirement and the three accepted source modes: url, draftId, or content text. It also tells the agent to ask the user for a source when none is given. It does not name alternative sibling tools, but there is no obvious overlapping sibling for this internal-linking task.

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

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

Annotations already cover the read-only/idempotent/non-destructive profile, and the description adds context the annotations cannot: no re-render of the audio, a few-seconds latency expectation, and the polling use case for in-progress episodes. It also prescribes output handling ('give the snippet to the user in full, in a code block'), which matters because there is no output schema.

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

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

Three short sentences, front-loaded with the return value and scoping, then the restyle/poll conditions, then the presentation instruction. Nothing is redundant and the non-obvious caveat (no re-render) appears early.

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

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

For a 9-parameter tool with no output schema, the description covers what is returned (a snippet), what it does not do (re-render audio), latency, the alternate polling use case, and how to present the result. An agent has everything needed to call and handle 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 100%, so every parameter including enums and defaults is already documented; that sets the baseline at 3. The description only loosely groups the styling fields ('theme, layout, colour, title, transcript or attribution') without adding per-parameter meaning beyond what the schema states.

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

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

States a specific verb and resource ('Returns the embeddable player snippet for an audio episode') and ties it to the sibling that produces the input ('made with create_audio'). It also distinguishes the operation's scope by clarifying that the audio itself is not re-rendered.

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 two concrete triggers: restyling via the optional display fields, and picking up an episode that was still rendering. There is no explicit when-not-to-use or naming of an alternative retrieval path, but the conditions for selecting this tool are clear.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds the one behavior annotations cannot express: the call blocks 'up to a minute' waiting for completion, which materially affects how an agent should sequence and time out. It omits what happens on timeout/failure, keeping 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 short sentences, zero filler, with the core action and the acquisition path front-loaded before the blocking-behavior caveat. Every sentence carries distinct information an agent needs.

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

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

The title's payload enumeration compensates for the absent output schema, so an agent knows what a finished job yields. The remaining gap is the failure/timeout path and retry semantics, which are unstated for a blocking call. Otherwise complete for a one-parameter tool with full annotation coverage.

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

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

Single parameter with 100% schema description coverage, so the schema already defines jobId and its provenance. The description's 'Call it with the jobId' and 'jobId returned by the tool that started the job' restate rather than extend the schema. Baseline 3 is the correct ceiling here.

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

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

States a specific verb and resource ('fetches a job ... started by another tool'), and the title enumerates the concrete payloads (brief, draft, image, FAQs, key points, audit, link plan). This makes the async-retrieval role unambiguous against the create_* siblings, though no sibling is named explicitly to complete the differentiation the rubric requires for 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?

Gives an explicit trigger condition: 'Call it with the jobId when a tool answered "still working"'. That is a clear, actionable when-to-use rule tied to observable state rather than guesswork. It stops short of a 5 by not naming the alternative path (e.g. what to do if the job never finishes) or stating explicit 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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing result ordering (newest first) and the key field returned (briefId), which is exactly the behavioral context an agent needs for planning. It does not mention truncation or what happens when no briefs exist.

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

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

A single sentence that front-loads the action and scope, then the routing hint. Nothing is redundant with the schema or annotations, and every clause carries information.

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

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

With no output schema, the description does name the critical return field (briefId) and the sort order, which is enough to call and use the tool. Minor gaps remain around empty-result behavior and what other brief fields come back, but nothing blocks correct invocation.

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

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

Schema description coverage is 100%, with both 'project' and 'limit' documented including defaults and the max of 50. The description only restates that results are scoped 'for a project' and adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Lists the content briefs'), the scoping domain ('saved in the Hi, Moose Library for a project'), and the ordering ('newest first'). It also names the downstream consumer ('the briefId create_draft needs'), which separates it cleanly from siblings like create_content_brief and list_drafts.

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

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

Gives an explicit trigger: 'Use it when the user refers to a brief made earlier,' and implicitly routes agents that need a briefId toward this tool rather than create_draft. It stops short of naming a when-not condition or a competing alternative by name, so it is clear context rather than full routing logic.

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 the safety profile is covered. The description adds genuinely new behavior: results are ordered newest first and each entry carries the draftId required by create_featured_image, which is beyond what annotations convey.

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

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

Two tight sentences with zero filler; the scope and ordering lead, and the chaining hint follows. Every clause earns its place.

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

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

There is no output schema, so the description usefully discloses ordering and that draftId is returned. It could say slightly more about what else a draft entry contains or what an empty result looks like, but it is sufficient for a two-parameter 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 coverage is 100% and the schema documents both 'project' (name from list_projects) and 'limit' (default 20, max 50) with constraints. The description adds no further parameter meaning, so the baseline 3 applies.

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

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

States a specific verb ('Lists') and resource ('drafts saved in the Hi, Moose Library'), plus the scope (per project), ordering (newest first), and the useful payload (draftId). That detail instantly distinguishes it from list_briefs, list_projects, and create_draft.

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

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

'Use it when the user refers to a draft made earlier' gives a concrete trigger condition. It also implicitly routes to create_featured_image by naming draftId as the consumer, though it stops short of explicit exclusions or a stated alternative for other listing needs.

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 behavior, so the bar is low. The description adds permission scoping ('this user can work on'), telling the agent results are filtered by access rights rather than returning all projects.

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

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

A single sentence with the purpose up front and the downstream dependency as the trailing clause. Nothing is wasted or buried.

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

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

With no output schema, the description should hint at return values; it names projectId but not other project fields. That gap is minor given the narrow, read-only scope and the annotations.

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 correctly indicates no filtering input is required and that the identity context is implicit.

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 ('Lists the Hi, Moose projects (websites)') and scopes it to the calling user. The resource is clearly distinct from sibling list tools like list_briefs and list_drafts.

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 clause 'with the projectId every other tool needs' implies this should be called before other tools, which is actionable routing guidance. It stops short of an explicit 'call this first' instruction 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?

The annotations already declare that this is a non-destructive but non-read-only open-world operation, and the description adds substantial context beyond that: it reads the current content, detects or uses the target query, runs live research, compares the content, saves a brief to the Library, and returns both a refresh brief and a revised draft. It also gives the expected runtime of three to six minutes and explains how the returned artifacts should be handled.

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

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

The description is long but front-loads the core purpose and is organized around what the tool reads, compares, returns, and requires. Most sentences earn their place by conveying process or input requirements, though some explanatory detail could be tightened.

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 complex multi-step tool with no output schema, the description is complete: it explains the workflow, required inputs, source precedence, expected runtime, and the two returned artifacts. An agent has enough information to decide whether to call it and how to present the results.

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

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

Schema coverage is 100%, so the schema already documents all eight parameters, and the description does not need to redefine them. It still adds useful semantic guidance by establishing a source precedence order (url preferred, then draftId, then content as text) and by explaining that targetQuery overrides automatic query detection. This is meaningful value beyond the schema 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?

States a specific verb and resource ('Refreshes one piece of content'), defines the scope as existing brand content, and explicitly distinguishes itself from create_content_brief. An agent can tell exactly what this tool is for without opening the schema.

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

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

Explicitly says to use this tool, not create_content_brief, when the user wants to update or improve existing content. It also states that a source is required, lists the acceptable source types in preference order, and instructs the agent to ask the user which page or draft to refresh when no source is given.

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

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

Adds substantial context beyond the annotations: latency of two to four minutes, paid-account-only live search evidence, and that AI crawler access and page-date checks are unavailable for non-live sources. It does not clarify whether the call returns the audit inline or a job handle to be retrieved via get_result, which matters given idempotentHint=false and a get_result sibling.

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

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

Purpose and output list are front-loaded, and the closing instruction to present the audit in full is useful. However, it is a single dense paragraph that bundles output shape, source selection, pricing tier, and latency together, making the key selection guidance harder to scan.

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

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

With no output schema, the description carries the return-value burden and does so well by naming the score, categories, issues, and recommendations. It covers the expensive, open-world run and its time cost; the only meaningful omission is whether results persist and are fetchable afterward.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds value by explaining the trade-off between url, draftId, and content and by noting targetQuery is optional and inferred if absent. It stops short of adding constraints like the 50000-character content limit, but that is already in the schema.

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

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

States a specific verb and resource ('Runs an AEO audit on one piece of content') and immediately enumerates what comes back: score out of 100, category scores, issues, recommended changes with proposed text. This is clearly distinguishable from siblings like create_draft or get_result, which operate on different artifacts.

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

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

Gives an explicit decision rule for the three source modes, ranked ('url of a live page (best, because technical checks ... run only on a live page)'), plus the fallback instruction to ask the user when no source is given. It also explains when to supply targetQuery versus letting inference happen.

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, non-destructive, and closed-world behavior. The description adds substantial operational context: latest versus earlier run comparison, mention/citation rates, excerpts, answer ids, tracked-sample limitations, no causation claims, and expected latency.

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

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

The description is dense but front-loaded and every sentence carries operational value, covering purpose, matching behavior, return fields, next steps, limitations, and latency. Its length is justified because there is no output schema and the tool has non-obvious result semantics.

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

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

Given no output schema and rich behavioral requirements, the description is complete: it explains what is returned per engine, the comparison window, excerpts, answer ids, matched prompts, other brands, and why results are not exhaustive. It also tells the agent how to handle zero matches and what not to claim.

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

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

Schema coverage is 100%, so all four parameters are documented in the schema. The description adds useful meaning beyond the schema by explaining that the question is matched to tracked prompts in any language and that results are limited to tracked engines and prompts, though it does not deepen engine or lookbackDays semantics much further.

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

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

States a specific verb and resource: it answers whether the brand appears in AI search for a topic using stored visibility results, including tracked prompts and engines. It distinguishes itself from visibility_get_answer by routing full-text needs there and from new audits by saying it reads stored results only.

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

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

Explicitly says to pass the user's question or topic in their own words, call visibility_get_answer when the user wants full answer text, and tell the user when no tracked prompt matches. It also clarifies the when-not case: it does not run new checks, so it should not be used when a fresh audit is 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 declare read-only and idempotent, so the description is free to add the things annotations cannot: this is a point-in-time snapshot of engine output and the text must be quoted as-is and treated as data, never instructions. With no output schema, its enumeration of returned fields is also the only disclosure of response 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?

Front-loaded with the action and its identifier, then the payload contents, then the usage trigger and safety note. Three sentences, each carrying distinct information with no repetition of the schema or annotations.

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

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

A two-parameter, read-only single-record fetch with a fully documented schema and no output schema; the description fills that gap by listing the returned fields and adds the prompt-injection caveat. Nothing an agent needs in order to call or interpret it correctly is missing.

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

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

Schema coverage is 100%, so the schema carries the definitions, but the description adds useful provenance for answerId ('as returned by visibility_check_topic') that tells the agent where to obtain a valid value rather than guessing. The project parameter is left to the schema.

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

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

States a specific verb (fetches) and resource (one stored answer) scoped to a project, and enumerates exactly what the record contains: prompt, engine, date, mention/citation status, sources, scorer notes, full text. That detail separates it cleanly from list/summary siblings like visibility_list_results and visibility_get_summary.

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

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

Gives a concrete trigger ('when the user asks to see what an engine said in full') and anchors the id's origin to visibility_check_topic, which is clear routing guidance. It stops short of explicitly excluding alternatives such as visibility_get_summary for aggregate questions, so it is strong but not exhaustive.

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

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

Adds context beyond the annotations: 'Reads stored results only,' 'Takes a few seconds' for latency, and a substantive data-provenance caveat that counts cover only tracked prompts/engines sampled on run days and are never the whole of AI search. That sampling limitation plus the 'never claim causation' instruction is exactly the kind of behavioral disclosure annotations cannot carry.

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

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

Front-loaded with purpose, then filters, then section choices, then comparison windows, then usage routing and caveats — a logical order with no filler sentences. It is dense and runs long for a single paragraph, but nearly every clause carries information an agent needs for a 19-parameter tool.

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

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

Given 19 parameters, a rich output schema, and full annotation coverage, the description supplies what structured fields cannot: section contents, comparison-window semantics, sampling limits, latency, and sibling routing. Nothing material for a correct call appears missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description exceeds it by explaining what each section actually contains (competitors = share of voice per engine and topic plus pages and prompts won; citations = pages and domains cited with own pages flagged; mentions = every brand with rank and sentiment) and by clarifying the compare vs compareFrom/compareTo two-window behavior.

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

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

Opens with a specific verb and resource: 'Returns the numbers behind the Visibility dashboard in Hi, Moose for one date range,' and immediately names the filters it accepts. It also distinguishes itself from the two closest siblings by name, so an agent can route correctly without opening any schema.

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

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

Explicitly states the use case ('reports, dashboards and "how are we doing" questions') and routes alternatives: visibility_list_results for the individual answers behind a number, visibility_check_topic for a one-topic plain-language question. It also gives selection guidance for the sections parameter to keep results small.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely new behavioral facts: reads only stored results, compares the last lookbackDays window against the prior window, covers tracked prompts/engines only, and takes a few seconds to a minute. It also surfaces reporting constraints ('report the window and sample sizes plainly and never claim causation') that an agent could not derive from any structured field.

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

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

Purpose and the five row kinds are front-loaded, and each block (what it returns, what it reads, the drill-down, the coverage caveats) earns its place. It is long and dense — the row-kind glosses and the reporting caveats could be tighter — but there is little pure filler for a tool this rich.

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

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

With no output schema, the description carries the full burden of describing the return shape, and it does: it names every field family per row (gap identity, next step, priority with reasons, consistency, effort, status, opportunity id) plus the richer evidence payload from the opportunityId call. Nothing an agent needs to call this correctly or interpret the result is missing.

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

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

Schema description coverage is 100%, so the schema carries the baseline; the description still adds value by explaining what each action enum value actually means (create-coverage, improve-page, earn-inclusion, correct-description, investigate-change) and by clarifying that opportunityId switches the tool from list mode to single-row evidence mode — a mode change the schema only hints at.

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?

Opening sentence gives a specific verb and resource ('returns the ranked work queue ... from stored AI search visibility results') and anchors it to a concrete UI artifact (the Opportunities tab). It then enumerates the five row kinds, which lets an agent distinguish this from visibility_list_results or visibility_get_summary without opening any schema.

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

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

Clear about the operating mode — 'reads stored results only ... it does not run new checks' — and gives an explicit follow-up path: 'Call it again with opportunityId to get the full evidence for one row.' What's missing is naming of alternatives; it never says to use visibility_check_topic when fresh checks are needed or visibility_get_summary for aggregates, so the agent must infer that 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 readOnly, idempotent, non-destructive and closed-world, yet the description adds real context: 'Reads stored results only, never runs new checks' and 'Takes a few seconds per page.' Pagination contract and the size cost of fields=full are spelled out. It doesn't need to explain return values because an output schema exists, so a 4 rather than 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?

Front-loaded with what a row is, then paging, then usage and alternatives — a sensible order. The long enumeration of row fields is dense but arguably earns its place for table-building; overall it runs a bit long for one tool.

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

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

For a 19-parameter, paginated read tool with an output schema, the description covers purpose, row shape, paging, cost, read-only semantics, sibling routing and latency. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a cross-reference that the schema cannot: the filters behave 'the same as visibility_get_summary.' It also restates the paging contract (default 50, max 200, pass nextCursor back) in workflow terms. The remaining filter parameters are left entirely to 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?

Specific verb and resource: lists stored AI search answers one row per prompt/engine/run. It explicitly distinguishes itself from visibility_get_summary (aggregate numbers) and visibility_get_answer (full text of one answer), so an agent can route correctly without opening a schema.

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

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

States concrete use cases (tables, spreadsheets, custom analyses, drilling into a summary number) and names the alternative for the other job ('Call visibility_get_answer with an answer id for the full text of one answer'). It also gives operational guidance: prefer narrow filters and several pages over one huge pull.

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, so the safety profile is covered. The description adds value beyond that with 'Reads stored settings only, nothing runs' (no job side effects) and 'Takes a few seconds' (latency expectation), neither of which is derivable from structured fields. Not a 5 only because the read-only nature is partly restated.

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 usage guidance and the no-side-effects note are front-loaded and earn their place, but the long multi-clause enumeration of return contents duplicates what the existing output schema already conveys, making the description denser than necessary.

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

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

For a one-parameter read tool with a full output schema, this covers purpose, exact trigger conditions, side-effect profile, and latency. An agent has everything needed to decide to call it and to interpret the result.

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

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

There is a single 'project' parameter with 100% schema description coverage, and the schema already explains that either the project name or projectId is accepted. The description adds no further parameter semantics, so 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 opens with a specific verb+resource ('Lists what Hi, Moose tracks for a project in AI search') and then enumerates the exact payload: tracked prompts with ids/topics/engines/branded flag, topics and engines with counts, competitors, brand aliases and owned domains, run schedule, and stored-answer span. It is clearly distinguishable from siblings visibility_get_summary and visibility_list_results, which are named as downstream consumers.

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

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

Explicit when-to-use: 'Call it before visibility_get_summary or visibility_list_results when the user names a topic, engine, prompt, page or competitor, so the filter values are exact.' It names the alternatives and the triggering condition, which is exactly the routing signal an agent needs.

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