telegram-ads-mcp

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description reinforces this by describing validation rather than mutation. 'Surfaces platform errors' adds useful behavioral information about what the tool reveals. There is no contradiction with the annotations.

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

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

Two short sentences with the core action and timing front-loaded and no filler. Each sentence earns its place, and the second adds a behavioral detail without bloating the description.

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 validation tool, the description plus rich annotations and an output schema provide enough for an agent to invoke it correctly. The main gaps are only limited parameter-specific details and lack of explicit routing among sibling tools, which are minor given the tool's low complexity.

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 description only restates the two parameters as 'promote URL + text' without adding formats, constraints, or relationships. The schema titles already convey most of this, so the description contributes minimal semantic value beyond what an agent would infer from the property names.

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

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

The description states a specific action ('Validate'), names the resource ('promote URL + text'), and positions it before create/launch, which clearly separates it from siblings like create_ad and launch_ad. 'Surfaces platform errors' further clarifies its diagnostic role. The phrase 'promote URL' is slightly jargon-heavy, but the overall intent is unmistakable.

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?

'Before create/launch' explicitly signals the intended lifecycle phase and implies the tool is a preflight check. It does not explicitly name alternative sibling tools or say when not to use it, so it falls short of full exclusion guidance, but the timing context is clear.

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

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

Beyond the readOnly/idempotent annotations, the description discloses exact returned fields (owner_id, cabinet, currency, balance), intentional omissions (api_hash, cookies), the caveat about Stars cabinets, and the secure auth-failure workflow. This is high-value behavioral context, especially around secret handling.

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

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

The description is four tight sentences with no filler. The core action is front-loaded, followed by essential output details, exclusions, and failure handling. Every sentence contributes meaningful 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 parameters, a provided output schema, and clear annotations, the description covers everything needed to invoke and react to the tool: what it checks, what it returns, what it avoids returning, and how to recover from auth failure.

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 schema coverage is 100%, so the empty input schema fully documents the interface. The description reinforces the session-scoped nature by saying 'current session,' which is sufficient at the baseline for no-parameter tools.

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

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

The description opens with a specific verb and resource: 'Ping the current ads.telegram.org session.' It then clarifies what the tool returns and explicitly states what it does not return, making it easy to distinguish from siblings like reload_session 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?

It clearly indicates this is a session health-check tool and provides a concrete next step on auth failure: offer INSTALL.md DevTools steps, write .env, then reload_session. It does not explicitly contrast with alternatives like get_account, but the intended usage context is clear.

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

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

Annotations already mark readOnlyHint=false and destructiveHint=false; the description reinforces that this is a write operation and adds the two-step confirm_hash flow plus the TG_ADS_WRITE_GATE write confirmation. It also clarifies the result is a draft, not a launched ad. No contradiction with annotations.

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

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

The description is compact and front-loaded: the core purpose appears in the first sentence, followed by a key behavior and the confirmation requirement in just a few short lines. Every phrase earns its place and nothing repeats 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?

Given the output schema and annotation hints, the description covers the main invocation concerns: what the tool does, the targeting behavior, and the confirmation/write-gate protocol. The only notable gap is the provenance of confirm_hash, which is hinted at via 'platform' but not fully spelled out.

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 must carry the param semantics. It gives meaning to ad_id by explaining an existing ad is duplicated, adds that targeting is copied, and interprets confirm/confirm_hash as a two-step write gate. It does not explain how to obtain the hash, but it provides useful meaning beyond the bare schema.

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

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

The description opens with a specific verb-resource-result: 'Duplicate an ad into a new draft.' It then adds functional nuance: targeting is copied and the clone can be edited. This clearly differentiates clone_ad from sibling create_ad, edit_ad, and delete_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?

The description gives clear context: use this tool when you want to duplicate an existing ad while preserving its targeting, and edit the clone afterward if you need changes. It does not explicitly name alternatives or exclusions, but the intended scenario is evident.

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?

Discloses several non-obvious behaviors beyond the annotations: enforced on_hold status, zero-budget ads not going to review, empty strings being stripped and not sent, langs being dropped on conflict, and the confirm gate for spending. These are exactly the side effects and constraints an agent needs, and none contradict the annotations.

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

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

