telegram-ads-mcp

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 still adds the return contract ('ok or the platform error text') and reinforces the read-only dry-run nature. It doesn't say what happens on failure (throw vs. error string) or whether it hits the live platform, which openWorldHint implies.

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

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

Three short sentences, front-loaded with the action and ordering constraint. Almost nothing is wasted; only 'Read-only' partly restates the annotation.

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 an output schema present, return values needn't be fully documented, and the description covers purpose, timing, and side-effect profile. The only gap is failure semantics and whether validation is a live platform call or local lint, which matters for an openWorld tool.

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

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

Schema description coverage is 0%, so the description must compensate. It names both parameters, which is more than the schema title alone, but adds no semantic detail such as format, constraints, or what 'text' length/type is expected. Naming without meaning earns a mid-range score.

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

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

States a specific verb+resource ('Validate promote_url and text') and names the exact fields being validated. It clearly separates itself from the mutation siblings create_ad and launch_ad, which it complements rather than duplicates.

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

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

Gives an explicit trigger ('Use before launch_ad/create_ad'), which is precisely when this pre-flight check matters. It does not address when to skip it or clarify its relationship to the similarly named preview_ad, but the core usage context is unambiguous.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so this is a safe read. The description goes further by disclosing the auth failure mode (ok=false, code=auth) and the remediation path, which is behavior the annotations cannot express. It stops short of noting rate limits or frequency expectations, keeping it at a strong 4.

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

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

Front-loaded with the action and the ordering rule, then the failure branch, then the return shape — a sensible priority order with no filler. The telegraphic 'ok=false code=auth' phrasing is dense but parseable in 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?

An output schema exists, so return values need not be fully explained, yet the description still names the key fields. Combined with the annotations covering the safety profile and the description covering the preflight/failure workflow, an agent has everything needed to call this correctly.

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

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

Zero parameters and full schema coverage, so there is nothing for the description to disambiguate; baseline applies. The listed return fields (owner_id, cabinet, currency, balance, write_gate) add orientation but are not parameter semantics.

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

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

States a specific verb and resource ('Ping the ads.telegram.org session') and clearly separates itself from siblings by naming reload_session as the follow-up and check_update as a distinct concern. An agent can identify this as the session preflight tool 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 an explicit ordering rule ('Use first in every chat') plus a concrete failure branch: on ok=false code=auth, present INSTALL.md DevTools steps and fall through to reload_session. This is textbook when-to-use plus when-to-escalate 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, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavioral context beyond the annotations: it is advisory-only ('Suggest only, never install'), which tells the agent not to chain into an install action.

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

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

Four short, front-loaded sentences with no filler; the purpose leads and the constraint follows. The trailing 'Returns current, latest, command, run_in' is largely redundant given a dedicated output schema exists, so it is slightly less than maximally efficient.

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

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

For a trivial read-only lookup with annotations covering safety and an output schema covering returns, the description is nearly sufficient. The only material omission is an explanation of the 'force' flag, which is undocumented everywhere.

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 'force' has 0% schema description coverage and is never mentioned in the description, so the agent cannot tell whether it bypasses a cache, forces a network re-check, or changes the response. This is the one place where the description needed to compensate for the schema and 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: 'Check GitHub for a newer telegram-ads-mcp release.' No sibling in the list performs this function, so the agent can distinguish it immediately. The scope (GitHub releases of this specific package) is unambiguous.

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

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

'Use when the user asks about updates' gives an explicit trigger condition, and 'Suggest only, never install' further constrains behavior at the point of use. There is no alternative tool to route to, so the lack of named alternatives is not a real gap.

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

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

Annotations already establish this is a non-readonly, non-destructive, non-idempotent, open-world mutation. The description adds genuinely new behavioral context beyond them: the clone lands in on_hold draft state (not published), requires a two-step confirm gate, and reuses the source targeting. It does not cover hash lifetime, whether media/creatives are copied, or any rate limits.

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

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

Four tight sentences, front-loaded with purpose, then usage, then the confirm mechanics, then the return. No filler or restatement; 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?

