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

Goes well beyond the annotations (readOnly=false, destructive=true, openWorld=true, idempotent=false) by disclosing that duplicates are not removed, no rollback occurs, positive budget transfers real funds and may trigger review, the idempotency window is 24 hours, and auth/permission/rate-limit errors always stop the batch regardless of stop_on_error. It also enumerates the four outcome states and the retry rule for 'unknown', which is exactly the operational context an agent needs before a destructive write.

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?

Dense and front-loaded: creation, then defaults, then idempotency, then outcomes, then dry_run caveats. Nearly every sentence carries distinct operational information; the only soft spots are the slightly fragmented line-by-line layout and the repeated mention of review triggering for positive budgets.

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, multi-item, open-world write tool with deeply nested target variants, the description covers defaults, monetary side effects, idempotency lifetime, partial-failure semantics, and dry_run blindness. An output schema exists, yet the description still names the outcome vocabulary (succeeded/failed/unknown/not_attempted), which is a useful bonus rather than a redundancy.

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?

Top-level schema coverage is 0%, so the description must carry the load, and it does for most of the four parameters: dry_run's semantics and blind spots, stop_on_error's default and its exceptions, account_id's fallback resolution, and the per-ad idempotency_key reuse rule. It adds little about the 'ads' array itself (e.g. no note on per-item ordering effects beyond 'in order'), which keeps it from a 5.

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

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

Opens with a specific verb and resource ('Create one or more ads in order') plus a distinct second mode ('or validate them locally with dry_run'), so an agent immediately knows this is a batch write tool with a validation path. That clearly separates it from the read-only siblings like list_ads, get_ads_by_id, and get_ads_stats.

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 guidance for dry_run and explicit when-not caveats ('makes no API calls and does not check access, budget or moderation'), and tells the agent to retry with the original key for unknown outcomes. It stops short of describing batch-size limits or when to prefer creating ads singly, but for a tool with no create-sibling that gap is minor.

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, open-world), so credit goes to what the text adds: only active ads are reported, monetary values follow each item's currency, and account_id falls back to TELEGRAM_ADS_ACCOUNT_ID then the token owner's account. The fallback resolution chain is real behavioral information an agent cannot get from the schema.

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

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

Front-loaded with the core function and kept to four short lines with no filler. The second sentence ("Returns a report of active ads for the given year and month") largely restates the first, which is the only notable redundancy.

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 described, and the description still adds output-relevant facts (active ads only, per-item currency). The main remaining gap is disambiguation from the sibling stats tools, which matters for a report tool in a crowded family.

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, and it does so only for account_id (the env-var/token-owner default chain). Year and month get no added meaning beyond "calendar month" and the schema's own 1-12 / 2021-2100 bounds, and nothing is said about timezone or month-boundary handling.

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?

"Get per-ad totals for a calendar month" gives a specific verb (get), resource (account report / per-ad totals), and granularity (calendar month). It partially separates itself from the stats siblings by specifying a per-ad breakdown over a monthly window, though it never names get_account_stats or get_ads_stats directly.

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

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

Usage is implied rather than stated: the agent can infer "use this for a monthly per-ad breakdown" from the scope wording. With four stats-related siblings (get_account_stats, get_ad_stats, get_ads_stats, this tool) there is no explicit when-to-use/when-not or alternative routing rule.

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

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

Annotations already cover read-only, idempotent, non-destructive, and open-world behavior. The description adds meaningful context beyond that: the accounts must be accessible to this token, and the call bypasses the default related account. It does not discuss return format or pagination, but the output schema exists to cover returns.

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 purpose. Each sentence adds distinct value: action, count/auth scope, and the default-account bypass nuance. No wasted wording.

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

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

This is a simple read-only lookup with one parameter, annotations, and an output schema. The description covers purpose, scope, auth constraints, and a key behavioral nuance. It could say more about handling invalid or inaccessible IDs, but for this complexity level it is largely 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 coverage is 0%, so the description must supply meaning. It explains that account_ids are IDs of accounts accessible to this token, restates the 1-to-100 count range, and clarifies that the IDs are used directly rather than via the default related account. That is substantial semantic value for the single parameter.

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

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