The description is dense and front-loaded, with each sentence covering a distinct operational rule. The phrasing 'TON/Gram cabinets' and 'EUR too' is somewhat cryptic, but the overall size is appropriate for the tool's complexity.

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

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

The critical safety, validation, and spending constraints are present, and the output schema covers return expectations. Still, for a 41-parameter creation tool, significant details around target_type-specific fields, scheduling, and targeting exclusions are 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?

The description adds useful cross-cutting parameter semantics such as semicolon-separated IDs, empty-string stripping, search-ad exclusions (text/picture/media), the langs/channels conflict, and the confirm requirement. However, with 41 parameters and 0% schema description coverage, many parameters like cpm, schedule, targeting options, and conversion_event still rely on self-explanatory names rather than documented meaning.

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

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

The description opens with 'Create an ad'—a clear verb-and-resource statement that distinguishes it from sibling tools like edit_ad, delete_ad, and clone_ad. The additional context about target types and supported cabinets does not obscure the core purpose.

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

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

The description provides explicit when-to/when-not-to rules: always create on_hold, do not pass text/picture/media for search ads, do not combine langs with channel IDs, and confirm is required for spend when the write gate is closed. It does not explicitly name alternative tools, but the primary use case is clear from the name and sibling set.

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

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

Annotations already indicate destructiveHint=true, but the description adds valuable context: the operation requires confirmation, the first call returns a hash for the second step, and confirm_hash is explicitly distinguished from the TG_ADS_WRITE_GATE. This goes well beyond the structured annotations and helps an agent understand the multi-step destructive behavior.

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

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

The description is short and front-loaded: it states the action first, then the flow, then the warning. The 'confirm: TG_ADS_WRITE_GATE (danger)' line is cryptic and may confuse an agent, but overall the structure is efficient and every sentence serves a purpose.

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

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

The description covers the core two-step flow and the dangerous nature of the operation, and an output schema exists so return values need not be described. However, the exact role of the confirm boolean and the relationship between confirm, confirm_hash, and the gate are underspecified. For a destructive tool with no schema parameter descriptions, this is a notable gap.

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

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

With 0% schema description coverage, the description must compensate, and it partially does by explaining confirm_hash as the returned platform hash, not the gate. However, the semantics of the confirm boolean are ambiguous—'confirm: TG_ADS_WRITE_GATE (danger)' does not clearly explain how the boolean should be set. ad_id is self-evident, but the incomplete explanation of confirm leaves a meaningful gap.

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

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

The description explicitly says 'Delete an ad' with a specific verb and resource, and goes further by describing the two-step confirmation flow. This clearly distinguishes it from sibling tools like edit_ad or clone_ad, and it is not a tautology of the tool name.

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

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

The description provides an explicit call sequence: first call without confirm_hash, then pass the returned hash to confirm. It also warns about the danger gate. It does not explicitly list alternatives or say when not to use the tool, but the actionable two-step instruction is sufficient guidance for most 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?

The description reveals critical behaviors beyond the annotations: only provided fields are sent, picture=True/False toggles the avatar, clear_media removes media, budget_action/budget_amount changes total budget and can resume a depleted Stopped ad, and confirm gates activation/budget changes. This is rich, actionable behavioral detail.

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

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

The description is compact and front-loads the most important invariant ('Only provided fields are sent'), then packs targeted details into short scannable lines. Every sentence provides useful information without 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?

Despite having an output schema, the tool is a complex 23-parameter mutation with no schema-level parameter documentation. The description covers the riskiest behaviors and the confirm requirement, but it leaves many fields with unclear formats, prerequisites, or interactions, making it incomplete for reliable invocation in all cases.

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 23 parameters and 0% schema description coverage, the description must carry the semantic burden, but it only explains a handful: picture, clear_media, budget_action, budget_amount, and confirm. Most remaining parameters (text, title, schedule, audience_id, daily_budget, conversion_event, etc.) are left to inference from their names alone.

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

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

The description opens with 'Edit an ad,' a specific verb and resource that distinguishes it from sibling tools like create_ad, delete_ad, and clone_ad. The added context about only provided fields being sent reinforces that this is a partial-update operation, not a full replacement.

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

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

It gives explicit guidance for a key distinction: targeting cannot be changed after creation, and clone_ad should be used instead. It also implies edit_ad is for updating existing ads rather than creating or deleting them. However, it does not provide a broader when-to-use comparison against other 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds context by enumerating the response fields, including write_gate, which is useful behavioral information beyond the annotations, though it does not discuss authentication or session requirements.

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

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