An output schema exists, so the tool needn't explain return values (the brief 'Returns the new ad id' is minor redundancy). For a 3-parameter mutation at 0% schema coverage the essentials are covered, but the confirm_hash provenance — the key to the two-step protocol — 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 description coverage is 0%, so the description carries the load. It explains confirm ('confirm=true for the gate') and gestures at confirm_hash ('two-step confirm_hash'), covering two of three parameters — but it never says where the hash comes from (a prior non-confirmed call?) which is load-bearing for the flow, and ad_id is undocumented beyond its name.

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

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

The description gives a specific verb (duplicate/clone) and resource (ad) and pins down the resulting state: 'a new on_hold draft with the same targeting.' That scope distinguishes it from create_ad, edit_ad, and get_ad without the agent needing to open the schemas, and it names the motivating scenario ('change immutable targeting').

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 use condition — 'Use to change immutable targeting' — and describes the intended flow (two-step confirm_hash, confirm=true for the gate). It does not state when *not* to use it (e.g., prefer edit_ad for mutable fields), so it falls short of explicit alternatives.

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

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

Annotations already declare the write profile (readOnly=false, destructive=false, non-idempotent), and the description adds genuinely non-obvious behavior: a confirmation gate ('confirm=true if budget>0 or active') and the fact that the ad is created on_hold. It also flags data-format constraints ('IDs semicolon-separated', 'no langs with channels') that the annotations cannot convey.

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

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

Four telegraphic clauses, front-loaded with purpose and the alternative, with no filler. Density is good, though the extreme terseness leaves important operands unexplained for a 41-parameter tool.

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

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

An output schema exists so return values need not be described, but the tool is highly complex (41 params, 3 required, 0% coverage) and the description covers only a fraction of the inputs and their formats. It is well short of what an agent needs to invoke this correctly.

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

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

With 41 parameters and 0% schema description coverage, the schema supplies no meaning and the description must compensate. It clarifies only a few: the confirm gate, semicolon-separated ID lists, and the langs/channels mutual exclusion; the remaining ~35 targeting, budget, and schedule parameters are left undocumented.

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

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

States a specific verb and resource ('Create an ad') plus the distinguishing scope ('full targeting field set', created 'on_hold'). It explicitly contrasts with the sibling launch_ad, so an agent can separate the two without opening either 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?

Names the alternative and the selecting condition: 'Prefer launch_ad for the normal flow', implying this tool is for the full/advanced targeting path. It is clear context but does not spell out explicit when-not cases or other siblings like clone_ad or edit_ad.

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

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

Annotations only declare destructiveHint=true, readOnlyHint=false and idempotentHint=false; the description adds the non-obvious human-in-the-loop confirmation workflow and the critical clarification that 'confirm=true is the gate flag, not the hash'. That is exactly the behavioral context annotations cannot express.

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

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

Three short sentences plus a routing clause, with the destructive warning and the confirmation sequence front-loaded. No filler and nothing repeated from the schema or annotations.

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

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

An output schema exists, so return values need no explanation, and the destructive flow is fully covered. It omits permission/authorization requirements and any note on consequences for related entities, but nothing essential to calling it correctly is missing.

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

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

With 0% schema description coverage, the description compensates well for the two risky parameters: it explains that confirm_hash comes from a prior call and that confirm is a boolean gate rather than the hash. ad_id is left unexplained, but its meaning is self-evident from the verb.

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

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

States a specific verb+resource ('Delete an ad') and immediately flags it as destructive. It also distinguishes itself from the closest sibling by noting 'To pause use `edit_ad`', so an agent can pick it correctly without opening any schema.

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

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

Gives an explicit two-step protocol: call without confirm_hash, show the user, then call again with the returned hash. It also states the when-not condition (pausing should use edit_ad) and disambiguates which flag is the real gate.

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 the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), so the bar is lower, yet the description still adds meaningful behavior: partial-update semantics ('only the fields passed'), the confirm=true guard on activate/budget, and that budget_target is read back rather than round-tripped. It omits what happens on failure, whether edits are reversible, and any rate limits, so not a 5.

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

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

Three short sentences, each front-loaded with an actionable fact: scope, immutability/alternative, and the confirmation prerequisite. No filler, no restatement of the tool name, and the most important constraint (edit only what is passed) 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?

