Run1Ads: live Meta ads consultant

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false; the description adds the valuable side-effect scope: nothing changes in Meta or the store. It does not warn that repeat calls are non-idempotent (duplicate fix entries), leaving one meaningful 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?

Three short sentences, zero filler, with the primary usage path and the side-effect scope both front-loaded. 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?

With no output schema, the description omits what is returned (e.g., the new fix's key/id), which would help follow-up calls to mark_fix_done. Otherwise it covers inputs, scope, and side effects adequately for a 6-parameter, all-optional 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 already 83%, and the description still adds real meaning: item_key must come from get_today and carries steps plus the tracking number, while title is the manual alternative. It doesn't clarify how how/why/pillar relate to item_key imports, but the core parameters are well grounded.

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 ('Add a fix to the brand's Run1Ads fix list') and immediately names the sibling tool get_today as the source of the primary input. An agent can distinguish it from get_fix_list and mark_fix_done without opening any schema.

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

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

Gives clear dual paths: pass item_key from get_today to import a finding with its steps, or pass your own title. It also scopes the write ('Writes to Run1Ads only'), which implicitly separates it from store/Meta-mutating tools. No explicit exclusion against mark_fix_done or duplicate additions, so not 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?

Adds real behavioral context beyond the annotations: a hard rate limit (10 questions per brand per day, shared with the app), the closed-world data source ('saved account data only'), and confirmation of non-mutation. The 'never changes anything' clause partially restates destructiveHint=false, but the quota and data-source scoping are genuinely additive.

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

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

Four dense sentences, each earning its place (purpose, data grounding, no-side-effects, quota), with the purpose front-loaded. No filler or repetition.

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

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

For a 2-param advice tool with no output schema and rich annotations, the description covers what it answers from, what it returns (steps you can apply), what it won't do, and the rate limit. Coverage is strong; only the routing vs. sibling data tools is left implicit.

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

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

Schema coverage is 50% – brand_id is documented in the schema with its fallback behavior, while question has only length constraints. The description adds meaning for question by specifying 'plain English,' signaling free-form natural language rather than a structured query, but does nothing for brand_id 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?

States a specific verb (ask) and resource (the consultant) about a specific scope (this brand), which cleanly distinguishes it from the get_*/list_* siblings that retrieve structured data. An agent can tell this is a natural-language advice tool rather than a data fetcher 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 description establishes clear context: use it for plain-English advice grounded in saved account data, and it 'advises only and never changes anything.' It doesn't explicitly name an alternative (e.g., use get_performance for raw metrics), so the when-not 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, idempotentHint, and destructiveHint=false, so 'Read only, saved data' largely restates structured data. It does add one useful signal by distinguishing saved (non-live) data and bounding the video window to 7 days, but discloses no rate limits, auth needs, or data-freshness caveats.

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

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

Two dense sentences that lead with the core function and enumerate the returned content compactly. The trailing 'Read only, saved data' is mildly redundant with annotations but does not bloat the definition.

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 well, listing copy elements, a score, issues, and video metrics including hook/hold rates, drop-off, frame review, and fix steps. Safety is covered by annotations, leaving only minor gaps around timing and how results are scoped.

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

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

Schema description coverage is 100% and the single brand_id parameter (including the default-to-most-recent-brand behavior) is fully documented in the schema. The description adds no parameter information, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: 'Get a review of the copy on ads already running', and scopes it to copy elements (first line, headline, CTA, link) plus video ad metrics. This distinguishes it from data-oriented siblings like get_performance or get_ad_fatigue, though it never names an alternative explicitly.

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

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

Usage is only implied through scoping phrases like 'ads already running' and 'video ads from the last 7 days'. There is no explicit when-to-use statement, no prerequisites, and no guidance on when to prefer this over sibling tools such as get_performance.

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, so the safety profile is covered. The description's 'Read only, saved data' partly restates that, but the 'saved data' note usefully signals the figures are not live (contrasting with get_live_alerts). It adds no detail on pagination, freshness window, or failure behavior.

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

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

A single dense sentence that front-loads the resource and enumerates returned metrics, with no filler. It is slightly packed ('frequency, click rate and its change, and hook rate per ad') but 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 rich annotations, one optional fully-described parameter, and no output schema, the description supplies the one thing the schema cannot: what metrics come back and in what order. Adequate for invoking the tool correctly, though an explicit cue on when to reach for this versus get_performance would close the last 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?

Only one parameter and schema description coverage is 100%, so the schema already explains brand_id and the 'most recently updated brand' default. The description adds no additional parameter meaning, which is acceptable at baseline 3.

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

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

Names a specific resource (ads) and the exact condition being reported (fatigue, signaled by frequency, click rate change, hook rate), plus the sort order (highest frequency first). It is clearly distinct from siblings like get_performance or get_ad_copy_review, though it never names an alternative to contrast against.

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

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

Usage is only implied — an agent infers it should call this when investigating ad wear-out. There is no explicit when-to-use statement, no mention of when to prefer get_performance instead, and no prerequisites beyond the optional brand_id.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so 'Read only' largely restates structured data. The genuinely additive phrase is 'saved data,' which signals the results are a stored snapshot rather than a live computation, plus the note that audiences are flagged for delivery viability. No permission requirements or refresh/freshness semantics are spelled out.

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 core purpose ('Get the audience picture') before enumerating the return contents. It is dense and slightly list-like, but no sentence is wasted and the most important information comes first.

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

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

With no output schema, the description carries the burden of describing returns and does so thoroughly (audience sizes, delivery viability, placement splits). Combined with annotations covering the safety profile and a fully documented single parameter, an agent has enough to call this correctly; only data freshness is left to inference.

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

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

Schema description coverage is 100%, and the single brand_id parameter is fully documented in-schema including the fallback to the most recently updated brand. The description adds nothing about the parameter, so the baseline 3 applies.

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

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

The description uses a specific verb (Get) plus resource (audience picture) and enumerates the concrete contents returned: buyers in the period, saved custom audiences with size and deliverability, and results split by placement. It distinguishes the payload from neighbors like get_performance or get_sales_funnel by naming audience- and placement-specific data, though it never names an alternative tool explicitly.

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

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

There is no when-to-use guidance and no routing to or away from siblings such as get_performance or get_sales_funnel. The only contextual cue is 'Read only, saved data,' which describes the data nature rather than the conditions under which this tool is the right choice.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds the one thing annotations cannot express — that the data comes from a saved store rather than live capture — which is useful context about possible staleness, but it stops there without describing liveness, refresh cadence or result size.

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

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

Two tight sentences: the first front-loads what is returned and its dimensions, the second carries the access/data-source qualifier. No filler or restatement of the name, and every clause adds 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 one-parameter read tool with no output schema, the description covers the result shape (who/what/when) and the data source, which is enough to call it correctly. The only real gap is the undefined horizon behind 'recent' and whether results are bounded or paginated.

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 optional parameter, and the schema documents it at 100% coverage, including the fallback behavior when it is omitted. The description adds no parameter guidance of its own, so the baseline of 3 for schema-covered parameters is the right level.

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

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

Names a specific verb and resource ('Get recent changes in competitor ads') and further pins down the payload as who changed what across volume, angle and format, plus timing. The competitor-ads domain is unique among the listed siblings, so no explicit sibling callout is needed to disambiguate.

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?

'Read only, saved data' implicitly contrasts this with a live/streaming sibling, suggesting it is the lookup against stored snapshots rather than a real-time feed. However, it never states when to prefer this tool, what time window 'recent' covers, or names an alternative, so usage remains inferred rather than explicit.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the appended 'Read only' is redundant. The one useful addition is the data-freshness nuance: the 'did the number move' signal only appears 'once newer data is saved,' which tells the agent results can lag. That is a genuine behavioral detail beyond the annotations, but it is thin.

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 leads with the verb and resource before listing contents. It is dense but earns most of its words, though the mid-sentence freshness clause makes it slightly harder to parse 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 read-only tool with no output schema, the description sketches the return contents (fixes, statuses, whether the number moved) and notes the data-freshness caveat, while annotations carry the safety profile. It is largely complete, with only the filter parameters left unexplained.

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 only 50% schema description coverage, the description should compensate for the undocumented parameters, but it never mentions 'status' or 'brand_id'. The schema does describe brand_id, and the status enum values are self-explanatory, so the description adds nothing about filtering behavior or the 'all' 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 specific verb+resource ('Get the brand's fix list') and enumerates the returned content: the fixes chosen, their status, and whether the metric moved after completion. It is clearly distinct from siblings like add_to_fix_list and mark_fix_done, but it never names an alternative, so sibling differentiation is implicit rather than explicit.

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 context is implied through 'fixes you chose to do' and 'after you marked the fix done,' which hints at the add/mark/get workflow, but there is no explicit when-to-use guidance, no when-not-to-use, and no named alternative (e.g. mark_fix_done for writes). The agent must infer the routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so 'Read only, saved data' is largely redundant with structured data. What the description does add is genuinely useful and not captured by annotations or an output schema: the ordering rule ('critical first'), the composition of the payload (open + 7-day resolved), and that each alert carries a rationale and a fix. It does not mention freshness/pagination limits, which keeps it from a 5.

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

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

Two dense sentences, zero filler. The primary payload (the hourly live check and its freshness) is front-loaded, with the alert content and safety note following in descending importance.

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

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

With no output schema, the description carries the burden of describing returns and does so well — freshness, sections, sort order, and per-alert content. Annotations cover the safety profile and the schema covers both parameters, so the only real gap is the absence of routing guidance versus sibling tools.

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

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

Schema description coverage is 100%, so both parameters (brand_id defaulting to the most recently updated brand, and include_resolved defaulting to true) are fully documented in the schema. The description only obliquely gestures at include_resolved via 'alerts resolved in the last 7 days' and adds no syntax or edge-case guidance. Baseline 3 is correct when the schema does the heavy lifting.

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

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

The description names a specific resource (the hourly live check / alerts) and enumerates exactly what comes back: last run time, today so far, open alerts sorted critical-first, and alerts resolved in the last 7 days. An agent can tell it is an alert-status read rather than a fix-list or performance tool. It stops short of explicitly contrasting itself with near-siblings such as get_today or get_fix_list.

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

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

Usage is implied rather than stated: the description frames it as the 'live check' read and notes it is read-only saved data, which signals when it is appropriate. However, it never names an alternative or a condition that would route the agent elsewhere (e.g. get_fix_list for remediation actions), leaving the when-to-use decision 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, idempotentHint, destructiveHint=false and openWorldHint=false, so 'Read only' is redundant. 'Saved data' adds real context that these are stored snapshots rather than live figures, but freshness, the reporting window covered, and any staleness caveats are not disclosed.

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

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

Two tight, front-loaded sentences with no filler and the metric list is where an agent needs it. The trailing 'Read only' clause is mildly duplicative of the readOnlyHint annotation, costing a bit of economy.

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, annotation-covered read tool with no output schema, the description does the important work of enumerating return values and flagging the saved-data nature. It is slightly incomplete on the time window the saved results cover and any freshness expectation.

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

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

Only one parameter and schema description coverage is 100%, so the schema already explains that brand_id comes from list_brands and that omitting it defaults to the most recently updated brand. The description adds nothing beyond that, which matches the baseline of 3 for full schema coverage.

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

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

States a specific verb (Get) and a narrowly scoped resource, then enumerates the exact fields returned (spend, revenue, ROAS, purchases, click rate, cost per click, frequency) plus the ROAS goal and gap. That enumeration is what separates it from siblings like get_sales_funnel, get_ad_fatigue or get_today.

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

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

There is no when-to-use or when-not-to-use guidance and no named alternative, despite heavy sibling overlap (get_sales_funnel, get_ad_fatigue, get_live_alerts). The only framing is a data trait ('Read only, saved data'), which is not usage 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, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is fully covered by structured data. The description adds the useful nuance that results come from 'saved data' (not a live query) and spells out the returned funnel metrics, but it does not address freshness, latency, or data windows beyond 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?

Two tight sentences, front-loaded with the core purpose, followed by a compact enumeration of the return contents. No filler and nothing redundant with the schema.

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

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

With no output schema available, the description carries the burden of explaining the return shape, and it does so well by listing the steps, benchmark comparison, trend, and worst-losing step. It stops short of 5 only because it says nothing about the metric's timeframe or how to interpret the benchmark.

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

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

There is only one parameter and schema_coverage is 100%: the schema already explains the brand_id fallback behavior ('most recently updated brand'). The description adds nothing about this parameter, so the baseline of 3 applies.

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

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

The description states a specific verb and resource ('Get the sales funnel from ad click to purchase') and even enumerates what each step contains, so the tool's job is unambiguous. It does not explicitly distinguish itself from siblings like get_performance or get_ad_fatigue, so it stops short of a 5.

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

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

The framing 'from ad click to purchase' implies the conversion-analysis context in which this is relevant, and 'Read only, saved data' implies it is a cheap lookup, but there is no explicit when-to-use statement, no prerequisites, and no named alternative such as get_performance. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so safety and idempotency need no repetition. The phrase 'saved data' does add real meaning: results are precomputed rather than live, which usefully contrasts with get_live_alerts. Beyond that, nothing is said about freshness, staleness, or what happens when no check has been run.

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

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

Front-loaded with the core action, but everything after the colon is one sprawling comma-spliced sentence that mixes symptoms, metrics, and fixes. The detail is informative rather than padding, yet it is dense and hard to scan; a bulleted breakdown would serve 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?

With no output schema, the description carries the burden of describing returns, and it does so thoroughly — scores, weakest pages, behaviour, Meta-ad visitor failure modes, and fix steps. Missing only framing items such as the reporting period, data freshness, and behaviour when no checks exist.

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

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

Schema description coverage is 100% and the single brand_id parameter is already documented in-schema ('Brand id from list_brands. Leave it out to use your most recently updated brand'). The description adds no further parameter semantics, so the baseline 3 applies.

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

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

The opening verb+resource ('Get the latest store checks') is followed by a concrete enumeration of what a store check contains (app-browser rendering, Add to Cart visibility, Meta Pixel firing, five scores, weakest product pages, visitor behaviour, Meta-ad visitor failures). That enumeration makes it clearly distinct from siblings like get_performance or get_live_alerts, though the purpose statement itself is a rambling list rather than a crisp one-liner.

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

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

There is no when-to-use guidance at all — nothing says whether this is the weekly diagnostic to run before add_to_fix_list, or how it relates to get_live_alerts/get_performance. The only usage hint ('Read only, saved data') describes the data mode, not when to reach for this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description's 'Read only, saved data' largely repeats that, though 'saved data' adds a useful nuance about staleness. It also hints at return shape ('the number behind it and exact steps') but does not explain freshness or pagination.

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

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

Front-loaded with the verb and resource, then a compact enumeration of contents and a short closing note. Dense but every clause describes actual output content, so little is wasted.

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

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

With no output schema, the description carries the burden of describing return content and does so by enumerating the brief's sections. What remains missing is freshness/timing context and any hint about the response format, but it is largely complete for a single-optional-param read tool.

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

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

Schema description coverage is 100% and the schema already explains brand_id and the fallback to the most recently updated brand, so the baseline is 3. The description adds no parameter-level detail beyond what the schema provides.

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

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

States a specific verb (Get) and resource (today's brief for a brand), then enumerates the brief's contents: the one fix, ranked findings, what changed, what's working, and live check status. This differentiates it as a summary/aggregation tool, though it never names the sibling tools it overlaps with (get_fix_list, get_live_alerts).

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

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

Usage is implied rather than stated: 'the one fix to do first' hints this is the top-level entry point, but there is no explicit when-to-use guidance and no mention of when to prefer get_fix_list or get_live_alerts 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 cover the safety profile (readOnlyHint, destructiveHint false, idempotentHint), so the bar is lower. The description adds useful behavioral context by stating that the result includes brand id and Meta connection status, though it does not discuss pagination or authentication needs.

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

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

Three short sentences, front-loaded with the resource being listed and the key usage hint. No sentence is wasted, and the final 'Read only' is brief even if redundant with annotations.

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

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

For a parameterless, read-only listing tool with rich annotations and no output schema, the description is complete enough: it identifies the resource, the return fields, and when to start here. No additional invocation details are needed.

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

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

The tool has zero parameters and an empty schema, so there are no parameter semantics to explain. A baseline of 4 is appropriate for a parameterless listing 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 names a specific verb and resource ('List the brands'), states the operational scope ('you can open in Run1Ads'), and lists the returned fields ('brand id and whether Meta is connected'). An agent can identify the tool's job 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?

It gives an explicit entry-point condition: 'Start here if you manage more than one brand.' This tells the agent when the tool is useful, though it does not name an alternative for single-brand or other 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 cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description adds real context beyond them: it records a snapshot of the number at that moment and confines writes to Run1Ads only. That blast-radius statement is genuinely useful for a mutation tool.

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

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

Two sentences, front-loaded with the action, followed by one sentence explaining the consequence and scope. No filler or repetition.

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

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

No output schema exists, but the description explains the observable effect (a number is recorded at that moment). Combined with full annotation coverage, the agent has enough to invoke it correctly, though it doesn't say what the call returns.

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

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

Schema description coverage is 100%, so both fix_id and brand_id are already fully documented in the schema, including the fallback to the most recently updated brand. The description adds no parameter-level detail, 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: marking an item on the fix list as done. It is clearly distinguishable from siblings like get_fix_list and add_to_fix_list, and the scope statement ('Writes to Run1Ads only') pins down what the operation affects.

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

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

The description implies the usage context (you mark a fix done so Run1Ads can later verify it worked) but never states when to use this versus get_fix_list or add_to_fix_list, nor any prerequisites. Usage is inferable but not spelled out.

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

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

Annotations declare openWorldHint=true, readOnlyHint=false and destructiveHint=false; the description goes further by clarifying that nothing spends while paused, that a preview is returned without confirm, and that only draftable findings qualify. It still doesn't say whether repeated calls create duplicate drafts (idempotentHint=false hints at this, but the description never addresses re-invocation or auth needs).

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

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

Short, front-loaded, and every sentence carries a distinct constraint (purpose, no-spend, eligibility, user consent). Slightly dense run-on phrasing but no filler.

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

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

For a 5-parameter mutation tool with no output schema, the description covers the safety profile, consent requirement and eligibility gate. What remains thin is the shape of the returned preview and whether a second send duplicates the first draft.

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

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

Schema coverage is 80%, so the baseline is 3, but the description adds real meaning: the confirm flag's false branch (preview, no send) and the fact that item_key must be a draftable finding from get_today. It does not explain the objective or daily_budget semantics beyond the schema, hence not a 5.

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

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

States a precise verb and destination resource ('send one finding from get_today as a PAUSED campaign and ad set on the brand's own Meta ad account') and names the sibling it draws from. It is clearly distinguishable from the other get_* analysis tools in the sibling list.

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 'Only use this when the user has clearly asked for it, and pass confirm true,' and states the ghost path ('without confirm it returns a preview and sends nothing'). It also gates eligibility ('only findings marked draftable can be sent'), so the agent knows the precondition.

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