The description is a single front-loaded sentence with no filler. Every word contributes either to identifying the resource or listing its output fields, making it appropriately sized for such a simple tool.

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

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

For a zero-parameter, read-only, idempotent tool with an output schema, the description is largely complete. It could be more explicit about what 'current' refers to (e.g., the active session or selected account) and clarify the domain terms like 'ton/eur/stars', but the tool's low complexity makes these gaps minor.

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 100% schema description coverage, so there is nothing missing at the schema level. The description sensibly focuses on clarifying what the returned data contains, which is the relevant semantic information for an agent.

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

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

The description identifies 'current cabinet card' as the resource and lists the returned fields (owner_id, cabinet, currency, balance, write_gate), so an agent can tell it is a getter for the active account. It does not explicitly name sibling alternatives like list_accounts, but the 'current' scoping provides some differentiation.

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

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

The word 'Current' implies this tool is for reading the currently active/selected cabinet rather than listing or switching accounts. However, there is no explicit guidance on when to prefer get_account over siblings like list_accounts or select_account, or what session state is required.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds a small amount of extra behavior context by mentioning API method, HTML state, and list fallback, but it does not explain errors, response behavior, or edge cases.

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

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

The description is a single front-loaded sentence that leads with the verb and object. It contains no filler, and even the parenthetical is compact enough not to qualify as 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?

For a one-parameter, read-only, idempotent fetch with an output schema and strong annotations, the description is mostly sufficient. It lacks explicit alternative routing or error context, but the tool's simplicity and structured metadata reduce the risk of misinvocation.

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 needed to compensate, but it only restates 'by id,' which adds no meaning beyond the schema's ad_id property name. It does not explain what format the id takes, where to obtain it, or any example values.

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

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

The description uses a specific verb ('Fetch') and resource ('a single ad') and scopes the operation 'by id', which clearly distinguishes it from sibling list tools like get_ads. The parenthetical about retrieval methods is secondary but does not obscure the core purpose.

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

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

The phrase 'a single ad by id' clearly implies this tool is for fetching one specific ad, contrasting with get_ads for lists. However, it does not explicitly name alternatives or state when not to use it, leaving some routing inference to the agent.

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

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

Annotations already declare the operation read-only, idempotent, open-world, and non-destructive, so the safety profile is covered. The description adds real behavioral context beyond those annotations: results are paginated at 100 per page, the status filter is applied client-side, and offset_id is described as a pagination cursor sourced from next_offset_id. These are useful traits not inferable from the schema or annotations alone.

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

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

The description is compact and front-loaded. The core behavior is captured in two short sentences, followed by a minimal, readable args list. No filler or redundant restatement of the 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?

For a read-only, idempotent list operation with an output schema available, the description covers the key behaviors needed to invoke it correctly: pagination volume, the client-side status filter, and the cursor semantics. It does not over-explain return values or external constraints, which is appropriate given the annotations and output schema. Some explicit guidance on when to choose this over get_ad would improve completeness, but nothing critical 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?

The schema provides the status enum and defaults but has zero description coverage. The description's Args section compensates by explaining that offset_id is a cursor taken from next_offset_id, which is meaningful semantic guidance. It also restates the status values and adds the 'client-side' filter note, giving the agent additional context about how the parameter behaves, even though the status meaning could be expanded further.

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

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

The description uses a specific verb 'List' with the resource 'ads', immediately clarifying this is a collection operation rather than a single-item fetch. It also adds the pagination size (100 per page) and the client-side status filter behavior. It does not explicitly contrast with the sibling get_ad, but the plural 'ads' and 'List' make the purpose clear.

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 this tool is for retrieving a paginated list of ads, and the sibling get_ad suggests a single-ad alternative. However, there is no explicit when-to-use guidance, no mention of alternatives, and no conditions that would direct an agent away from get_ads toward another tool in the ad-management group.

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 indicate read-only, idempotent, non-destructive behavior, so the description earns full credit for going beyond them. It warns that summary.spend is already scaled and should not be divided again, explains summary.period is a span label rather than the request arg, and clarifies charts.budget scaling. These are exactly the behavioral traps an agent needs to avoid.

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

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