For a 24-parameter mutation tool this is adequate but thin: an output schema exists so return values need no explanation, and annotations cover the safety profile, but the description documents only a small fraction of the parameters. An agent trying to edit media, scheduling, or audience-related fields gets no guidance on whether those are supported or what values are expected.

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 0% across 24 parameters, so the description carries the full burden and only partially meets it. It adds genuine semantics for the budget parameters (budget_action must pair with budget_amount, or use budget_target, which is read back) and maps 'pause/activate' to the active field. However, the majority of parameters (media, clear_media, title, button, schedule, schedule_tz, audience_id, promote_url, conversion_event, etc.) are never mentioned, leaving most of the schema opaque.

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 (edit) plus resource (ad) and enumerates the editable field groups (copy, CPM, pause/activate, budget), which is far more than a restatement of the name. It also explicitly carves out targeting as out of scope and points to the sibling `clone_ad`, so an agent can separate it from clone_ad/create_ad/delete_ad. It falls short of 5 only because it does not frame itself against get_ad or preview_ad, the other ad-level tools.

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

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

Gives concrete when-to-use rules: only pass the fields you want changed, targeting is immutable so use `clone_ad` instead, and activate/budget operations require confirm=true. That is a real routing condition plus a prerequisite. It does not say when *not* to use edit_ad versus launch_ad or create_ad, which keeps it from a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered. The description adds workflow context (call before writes to verify currency and the write gate), but never explains what a gate state means or what happens if the gate is closed, so added value is modest.

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

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

Two sentences with no waste: action first, then usage trigger and alternative, then returned fields. Nothing requires trimming.

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?

An output schema exists, so the trailing field list (owner_id, cabinet, currency, money, balance, write_gate) is partially redundant, and it is the only thing slightly bloating the description. For a zero-parameter read tool with full annotation coverage, the purpose and routing information are otherwise complete.

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

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

The tool takes zero parameters, so the baseline is 4. The currency values mentioned (GRAM/EUR/XTR) describe returned data rather than inputs, and the agent has no parameter ambiguity to resolve.

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 the current cabinet card") and explicitly separates itself from the sibling that handles advertising data ("for the ad list use `get_ads`"). An agent can distinguish it from list_accounts/select_account 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 an explicit when: "Use before any write to check currency and gate," and names the alternative for a closely related need ("use `get_ads`"). The trigger condition and the routing rule are both stated, not implied.

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, open-world, non-destructive, so the safety profile is covered. The description adds genuinely useful non-obvious behavior: it 'Falls back to HTML/list when getAd returns 400,' disclosing an error-handling quirk that the annotations do not capture.

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 core action, then usage routing, then fallback behavior. Most sentences earn their place, though 'Returns the ad card' is mildly redundant given an output schema exists.

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?

Output schema exists, so the description need not explain return values, and it doesn't over-invest there. It covers action, alternative, and failure fallback, which is nearly everything an agent needs for a simple one-param read tool.

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

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

Schema description coverage is 0% for the single ad_id string, so the description must carry parameter meaning. It implies ad_id is an ad identifier ('by id') but adds no format, type, or validity guidance beyond that, leaving the param thin.

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 ('Fetch one ad by id with full fields'), and the singular 'one ad' implicitly distinguishes it from the sibling get_ads list tool. The scope ('full fields') is concrete enough that an agent knows what it gets back.

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

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

Explicitly routes metrics work to get_ad_stats ('for metrics use `get_ad_stats`') and frames this tool for diagnosis. It gives clear when-to-use context but does not address the other adjacent siblings (get_ads, preview_ad), so it falls just short of fully exhaustive 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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower. The description adds real behavioral context beyond them: 100-per-page batching, the pagination loop via offset_id=next_offset_id, and the returned fields. It stops short of stating rate limits or truncation behavior, so not a 5.

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

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

Three compact sentences, front-loaded with what the tool does, then usage, then pagination mechanics. Every clause earns its place with no filler.

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

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

With an output schema present, the return-field mention is a bonus rather than a requirement, and pagination plus filtering are covered. The only real gap is the unexplained `detail` parameter, which an agent would have to guess at.

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

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

Schema description coverage is 0%, so the description carries the burden. It explains offset_id (pagination continuation via next_offset_id) and repeats the status enum, but the 'detail' parameter (summary|full) is never mentioned, leaving one of three parameters undocumented anywhere.

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

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