The description uses a specific verb (Get) and resource (balances and currencies) scoped to specified account IDs. It implicitly distinguishes itself from default-account siblings by stating it uses account_ids directly regardless of the default related account, though it never names those siblings explicitly.

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

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

Usage context is implied: call this when you have one or more account IDs and need their balances/currencies. It notes the 1-to-100 ID limit and token-accessibility constraint, but gives no explicit when-to-use-vs-alternatives guidance or exclusions beyond the default-related-account note.

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, open-world), so the description's job is to add operational detail — and it does: bounds are rounded to interval starts, there is a hard 1000-interval cap, granularity is fixed at 300 or 86400 seconds, and monetary values follow the returned currency. The only gap is return shape and what happens when the requested window exceeds the 1000-interval limit, but the output schema covers return values.

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

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

Four short sentences, front-loaded with the verb and resource, then constraints, then the account_id fallback rule. No sentence is redundant and the line breaks separate distinct concerns cleanly.

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 time-series tool with an output schema, annotations, and four short parameters, the description supplies everything an agent needs to call it correctly: units, rounding, interval options, the interval cap, and account resolution. Nothing material 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 carries the full burden, and it names all four parameters' meaning: from_time/to_time as Unix seconds in a half-open range with rounding behavior, interval as the 300/86400 granularity, and account_id defaulting to TELEGRAM_ADS_ACCOUNT_ID or the token owner. It adds real semantics beyond the bare 'To Time'/'Account Id' titles; a minor gap is not restating the interval default of 86400.

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 ('Get account statistics') with the scope immediately qualified by a half-open time range in Unix seconds. An agent can distinguish this from get_ads_stats or get_account_report by the 'account' scope, but the description never explicitly contrasts with those siblings, 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?

Usage boundaries are implied by the time-range framing rather than stated: nothing says when to prefer this over get_account_report or get_ads_stats, and there are no exclusions. The operational constraint (max 1000 intervals) and the account_id fallback rule give some context, but the choice among sibling analytics tools is left to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive, openWorld, so the safety profile is covered. The description adds real behavior beyond that: a hard 1-100 batch bound, per-account ID uniqueness, the effect of return_target, and an account-resolution fallback chain (TELEGRAM_ADS_ACCOUNT_ID, then token owner). It is silent on what happens with unknown or cross-account IDs, which is a minor remaining gap.

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

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

Four short lines, front-loaded with the core action, then limits, then the optional flag, then the default resolution rule. No redundant restatement of the name or title, and every sentence adds a distinct fact.

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?

This is a simple read tool with an output schema, so return shape need not be explained, and annotations cover safety. The description covers batching, account resolution, and the optional targeting payload; error behavior for missing IDs is the only notable omission.

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 full burden, and it does so for all three parameters: ad_ids (count limits and account-scoped uniqueness), account_id (env-var and token-owner fallback), and return_target (pulls in targeting settings). Only the array-of-integers typing is left to the schema, which is acceptable.

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

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

The description names a specific verb and resource (get ads by their IDs) and states the key scoping fact that ad IDs are unique within an account. It implicitly contrasts with the listing sibling (list_ads) by emphasizing lookup by ID, but never names the alternative explicitly.

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

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

It gives concrete usage context (batch of 1-100 IDs, IDs unique per account) and a defaulting rule for account_id, which tells the agent how to call it. It does not state when to prefer this over list_ads or get_ads_stats, so routing between siblings is left to inference.

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

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

Beyond the readOnly/idempotent annotations it discloses several non-obvious behaviors: a hard 1000-interval cap, implicit paging when ad_ids is empty, that supplied ad_ids are used verbatim, that account_id falls back to TELEGRAM_ADS_ACCOUNT_ID then the token owner, and that totals are null when data is absent. It also instructs the agent to check complete and errors before trusting results, which is exactly the kind of caveat 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?