The description is dense but every sentence earns its place. It front-loads the main purpose, then organizes behavioral caveats with clear references to JSON fields. The final note about no CSV tool prevents a likely mistaken workflow without adding noise.

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?

Despite being a read-only stats tool with an output schema, the description adds crucial context about period labels, spend scaling, chart scaling, and the preferred summary field. It gives an agent everything needed to call the tool correctly and interpret its response without falling into known pitfalls.

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 carries full responsibility for parameter semantics. It explains period=5min vs period=day behavior, the request echo, and the scaling-related fields. ad_id is not elaborated, but it is self-evident from the tool name and required 'Ad Id' schema title.

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

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

The description opens with 'Time-bucketed stats plus CTR / CPC / actual CPM', which clearly identifies the resource (ad stats) and the specific value-add over sibling tools like get_ad or get_ads. It also distinguishes the tool by emphasizing time bucketing and derived metrics.

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 makes the intended use clear: fetch time-bucketed statistics for an ad with period options. It does not explicitly name when-not-to-use alternatives like get_ad or get_ads, but the period semantics and metrics make the tool's role obvious.

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 non-destructive behavior, so the bar for additional behavioral disclosure is lower. The description adds value by explaining that empty lists indicate the form did not embed that taxonomy, and that Stars cabinets never reach this tool. This goes beyond the annotations without contradicting them.

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 deliver the core content, a key exclusion, and an important empty-list interpretation without redundancy. The main taxonomy content is front-loaded, and the extra behavioral notes are concise.

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

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

The tool has one optional parameter, a rich output schema, and strong annotations, so the description does not need to explain return shapes. The description covers what data is available, who should not use it, and how to interpret empty results. Minor references like 'Gram cabinets' are unexplained but do not create a critical gap.

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

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

Schema description coverage is 0%, so the description must compensate for the sole 'kind' parameter. The description's user-geo vs channel distinction loosely maps to the kind enum values, but it does not explicitly explain that kind=user, kind=channel, or kind=both controls which taxonomies are returned. It partially compensates but leaves the mapping 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 clearly states the resource: countries, languages, topics for user-geo, and channel taxonomies. The tool name supplies the 'get' verb, so the action is clear. It does not explicitly contrast with the closely related sibling 'search_targets', but the scope is specific enough to distinguish the tool's purpose.

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

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

The description gives useful context: it is for targeting reference data, applicable to Gram cabinets, and explicitly says 'Stars cabinets never reach this tool,' which provides a clear exclusion. It does not name alternative tools or give explicit when-to-use guidance versus siblings, but the use case is reasonably 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?

Beyond annotations, the description discloses side effects (spends `budget`, default 1 Gram), lifecycle state (on_hold, not go-live), review submission, per-step failure reporting, an auth gate requirement (`confirm` required unless TG_ADS_WRITE_GATE=open), and a data-dropping behavior (`langs` dropped with specific channel IDs). This is rich, actionable behavioral context.

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

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

The description is dense and front-loaded, with the core behavior in the first sentence followed by constraints and alternatives. There is minor redundancy ('Does not activate' / 'Not go-live', 'review' repeated), but every sentence still contributes useful operational information.

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

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

Given the complexity of 26 parameters, three required fields, and a large sibling set, the description covers orchestration, side effects, constraints, and auth well, and the output schema covers return values. It does omit some material parameter behaviors like skip_review and daily_budget, but it explicitly routes agents needing the full field set to create_ad, making the common and safe invocation path complete enough.

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 for key parameters: budget default, confirm requirement, the langs/channel conflict, and the safe targeting subset. However, it does not explain most of the 26 parameters (e.g., cpm, promote_url, target_type, daily_budget, search_queries, audience_id, skip_review), leaving the agent to infer meaning from names and enums. It is meaningful but incomplete compensation for a large parameter set.

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

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

The description opens with 'Create on_hold, add budget, submit for review' — a concrete multi-step action with a clear resource and lifecycle state. It also distinguishes launch_ad from create_ad ('Safe targeting subset', 'Full field set remains on create_ad') and from the manual sequence, so an agent can tell exactly what this tool does.

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 says 'Prefer this over calling create_ad + edit_ad + send_target_to_review by hand,' naming the alternative workflow and the condition to choose this tool. It also points to create_ad when the full field set is needed and gives a concrete constraint about langs and channel IDs, which is clear when-to-use/when-not-to-use 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 read-only, idempotent, and non-destructive behavior. The description adds a meaningful behavioral trait beyond annotations: it works even on a Stars cabinet, which is useful compatibility information for an agent deciding whether to call it in that 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?