States a specific verb and resource ('List ads'), gives the page size, and names the sibling it is not ('for one ad use `get_ad`'). An agent can distinguish it from get_ad and get_ads-adjacent list tools 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?

Explicitly scopes usage ('Use for account overviews') and routes to the alternative ('for one ad use `get_ad`'). The when-to-use condition and the competing tool are both named, leaving nothing 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 cover readOnly/idempotent/non-destructive, so the safety profile is handled. The description adds real behavioral context beyond that: the spend scaling caveat ('already scaled (Gram); never divide') and that detail=full adds charts. It omits any auth or rate-limit notes.

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

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

Three dense sentences with no filler; the returned metrics and the key scaling warning are front-loaded, and the sibling routing comes at the end.

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 an output schema present, return structure need not be described, yet the description still names the metrics and the spend-scaling gotcha. Combined with the period/detail semantics and sibling routing, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 0%, so the description carries the burden and largely does: it defines the non-obvious enum values for period (5min vs day) and explains detail=full. It leaves detail=csv and ad_id unexplained, but ad_id is self-evident.

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) plus the exact resource (stats for one ad) and enumerates the returned metrics (views/clicks/CTR/CPC/CPM/spend). It explicitly distinguishes itself from the sibling get_ads for the many-ad case.

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?

Routes the agent to the correct alternative: 'For many ads use `get_ads`.' It also defines when each period mode applies (5min = last 24h, day = lifetime), which is exactly the selection guidance an agent needs.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description still adds a genuinely useful behavioral edge case — 'Empty list means not embedded' — which tells the agent how to interpret an empty result rather than treating it as an error.

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

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

Two dense sentences: scope first, alternative second, edge-case semantics last. Nothing is wasted and the routing information is front-loaded.

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

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

With an output schema present, return values need no explanation, and the description covers scope, alternative-tool routing, and empty-result semantics. The only meaningful gap for this one-parameter read tool is the unexplained/tension-laden `kind` enum.

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 the single `kind` parameter (enum user/channel/both) is never mentioned in the description. Worse, the enum offers kind=channel while the description says to use `search_targets` for channels, so the parameter's meaning is not just undocumented but potentially misleading.

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 enumerates the returned resource types (countries, languages, topics, channel taxonomies with IDs), which is far more than a restatement of the name. There is a mild internal tension: it claims to list channel taxonomies but then routes channels/bots to `search_targets`, leaving an agent slightly unsure what the channel portion of the output actually is.

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 explicitly states the use case ('user-geo and topic targeting') and names the alternative tool with the condition that selects it ('for channels/bots use `search_targets`'). This is exactly the when/when-not routing an agent needs among 25 siblings.

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

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

Annotations already establish write (readOnly=false), non-destructive, non-idempotent, open-world behavior. The description adds genuinely non-obvious traits: the ad never activates (stays on_hold), it goes to review, and it carries a spend-confirmation gate. It does not explain skip_review semantics or failure modes, so it stops short of a 5.

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

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

Three dense, front-loaded sentences with no filler; the core flow (create on_hold, budget, review) comes first. 'Returns per-step results' is mildly redundant given an output schema exists, but it is not wasteful enough to drop the score.

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?

Output schema exists, so return values need no explanation, and annotations cover the safety profile. However, for a 26-parameter tool the description is thin: it leaves the targeting/param surface essentially unexplained and creates ambiguity about whether the tool's own targeting fields apply or whether create_ad is required.

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

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

Schema description coverage is 0% across 26 parameters, so the description must carry parameter meaning and largely does not. It usefully documents two high-value params (budget defaulting to 1 Gram, confirm=true gate for spending), but the remaining ~24 params, including all targeting fields, are undocumented in both description and schema.

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

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

The description states a specific composite action: create the ad in on_hold, set budget, send to review, and never activate it. It names the sibling it is not (create_ad for full targeting). Clarity is slightly undercut by ambiguity over whether the tool's own targeting params are usable, since the description points to create_ad for 'full targeting' while the schema carries 20+ targeting fields.

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 for new ads' gives a clear positive selection rule, and 'full targeting via create_ad' names an alternative with its distinguishing condition. The spend precondition 'confirm=true unless gate=open' adds a concrete gate. No explicit when-not-to-use beyond the create_ad pointer, 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuine context beyond that: the result is scoped to 'this Telegram login' (an active session is implied) and it spans all cabinet types (TON, EUR, Stars).

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 core action, followed by the workflow hook and the scope note. No filler or repetition of the schema/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?