Purpose and time-range constraint are front-loaded in the first sentence, followed by short paragraphs each addressing one concern (paging, timeseries, return shape, defaults). No sentence is redundant or restates the schema, and the warning about complete/errors lands where an agent will read it before calling.

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 fields need not be fully documented, yet the description still summarizes the payload (rounded bounds, per-ad totals, counts, complete, errors) and flags null totals. The only real gap against a 6-parameter stats tool is the unexplained interval parameter and its interaction with the 1000-interval limit.

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 the full burden and covers five of six parameters meaningfully: from/to semantics (half-open interval in Unix seconds), ad_ids empty-vs-supplied behavior, include_timeseries effect, and account_id defaulting chain. The interval parameter itself is never explained — neither the 300 vs 86400 enum values nor the 86400 default — so the largest remaining ambiguity is left unaddressed.

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 sentence states a specific verb and resource ("Get per-ad totals") plus the scope ([from_time, to_time), Unix seconds), which lets an agent separate it from get_account_stats and get_ads_by_id. It stops short of explicitly distinguishing it from the singular get_ad_stats sibling, leaving the plural/singular distinction to inference from the 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?

It gives operational conditions (period must not exceed 1000 intervals, empty ad_ids triggers automatic paging, include_timeseries adds interval rows) but never states when to choose this over get_ad_stats, get_account_stats, or get_account_report. The when-to-use decision is implied by output granularity rather than spelled out.

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

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

Beyond the annotations (which already declare readOnly/idempotent/non-destructive), the description discloses several non-obvious behaviors: the 300/86400 interval granularity, server-side rounding of bounds to interval starts, a hard cap of 1000 intervals, and ad-ID scoping to the selected account. It also explains account resolution (TELEGRAM_ADS_ACCOUNT_ID, else token owner), which is the kind of implicit-state behavior an agent cannot infer from the schema.

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

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

The core action and time semantics are front-loaded in the first two lines, with constraints following. All five sentences carry information, though the line-broken formatting reads as an unordered list of facts rather than a deliberately structured brief.

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 explanation is correctly omitted, and the description covers the constraints an agent needs before calling (interval cap, rounding, account default). It stops short of saying what happens when the 1000-interval cap is exceeded or when ad_id is invalid for the account, which matters for a read call that can fail on bounds.

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 the parameter burden and it largely does: from_time/to_time are Unix seconds in a half-open range, interval values mirror the enum, account_id has a documented default resolution chain, and ad_id is described as account-scoped. Minor omissions (the 86400 default, non-negative minimums) are already encoded in the schema itself.

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 ("Get one ad's statistics") and bounds the scope with a half-open time range in Unix seconds. The word "one" implicitly separates it from the plural sibling get_ads_stats and from get_account_stats, but it never names those alternatives, so the differentiation is inferential rather than explicit.

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

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

There is no when-to-use or when-not-to-use guidance, and none of the plausible alternatives (get_ads_stats for multiple ads, get_account_stats, get_account_report) are mentioned. The only routing-adjacent information is the account_id fallback rule, which is about defaults rather than tool selection.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds a genuine behavioral nuance — it always resolves to the token owner and ignores the default related account — but says nothing about auth requirements, failure modes, or response shape (though an output schema exists).

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

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

Two short sentences, zero waste: the first states the operation and the second front-loads the disambiguating constraint immediately after. Nothing could be removed without losing meaning.

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

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

For a parameterless, read-only lookup with full annotation coverage and an output schema, the description covers purpose and scope adequately. Only the absence of any note on auth/error behavior keeps it from being fully 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 there is nothing for the description to disambiguate; the baseline of 4 applies. The description correctly omits any parameter discussion rather than inventing one.

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

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