The description is two compact sentences with no redundancy. It front-loads the core action and resource, then adds a valuable edge-case guarantee about Stars cabinets without wasting words.

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

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

For a parameterless list tool with comprehensive annotations and an output schema, the description is complete. It identifies the resource, scope, and an important compatibility condition, leaving no critical gaps for correct invocation.

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

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

The tool takes zero parameters, and the schema has full coverage with an empty properties object. There is no parameter detail for the description to add, so the baseline score of 4 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: 'List ad cabinets for this Telegram login.' It also distinguishes itself from related tools like get_account or select_account by indicating it returns a list and enables switching away from the current cabinet.

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

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

The description gives clear context: use it to see ad cabinets for the current login, and it works even on a Stars cabinet so you can switch away. It does not explicitly name alternative tools or state when not to use it, but the usage context is clear.

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

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

Annotations already mark this as destructive and non-idempotent. The description goes beyond those flags by clarifying the specific consequence: the session's cookies are invalidated and must be refreshed in .env. This is actionable context for the agent and does not contradict the annotations.

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

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

Two sentences with no filler. The main action is front-loaded, and the critical post-requisite about cookies is stated immediately after. Every word contributes useful information.

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

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

For a simple logout tool with an output schema and annotations that already flag destructive behavior, the description covers the core purpose and key side effect. However, it leaves the confirm parameter undocumented and offers no explicit usage guidance, so it is adequate but not 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 schema has one optional boolean parameter, confirm, with 0% description coverage, and the description never mentions it. The agent receives no explanation of what confirm does or why it might need to be set, making the parameter's semantics unclear despite its self-explanatory 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 clearly states a specific verb and resource ('Log out of ads.telegram.org') and scopes it to 'this session', making the tool's function immediately apparent. It does not explicitly differentiate itself from sibling tools like revoke_token or check_session, but the session-scoped language is distinctive enough to avoid confusion with most peers.

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 usage context is implied: use this when you want to end the current session. The description adds a useful post-condition ('You will need fresh cookies in .env afterwards'), but it does not explicitly say when to use this tool versus alternatives such as revoke_token or reload_session, nor does it provide any when-not-to-use guidance.

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

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

The description adds valuable behavior context: it explains gating ('list is not gated', 'confirm is TG_ADS_WRITE_GATE') and gives an explicit no-retry hint on access denial. However, it contradicts the annotation destructiveHint=false by exposing a delete action described as 'delete/clone: two-step confirm_hash'. This is an annotation contradiction because the tool can clearly perform destructive operations while the annotation claims it is not destructive.

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

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

The description is compact and well-structured: it front-loads the action enum and uses line breaks to separate create, delete/clone, and list gating guidance. There is no obvious fluff, though some phrasing is cryptic rather than explanatory, which slightly reduces clarity.

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

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

The tool is a multi-action manager with seven parameters and no schema descriptions, so the description carries a heavy burden. It covers create, delete/clone, and auth gating, but omits essential details for rename (which parameters are needed), how confirm_hash is obtained, and what confirm actually does. An agent could not confidently invoke every action correctly from this description alone.

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

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

With 0% schema description coverage, the description must compensate, and it does clarify file_path (one user id per line), user_ids as an array, and confirm_hash as required for delete/clone. However, it leaves title, audience_id, and the exact interplay between confirm and confirm_hash underspecified, so an agent still lacks full parameter semantics for all actions.

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 anchors the tool to 'Custom audiences' and explicitly enumerates the supported actions: list, create, rename, delete, clone. This makes the resource and operation scope clear and distinguishes it from sibling tools about ads, funds, and accounts. It lacks a single overarching verb phrase like 'Manage custom audiences', but the action list communicates the purpose well.

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

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

The description gives operation-specific guidance: create requires file_path or user_ids, delete/clone need a two-step confirm_hash, and list is not gated. It also warns that access_denied should be skipped and not retried, which helps the agent decide when to stop. It does not name sibling tools or explicitly say when manage_audience should be preferred over alternatives, but the guidance within the tool's domain is clear.

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

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