An output schema exists so return shape need not be explained, and the description nonetheless confirms it returns accounts. With annotations covering safety and the description covering session scope, workflow role and cabinet coverage, an agent has everything needed to call this correctly.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No misleading parameter language is present.

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

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

States a specific verb and resource ('List ad cabinets'), and immediately reconciles the name/description mismatch by clarifying cabinets == accounts for this Telegram login. It is clearly separable from siblings like get_account (single account) and select_account (which consumes the owner_id this tool produces).

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

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

Gives explicit workflow guidance: use it to find owner_id before calling `select_account`, which tells the agent both the purpose and the next step. It does not state when-not to use it (e.g. versus get_account), so it stops short of full alternative coverage.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the word "Destructive" adds nothing. What earns credit is the real-world consequence it discloses beyond the annotations: the user needs fresh cookies in .env afterward, an operational side effect no schema or annotation conveys.

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

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

Three tight clauses separated by semicolons: the action, the consequence, then the usage restriction. Front-loaded and zero waste.

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?

An output schema exists, so return values need not be explained, and annotations carry the safety profile. The description adds the post-condition and usage restriction, but the undocumented confirm parameter keeps it from being complete.

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

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

Schema description coverage is 0% and the sole parameter (confirm) is never mentioned in the description. The description says "use only when explicitly asked" but does not connect that to the confirm boolean that enforces it, leaving the safety gate undocumented.

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

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

States a specific verb and resource ("Log out of ads.telegram.org"), far more precise than the bare title. It does not name which sibling to prefer instead, so differentiation from reload_session or revoke_token is only implied.

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

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

Gives an explicit positive condition ("use only when explicitly asked") and an explicit exclusion ("Never use it to fix auth"), which is exactly the when/when-not guidance an agent needs for a destructive 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 indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true. The description adds important behavioral context: list is read-only, delete/clone require a two-step confirmation via confirm_hash and confirm, and access_denied should be skipped without retry. This goes beyond annotations by detailing the confirmation workflow and error handling. It doesn't explain what happens on create/rename errors or the output format, but given the annotations and output schema, this is a good level of disclosure.

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

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

Extremely concise: two sentences that pack action enum, read-only note, confirmation requirement, and error handling. No filler, front-loaded with the core operation list.

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 multi-action tool with 7 parameters and 0% schema coverage, the description covers the action semantics and critical confirmation flow but omits parameter-to-action mapping and output details (though output schema exists, so return values are covered). It also doesn't mention required parameters for each action (e.g., audience_id for rename/delete/clone). Given the complexity, more guidance on parameter usage would improve completeness.

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

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

Schema description coverage is 0%, so the description must compensate. It maps actions to parameters implicitly (confirm_hash and confirm for delete/clone) but doesn't describe the other parameters: title, user_ids, file_path, audience_id. For example, it doesn't say which action uses audience_id, or what file_path/user_ids are for (create/clone?). This leaves several parameters semantically unexplained. Baseline 3 is appropriate.

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

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

States the resource (custom audiences) and enumerates the exact operations: list|create|rename|delete|clone. An agent knows precisely what this tool does without ambiguity, and the operation set distinguishes it from sibling tools like create_ad or edit_ad.

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

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

Provides clear conditional guidance: 'list is read-only; delete/clone use two-step confirm_hash plus gate confirm' and 'code=access_denied means skip, do not retry.' This tells the agent when to set confirm_hash and confirm, and how to handle a specific error. However, it doesn't explicitly state when to use this tool vs alternatives or prerequisites for each action beyond the confirmation flow.

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

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

The description adds genuinely useful safety context that booleans cannot express: only one action is destructive, it is gated by a two-step confirm_hash, and access_denied should be treated as a skip. But it directly conflicts with the tool annotation destructiveHint=false by asserting that delete is destructive, giving the agent two contradictory signals about safety; that conflict caps the score.

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 resource, then the action set, then the safety and error semantics in a few dense clauses with no filler. The only cost of the compression is slight ambiguity in fragments like 'code=access_denied means skip', where the referent is not spelled out.

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?

