telegram-ads-mcp

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.2.0
Disambiguation4/5
Most tools target a distinct resource or action, and the descriptions clarify boundaries. Minor overlap exists between launch_ad and the create/edit/review sequence, and manage_funds search overlaps with list_accounts, but agents can generally select correctly.
Naming Consistency4/5
Tool names follow a mostly consistent snake_case verb_noun pattern. The generic manage_* tools and varied verbs like check, send, launch, and save introduce slight inconsistency but the naming remains readable and predictable.
Tool Count3/5
With 25 tools, the server is at the heavy end of the acceptable range. Each tool has a purpose, but the broad surface feels slightly over-scoped; some manage_* actions could have been split or grouped more tightly.
Completeness4/5
The tool set covers the core ad lifecycle, account/session management, media upload, stats, targeting, audiences, events, funds, and API settings. Minor gaps exist such as no explicit pause/resume action or detailed transaction history, but agents can work around these.
Average 3.9/5 across 25 of 25 tools scored. Lowest: 2.4/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 9 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
Add a LICENSE file by following GitHub's guide. Once GitHub recognizes the license, the system will automatically detect it within a few hours.
If the license does not appear after some time, you can manually trigger a new scan using the MCP server admin interface.
MCP servers without a LICENSE cannot be installed.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly lists a delete action while the annotations declare destructiveHint=false. This is an annotation contradiction: delete is semantically destructive, so the agent cannot trust the stated safety profile. No additional behavioral context is provided about side effects, confirmation requirements, or external changes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loads the resource and action list, with no filler. However, it is telegraphic and omits crucial operational context, so its brevity is not a strength in this case.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a multi-action tool with five parameters, conditional relationships among actions and fields, and open-world side effects. The description provides almost none of the needed context for correct invocation, making it inadequate for an agent to use reliably.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain title, event_id, event_type, or confirm_hash. It only repeats the action names already present in the schema enum, so the agent cannot determine which parameters are needed for each action or what confirm_hash is for.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the domain ('Conversion events and pixels') and explicitly enumerates the supported actions. It is clear enough to distinguish the tool from its non-event siblings, though it relies on the tool name rather than a fully formed verb+resource sentence.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The domain label gives the agent a general sense of when to use the tool, but there is no guidance on which action to choose under which conditions, nor any indication of why this tool is preferable to alternatives. Usage is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description lists a delete action, which is a destructive operation, while the annotations set destructiveHint to false. That is an annotation contradiction. The confirm_hash note is helpful, but the conflicting metadata undermines the safety signal rather than adding trustworthy context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: resource scope, action enum, then conditional parameter notes. No filler is present, though the terse command syntax could be more readable with per-action bullets.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a multi-action tool with six parameters, this is incomplete: rename is never explained, list has no context, and the two-step confirm_hash flow is only hinted at. The output schema may cover return values, but the input and action semantics are not fully specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate for the schema's bare parameter names, but it only explains file_path/user_ids for create and confirm_hash for delete/clone. The title, audience_id, and rename/list usage remain unexplained, so an agent cannot confidently fill all parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Custom audiences' and enumerates the five actions (list/create/rename/delete/clone), so an agent can tell this is the audience-management tool and roughly what it does. It does not fully define each action, but the resource and command set are specific enough to separate it from ad/account/event siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit input-mode guidance for create (file_path or user_ids) and a precondition for delete/clone (confirm_hash), which is useful routing within the tool. However, it never states when to prefer this tool over a sibling, and list/rename have no usage guidance at all.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds useful behavioral context beyond the annotations: currency is determined by the cabinet (Gram or EUR), amounts are strings, and add is characterized as a request. It does not explain side effects of withdraw/transfer, potential approval flows, or how openWorldHint/destructiveHint apply per action, leaving part of the burden unmet.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loads the key currency rule before the action list. The line-broken action list is easy to scan, though the opening 'Funds.' is a bit cryptic and could be replaced with a complete sentence without bloating the text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a five-parameter, multi-action dispatcher with destructive and non-idempotent operations, the description is too thin: it does not address action-specific parameter use, prerequisites, or operation outcomes. The output schema may cover returns, but an agent cannot reliably construct a correct call without knowing which fields matter for each action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description needed to define all parameters, but it only glosses the action enum and the amount-as-string rule. query, account_id, and additional_comment are left undefined, and there is no mapping of which parameters are required per action.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The action list (add/transfer/withdraw/search/list) makes the tool's function concrete and separates it from account/listing siblings. However, the opening 'Funds.' is a noun fragment rather than a verb-led statement, so the overall purpose relies partly on 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.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Action annotations ('top-up request', 'find a cabinet', 'linked cabinets') imply when each operation is appropriate. There is no explicit guidance on choosing manage_funds over sibling tools like list_accounts or get_account, and no 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.
Behavior1/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines3/5
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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the concrete returned fields and 'current' context, but no new operational constraints or side-effect details beyond that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single compact sentence with no filler. 'Current' is front-loaded, and the field list immediately tells the agent what to expect.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-argument, read-only getter with a strong annotation set and an output schema, this description is nearly sufficient. It could be slightly more complete by explicitly saying 'currently selected account' or referencing select_account as a prerequisite.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 baseline for parameter semantics is 4. The description correctly omits parameter details because none exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource ('current cabinet card') and enumerates the returned fields (owner_id, cabinet, currency, balance), distinguishing it from sibling list tools. It lacks an explicit verb such as 'retrieves', which prevents a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use get_account versus list_accounts or select_account. The word 'current' implies the selected account, but the description never states how selection works or when to prefer a sibling tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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.
Conciseness4/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines3/5
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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal this is a non-read, non-idempotent, non-destructive operation. The description adds useful context by noting that submissions/resubmissions are possible and that a non-zero budget is required, which is not present in the annotations. It provides a meaningful behavioral precondition beyond the structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that leads with the primary action and then adds the key prerequisite. There is no redundant phrasing or filler, and the resubmission behavior is efficiently folded into the opening clause.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one required parameter and a clear workflow step, the description captures the action, resubmission possibility, and a critical precondition. The output schema exists, so return-value details are not required here. The main gap is the lack of explicit guidance about how this step relates to sibling tools, but the low complexity keeps this from being a serious deficiency.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not explain the ad_id parameter at all. The schema only provides the property name and a generic title 'Ad Id,' so the description fails to compensate for the low coverage by clarifying which ad or targeting entity the ID refers to. The single parameter is self-explanatory from its name, but the description itself adds no parameter-level meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear action verb and resource: 'Submit (or resubmit) targeting for review.' It clearly conveys the operation and the review workflow step, and distinguishes itself from actions like launch_ad or create_ad through the 'review' framing. However, it does not explicitly differentiate from sibling tools or mention that ad_id is the target identifier.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should be used when targeting needs to be submitted or resubmitted for review, and it gives a concrete precondition: 'Requires a non-zero budget.' It does not state when not to use this tool or point to alternatives like launch_ad or preview_ad, leaving the usage context implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters2/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose4/5
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.
Usage Guidelines3/5
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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as non-read-only and non-destructive. The description adds that it changes the active ad cabinet and that verification is recommended afterward. It does not go into side effects or error behavior, but with annotations covering the safety profile this is a minor gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the main action is the first sentence, verification steps follow, and the only parameter is documented in one line. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter state-switch tool with annotations and an output schema, the description is nearly complete. It names the parameter source and the recommended follow-up calls. It could mention what response to expect or what happens to the current session, but the output schema likely covers the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description carries the burden. It adds 'From list_accounts', which tells the agent exactly how to source owner_id—meaningful provenance beyond the schema's generic 'Owner Id' label. It could further explain what owner_id represents, but the purpose statement largely covers that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
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: 'Switch the active ad cabinet.' This clearly identifies the state-changing nature and distinguishes it from read tools like list_accounts/get_account. It does not explicitly name a sibling in the purpose, but the action is unique among the provided tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives contextual sequencing: switch first, then check_session / get_account, and it states where owner_id comes from (list_accounts). This communicates when to call it, though it does not explicitly state when not to use it or name alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish non-read-only, non-idempotent, non-destructive. The description adds that the operation produces a new draft rather than affecting the live ad, and that targeting is carried over. This is useful context beyond the annotations, though it omits details like whether other ad fields are copied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler. The core action is front-loaded and the follow-up workflow is stated compactly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for the main action and output schema covers return values, but the unexplained confirm_hash is a genuine gap for a tool with only two parameters. An agent may not know when or why to provide the hash.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, so the description must compensate. It indirectly identifies ad_id as the ad to duplicate, but it entirely ignores confirm_hash, leaving that parameter's role and required conditions unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Duplicate' and resource 'ad', and clarifies result is a new draft. This makes it clearly distinct from create_ad (new from scratch), get_ad, and launch_ad, with no need to open schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context: use it to create a workable copy with targeting preserved, then edit the clone. It does not explicitly name alternatives or exclusion cases, 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations' write flag, the description discloses critical runtime behavior: ads are always created in on_hold state, budget 0 blocks review, ID lists are semicolon-separated, search ads must omit text/picture/media, and empty strings are stripped. These are exactly the non-obvious behaviors an agent needs before calling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the main verb, followed by terse constraints. The 'EUR too' fragment is ambiguous and slightly disorganized, but overall every line adds a distinct operational fact with little waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 40-parameter write operation, the description covers the most likely failure points: initial state, budget/review condition, ID format, search-ad parameter restrictions, and empty-string handling. It does not spell out the account/session prerequisite or all target-type parameter relationships, but the output schema and sibling tools compensate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description provides crucial semantics: semicolon-separated IDs, the search-ad exclusion of text/picture/media, and the budget 0 review rule. It does not define every parameter, but it adds meaning that could not be inferred from the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The opening 'Create an ad' states a clear verb and resource, and the surrounding notes (Gram cabinets, target types, search ads) tell the agent this is for a specific advertising domain. It does not explicitly contrast itself with sibling tools like clone_ad or edit_ad, so it stops short of full differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is the entry point for creating new ads and carries important workflow rules: ads are always created on_hold and a zero budget prevents review. However, it never explicitly says when to prefer create_ad over clone_ad/edit_ad or mentions prerequisites such as an active session/account.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines4/5
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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a non-read-only, non-idempotent, non-destructive operation. The description adds that the tool 'sets' the whitelist, implying replacement of existing values, but it does not disclose side effects, whether the old whitelist is cleared, or any operational consequences. This adds some context beyond annotations but not rich 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single efficient sentence with the primary action first, followed by the critical input format detail. There is no wasted text, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one simple parameter, the description provides the essential purpose and parameter format. An output schema exists, so return values do not need explanation. Minor gaps include not stating whether the whitelist is fully replaced or how empty input behaves, but the core calling context is complete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, leaving the single required parameter ip_list completely undocumented. The description compensates by specifying that the value is 'Newline-separated IPs', giving essential format semantics. It does not detail IP address types or validation rules, but the core meaning is clearly conveyed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Set') and a clear resource ('IP whitelist for the cabinet API token'), stating exactly what the tool does. It is distinct from all sibling tools, none of which involve IP whitelist configuration, so an agent can easily identify when this tool is relevant.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies its usage: call this tool when you need to set the IP whitelist for the cabinet API token. However, it does not explicitly mention alternatives, when-not-to-use conditions, or any prerequisite steps, so the guidance is only implicit rather than fully articulated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters2/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive and non-read-only behavior. The description adds valuable context by warning that fresh cookies will be needed in .env afterward, disclosing the session invalidation consequence beyond 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences fully convey the action and key consequence. The information is front-loaded and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter destructive session action, the description is complete: it states what is logged out, the session scope, and the immediate follow-up requirement. The output schema handles return-value expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the schema provides no meaningful semantics to clarify. The description correctly focuses on the operation's side effect rather than parameters, matching the baseline for parameterless tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'log out' and identifies the exact resource 'ads.telegram.org for this session,' making the action unambiguous. It also clearly distinguishes this from sibling tools like check_session and reload_session.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states the action and a consequence but provides no guidance on when to choose log_out over related tools such as revoke_token or check_session. No alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite the launch_ad name, the description discloses the surprising key behavior that it does not activate the ad, and reveals the multi-step internal workflow (on_hold creation, budget, review). It also explains the failure-reporting response design ('Returns each step so you can see which one failed'), all of which goes well beyond the annotations' bare mutation/non-idempotent flags.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences each earn their place: the workflow plus the critical non-activation caveat are front-loaded, followed by the failure-reporting behavior and the routing guidance. No filler or repetition of schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The workflow, the non-activation side effect, the error-reporting behavior, and the usage routing are all covered, and the output schema handles return values. However, with 16 parameters at 0% schema description coverage and required params like cpm unexplained, the description is not fully self-sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% across 16 parameters and the description adds no parameter explanations; only 'add budget' loosely hints at budget/daily_budget. The required cpm parameter is particularly cryptic, and string-list fields like countries, channels, and audience_id have no format guidance (e.g., delimiters or encoding).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a concrete multi-step workflow ('Create on_hold, add budget, submit for review') with an explicit negative scope ('Does not activate'). It also differentiates from sibling tools by naming the exact calls it replaces (create_ad + edit_ad + send_target_to_review), so an agent can immediately tell launch_ad apart from those alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Prefer this over calling create_ad + edit_ad + send_target_to_review by hand,' giving a clear directive for when this tool is the right choice. However, it stops short of stating exclusions — e.g., when an agent would want the manual sequence or immediate activation instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false. The description adds important behavioral context beyond annotations: the delete requires a two-step confirmation flow involving a returned hash. This clarifies that the deletion is not immediate and depends on an additional confirmation call.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, no wasted words. The core action is front-loaded, and the essential confirmation protocol is stated immediately after. Every word contributes to correct invocation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's two-step confirmation behavior, the description provides the essential sequence and the role of confirm_hash. The required ad_id is obvious, and an output schema exists. It could be slightly more explicit that the second call should also include the ad_id, but the schema requiring ad_id covers that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 meaning. It does explain confirm_hash's role clearly: omit it on first call, then pass the returned hash to confirm. ad_id is not described in detail, but its meaning is self-evident from the name and the tool's purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Delete an ad.' This clearly distinguishes it from sibling tools like edit_ad, clone_ad, launch_ad, and get_ad. The additional confirmation-flow detail reinforces the tool's unique purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit how-to guidance: 'First call without confirm_hash; pass the returned hash to confirm.' This is a clear procedural instruction. It does not explicitly compare against alternatives or state when not to use the tool, but the delete intent makes the primary use case obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag this as destructive and non-read-only, so the description does not need to re-establish that. It adds value by specifying exactly what is affected (the ads.telegram.org cabinet/IP-whitelist token) and that the operation both revokes and regenerates rather than simply deleting. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with the action and object, with no filler. The parenthetical adds the precise scope information without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With zero parameters, an existing output schema, and annotations covering destructiveness, the description is nearly complete for correct invocation. It tells the agent what will happen and what resource is affected. A slightly more explicit statement about consequences for existing API integrations would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the schema already fully covers parameter meaning. The description's mention of the token adds context but does not need to document inputs. This meets the baseline for a zero-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action ('Revoke and regenerate') on a specific resource ('cabinet API token') and pinpoints it as the IP-whitelist token on ads.telegram.org. This is unambiguous and distinguishes the tool from session-level siblings like check_session, log_out, and save_api_settings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to invoke it: whenever the cabinet API token needs to be revoked and regenerated. It does not explicitly name alternatives or exclusion criteria, but with zero parameters and no overlapping token tool in the sibling list, the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already state readOnlyHint=false and destructiveHint=false, so the tool is known to perform a write/upload action without being destructive. The description adds useful behavioral context about accepted input methods (file_path OR media_base64), required filename when using base64, and size/format limitations, which helps the agent avoid failed calls. It doesn't disclose potential side effects or auth requirements, but for a media upload tool this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the most critical constraints (formats and sizes), and every sentence earns its place. It gives the two upload modes, a clear output ('media hash'), and usage direction to downstream tools without any filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists and provides a return-value structure, so the description need not repeat it. The main missing piece is documentation of the ad_id parameter, which the description ignores. Also, there's no mention of whether the ad_id is required for updating existing media. Given the overall detail and the presence of an output schema, the description is mostly complete but has one notable gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes all four parameters but provides only names and nullability, with 0% coverage on meanings. The description steps in and clarifies that file_path and media_base64 are alternative sources ('Pass a local file_path OR media_base64 (+ filename)'), and that filename is required with base64. It does not explain the ad_id parameter, but the description still compensates meaningfully for the schema's lack of documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Upload'), the resource ('photo' or 'video'), and specifies the exact supported formats and size/size constraints. It also explains the return value is a media hash that feeds into other ad-related tools, distinguishing it clearly from siblings like preview_ad or manage_event.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (uploading media for ads) and even gives a pointer to how the result should be used in create_ad/edit_ad. It does not explicitly list exclusions or alternatives, but the sibling context makes this tool uniquely responsible for media upload, and the 'feed into' wording implies the subsequent workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, non-destructive behavior. The description adds valuable behavioral detail beyond annotations: the exact time-bucketing semantics, the supported metrics, and the differing date ranges for each period value. This helps the agent predict what the tool will actually return.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: an initial summary line followed by the two relevant period behaviors. Every sentence adds useful information with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, read-only, two-parameter stats tool with an output schema and strong annotations, the description is sufficient. It explains metric coverage, period-specific behavior, and default context. Return value details are already covered by the output schema, so nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry parameter meaning. It fully explains the 'period' enum semantics with examples, which is the main non-obvious parameter. The ad_id parameter is self-evident from the schema and tool name, so not explaining it is acceptable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource and function: retrieving ad statistics broken into time buckets with specific metrics (CTR, CPC, actual CPM). The 'time-bucketed' qualifier separates it from simpler sibling tools like get_ad or get_ads.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives concrete guidance on choosing between the two period values: '5min' covers the last 24 hours, while 'day' covers full lifetime daily stats. It does not explicitly name alternatives or exclusions, but the context is clear enough for correct tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavior beyond the annotations: partial-update semantics ('Only provided fields are sent'), the special encoding of picture=False as sending picture=0, media removal via clear_media=True, and the surprising budget behavior that increase resumes a depleted ad. No contradiction with the readOnly, destructive, or idempotent hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: a one-line purpose followed by dense, scannable exception notes. Every sentence earns its place without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating tool, the description covers the most important operational concerns: partial updates, ambiguous boolean flags, budget behavior, and the targeting/clone_ad distinction. It falls short of a 5 by not addressing several of the 22 parameters, particularly the schedule-related and conversion fields, though an output schema does exist.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage and 22 parameters, the description explains only the highest-risk parameters: picture, clear_media, budget_action, and budget_amount. The global 'only provided fields are sent' rule helps, but many parameters such as schedule_tz, schedule_tz_custom, views_per_user, and conversion_event remain dependent on name inference.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Edit an ad', a clear verb and resource. It also distinguishes itself from the closest sibling by explicitly noting that targeting cannot be changed after creation and directing the agent to clone_ad instead.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly states when to use this tool (field-level edits to an ad) and when not to (targeting changes), naming clone_ad as the alternative. It also gives conditional usage guidance for picture, clear_media, and budget_action + budget_amount.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters5/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given the annotations already declare readOnlyHint, openWorldHint, and idempotentHint, the description still adds meaningful behavioral context: it excludes api_hash and cookies, notes that stars cabinets are reported but not used, and explains the auth-error recovery path. This goes beyond what annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core action. Each sentence adds distinct value: what it does, what it returns, what it does not return, and how to recover from auth failure. There is no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only session check with an output schema, the description is complete. It covers expected return fields, important exclusions, and failure handling. An agent has everything needed to decide when to call it and what to do with the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so there are no parameter semantics to document. The baseline for a no-parameter tool is 4, and the description correctly focuses on behavior and return data instead of inventing parameter guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb and resource: 'Ping the current ads.telegram.org session.' It clearly distinguishes check_session from siblings like reload_session and get_account by focusing on checking session state and returning ownership/cabinet/balance information. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit conditional usage path: if ok=false with code=auth, tell the user to refresh cookies and call reload_session. This directly references an alternative tool and the condition that triggers it. It does not broadly compare against all sibling tools, but provides sufficient situational guidance for the main failure case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![telegram-ads-mcp MCP server](https://glama.ai/mcp/servers/zai-one/telegram-ads-mcp/badges/card.svg)](https://glama.ai/mcp/servers/zai-one/telegram-ads-mcp)

Score Badge

Copy to your README.md:

[![telegram-ads-mcp MCP server](https://glama.ai/mcp/servers/zai-one/telegram-ads-mcp/badges/score.svg)](https://glama.ai/mcp/servers/zai-one/telegram-ads-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/zai-one/telegram-ads-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server