The description discloses useful behavioral traits like delete danger and the access-denied skip hint, but it directly contradicts the annotation destructiveHint=false by calling delete dangerous. Because the description and annotations conflict, behavioral transparency must be scored as 1.

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

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

The description is compact, scannable, and front-loads the action list and safety notes. The opening noun phrase is slightly awkward, but every sentence contributes operational value and no space 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?

Even though an output schema exists, the description is not complete enough to call the tool reliably across all five actions. It does not specify parameter requirements for create, rename, or create_pixel, and the roles of confirm, event_id, event_type, and title remain unclear.

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 for parameter meaning. It only clarifies action and confirm_hash; it does not explain event_id, event_type, title, or confirm, nor does it map required parameters per action. This is only partial compensation for a six-parameter 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 the resource (conversion events and pixels) and enumerates all supported operations via action=list|create|rename|delete|create_pixel. This is specific enough to distinguish it from sibling tools like manage_audience or manage_funds, though it is phrased as a noun fragment rather than an explicit verb statement.

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

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

It gives action-specific guidance: list is not gated, delete is dangerous and needs a two-step confirm_hash, and access-denied results should not be retried. However, it does not explain when to choose this tool over sibling tools or which action to prefer for a given scenario, leaving selection somewhat 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?

The description goes well beyond the annotations by disclosing that add is only a top-up *request* rather than instant credit, and that transfer/withdraw execute money movement in this one call with no confirm_hash. This is exactly the kind of non-obvious behavioral context (latency, irreversibility, missing confirmation step) that annotations cannot express. It aligns with destructiveHint=true and readOnlyHint=false, with no contradiction.

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

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

The description is extremely compact—five short lines with no filler—and front-loads the domain, then the action taxonomy, then the danger warning. The fragmentary style ('Funds.', 'Danger gate.') is somewhat cryptic, but every token earns its place and the most critical warnings are placed at the end for emphasis.

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 medium-complexity tool with an output schema present and annotations covering the read-only/destructive profile, the action taxonomy and danger tiers are well covered. The gaps are the ambiguous referent of 'Danger gate' (whether confirm=true is the gate or the tool itself requires gating) and the unexplained parameters. Adequate for safe invocation of the core actions, but with clear room for clarification.

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

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

Schema description coverage is 0%, so the description carries the burden. It does compensate for the safety-critical parameters: amount is defined as a Gram (or EUR) string, and the confirm/no-confirm_hash behavior is flagged. However, query, account_id, and additional_comment receive no explanation, and the exact role of the confirm boolean is left ambiguous. Meaningful additions, but roughly half the parameters remain 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?

The description identifies the resource (funds) and enumerates five distinct actions (list/search/add/transfer/withdraw) with differentiated semantics, so an agent can tell what the tool does. It clearly belongs to the funds domain and is distinguishable from the ad/account siblings. The opening 'Funds.' is telegraphic but not a tautology, since it is backed by operational detail.

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

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

The description explicitly tiers actions by safety and behavior: list/search are lookups 'not gated', add is a deferred top-up request, and transfer/withdraw move money immediately with a 'Danger gate'. This gives an agent a usable decision rule for choosing among actions. It does not reference sibling alternatives, but no sibling handles funds, so within-tool action routing is the relevant 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?

Annotation contradiction: the description says the tool 'save[s]' a PNG under a directory, which is a filesystem write, while annotations declare readOnlyHint=true. Per the scoring rule, a description that contradicts an annotation receives 1.

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

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

One efficient sentence that front-loads the action, target, and output, then adds the destination and default path. Every clause earns its place.

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

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

There is no output schema and the description does not say what the tool returns (file path, success, PNG data?). It covers enough for a one-parameter tool, but return behavior and ad_id semantics are gaps.

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

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

Schema description coverage is 0%, so the description must compensate, but it never explains the single required ad_id beyond the schema title 'Ad Id'. The parameter is self-evident enough to guess, but provenance/format information is missing.

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 clear action and resource: 'Render a sponsored-message preview PNG for chat' plus the save location. It is more specific than a generic 'preview an ad', though it doesn't explicitly distinguish itself from sibling tools like check_ad_post or launch_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?