An output schema exists, so return-value explanation is legitimately omitted, and the description does cover the critical safety flow. But for a 6-parameter mutation tool with 0% schema coverage, it leaves the fields required by each action (e.g. title for create, event_id for rename/delete) unaddressed, so an agent still has to guess per-action argument requirements.

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

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

Schema description coverage is 0% across 6 parameters, so the description carries the full explanatory burden. It explains the action values (which the enum already conveys) and hints at confirm_hash via the 'two-step confirm_hash' flow, but says nothing about confirm, event_id, event_type, or title, leaving most of the parameter surface undocumented.

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

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

The description names a specific resource domain (conversion events and pixels) and enumerates the concrete action verbs (list|create|rename|delete|create_pixel), so an agent knows exactly what surface this tool covers. It does not explicitly differentiate itself from similarly named siblings like manage_audience or manage_funds, 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?

Action-level usage is implied well: list is read-only, delete needs a two-step confirm_hash, and access_denied should be skipped rather than retried. However, there is no explicit 'use this tool when X, use sibling Y otherwise' guidance, and no stated prerequisites for create/rename, so usage is only partially inferable.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds real context beyond them: money moves immediately ('no hash'), and destructive actions require confirm=true and explicit user consent. The irreversibility/immediacy and the confirmation protocol are the substantive additions; no auth or rate-limit detail is given.

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?

Very compact and front-loaded: resource first, then action semantics, then the destructive precondition. The fragment style ('no hash') is slightly cryptic, but every clause carries information and nothing is padded.

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?

An output schema exists, so return values need no explanation. For a multi-action mutation tool, the safety protocol and action mapping are present; the remaining gap is the semantics of amount/query and the account_id requirement per action.

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

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

Schema description coverage is 0%, so the description must compensate. It fully explains the action enum, the confirm flag, and how to treat account_id, but says nothing about query, amount, or additional_comment (e.g., amount format, whether add requires account_id), leaving three of six parameters unexplained.

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

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

Names the resource (funds) and maps each enum action to a meaning: list|search are lookups, add is a top-up request, transfer|withdraw move money immediately. That is far more specific than the title, though it does not differentiate itself from adjacent money/account siblings like list_accounts or get_account.

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 when-to-use mapping per action and a hard precondition for the destructive branches (confirm=true plus an explicit user yes). It also instructs 'Never guess account_id', an actionable guardrail. It stops short of naming an alternative sibling tool to use 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?

Adds key behavioral context beyond annotations: the file output path './previews (gitignored)' and an explicit statement that it returns an image. Annotations already cover the safety profile (readOnly, idempotent, openWorld), so this description fills the gaps about what the tool does with the output.

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

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

Three sentences, no waste. Front-loads the primary action, then usage context, then return type. Every sentence earns its place.

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

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

Given the simplicity (1 required parameter, no output schema), the description is complete enough. It covers purpose, usage, and output. The only gap is how to obtain 'ad_id', which is minor but leaves a small 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 coverage is 0%, so the description must compensate. It doesn't explain what 'ad_id' refers to or how to obtain it (e.g., from get_ads). The only parameter is effectively undocumented, leaving the agent to infer its source. Baseline 3 for one parameter, but with no added semantic value.

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

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

States a specific verb+resource: 'Render a sponsored-message preview PNG'. This clearly distinguishes it from get_ad (retrieves data) and create_ad (creates). The specific output format (PNG) adds helpful precision.

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

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

Explicitly states when to use: 'to show the user the copy before launch or during diagnosis'. It doesn't name alternatives like get_ad, but the use context is clear enough for an agent to select this tool correctly.

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

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

Annotations already declare non-read-only, non-idempotent, non-destructive and open-world behavior. The description adds context beyond that: the operation re-reads a local .env file from disk, the session is rebuilt as a side effect, and credentials must not be passed in. That is genuinely useful, though it doesn't discuss failure modes when .env is stale.

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: action first, then trigger, then constraint. Every sentence earns its place with no padding.

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

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