The description gives a specific verb and resource ('Get the token owner's account, balances and currency') and implicitly separates this tool from related-account siblings via 'regardless of the default related account.' It does not name `list_related_accounts` or `get_accounts_by_id` outright, so differentiation requires a small inference.

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 second sentence provides clear context: use this when the token owner's own account is wanted, even if a default related account is configured — which is the key distinction from the related-account tools. It stops short of explicitly naming the alternative sibling to use instead, so a 4 rather than 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 covered. The description adds genuinely new behavior: single-page semantics, no auto-pagination, reliance on an unchanged opaque offset token, and account resolution via the TELEGRAM_ADS_ACCOUNT_ID environment variable — none of which appear in structured fields.

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?

Each of the four short blocks addresses one decision the caller must make (page fetching, pagination behavior, targeting payload, account resolution) and the core purpose is front-loaded in the first sentence. Nothing is redundant or 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?

With an output schema present, return values need no explanation, and the description covers the pagination and account-defaulting behaviors an agent must know to call this correctly. The only minor gap is the absence of any note on limit's effect or default.

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 it does for three of four parameters: offset must be the returned next_offset verbatim, account_id falls back to an env var then the token owner's account, and return_target toggles inclusion of targeting settings. Only limit is left unexplained, though its 1-100 bounds are visible in the schema.

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

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

The description opens with a precise verb+resource+scope statement: 'Get one page of ads from an account.' The 'one page' qualifier immediately distinguishes it from a full-listing or single-record retrieval tool such as get_ads_by_id, so the agent can select it 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?

It gives concrete operational guidance: how to fetch subsequent pages ('pass the returned next_offset unchanged as offset'), that pagination is not automatic, and when to set return_target. It does not explicitly contrast itself with get_ads_by_id or get_ads_stats, so the when-to-use-versus-siblings dimension is only 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 readOnlyHint=true, idempotentHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the pagination contract and the return shape ('total_count and up to limit accounts'), which is the behavior an agent actually needs to drive a loop.

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 what the tool returns, then the paging rule. Nothing is repeated from the schema and nothing is filler.

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

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

For a two-parameter read tool with an output schema and full annotation coverage, the description supplies the one thing structured fields cannot: the paging loop. The residual gap is definitional — what counts as a 'related' account — which the agent may need in order to choose this tool over get_accounts_by_id.

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 full burden, and it does explain both parameters functionally: limit caps how many accounts come back, and offset is to be advanced by the count of accounts returned. It omits the default of 20 and the 1–100 cap, but those are visible in the schema, so the semantic gap is minor.

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: 'Get one page of the token owner's related accounts,' which separates it from get_current_account and get_accounts_by_id (singular identity lookups) and from the list_ads/list_ads_stats family. The one soft spot is that 'related' is left undefined — an agent cannot tell what the relation is or whether a more direct sibling would serve better.

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

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

Usage is implied rather than stated: the pagination instruction tells the agent how to continue iterating, which is real operational guidance. But there is no explicit when-to-use vs. when-not, and no mention of when get_accounts_by_id or get_current_account would be the better call.

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 the generic profile (openWorld, non-idempotent, non-destructive); the description adds the material behavior the agent actually needs: file bytes leave the machine for Telegram, local runtime dependencies (Pillow, ffprobe) can cause failure, media IDs are account-scoped, and there is no idempotency key so retries may duplicate media. This is meaningful disclosure well beyond the annotation flags.

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 first sentence pins the purpose, followed by preconditions, return summary, ID-reuse constraint, and retry caveat in short declarative blocks. Every sentence adds operational information and the most important 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?

For a three-parameter upload tool with an output schema, the description covers prerequisites, scoping, defaults, and the non-idempotency risk — everything needed to call it correctly or decide against retrying. The return summary is slightly redundant with the output schema but costs nothing.

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 the load, and it does for two of three parameters: file_path is constrained to an absolute server-side path with its bytes transmitted, and account_id's fallback to the configured default or token owner is spelled out. The kind parameter is only described indirectly via the media-type list rather than mapping ad_photo/ad_video/website_photo explicitly.

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 — 'Upload a local photo, MP4 video, or website photo to Telegram Ads' — and enumerates the supported media types, which map onto the three kind enum values. No sibling tool performs uploads, so no disambiguation is required, and an agent can tell immediately what this 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?

Gives concrete preconditions for use: file_path must be an absolute server path, images are validated with Pillow, and video uploads require ffprobe from FFmpeg on PATH. It also warns that reuse should stay within the same account and that retries may create a new media ID. It does not state explicit when-not-to-use cases, but there is no competing sibling to route away from.

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