'for chat' gives an implied use case, but there is no explicit when-to-use / when-not-to-use guidance and no alternative sibling tool names. An agent must infer that this is for obtaining a PNG preview before launch.

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 discloses the internal behavior of reading .env variables and rebuilding the HTTP session, adding meaningful context beyond the annotations. With annotations already present, this is sufficient and does not contradict any hints.

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 concise sentences; the action is front-loaded and every sentence earns its place. No redundant details or schema 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 zero-parameter tool with an output schema, the description fully covers what it does, when to use it, and the key constraint. Nothing necessary for correct invocation 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?

There are no parameters, so the schema already fully communicates the zero-argument contract. The description reinforces this with 'Never pass cookie values as arguments,' which is especially valuable and prevents a common misuse.

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

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

Description uses a specific verb phrase ('Re-read .env' and 'rebuild the HTTP session') and names the exact resource/env vars involved. It is clearly distinguished from sibling tools like check_session and log_out by the reload/rebuild action.

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

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

Provides an explicit trigger: 'Use this after the user updates cookies on disk.' It also gives a clear negative directive ('Never pass cookie values as arguments'), though it does not explicitly name alternative sibling tools or when-not-to-use conditions.

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 signal destructiveness (destructiveHint=true, readOnlyHint=false). The description adds useful context by stating that the action both revokes and regenerates the token and that it applies specifically to the IP-whitelist token. It does not contradict annotations, though it could disclose more about consequences.

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

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

The description is a single focused sentence with no filler. The core action and resource are front-loaded, and the parenthetical clarification adds precision without bloat.

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 mutation tool, the description leaves critical operational details out: how the 'confirm' parameter is used, whether false makes the call a no-op, and what happens to existing integrations using the old token. The annotations and output schema help, but the description alone is not sufficient for an agent to safely invoke this destructive 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 for the single 'confirm' parameter, but it never mentions it. The agent is left to infer that 'confirm' gates a destructive operation, and the description does not explain what happens when confirm is false or true.

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

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

The description clearly identifies the action ('revoke and regenerate') and the resource ('cabinet API token'), and it narrows scope with 'IP-whitelist token, not ads cookies'. This distinguishes it from cookie/session-related tools and leaves no ambiguity about what it operates on.

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 clearly states what the tool does and explicitly excludes ads cookies, giving the agent a sense of when not to use it. However, it does not name any alternative tool or provide more explicit when-to-use guidance beyond the token type distinction.

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 convey readOnly=false, idempotent=false, and destructive=false. The description adds that the whitelist uses newline-separated IPs, but it does not disclose whether the operation replaces or appends to an existing whitelist or whether the confirm parameter is required for the change to take effect. No annotation contradiction is present.

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

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

The description is two short sentences with no filler. The main action and resource are front-loaded, and the second sentence adds a necessary formatting detail.

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 mutating settings tool, the description is not complete enough: it leaves the confirm parameter undocumented, does not state whether the whitelist is replaced or extended, and does not explain post-conditions or the effect of the change. The output schema helps with return shape but cannot compensate for missing operational semantics.

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 explains what ip_list means and its format, but it says nothing about the confirm boolean parameter, whose purpose is entirely unclear from both the schema and the description. An agent cannot determine why confirm exists or when to set it to true.

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

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

Description states a clear verb ('Set'), a specific resource ('IP whitelist for the cabinet API token'), and even the input format ('Newline-separated IPs'). It clearly distinguishes this from sibling tools because none of them target API token settings.

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 tool is for configuring allowed IP addresses for the cabinet API token, but it provides no explicit when-to-use guidance, prerequisites, or exclusions. Sibling tools are unrelated, so the lack of alternatives mentioned is not a major shortcoming, but the guidance remains implicit.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior, so the bar is lower. The description adds meaningful behavior: kind-specific search modes, semicolon-separated ids for similar lookups, and purpose-specific target vs promote semantics. The 'field=bots vs promote_url' reference is somewhat opaque but does not contradict the annotations.

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

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

The description is very compact and front-loaded with the core purpose. Every line adds density, though the telegraphic style and unexplained 'field=bots' phrasing hurt readability slightly.

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 output schema and safe annotations, the description covers the most critical distinctions (kind, purpose, ids). But it leaves several parameters implicit and includes a confusing field reference, so the overall picture is adequate but not fully complete for an agent invoking it on a first attempt.

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 must compensate, and it partially does: it explains kind, purpose, and the ids behavior for similar_* kinds. It leaves query, region, and country unexplained, and the 'field' reference does not map cleanly to any input schema property, so parameter coverage is incomplete.

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

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