An output schema exists, so return values need not be detailed, yet the description still notes the ok result and session card. Combined with full annotation coverage and a zero-parameter schema, the definition gives an agent everything required to invoke it correctly.

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

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

The tool takes zero parameters, so the baseline is 4. The description reinforces this by explicitly warning against passing cookie values, which clarifies the no-argument contract rather than leaving it implicit.

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

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

The description states a specific verb and resource: 'Re-read .env cookies and rebuild the HTTP session.' An agent immediately understands the operation. It does not explicitly contrast with the closest sibling check_session, so it falls short of the highest bar.

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 trigger ('Use after the user updated .env on disk') and a hard constraint ('never pass cookie values as arguments'), which is more than most tools offer. It stops short of naming an alternative such as check_session for the case where the user wants to inspect rather than rebuild.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that: it discloses the two-step revoke-and-regenerate behavior and warns against using it as an auth fix. It stops short of stating permission requirements or whether regeneration is immediate/irreversible.

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-loading the operation and scope before the usage constraints. No filler; every clause earns its place.

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

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

For a destructive, non-idempotent tool with an output schema, the description covers what happens, when to use it, and when not to. The only material omission is semantics of the confirm parameter, which is minor against annotations that already carry the safety profile.

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 the single 'confirm' parameter is never mentioned in the description. The phrase 'use only when the user asks' loosely gestures at a confirmation gate but does not explain that confirm must be set true or what happens under the default of false, so the description does not compensate 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?

States a precise verb (revoke/regenerate), the exact resource (cabinet API IP-whitelist token), and explicitly scopes out a look-alike ('not the ads cookies'). An agent can distinguish this from save_api_settings or log_out 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 explicit when ('use only when the user asks') and when-not ('never use it to fix auth') guidance. This is exactly the kind of routing and exclusion an agent needs for a destructive operation, leaving nothing 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?

The description explicitly labels the tool 'Destructive', while the annotations declare destructiveHint=false. These are directly conflicting signals about whether the operation destroys or overwrites data, so the agent cannot trust either source. (The added 'confirm=true' requirement is useful, but the core behavioral claim contradicts the structured metadata.)

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

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

Three short, front-loaded sentences with no filler; the destructive warning and the confirmation rule are both immediate. The 'gate=open' clause is wasted and misleading text, which is the only structural blemish.

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?

An output schema exists, so return values need not be described. But for a mutating settings tool, the description leaves the contradiction with destructiveHint unresolved and references an undefined gate condition, so the agent still lacks a coherent picture of the operation's effects.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It does clarify that ip_list is newline-separated and that confirm should be true, but it never explains what confirm=false does and invents a 'gate' parameter that does not exist, which risks an invalid call.

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: 'Set the newline-separated IP whitelist for the cabinet API token.' The scope and data format are clear, and no sibling tool overlaps with API settings, so an agent can identify the operation without ambiguity.

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

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

'Use only when the user asks' gives an explicit usage restriction, and 'confirm=true' gives a precondition, which is more than most siblings offer. However, 'unless gate=open' references a condition/parameter that does not exist in the schema, so the guidance is partially unusable as written.

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds useful non-schema behavior: it is a lookup that must precede mutating calls, and it returns a platform match list. It does not mention rate limits, auth scopes, or what happens on no-match.

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

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

Three tight sentences with zero filler, and the core action is front-loaded before the usage constraint and the purpose disambiguation. Every clause adds information an agent needs.

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

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

An output schema exists, so return values needn't be detailed, and the safety profile is carried by annotations. The gap is the six-parameter surface at 0% schema coverage: half the parameters (ids, query, region, country) have no meaning anywhere in the definition, leaving an agent to guess how to narrow a search.

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 0%, so the description carries the parameter burden, and it does explain two of the six: the kind values map to the listed resource classes, and purpose is disambiguated ('target (placement)' vs 'promote (URL lookup)'). However, ids, query, region and country are left entirely unexplained, so the compensation is only partial.

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 ('Resolve') plus the exact resource classes it operates on (channels, bots, search queries, locations, similar_*), and states the output ('to IDs'). An agent can distinguish this ID-resolution step from the mutation siblings (launch_ad/create_ad) 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?

