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

Annotations already declare this is a non-destructive write (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the description only needs to add operational context. It does so by disclosing the locked-check restriction and the optional match-based scoping behavior. It omits whether exceptions are idempotent, reversible, or error on duplicates, which keeps 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?

Three short sentences, zero filler, with the core action and its negative scope front-loaded before the alternative route. 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?

For a 3-parameter mutation with no output schema, the definition covers purpose, key constraint, and the escape hatch to a different tool. The only real gap is what happens on success or on a duplicate exception, which an agent might want before retrying.

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%: `match` is documented in the schema, but `reason` and `check_id` have no schema descriptions. The description only gestures at these ('with a reason', implicitly a finding/check id) and adds the useful 'Optionally scoped' framing for match. It partially, but not fully, compensates for the coverage gap.

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: recording that a finding is acceptable for this team, with an explicit clarification that this is not a tool bug. It also names the contrasting path (/report-problem) so the agent can distinguish this waiver action from bug reporting without consulting other definitions.

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 a clear exclusion ('For tool bugs use /report-problem instead') and a hard precondition ('Locked checks can't be waived'). It does not enumerate when to prefer a waiver over other remediation siblings like bulk_edit_preview, but the when/when-not framing is explicit enough to route correctly.

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

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

The readOnlyHint=true annotation already carries the safety profile, and the description usefully corroborates it ('nothing is written') while adding the search-field scope and result ordering. It does not say whether results are truncated/paginated, how many matches are returned, or how regex errors surface — gaps that matter for a preview 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, zero filler: the search scope and ordering come first, and the read-only guarantee is front-loaded at the end where it functions as the key constraint. Nothing is repeated from the title beyond what is needed.

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 is the only place an agent could learn what a 'preview' actually returns — match counts, per-field diffs, affected-item list — and it says nothing about the result shape or size. For a 6-parameter, cross-field search tool this leaves a meaningful hole.

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 33% (only platform and workspace are documented), so the description needs to carry weight: it does clarify that find accepts plain text or a regex and that replace is the substitution, which maps to the regex flag. But active_only is never explained (the phrase 'live items first' hints at it without defining it), and the boolean default for regex is unstated.

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 ('Find text... and preview the replacement') plus the exact search scope (subject, preheader, body, content block) and the ordering rule ('live items first'). The closing clause 'Preview only; nothing is written' sharply separates it from any apply/commit counterpart, so an agent can identify it 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?

The 'Preview only' clause implies this is a dry-run step before an actual edit, which is useful contextual guidance. However, it never names an alternative tool or states explicit when-not conditions, so routing to it versus the sibling diagnostics (check_message, find_overlaps, etc.) is left to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds real value by disclosing the depth of inspection ('content blocks expanded') and the breadth of what is examined (audience, conversion events, naming, dead ends and unreachable steps). It stops short of saying what a failed check looks like or whether the scan is expensive/long-running on large canvases.

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

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

A single dense sentence that front-loads the action and scope before the parenthetical detail. It is efficient, though the nested parentheticals (Canvas/flow) and (dead ends, unreachable steps) make it slightly list-heavy; splitting the settings clause out would read better.

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

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

For a read-only, three-parameter check with no output schema, the description covers enough: it enumerates exactly what surfaces are validated, which stands in for describing return content. The remaining gap is the identifier format for name_or_id and whether results are per-message or summarized.

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%: platform's enum is self-documenting and workspace's default is spelled out in the schema, but name_or_id has no description anywhere. The description never clarifies whether name_or_id accepts a campaign name, a numeric ID, or both, which is the one genuinely ambiguous parameter for this tool.

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 concrete verb ('QA') plus a precise scope: every message in a campaign or journey, enumerated across emails (with content blocks expanded), push, SMS, in-app, and settings like audience, conversion events, naming and journey structure. The plural 'campaign or journey' scope implicitly distinguishes it from the singular check_email/check_message siblings, but it never names them outright, so the differentiation is inferred rather than stated.

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

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

Usage is only implied: the agent can gather that this is the batch-level QA entry point rather than the single-message check, but there is no explicit when-to-use, when-not-to-use, or named alternative. Nothing tells the agent whether to run show_journey or what_breaks first, or what to do if the campaign is a draft.

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

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

Annotations already declare readOnlyHint and openWorldHint, and the description reinforces the safety profile with 'Read-only; sends nothing.' More valuably, it discloses network behavior that the annotation alone does not: check_links_live uses HEAD requests only and never requests unsubscribe or click-tracking links. It does not describe what a failed check looks like or how results are returned.

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 purpose and checklist are front-loaded in the first sentence and the input-mode and safety notes follow. The middle clause is a long parenthetical list that is dense but scannable, and no sentence 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 10-parameter tool with no output schema, the description covers inputs and behavioral limits well but says nothing about what the check returns or how findings are structured. An agent knows how to call it but not what to expect back, leaving a meaningful 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?

With 70% schema coverage across 10 parameters, the description adds real meaning: it explains that personas are rendered to test personalization ('several synthetic personas'), that link checks cover non-production hosts, unsubscribe, UTMs and approved domains, and that transactional mail skips the unsubscribe rule. A few parameters (name, subject, preheader) are only implied by the checklist rather than directly explained.

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 ('QA one email before it sends') and enumerates exactly what is validated: HTML structure, Outlook conditionals, Gmail clipping, alt text, links, personalization, subject, sender, brand terms, spelling, footer text. It does not explicitly name sibling tools like check_message or check_campaign, so the agent must infer the distinction, keeping 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?

'QA one email before it sends' gives a clear usage context, and 'Pass HTML or a local file path' states the accepted input modes. It stops short of naming alternatives (e.g. check_campaign or check_message) or stating when not to use this tool, so there is no explicit routing guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description reinforces this consistently with 'Read-only; sends nothing'. Beyond that it discloses substantive behavior the annotations cannot: personalization is rendered against synthetic personas, and specific check categories (lock-screen/segment limits, SMS encoding and billed segments, link host validation, secret-in-URL detection) are performed. What is missing is any hint of the output shape or whether checks can fail hard.

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 verb and resource, and every clause names a concrete check rather than restating the title. The single long sentence is dense but readable; it could be split into 'what it does' and 'what it checks' for faster scanning.

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 11 parameters, no output schema and no nested objects, the definition does enough to let an agent assemble a correct call and understand what will be validated. The residual gap is return values: absent an output schema, the description should say whether the agent receives a findings list, pass/fail verdicts, or rendered previews.

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 64%, so the schema carries much of the burden, and the description adds real meaning for personas (rendering synthetic attribute sets), buttons, deep_link, webhook_url and quoted-string breakage in JSON bodies. However it never explains that 'platform' selects the template language whose syntax will be rendered, and 'name', 'image_url' and 'webhook_method' go unmentioned despite 11 parameters. The platform omission is the most costly gap.

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 ('QA one push notification, SMS/MMS, in-app message, content card or webhook') and enumerates the exact channel scope, which immediately separates it from check_email and check_campaign. It also names the rule source ('the team's house rules'), telling the agent which governance framework is applied.

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

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

Usage is implied by the channel list and by the sibling set (check_email, check_campaign), but the description never explicitly says 'use this instead of X when Y' nor states prerequisites such as 'platform must match the template language used in the body'. The 'Read-only; sends nothing' line gives useful framing but 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?

Annotations already declare readOnlyHint and openWorldHint, and the description usefully adds that key values are never exposed (a security-relevant guarantee) and that testing performs one call per connected platform. It stops short of describing failure behavior when a key is invalid or a call fails, which for an open-world diagnostic tool would be valuable.

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 compact sentence with three informative clauses and no filler, front-loading the key status question. The noun-phrase list style is a bit clipped but wastes no words.

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

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

For a simple read-only, single-optional-parameter tool with no output schema, the description adequately covers what the agent gets back: key presence, test results, and required env vars. Only a note on how results are shaped or how failures surface is missing.

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

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

Schema coverage is 100% and the single 'test' parameter is fully documented in the schema, so the baseline is 3. The description's 'test each connection' clause hints at the parameter's effect but does not add format or cost details beyond what the schema already says.

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 three concrete outputs: which platforms have keys configured, per-connection tests, and the environment variables each platform requires. That is specific enough to distinguish it from siblings like launch_health or what_breaks, though the fragment-style phrasing (no leading verb) makes it slightly less crisp than it could be.

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

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

Usage is only implied: an agent can infer this is the tool for diagnosing credential/connection setup, but the description never states when to use it instead of launch_health, what_breaks, or how_to, and gives no 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 and openWorldHint=false, so safety is covered. The description adds meaningful behavior beyond that by signaling the result is approximate — it returns items that 'can't be ruled out,' telling the agent to expect fuzzy candidate matches rather than confirmed collisions.

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 scoping context ('For a planned journey or campaign') and then enumerates the match dimensions without filler. Slightly dense with the trailing 'can't be ruled out' clause, but 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?

Input semantics are adequately covered for a 6-parameter tool with no output schema, but the description never indicates what the response looks like — a per-item list of overlaps with reasons, a grouped summary, or counts — leaving the agent to discover result shape at call time.

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 33% (lists, events, segments, attributes are undocumented in the schema). The description compensates by defining each dimension's role: segments/lists are targeted, events are triggered on, attributes are used — giving the agent the matching semantics the schema omits.

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 analysis: surfacing live campaigns/journeys that share segments, lists, events, or attributes with a planned one. It is framed as a question rather than a verb ('find'), but the resource and matching dimensions are concrete, and it reads distinctly from siblings like what_breaks or what_changed.

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 a planned journey or campaign' implies the pre-launch context, which is real usage guidance. However, no alternatives are named (e.g., what_breaks, check_campaign) and no when-not condition is given, so the agent must infer 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 readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: it discloses the fallback behavior when /setup hasn't run, telling the agent that a returned result may be defaults rather than team-authored rules. It stops short of describing the return shape, but that 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?

Two short sentences with no waste, and the core identification ("the team's rulebook") is front-loaded with the parenthetical gloss clarifying what a rulebook means. Nothing is redundant, though the second sentence reads as a bolt-on rather than integrated context.

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 explaining what comes back. It says the result is the rules and their storage location and may be defaults, but it doesn't convey the return shape (fields, format, what "where it's stored" actually resolves to), leaving an agent partially blind for a zero-param read tool that is otherwise simple.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. The description neither adds nor contradicts parameter information, which is appropriate 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 the resource ("the team's rulebook") and what it returns (the rules plus where they're stored), which is enough for an agent to distinguish it from the write-side sibling save_house_rules. It never states an explicit verb like "get" or "read", relying on the name and the phrase "Returns defaults" to convey the operation, so it falls just short of full specificity.

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 alternatives (save_house_rules, how_to, what_breaks) and no precondition beyond the incidental note that /setup may not have run. An agent must infer that this is the read-side lookup before editing rules; nothing in the text says so.

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

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

Beyond the readOnlyHint/openWorldHint annotations, the description discloses that output is enriched with house rules (naming, sender, UTMs, fallback syntax, footer, channel limits) and, when a snapshot exists, with account context including segments to reuse, live status, and shared content that would affect other live programs. It also states the safety-relevant boundary that no account mutation occurs.

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 opening sentence front-loads what the tool returns and for which platforms, then house rules, then the task catalogue. It is dense but nearly every clause carries information, and the long task list earns its space because the schema's enum has no per-value descriptions. The single-block prose is harder to scan than a short list would be.

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

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

For a read-only tool with no output schema, the description does a good job explaining what the steps contain and what context is layered in. It leaves open the shape of the returned instructions and whether house rules or a snapshot are prerequisites versus optional enrichments, which matters for a 7-parameter 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?

With 71% schema coverage, the schema leaves the twelve-value task enum and channels enum undescribed; the description compensates by glossing every task value, which is genuine added meaning. Platform is covered by both, but target, audience and attributes get only indirect treatment (attributes not addressed at all), so it stops short of full compensation.

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 deliverable (step-by-step instructions for a build or edit task) with a precise scope (Braze, Klaviyo or Iterable, in the platform's own terms, from a doc-verified procedure library). The enumerated task list makes the tool's surface concrete and clearly separates it from siblings like check_campaign or what_breaks.

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 twelve task names effectively encode when to reach for this tool (creating, editing live assets, changing audience, tracking, testing, pausing). It also states the operating mode clearly: 'The plugin never edits the account; a person follows the steps.' What's missing is explicit routing against siblings — nothing says to prefer check_campaign or what_breaks for validation versus this for procedure.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and external-dependency posture are covered. The description adds the connected-account requirement, which is useful, but leaves the key behavioral question unanswered: where the 'stated thresholds' come from (house rules? per-campaign config?) and what happens when no threshold exists.

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

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

Two sentences that are front-loaded with the returned metrics and waste little space. The trailing 'Needs a connected account' sentence is a slightly tacked-on prerequisite but still earns its place as actionable 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 two-parameter read-only tool with no output schema, the description is serviceable but incomplete: it omits the format and source of thresholds, the time window implied by 'recent,' and the accepted form of name_or_id. None of these gaps are fatal, but an agent would need trial and error on the required identifier.

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 50%: platform has both an enum and a description, while name_or_id has neither in the schema nor any explanation in the description. An agent cannot tell from either source whether name_or_id accepts a campaign name, a journey name, a numeric ID, or a URL, which is a meaningful gap for a required 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?

States a specific verb-like outcome (delivery numbers judged against thresholds) and enumerates the metrics covered (sent, delivered, bounces, unsubscribes, spam complaints, opens, clicks). It is clear what the tool returns, but it never distinguishes itself from siblings like check_campaign, check_message, or check_email, which plausibly cover overlapping ground.

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 conditional guidance is 'Needs a connected account,' which is a prerequisite, not a when-to-use rule. There is no statement of when to pick this over check_campaign or check_message, and no exclusions or routing hints despite a crowded sibling set.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description is consistent with them while adding the non-obvious workflow fact that output is a set of proposals requiring human confirmation before persistence. It stops short of describing how many proposals come back or how conflicts with existing house rules are 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?

Two sentences, front-loaded with the action and the enumeration of extracted conventions, with the safety constraint appended where it matters most. Every clause carries information; nothing is redundant.

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

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

No output schema exists, so the description should hint at the shape of the proposals it returns, and it only says they are proposals needing confirmation. Combined with unexplained input parameters, the definition leaves real gaps for a tool with four undocumented 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 description coverage is 0% and none of the four parameters (file, from, html, subject) are explained in the description, nor is it stated which combination constitutes a valid email input or that all are optional. With zero coverage the description was the only place to compensate and it did not.

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

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

States a specific verb and resource ('Read an email... propose house rules from it') and enumerates exactly what it extracts: link domains, UTM params and values, sender, name fallback, US/GB spelling, subject style, footer and postal address. The 'Proposals only; confirm with the person before saving' clause implicitly separates it from save_house_rules, 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?

Gives a clear usage condition ('an email the team considers correct') and a clear boundary ('proposals only... confirm before saving'). It does not explicitly name get_house_rules or save_house_rules as the follow-on/alternative steps, so the routing is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered; the description adds genuinely new behavior by disclosing that the result marks which checks are 'locked (can't be turned off)', which tells the agent something about downstream edit feasibility. It does not address result size, ordering, or whether the full catalog is paginated despite returning 'every check'.

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

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

A single dense sentence that front-loads the resource and return contents, then closes with the two usage cases. Every clause carries information; nothing is redundant with the name or title.

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

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

With no parameters and no output schema, the description carries the burden of describing return shape, and it does so by listing the key fields including lock status. What is missing is a sense of result volume and ordering for a catalog that returns 'every check'.

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 properties, so there are no parameter semantics to explain and the baseline applies. The description correctly implies a no-argument call rather than implying any filters exist.

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 ('every check') and enumerates what each record contains — id, default severity, what it catches, and lock status — so an agent knows exactly what this returns. The verb 'list' is only implied through the name and title rather than stated, and no sibling is named, but no sibling in the set overlaps in 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?

'Use to explain a finding or fill in a problem report' gives two concrete triggering scenarios, which is real when-to-use guidance rather than implication. It stops short of naming alternatives or exclusions (e.g., when to prefer check_message or get_house_rules instead).

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description usefully adds that results come from the 'latest snapshot', implying cached rather than live data, but says nothing about result shape, pagination, or what happens when a query matches many items.

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

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

Two sentences, front-loaded with the core action and followed by the routing guidance. No filler or repetition of schema content.

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

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

With 6 parameters, 50% schema coverage, and no output schema, the description needs to explain what comes back (names? IDs?) and how many. It does not, so an agent cannot tell what it will receive or whether results are directly usable by the check_* 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 only 50%: 'query' and 'active_only' have no field descriptions. The phrase 'by name' does clarify that the free-text query matches on names rather than IDs, which is genuine added meaning. But the description contributes nothing about 'kind' defaulting to 'all', the meaning of 'active_only', or how 'workspace' resolves, leaving a real gap.

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 concrete verb and resource: 'Search the latest snapshot by name.' Combined with the title, an agent can tell this is a name-based entity resolution/lookup tool rather than a checker or editor. It does not explicitly say it returns campaigns/journeys/segments/blocks, so the entity scope comes mostly from the title rather than the description itself.

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

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

'Use it to resolve what the person means before checking, mapping or analysing impact' clearly positions it as a disambiguation step that precedes the check_*/what_breaks siblings. It gives context but no explicit exclusions or named alternatives, so it stops short of a full when/when-not statement.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuine context beyond that: it discloses that 'estimated hours saved' is derived from a stated assumption, and that team mode aggregates across a shared folder and splits per operator. It still says nothing about behavior when the log is empty or partial, or about the 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?

Two sentences, no filler, and the report contents are front-loaded. However, the first sentence is a dense comma list rather than a clear statement of purpose, so the core 'what this is' arrives later than it should.

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 carry its weight by enumerating the report's components, which is the most valuable thing it does. For a three-parameter tool with low schema coverage, though, leaving `days` and `minutes_per_manual_check` unexplained leaves the agent guessing on two of three inputs.

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 `team` is documented. The description reinforces the team semantics and obliquely gestures at `minutes_per_manual_check` through 'estimated hours saved (assumption stated)', but never explains what that parameter controls or its units, and `days` (the reporting window) is not mentioned at all in either the description or 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 names the concrete contents of the report (checks run, problems caught, top findings, weekly trend, hours saved) and its data source (the usage log), so an agent knows exactly what the tool produces. It does not distinguish itself from adjacent reporting siblings such as what_breaks, what_changed, or launch_health, which is the only thing keeping it from 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?

Usage is implied by the aggregation framing and by the explicit 'With team: true' branch, which tells the agent when to flip that flag. There is no statement of when to prefer this over the sibling overview tools (what_breaks, what_changed, launch_health) or any prerequisite beyond the team-folder note carried in the schema.

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

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

Beyond the annotations, it discloses that the observation is persisted on the latest snapshot, labeled "seen-on-screen," and stamped with today's date. It leaves repeat-call behavior and the outcome when no snapshot exists unspecified.

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 cover purpose, source, and persistence without filler. The API-gap context is front-loaded, followed by the concrete recording action and storage 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?

Together with the schema and annotations, the description supports the common invocation, but important behavior remains unclear for a write tool with no output schema. In particular, mode semantics and defaults, snapshot prerequisites, repeat-write behavior, and the returned result are not 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?

The schema already documents platform, item, segment, and workspace, while the description mainly restates the campaign/journey and segment/list relationship and adds their dashboard provenance. It does not compensate for the undocumented mode parameter by explaining include versus exclude behavior or its default.

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 concrete operation: recording which segment or list a campaign or journey targets, with dashboard observation as the source. It is clear and distinct in scope, but does not explicitly differentiate itself from any sibling tool.

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

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

"Fill an API gap" and "as read from the platform's dashboard" establish a clear use case: preserving manually observed audience data that the API does not expose. It does not state when not to use the tool, name an alternative, or explain prerequisites such as the existence of a latest snapshot.

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 state readOnlyHint=false, openWorldHint=true, and destructiveHint=false, and the description usefully clarifies that the external API calls are read-only while the tool writes a local snapshot. It also discloses demo-mode behavior and what gets loaded, but it does not cover authentication needs, rate limits, failure modes, or snapshot storage details.

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

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

The description is two tightly written sentences with no wasted wording. The main action is front-loaded, and the demo-mode note is placed after the core 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?

For a two-parameter tool with no output schema, the description covers the core behavior, the local snapshot outcome, change reporting, and demo mode. It leaves some operational details unstated, such as where the snapshot lives and how results are returned, but it is substantially complete for selection and 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 50%, with demo undocumented in the schema and platform described only as 'Which platform.' The description compensates by explaining demo: true as loading the fictional Fernbrook Market demo account, while platform semantics are left mostly to the enum values.

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: pull campaigns, journeys, segments, templates, and content blocks into a local snapshot, then report changes. It is clear enough to distinguish from most siblings, though the final 'report what changed' phrase overlaps slightly with the sibling tool what_changed.

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 usage detail: set demo: true to load the fictional Fernbrook Market demo account. It does not explicitly say when to use refresh_account versus what_changed, connection_status, or other related sibling tools, so the agent must infer the workflow 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 already mark destructiveHint=true, so the safety profile is known; the description nonetheless adds substantive context: the operation replaces the whole rulebook and locked checks cannot be overridden. It does not say what happens to unspecified keys or what error surfaces when a locked check is violated, which keeps it below a 5.

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

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

The purpose and the confirmation precondition are front-loaded in two short sentences, and nothing is padded. The trailing "Schema: ..." key dump reads as a raw list rather than prose, which is slightly inelegant but still informative.

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

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

For a one-parameter, destructive, no-output-schema tool, the definition covers intent, human-confirmation requirement, the locked-check constraint, and the shape of the payload. The remaining gap is failure/partial-update behavior, which an agent would want before overwriting a rulebook.

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

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

The single parameter has 100% schema coverage and the schema points to get_house_rules, so the baseline is a 3. The description earns an extra point by enumerating the actual rulebook keys (locale, brand, links, compliance, etc.), which the open-ended additionalProperties schema does not reveal at all, though it does not explain what each key means.

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

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

"Replace the team's rulebook" gives a specific verb (replace, not update) and resource (rulebook), which also tells the agent this is a full overwrite rather than an incremental edit like add_exception. The full-replacement scope is enough to distinguish it from the sibling get_house_rules read path.

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?

"Always show the person the changes and get a yes first" is a real precondition that gates invocation and is stated explicitly. It stops short of naming alternatives (e.g., add_exception for a single rule) or saying when not to call it, so it is clear context but not a complete routing rule.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real value by naming the exact structural problems it detects, but says nothing about failure behavior when the journey isn't found, how name_or_id is resolved, or whether the diagram is truncated for large flows.

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 primary output type and then enumerates the secondary diagnostics. No filler, though one clause separating diagram content from problem reporting could improve scanability.

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 convey return shape, and it does reasonably well by naming the diagram format and defect categories. However, for a tool requiring platform + identifier across three platforms, the absence of any parameter or error-path context leaves it only adequate.

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%, and the undocumented parameter is name_or_id — precisely the one that needs clarification (journey name vs. numeric ID, ambiguity handling). The description never references platform, workspace, or identifier resolution, so it does not compensate for the gap.

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

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

States a concrete deliverable (a Mermaid diagram of a live journey/Canvas/flow) plus diagnostic content (dead ends, unreachable steps, empty message steps). This is specific enough to separate it from diagnostic siblings like what_breaks or launch_health, though the verb ('shows') is implied rather than stated.

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

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

There is no guidance on when to pick this over what_breaks, launch_health, or list_items, all of which plausibly overlap in diagnosing a journey. No prerequisites or exclusions are mentioned; the agent must infer usage purely from the output description.

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 readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuine value by disclosing result ordering ('live items first'), the provenance markers per item ('api-verified, parsed from template, seen on screen'), and a separate bucket of 'live items we can't rule out' — information not available in annotations and important given 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?

It is a single run-on sentence with no separation between what the tool returns, how results are ordered, and the caveat list. It is short, but the clauses are not front-loaded and the lack of structure makes it harder to scan than its length warrants.

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?

Because there is no output schema, the description usefully sketches the return shape and ordering. However, it omits routing guidance relative to closely related siblings and says nothing about scope limits (e.g., cross-platform behavior, what 'live' means), leaving meaningful gaps for an impact-analysis 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 75% and the schema already supplies enum values plus examples ('loyalty_tier, VIP members, footer_v2, Order Placed, or a phrase/URL'). The description's enumeration of kinds largely restates the schema's kind enum and adds no format or matching semantics beyond it.

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

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

The description makes clear this is a dependency/impact analysis: it returns 'everything that depends on an attribute, segment/list, content block, event, message or piece of text.' The verb is implicit (the tool name carries it), but the resource and scope are specific enough to distinguish it from siblings like list_items or find_overlaps.

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

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

There is no statement of when to use this versus alternatives such as find_overlaps, list_items, check_campaign, or what_changed, and no preconditions (e.g., must be connected, what happens in demo mode). The agent must infer usage from the purpose sentence alone.

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 disclose readOnlyHint=true and openWorldHint=false, so safety and data boundary are covered. The description adds real behavior beyond that: the baseline-selection rule and the 'live items first' ordering. It does not say what happens when no prior snapshot exists, whether output is truncated, or how large a diff can be, which are the notable remaining gaps.

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

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

A single front-loaded sentence that defines the operation first and then the change taxonomy, closed by a short ordering note. Nothing is repeated from the schema or annotations, and no sentence 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?

With no output schema, the description carries the return-value burden and does so by enumerating the change categories, which effectively sketches the result shape. Missing pieces are the empty/no-snapshot case and any indication of result volume or aggregation, which matter for a diff tool but are secondary.

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 baseline is 3. The description still earns a bump: it explains that `since` acts as a snapshot-selection anchor rather than a strict filter, meaning the agent learns it can get a diff as-of an arbitrary past date. `platform` and `workspace` are already fully documented in the schema and are not restated, appropriately.

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

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

The description names the exact computation — a diff between the latest snapshot and the prior one (or the newest before `since`) — and enumerates the change categories: added, removed, status, content, audience, structure. That is far more specific than the title alone and distinguishes it from inspection siblings like show_journey or what_breaks, though it never explicitly contrasts itself against them.

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

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

Useful usage detail is embedded in the `since` fallback rule (baseline becomes the newest snapshot before that date), which tells the agent how to steer the comparison. However there is no explicit when-to-use/when-not guidance and no named alternative (e.g. what_breaks for regressions, show_journey for flow-level views), so routing must be inferred from the sibling names.

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