The description opens with a clear verb+resource pair, 'Search targeting entities', and enumerates the six kinds of entities covered. It does not explicitly differentiate itself from sibling tools such as get_targeting_reference, which keeps it from a 5, but the scope is specific enough for an agent to know what it searches.

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 useful in-tool guidance for choosing kind and purpose, e.g. 'purpose=target (placement) vs promote (destination URL lookup)', and explains that similar_* modes take semicolon-separated ids. However, it never states when to prefer this tool over alternatives like get_targeting_reference, and it does not explain how query, region, or country should be used.

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

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

Annotations already mark this as non-read-only and non-idempotent, so mutation is expected. The description adds the stateful consequence ('Switch the active ad cabinet') and a recommended follow-up (check_session/get_account), plus the confirm gate. It does not detail side effects on the current session or whether switching is reversible, but for a simple selector this is adequate.

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?

Every sentence earns its place: main action, follow-up, and parameter guidance in a compact layout. No redundant clauses.

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 only two params, an output schema, and no nested objects, the description covers the key sequence and data source. The only minor gap is a clearer statement of when not to call this tool (e.g., if already on the desired account).

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%, but the description documents both parameters: owner_id is sourced from list_accounts, and confirm is required only under strict write gate. This adds real meaning beyond the schema's bare string/boolean types. It doesn't specify confirm's default semantics beyond the schema.

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

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

States a specific action ('Switch the active ad cabinet') and signals its role as a precursor to check_session/get_account. It is clearly distinct from listing or reading accounts, though it does not explicitly name a sibling it is not.

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?

Tells the agent owner_id comes from list_accounts and that confirm is required under TG_ADS_WRITE_GATE=strict, effectively giving when-to-use conditions. It lacks explicit exclusions or when-not-to-use 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 signal this is a write/non-idempotent operation; the description adds the useful precondition of a non-zero budget and the 'spend-class gate' warning. It does not clarify consequences such as duplicate review submissions or the confirmation flow, so it only partially supplements the annotations.

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

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

Three short sentences place the main action first and keep the rest minimal. 'Spend-class gate' is a fragment and somewhat cryptic, but there is no redundancy or wasted prose.

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 output schema present, return-value documentation is not needed, but the description does not explain the confirm parameter, the effect of resubmission, or what exactly happens at the gate. The non-zero budget clue is useful, yet the overall definition is just barely enough for confident invocation.

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

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

Schema description coverage is 0% and the description never mentions ad_id or confirm. 'Requires a non-zero budget' is an account/ad-level precondition, not a parameter explanation; the confirm boolean's role in actually submitting vs dry-running remains 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 opening phrase 'Submit (or resubmit) targeting for review' uses a concrete verb and resource, and it clearly distinguishes this from sibling tools like search_targets or launch_ad as a submission/review step.

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

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

It gives one explicit precondition ('Requires a non-zero budget') and hints at resubmission, but does not explain when to choose this over alternatives or when resubmission is appropriate. No exclusions or lifecycle context are provided.

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

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

Annotations already mark this as non-read-only but non-destructive, and the description adds useful behavioral context: supported formats, size/duration limits, binary-vs-base64 input modes, and a returned media hash. It does not contradict the annotations, though it omits the role of ad_id and confirm.

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

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

The entire definition is two compact sentences with the core upload contract front-loaded. It packs constraints, input alternatives, and downstream usage without 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?

The description is adequate for the common upload-then-create path and the output schema backs the return value, but it omits two parameters (ad_id, confirm) and does not state when they matter. That leaves an agent unable to fully reason about all valid invocations.

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 must carry parameter meaning. It does clarify file_path, media_base64, and filename, including the exclusive-or relationship, but it says nothing about ad_id or confirm, leaving 40% of the 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?

The description uses a specific verb ('Upload') and names the exact media resources with format, dimension, and size constraints. It also distinguishes the tool from siblings by stating its output feeds create_ad and edit_ad, making its role in the ad workflow 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?

The description clearly situates the tool in the ad-creation workflow: upload media first, then pass the resulting hash into create_ad or edit_ad. It does not explicitly state when not to use it or name an alternative upload mechanism, so it stops short of a 5.

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