It says explicitly when to call it ('Use before launch/create') and gives a strong anti-pattern ('never guess IDs'), which routes the agent away from fabricating identifiers. It stops short of naming the specific sibling tools (launch_ad, create_ad) as the alternatives it precedes, so it is clear context rather than a fully explicit when/when-not map.

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 confirm a non-read-only, non-destructive, non-idempotent, open-world operation; the description adds real value beyond that by disclosing the write-gating mechanic ('confirm=true under gate strict') and the required post-step. It does not explain what happens when confirm is omitted or whether the switch is reversible.

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, front-loaded sentences that open with the action and then layer condition, mechanics, and follow-up with no filler. The compressed 'Writes: confirm=true under gate strict' phrasing is terse jargon that slightly taxes readability.

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 state-switching tool with an output schema (so return values need no explanation), the description covers the action, the trigger, the parameter source, the write gating, and the recommended follow-up call. Nothing essential is missing.

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

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

Schema coverage is 0%, so the description must carry the burden, and it does explain both parameters: owner_id is sourced from `list_accounts`, and confirm is the write-gate flag enabled under strict gating. It leaves the confirm=false default behavior 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 and resource ('Switch the active ad cabinet') and names the source of the key parameter ('by owner_id from `list_accounts`'), which distinguishes it from the list/get siblings. An agent can tell exactly what state this tool changes without inspecting 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?

Gives an explicit trigger ('Use when the wrong or a Stars cabinet is active') and a follow-up step ('Then call `get_account`'). It does not state when not to use it or name an alternative switching path, so it falls short of a full routing guideline.

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

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

Annotations already declare it is a non-idempotent, non-destructive write to an open world. The description adds value beyond that: the non-zero budget precondition, the submission/resubmission distinction, and the confirm semantics. It does not explain what moderation failure looks like or whether resubmission overwrites prior state.

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

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

Four short, front-loaded clauses with no filler. Slightly telegraphic — 'spend-class' and 'gate=open' are unexplained jargon — but every sentence carries routing or constraint 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?

An output schema exists, so return values need no explanation. The description covers when to call it, the budget precondition, the launch_ad alternative, and the confirm flag. The undefined 'gate'/'spend-class' terms leave a small gap in what determines confirm.

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 0%, so the description must carry parameter meaning. It gives guidance for confirm ('confirm=true unless gate=open'), though 'gate' is never defined, and ad_id is left implicit. Partial compensation for a genuine 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?

States a specific verb+resource ('Submit or resubmit an ad's targeting for moderation') that an agent can distinguish from siblings like edit_ad, launch_ad, or create_ad. It also flags the near-duplicate relationship with launch_ad, removing the main source of confusion.

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 when to use it ('Use after edits'), names the tool that already covers this case ('launch_ad already does it'), and states a precondition ('Needs non-zero budget'). Routing and prerequisites are both covered.

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 (not read-only, open-world, non-idempotent, non-destructive), and the description adds value beyond them: concrete format/size limits (16:9 <5 MB photo, MP4 3-60s <20 MB video) and the return value. It omits that re-uploading the same file yields a new hash (non-idempotent) and says nothing about permissions or rate limits.

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

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

Three short clauses, each load-bearing: format constraints first, sequencing second, return value last. No filler and the critical constraints are front-loaded.

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

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

An output schema exists, so the description need not explain return values, yet it helpfully names the hash. For a mutation tool with annotations and a rich schema it is nearly complete, with the main gap being the unexplained confirm/ad_id parameters.

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

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

Schema coverage is 0%, so the description must carry parameter meaning; it explains file_path and media_base64 as the two upload sources. However it says nothing about ad_id, confirm (a boolean defaulting to false, likely a confirmation gate), or filename, leaving three of five parameters undocumented anywhere.

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

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

States a specific verb (upload) and resource (photo/video media) plus the accepted input modes (file_path or media_base64) and the output (media hash). It also implicitly separates itself from create_ad/edit_ad, which consume the hash rather than produce it.

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

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

Explicitly says to use it before create_ad/edit_ad media=, which is a real sequencing instruction tied to named siblings. It does not state when not to use it (e.g., reusing an existing hash) or any auth/precondition, so it stops short of full when/when-not guidance.

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