mcp-microsoft-ads
Server Quality Checklist
Latest release: v1.0.1
- Disambiguation2/5
Several tools have overlapping purposes: create_pmax_campaign and draft_campaign both create campaigns, remove_entity and remove_keywords both delete keywords, and update_campaign overlaps with pause_entity/enable_entity for campaign status changes. The detailed descriptions help, but an agent could easily select the wrong tool for the same underlying operation.
Naming Consistency2/5The names are all snake_case but the verb conventions are inconsistent: create_ and draft_ are used interchangeably for the same 'draft a write' pattern, get_ and list_ both appear for read operations, and generic tools like remove_entity sit alongside specific remove_keywords/remove_geo_target. This makes the tool surface less predictable than it could be.
Tool Count2/5With 47 tools, this is far beyond the 25-tool threshold the rubric treats as too many. The server covers a broad domain, but many tools are convenience wrappers (e.g., get_campaign_performance, get_ad_performance, run_report) and the set would benefit from consolidation.
Completeness2/5There is no tool to create an ad group, which is a core requirement for building out a Search campaign: draft_campaign creates campaigns and draft_keywords/draft_responsive_search_ad need ad groups, so the lifecycle has a critical dead end. Other gaps include no ad-copy update path and no way to create shared negative keyword lists.
Average 3.6/5 across 47 of 47 tools scored. Lowest: 1.1/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 5 commits in the last 12 weeks
- Last stable release on
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
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.jsonto 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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses nothing about side effects, data returned, or operational constraints. This is a complete absence of transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief, but this is under-specification rather than concise writing. It consists of two words that convey no operational information, so it fails to earn its place. A 2 is appropriate because it is at least short, but not because it is effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has a parameter, no output schema, and no annotations, the description is wholly inadequate. It does not explain what geographic performance means, what data is returned, or how the 'days' parameter affects results. The agent has no useful information to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not mention the 'days' parameter at all. The schema only provides a default of 30 but no meaning, and the description fails to compensate, leaving the parameter's purpose completely undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose1/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Geographic performance' is a vague label that fails to state what the tool does, what resource it acts on, or what action it performs. It provides no verb and no differentiation from sibling performance tools like get_campaign_performance or get_ad_performance, so an agent cannot infer its function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. No context about typical use cases, prerequisites, or comparisons to sibling tools is provided, leaving the agent without any basis for selection.
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?
With no annotations provided, the description must fully disclose behavioral traits. It mentions 'nil ids returns all goals of the given types,' but this is confusing because the schema has zero parameters, so 'nil ids' and 'types' are undefined. No return format, side effects, permissions, or error behavior are described. The description actively misleads by referencing non-existent inputs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (one sentence), but it is not effectively concise because it omits essential information and includes ambiguous references. The front-loaded phrase 'Conversion goals' does not communicate the action, and the parenthetical about nil ids is more confusing than helpful. Under-specification, not conciseness, is the issue.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with zero parameters, no annotations, and no output schema, the description should be sufficient to understand purpose and usage. It is not. It does not explain what conversion actions are, what data is returned, or how to differentiate this from similar tools like get_entities or run_report. The description is inadequate for an agent to confidently invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero parameters, so the baseline is 4 according to instructions. However, the description introduces phantom parameters ('nil ids' and 'given types') that are not part of the schema. This adds confusion rather than value, effectively misleading the agent about how to call the tool. No actual parameter semantics are clarified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Conversion goals' is a noun phrase, not an explicit action. It implies retrieval but never states the verb (e.g., 'list' or 'get'). It also references 'nil ids' and 'given types,' which suggest parameters that do not exist in the schema, creating ambiguity about what the tool actually returns. While it vaguely points to conversion goals, it fails to clearly distinguish this from sibling tools like get_entities or run_report.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as create_conversion_action or set_conversion_action_primary_status. The description gives no context about typical scenarios, prerequisites, or exclusions. An agent would have to guess whether this is for reading conversion data or something else.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations available, the description must disclose behavioral traits, but it only states the bare noun phrase. It does not reveal what 'performance' means, whether data is aggregated, any rate limits, or what the return structure looks like. This is a significant gap for a tool with zero annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short but its brevity reflects under-specification, not intentional conciseness. It provides no structure, no front-loading of critical information, and every word is essentially a restatement of the name. It lacks the detail that would make it useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple getter with one optional parameter and no output schema, a minimal description might suffice, but even minimal usage requires knowing what performance data is included and how 'days' relates to it. The description offers none of this, making it inadequate for an agent to invoke correctly and interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter 'days' with no description (0% coverage), and the tool description makes no mention of it. Since the description does not compensate for the schema's lack of explanation, the agent is left without any hint of the parameter's meaning or usage. This is a complete failure to add value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Per-ad performance.' is essentially a repetition of the tool name 'get_ad_performance', adding no new specificity about what metrics, scope, or verb are involved. It fails to distinguish this from sibling tools like get_campaign_performance or get_keyword_performance, since all are performance getters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives. There is no mention of use cases, exclusions, or how it differs from other performance-related tools. An agent receives no signal about when to pick this over similar siblings.
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?
With no annotations provided, the description must fully disclose behavior, but it only states 'Search query report'. It does not indicate whether the operation is read-only, what data it returns, its side effects, or any limitations. The tool name implies a 'get' operation, but the description adds no behavioral context beyond a label.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely brief — a single phrase — but this is under-specification rather than effective conciseness. It omits essential information about the tool's purpose and parameters, so the brevity is not appropriate for the complexity. It fails to earn its place because it offers almost no value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool being simple (one parameter, no output schema), the description is incomplete. It does not state what the report contains, how the 'days' parameter affects results, or any typical use cases. An agent would have to guess at nearly every aspect of calling this tool, leaving significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter, 'days' (integer, default 30), but schema description coverage is 0%. The description does not mention 'days' or explain that it likely controls the reporting period. Since the schema lacks descriptions and the description does not compensate, the parameter semantics are entirely unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Search query report' is a noun phrase that vaguely indicates the tool deals with search terms but lacks a clear action. It doesn't explicitly state what it does (e.g., retrieve, generate, list), making it generic. It is not a tautology of the name, but it is too vague to distinguish from related tools like get_keyword_performance or run_report.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus its siblings. The description says nothing about use cases, filters, or alternatives. It does not mislead, but it offers no context to help an agent decide when to invoke it among the many reporting tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not state that the tool is read-only, mention any permissions or rate limits, or explain what happens if no data is available. The 'get' prefix implies a read operation, but this is not explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise phrase listing the key metrics, with no redundant wording. It is front-loaded with the core purpose. However, it is so brief that it borders on under-specification, though the conciseness itself is not flawed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only one parameter and no output schema, the description is incomplete. It does not explain the parameter, does not state read-only behavior, and does not specify any constraints like date ranges or filtering. An agent has limited ability to call it correctly without additional schema inspection or guessing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema defines a single parameter 'days' with a default of 30, but the description provides zero explanatory value for it. With schema description coverage at 0%, the description must compensate, yet it does not mention that 'days' controls the lookback period or any format/details. An agent is left to guess what this parameter means.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as retrieving campaign performance metrics, listing specific metrics (impressions, clicks, spend, conversions, CPA). This is a specific verb–resource combination, but it does not explicitly differentiate itself from sibling tools like get_ad_performance or run_report, 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.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. It does not mention that it only operates on campaigns, nor does it suggest run_report for custom reporting or other performance tools for ad/keyword level data. The usage context is entirely implied by the name and description.
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 are absent, so the description bears the full burden. It discloses that only the ad_group branch is live-verified while others are not, which is useful transparency about reliability. However, it does not explain what 'draft' means (whether changes are applied immediately or queued), any permission requirements, or reversibility. The mention of 'Same shape as pause_entity' hints at non-destructive behavior but is not explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with two sentences and a brief status note. It front-loads the primary purpose. No redundant or filler content. However, the structure could be improved by separating the purpose from the verification details, but it remains efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is incomplete. It lacks parameter explanations (see parameter_semantics), does not describe expected outcome or return value, and gives no prerequisites or side-effect warnings. The verification status note adds some context, but overall it fails to equip an agent to call the tool correctly across all entity branches.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description adds no meaning to entity_type, entity_id, or parent_id. It does not explain their roles or acceptable values. The reference to pause_entity does not help an agent understand parameter semantics. This is a significant gap given all parameters are undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Draft an enable (Status=Active)' – a specific verb with a target status. It also references 'Same shape as pause_entity' to help distinguish it from the sibling pause_entity. However, it does not enumerate all supported entity types upfront (they appear only in the verification note), which slightly reduces clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The reference to pause_entity describes structural similarity, not usage context. There is no mention of when an enable is appropriate (e.g., reactivating a paused entity) or how it differs from update_* tools. The guidance is minimal and implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states what data is returned, not how the tool behaves — no return format, no pagination, no handling of the 'days' window, no statement that this is a read-only operation (which annotations would otherwise confirm). For a data-retrieval tool with zero annotation coverage, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded clause with zero wasted words — 'Per-keyword performance incl. QualityScore.' delivers the core purpose immediately. It is genuinely concise, though it achieves this by sacrificing completeness, which keeps it from a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one optional parameter, no output schema), so the job is not large, but the description is still incomplete: the 'days' parameter is entirely unexplained and no behavior outside the return value is described. An agent would know what data arrives but not how to scope or interpret the request. Incomplete even for a low-complexity tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does 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 undocumented 'days' parameter. It does not — 'days' is mentioned nowhere in the description. The schema supplies only the name, type, and default, leaving the agent to guess what the time range controls and how it is interpreted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource — 'Per-keyword performance incl. QualityScore' — and the resource type (keyword) distinguishes it from sibling performance tools such as get_campaign_performance, get_ad_performance, and get_geo_performance. The 'incl. QualityScore' detail adds a concrete, specific element. It falls short of a 5 because it never explicitly names the siblings it is not.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides no when-to-use guidance, no exclusions, and no pointer to alternatives. The sibling set contains closely related tools (get_keyword_forecasts, discover_keywords, get_campaign_performance) that an agent might confuse it with, but the description gives no context for choosing among them. The intended use case is only implied by the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility. It discloses irreversibility, which is critical, but it does not mention side effects, confirmation steps, or what happens to associated data. The term 'draft' further obscures behavior, making the disclosure insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The information is compact and front-loaded: the core purpose and irreversibility are in the first sentence, and the alternative is clearly noted. The 'Live-verified 2026-07-28' line is extra but not distracting, so the structure is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (2 simple params, no output schema) and the lack of annotations, the description is still inadequate. It does not mention prerequisites, effects on related entities, or how this differs from other deletion tools beyond pause_entity. An agent cannot fully gauge the tool's impact from the description alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does 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 any parameters. ad_group_id and keyword_ids are only given by name and type in the schema, with no added meaning about their purpose or constraints. The description fails to compensate for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'keyword deletion' and 'irreversible', which clearly identifies the core action and distinguishes it from pause_entity. However, the word 'draft' introduces ambiguity—whether this is a pending operation or an immediate deletion—so it is not fully explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'pause_entity is the reversible lever', implying a usage condition (permanent vs reversible). However, it does not differentiate from other sibling removal tools like remove_entity, remove_negative_keywords, or remove_extension, so guidance is partial.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It does not state that it is a read-only operation, mention side effects (likely none), or disclose any constraints. The single sentence only lists output content, not behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is an extremely concise single sentence that front-loads the essential information. There is no wasted text, and it is appropriately sized for a simple retrieval tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and no output schema, the description is minimal. It lacks context on when to use the tool, what the return structure looks like, or any caveats. In the presence of many sibling tools, missing usage context makes it incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema already covers everything. The description adds no parameter-specific information, which is appropriate for a no-parameter tool. Baseline 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states it returns authenticated user info, roles, and configured account/customer IDs. This is specific about the content and resource. It implies distinction from siblings like list_accounts, but doesn't explicitly name an alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like list_accounts or health_check. It only describes what it returns, not the context or scenarios where it should be invoked.
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?
With no annotations, the description carries the full burden. It discloses that the API is 607-gated on the dev account, that a null recommendation_type is rejected, and that all documented enum values fail, indicating an account/feature gating issue. This transparency about failure modes and passthrough behavior is valuable, though it omits details about return format or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct, with the core purpose in the first sentence and the key caveat following. The second paragraph repeats the gating note but adds the 'NOT live-verified' label. It is not verbose and front-loads the most important information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 optional parameters, no output schema, and no annotations, the description is incomplete. It does not explain the role of ad_group_id and campaign_id, nor what a successful response looks like or how results are scoped. The warning about the 607 error is useful, but an agent still lacks enough context to call it safely and interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description explains the semantics and quirks of recommendation_type, but provides no information about ad_group_id or campaign_id. Since two of the three parameters are completely undocumented, the description only partially compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool fetches account recommendations and references the underlying MS Ad Insight GetRecommendations API. The verb 'list' is implicit in the name, and the resource is clear. It doesn't explicitly differentiate from siblings like apply_recommendation or dismiss_recommendation, but the read-only nature is evident.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives such as apply_recommendation, dismiss_recommendation, or confirm_and_apply. The description only explains a technical quirk about recommendation_type and does not mention any logical ordering or prerequisites.
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?
With no annotations, the description carries the full burden. It does disclose verification status (ad_group branch live-verified, others not) and mentions a state transition ('Paused→Active→Paused'), which adds transparency. However, it does not clarify whether the tool actually pauses or just drafts, nor describe side effects, permissions, or irreversibility—significant gaps for a mutation operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is fairly concise at two paragraphs, but the verification note is cryptically worded ('on a z. ad group' appears to be a typo) and the state transition line is confusing. The essential info is front-loaded, but the unclear phrasing reduces readability and wastes space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is incomplete for a mutation tool with no annotations and no output schema. The phrase 'Draft a pause' leaves it ambiguous whether the operation is applied immediately or staged, which is a core behavioral detail. It does not mention return values, synchronous vs asynchronous behavior, or what happens to child entities. The verification status is helpful but does not fill these gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains the allowed values for entity_type and the specific parent_id dependencies (keyword/ad need ad group id, ad_group needs campaign id), which directly addresses two of the three parameters. entity_id is left as obvious (the entity's id), but the provided parameter details are valuable and clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('pause') and lists the entity types it applies to (campaign, ad_group, keyword, ad), clearly identifying the resource. It distinguishes from siblings like enable_entity and remove_entity by the verb, though the phrase 'Draft a pause' introduces ambiguity about whether it actually executes the pause or creates a draft.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as enable_entity or remove_entity. It only mentions parameter preconditions (parent_id requirements) which are about argument usage, not tool selection. No explicit 'when to use' or 'when not to use' context is provided.
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?
With no annotations, the description carries the full burden. It discloses important behaviors: errors if UET tag missing, url_contains defaults to advertiser_domain and errors if neither set, whitespace-only rejection. Still, it omits behavioral details like whether the result is a draft requiring confirmation (implied by 'Draft'), what response/identifier is returned, and any side effects of membership_duration_days. It is partial but adds meaningful value beyond 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the purpose and prerequisite, then dives into url_contains behavior in a structured way. Each sentence serves a purpose, and the verification note is a minor addition. It's not overly long and avoids redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a creation tool with 4 parameters, no output schema, and no annotations, the description is incomplete. It fails to explain membership_duration_days (though schema gives a default), what the tool returns (e.g., IDs), and whether the 'draft' nature means a separate confirmation step is needed (given the sibling confirm_and_apply). The agent might be able to call it, but important behavioral and return details are missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds substantial meaning to url_contains: substring matching, default behavior, and whitespace rejection—exactly the kind of nuance an agent needs. But membership_duration_days is not explained at all (only its default in schema), and name/description are self-evident. The description covers one parameter in depth but leaves another interpreted while the schema provides only type and default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Draft a remarketing list targeting site visitors,' which identifies the resource and action. It also mentions the UET tag prerequisite, adding specificity. However, it does not explicitly differentiate from sibling audience-related tools like add_audience_targeting (which applies audiences rather than creates them), so a clear distinct purpose isn't fully established.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a prerequisite (UET tag must exist, otherwise error) and explains when errors will occur, which aids the agent in deciding readiness. However, it does not mention when to use this tool versus alternatives (e.g., when creating vs. targeting audiences), so usage context is partially informative but lacks explicit alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not state whether the operation is read-only, any rate limits, authentication needs, or side effects. It only mentions it uses the Ad Insight GetKeywordIdeas API, which implies a read operation but does not explicitly confirm safety or non-mutating behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no redundant phrases. The main purpose is stated upfront, followed by essential scope information. Every sentence contributes value and it is easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two optional parameters and no output schema, the description covers the tool's core purpose and scope, but it omits expected return format, potential errors, or limitations. It is adequate for a basic invocation but leaves some unknowns (e.g., what exactly is returned, how results are structured) that an agent might need.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It explains that the tool uses 'seed keywords' and/or 'landing-page URL', directly mapping to the two parameters. However, it does not clarify the format, constraints, or whether one is mandatory (the schema shows both are optional with null defaults), nor does it explain behavior when both are provided. It adds some meaning but not enough for full clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('discover') and resource ('keyword ideas') and specifies the two input sources (seed keywords and/or landing-page URL) plus the underlying Ad Insight API. It is specific and easily distinguishable from related tools like draft_keywords or get_keyword_forecasts, though it does not explicitly name a sibling it is not.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives useful scope context (location/language/network configured via advertiser settings) and defaults, which helps the agent understand the operating environment. However, it does not provide guidance on when to use this tool versus alternatives like draft_keywords or get_keyword_forecasts, nor any exclusions or prerequisites.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states 'NOT live-verified', 'Fakes only', and 'same 607 gate', which reveal that this is a non-production, test-only action with a specific access constraint. These are valuable behavioral traits beyond the tool's name, though the exact nature of the 607 gate is not explained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is terse, with the primary purpose in the first sentence and caveats following. It is appropriately sized for a single-parameter tool and is front-loaded, containing no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description provides key behavioral caveats (draft, not live, fakes only) and references a shared gate. However, it does not explain what 'draft' implies (e.g., does it create a draft object? what happens after?), nor the meaning of '607 gate' or 'Fakes only'. These gaps leave an agent uncertain about the full execution context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does 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 'recommendation_id' parameter at all. It only references 'a recommendation' generically, providing no additional meaning beyond the schema's minimal 'Recommendation Id' label. Since the description must compensate for the lack of schema documentation, it fails to do so.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('Draft dismissing an MS recommendation') and differentiates it from siblings like apply_recommendation by noting it drafts a dismissal rather than applying one. However, 'MS' is not expanded and 'Fakes only' introduces ambiguity about the intended scope, but the core purpose is understandable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'same 607 gate as apply_recommendation', implying a shared prerequisite, but does not explicitly state when to use this tool versus alternatives (e.g., apply_recommendation). It hints at similarity but lacks clear guidance on selecting between drafting versus applying, and no when-not-to-use instructions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'Draft' and adds 'Live-verified 2026-07-30.' It does not clarify whether the draft is immediately applied, requires confirmation, is reversible, or what side effects occur. For a mutation-like action, this is a significant 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, front-loaded sentences. The primary action is stated first, and the parameter hint is on the second line. Zero filler, and the 'Live-verified' timestamp is a lightweight but useful piece of metadata. Excellent structure for scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (two params, no output schema), but the 'draft' concept is ambiguous and could affect the agent's workflow (e.g., whether it must be followed by confirm_and_apply). The description does not close this gap, but it provides the key parameter source and purpose, so it is minimally viable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Given the 0% schema coverage, the description should compensate. It does provide a meaningful hint that location_id comes from search_geo_targets, which helps the agent understand the parameter's provenance. However, it does not explain the format or any constraints beyond the schema's integer type, and campaign_id is only implicitly obvious.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Draft a location EXCLUSION on a campaign') with a clear resource and scope, and even hints at the required data source ('location_id from search_geo_targets'). It is distinct from sibling tools like remove_geo_target (removal vs. drafting), though it does not explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The only usage guidance is the hint that location_id should come from search_geo_targets. There is no explicit statement on when to prefer this over removing an exclusion or when a draft must be confirmed/approved. The 'draft' semantics imply a two-step flow, but this is not spelled out.
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?
With no annotations provided, the description carries the full burden. It discloses the return values (clicks/impressions/CPC/cost), the default behavior for max_cpc (falls back to MS_ADS_MAX_CPC cap), and the scope. However, it does not explicitly state that this is a read-only operation (no side effects) or mention any limits or error handling. The behavioral context is useful but not exhaustive, especially given the absence of 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core function and output, then adding scope and a pointer to a sibling. Every sentence adds value with no redundancy. It is efficiently structured and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the purpose, output metrics, default max_cpc, and scope, and points to discover_keywords for the advertiser settings. However, it does not explain the match_type parameter, the exact output format (e.g., per-keyword breakdown), or any additional behaviors like error cases or rate limits. Given the tool has 3 parameters and no output schema, it is moderately complete but leaves key details unresolved.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains 'keywords' (candidate keywords) and 'max_cpc' (defaults to the account's MS_ADS_MAX_CPC cap), but it completely omits 'match_type', which is a parameter with a default value. Without explanation, an agent may not know that match_type is valid (e.g., Exact, Phrase, Broad) or how it affects results. This is a significant gap given the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it provides traffic estimates (clicks/impressions/CPC/cost) for candidate keywords, with a verb implied by 'get' and the resource as keyword forecasts. It also mentions scope (location/language/network), which adds specificity. It does not explicitly distinguish from siblings like get_keyword_performance, but the context 'candidate keywords' implies planning vs. actual performance, so it's mostly 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives some context—it's for candidate keywords and is scoped to advertiser settings, referencing discover_keywords to see those settings. However, it does not explicitly state when to use this tool versus alternatives (e.g., get_keyword_performance for actual data, or others), nor does it mention any exclusions or prerequisites. The guidance is 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does well: it discloses the non-idempotent retry behavior (a retry re-runs ALL steps, re-adding extensions), the partial-failure state (association raises after library add lands), and that the error carries extension_ids for reconciling. This is genuinely useful beyond the schema. The only minor gap is no statement of the return shape on success.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences with the main purpose front-loaded; the failure-mode detail is dense but earnestly informative and not padded. Slightly tighter if the 'Live-verified' timestamp were dropped, but overall well-proportioned.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 2-param tool with no annotations, no output schema, and 0% schema coverage, this description covers purpose, a key constraint, and a critical failure trap — a good start. But it omits campaign_id semantics and any usage-vs-alternative direction, and gives no indication of the success response. Both required params are touched only partially.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 for `texts` by adding the 25-char-per-item constraint. But it says nothing about the required `campaign_id` parameter — its meaning, how it maps to an account, or whether it must reference an existing campaign. Half the parameters remain effectively undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('create'/'Draft') and resource ('callout extensions') with a concrete constraint (max 25 chars each), and it is visually distinguishable from siblings like draft_sitelinks and create_structured_snippets, which are different extension types. However, it does not explicitly name or contrast itself against those siblings, relying on the user's understanding of ad-extension taxonomy.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as list_extensions (to check existing callouts), remove_extension (to delete), or draft_sitelinks (for a different extension type). The mid-apply failure note is behavioral, not usage direction, so an agent gets no help deciding whether create_callouts is the right tool in a given flow.
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?
With no annotations, the description carries the full burden of behavioral disclosure. It explicitly describes a mid-apply failure mode, including that the error carries extension_ids and that retrying re-runs all steps, which is actionable and goes beyond schema. However, it does not mention typical success behavior or whether the operation is destructive, so it's not fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The main action and constraints are front-loaded in the first sentence. The verification date is one line, and the failure-handling paragraph is relevant but somewhat lengthy. Overall, it is compact enough and each section serves a purpose, though the verification line could be considered noise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter tool with no output schema, the description covers the parameter constraints and a specific failure scenario, which is good. But it omits success behavior, any prerequisites (e.g., campaign existence), and clarification of 'MS-supported'. The failure note hints at a larger workflow but does not fully describe what the tool returns on success, leaving gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It adds semantics for header (must be MS-supported, e.g., 'Services') and values (3+ required), which is helpful. But it provides no explanation for campaign_id, and it doesn't define what 'MS-supported' means or the expected format of values. Partial compensation only.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Draft a structured snippet', which clearly identifies the verb and resource type. It also states concrete constraints (header must be MS-supported, 3+ values), reinforcing the tool's scope. While it doesn't explicitly name siblings like draft_sitelinks or create_callouts, the resource type distinguishes it enough that an agent can infer its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternative extension-creation tools (e.g., draft_sitelinks, create_callouts). There are no prerequisites mentioned, no context about campaign suitability, and no exclusions. The only usage hints are parameter constraints, which are not usage-scenario guidance.
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?
No annotations are provided, so the description carries the full burden. It discloses that campaigns are ALWAYS created Paused, which is a critical safety behavior. It also adds reliability information with live-verification dates and warnings about non-default language values. This goes beyond typical descriptions, though it does not cover return values or failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, uses clear bullet-like formatting, and front-loads the most important fact (paused state). The live-verification note is additional but not verbose. It earns its place and is easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the agent is left unaware of what the tool returns (e.g., campaign ID) and cannot know how to use the result for subsequent steps. It also does not address when to choose this over create_pmax_campaign. The verification notes add trust but the operational context is incomplete for a tool that creates a draft entity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It does clarify that campaign_type accepts 'Search' or 'PerformanceMax' and that time_zone/language have US-centric defaults that should be overridden for other markets. However, it does not add meaning for 'name' or 'daily_budget' beyond what the schema's titles imply, leaving partial coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Draft') with resource 'campaign' and immediately clarifies the two supported campaign types (Search, PerformanceMax). However, it does not explicitly differentiate from the sibling create_pmax_campaign, which might also create a campaign of that type, so it is clear but lacks sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like create_pmax_campaign or update_campaign. It mentions defaults and overrides for markets but does not state scenarios favoring this tool over siblings. The agent must infer usage context.
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?
With no annotations provided, the description carries the full behavioral burden. It discloses critical behaviors: mandatory claim verification against the website, enforcement of a blocklist on all ad components, and the lack of a per-ad paused state on creation (requiring parent ad group pausing for isolation). It also notes that new ads serve post-approval. This is substantial transparency, though it does not cover all edge cases or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably concise and well-structured, front-loading the core purpose and constraints before additional policy and behavioral notes. The final 'Live-verified' line is an audit trail that is extra and not essential for usage, slightly reducing conciseness, but the overall structure is effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 parameters, no schema descriptions, no output schema, and no annotations, the description covers key constraints and behaviors but omits explanations for most parameters, prerequisites, or return value expectations. It is adequate for basic use but leaves gaps that an agent might need to infer or test to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does 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 all parameters. It adds constraints on headlines (3-15) and descriptions (2-4), which adds meaning to those array parameters. However, it does not explain path1, path2, final_url, ad_group_id, or campaign_id beyond their existence, leaving most parameters undocumented. The partial coverage is insufficient for full compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool drafts a Responsive Search Ad with explicit constraints on headline and description counts. It is specific and unambiguous, but it does not differentiate from siblings like draft_campaign or draft_keywords. The verb and resource are clear, earning a strong score, though not perfect due to lack of sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the tool name and purpose, but the description provides no explicit when-to-use or when-not-to-use guidance, nor mentions any alternative tools. It does offer process guidance (verification, blocklist), but that is more about how to use, not selection criteria. This is adequate but not 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?
With no annotations, the description must carry the full behavioral burden. It explains the effect of the boolean: associate = campaign optimizes to the goal; disassociate = falls back to account-level goals. It also states 'Live-verified 2026-07-30, both directions,' indicating reliability. However, it does not disclose whether the operation is immediate or a draft requiring confirmation (suggested by the word 'Draft' but not elaborated), nor does it mention idempotency, side effects on existing associations, or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, at two substantive sentences plus a verification note. It front-loads the core purpose and then explains the semantics clearly. There is no fluff or redundant information. The only minor issue is the word 'Draft' which might cause confusion but is followed by clarification. Overall, it is efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description should cover operational details. It explains the core behavioral effect and the association model, which is the most important part. However, it lacks information about the draft/confirmation nature (there is a sibling 'confirm_and_apply'), potential error conditions, and return values. Given the moderate complexity (3 params, no nesting), the description provides adequate but not comprehensive context, leaving gaps around execution flow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the primary boolean parameter semantically (associate/disassociate) and implies the roles of campaign_id and goal_id through the phrase 'campaign-goal association.' However, it doesn't explicitly define each parameter's type or format, and the explanation is primarily targeted at the primary flag. While this adds meaning beyond the bare schema, it leaves campaign_id and goal_id to be inferred from names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool's purpose: setting the primary status of a conversion action for a campaign, modeled as a campaign-goal association. It explains the semantics (associate/disassociate) which distinguishes it from siblings like create_conversion_action. However, the opening phrase 'Draft a campaign-goal association' is slightly ambiguous because it could be interpreted as creating a new association rather than updating an existing one, and it doesn't explicitly name the tool's action (set primary status).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied: to make a conversion action primary for a campaign, use this tool. The description explains the meaning of 'primary' but does not explicitly state when to use this tool vs alternatives, such as update_campaign or create_conversion_action. There are no exclusions or conditions, and no mention of prerequisites or confirmation steps, relying on the agent to infer timing.
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?
No annotations are provided, so the description carries the full burden. It discloses the key trait — this is a draft, not an immediately applied operation — and the account-shared scope. But it does not explain the target_cpa/strategy_type interplay, permissions, or what the returned draft contains. The 'Live-verified 2026-07-30' line is non-functional noise.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Compact and front-loaded: purpose first, then enum values, then workflow. The verification timestamp adds marginal noise but does not impede readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the definition must stand alone. It covers purpose, scope, valid types, and the draft-then-apply flow, but leaves target_cpa usage conditions and the draft response shape unstated. Adequate but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It documents the strategy_type allowed values, which is genuinely additive. But target_cpa is left unexplained — notably that it matters mainly for MaxConversions — and name is self-evident, so compensation is only partial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (draft) + resource (portfolio bid strategy) plus scope (account library, shared across campaigns). It also enumerates the valid strategy_type values. This clearly differentiates it from the many other draft_* siblings by resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a useful workflow hint: creates a draft that must be applied via confirm_and_apply. However, it gives no guidance on when to choose a portfolio-level strategy vs. campaign-level bidding (e.g., update_ad_group/update_campaign), and no explicit exclusions.
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?
With zero annotations, the description carries the full burden and does meaningful work: it discloses that parent_id is required, that campaign_criterions excludes Audience (which is 'not readable via this API'), and the notable quirk that campaign BiddingScheme reads as None on MS while the effective strategy lives on ad_groups. These are genuine behavioral disclosures beyond a plain 'fetch'. It stops short of covering pagination, limits, or result format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The main action and entity list are front-loaded, with constraints and caveats appended in a logical order. Every sentence carries information — the entity enumeration, the parent_id rule, the criterion-type restriction, and the BiddingScheme quirk all earn their place. It's dense but not padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter tool with no annotations and no output schema, the description covers entity values, the parent_id requirement, and the two notable API quirks. The gap is the undocumented `ids` parameter, and with no output schema the return format for each entity type is unstated, which an agent would need to know to use results downstream.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It documents `entity` by listing valid values and `parent_id` by stating the 'required for all but campaigns' rule, which is real added meaning. However, `ids` is left completely unexplained — the schema only shows a nullable integer array defaulting to null, and the description never clarifies whether omitting it lists all rows or fetches a single entity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb-resource pair ('Fetch entity state') and enumerates the exact supported entity types (campaigns, ad_groups, keywords, ads, asset_groups, campaign_criterions), which distinguishes it from the specialized sibling getters like get_negative_keywords and get_conversion_actions. It's slightly vague on what 'state' means, but the entity enumeration gives sufficient specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The constraints (parent_id required for all but campaigns; Audience not readable; BiddingScheme reads as None) imply usage context but are procedural constraints, not tool-selection guidance. It never explicitly says when to prefer this generic getter over specialized getters or run_report, so an agent would have to infer the routing from the entity list alone.
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?
No annotations are present, so the description carries full responsibility for behavioral disclosure. It explains the core scoping behavior between the two campaign_id states, which is valuable. However, it never signals that this is a non-destructive read operation, nor does it mention return format, pagination, or the fact that it aggregates multiple extension types into one response.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences, front-loaded with the resource name and immediately followed by the key scoping rule. The colon usage is slightly unconventional but functionally clear. No wasted words; every sentence carries meaningful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter list tool, the description covers the critical scoping logic comprehensively. The only omission is the return format, which is somewhat mitigated by there being no output schema. Given the tool's low complexity, this is reasonably complete, though a brief note on the returned extension structure would fully close the gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does 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: it assigns behavioral meaning to the single parameter, clarifying that null means 'full account library' and a set value means 'only extensions associated with that campaign.' This goes well beyond the schema's bare 'Campaign Id' field, providing precisely the disambiguation an agent needs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the resource (ad extensions) and concisely describes the two distinct behaviors based on campaign_id: a full account library versus campaign-scoped results. The verb 'list' is implied from the name rather than stated explicitly, and example extension types ('sitelinks, callouts, structured snippets') help clarify scope, which reasonable disambiguates it from mutation siblings like remove_extension and create_callouts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly explains the two calling modes (campaign_id=None vs set), which serves as effective usage context for a single-parameter listing tool. However, it provides no explicit when-not-to-use guidance or mention of alternatives, relying on the mode distinction to implicitly convey when each call form is appropriate.
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?
With no annotations provided, the description carries the full burden of disclosing behavior. It explicitly states that the tool mutates the account, is not live-verified, faults with 607 on the development account, is gated by an additional flag due to unbounded monetary effect, and that it is a fake. This is comprehensive and goes beyond typical descriptions, covering mutation, failure mode, and risky side effects. No contradictions with annotations since none exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the action in the first sentence, then provides necessary safety and failure information. Each sentence adds value: the mutation warning, the fake status, and the gating details. It is a bit long but everything included is relevant and not redundant. The structure is logical, moving from function to caveats.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema and a single parameter, the description covers key functional aspects: it states the action, the mutation side effect, the gating requirements, the failure behavior, and the fact that it's not live. It doesn't describe what a successful apply would produce, but given that it's marked as fake, that may be moot. It also doesn't mention prerequisites like obtaining the recommendation from list_recommendations, but that is implicit. Overall, quite complete for the tool's context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is only one parameter, recommendation_id, and the schema provides its type and required status but no description. The schema coverage is 0%, so the description should compensate, but it doesn't explicitly explain what the ID refers to. However, the context of 'MS recommendation' in the description makes it obvious that the ID is the identifier of the recommendation to apply. While not explicit, the meaning is easily inferred, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action clearly: 'Draft applying an MS recommendation (mutates the account — rails apply)'. It identifies the resource (MS recommendation) and the verb (apply). The word 'Draft' is slightly ambiguous—it could imply a non-final action—but the parenthetical clarifies that it actually mutates the account, so the purpose is understandable. It is distinct from siblings like dismiss_recommendation and confirm_and_apply, though it doesn't explicitly name them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus alternatives. It mentions that the tool is 'NOT live-verified' and 'Fakes only', which implies it should not be used in production, but it doesn't direct the agent to a sibling like confirm_and_apply or list_recommendations. The gating details (MS_ADS_ALLOW_APPLY_RECOMMENDATION) are environmental prerequisites, not usage guidance for choosing this tool. Overall, the agent is left to infer when this tool is appropriate.
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?
With no annotations present, the description must carry the full behavioral burden. It discloses the key fact that the tool mutates the account and adds a verifiability note ('Live-verified from 2026-07-28 onward'), which is useful. However, it omits other behavioral aspects such as idempotency, error handling if draft_id is invalid, or whether there are irreversible consequences. Still, the primary behavior is clearly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with the core purpose front-loaded. The second sentence about live verification adds context but is arguably tangential to calling the tool correctly. Still, it is not bloated and reads clearly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with a single parameter and no output schema, the description provides the essential guidance on mutation and sequencing. However, it lacks any information about the return value or success/failure indicators, which an agent needs to interpret the result. The parameter semantics are also weak, so overall completeness is moderate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate for the undefined parameter. It does not mention draft_id at all, leaving the agent to infer its meaning from the tool name and description. The implication is that it refers to a previously drafted item, but this is not explicit and lacks any detail about types or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Execute a previously drafted write') and explicitly declares it as the only mutation path, distinguishing it from all sibling tools that draft or modify. This leaves no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the usage pattern: draft first, then confirm_and_apply to actually mutate. It emphasizes being the only mutation path, which routes the agent away from other tools for writes. However, it does not explicitly name alternatives or list when not to use it (e.g., for reads), but the context is strong.
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?
No annotations are provided, so the description carries the full burden. It discloses that the tool returns disapproved ads and keywords and attributes them to editorial review failures, which adds context beyond the bare function. However, it does not mention side effects (none expected), return format, or any edge cases. The description is not misleading but is sparse.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one concise sentence, front-loaded with the core information (what it returns and for which entity). No wasted words or redundant detail. It is appropriately brief for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With only one parameter, no output schema, and no annotations, the description is adequate for a basic retrieval tool. It states what is returned (ads and keywords) and why (editorial failures), which is sufficient for an agent to understand the primary purpose. However, it omits details about the return structure, pagination, or error handling, though these are less critical given the simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must explain the parameter. The phrase 'in an ad group' clarifies that the single ad_group_id parameter refers to the ad group whose issues are retrieved, adding meaningful scope. Yet it does not explicitly state that ad_group_id is required or provide details on its expected value, leaving the connection implicit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (get) and resource (policy issues) with scope (in an ad group) and clarifies it returns disapproved ads and keywords due to editorial review failures. This clearly distinguishes it from sibling tools like get_negative_keywords or get_keyword_performance, as no other tool focuses on policy issues.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (when you need policy issues for an ad group) but provides no explicit guidance on when to prefer this tool over alternatives, nor does it mention exclusions or prerequisites. The context is clear, but there is no explicit when-to-use statement.
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?
With no annotations provided, the description carries the full behavioral burden and does so excellently. It discloses the mid-apply failure mode (association raises after the library add landed), that errors surface extension_ids for reconciliation, and the non-idempotency trap that a retry re-runs ALL steps including re-adding extensions. This is precisely the failure/retry context an agent needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The core purpose and data shape are front-loaded, followed by a verification caveat and then the failure/retry detail. Every sentence earns its place and there is no filler; the retry paragraph is dense with parentheticals but contains substantive, necessary information rather than padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 2-param tool (one being a loosely-typed array), it covers purpose, item shape, a prerequisite, and failure semantics. Gaps remain: no mention of the return value on success, campaign_id semantics are unaddressed, and given sibling confirm_and_apply exists, the description never explains the draft-then-confirm lifecycle or that a draft may require a subsequent confirmation step.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does document the sitelinks array item shape ([{text, url, description1?, description2?}]), which adds real meaning to that parameter. However, campaign_id receives no semantic help beyond 'integer' in the schema, and the array's additionalProperties: true means the shape relies entirely on this prose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
'Draft sitelinks on a campaign' states a specific verb, resource, and scope, and the bracketed item shape clarifies what is being created. It distinguishes from sibling extension tools (create_callouts, create_structured_snippets) by resource type and from apply/confirm tools by the 'draft' verb, though it never explicitly names a sibling it is not.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides one genuine prerequisite ('Copy claims must be site-verified') that an agent must check before calling. However, it gives no explicit when-to-use vs alternatives guidance and no exclusion conditions, leaving the decision between this and related extension tools (create_callouts, remove_extension) to inference.
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?
With no annotations, the description must carry the full behavioral burden. It discloses the return scope (campaign-level + shared lists, with items and associations), which is useful, but it does not mention side effects, performance, pagination, or the meaning of a null campaign_id. For a get tool, the absence of read-only declaration is minor, but the missing parameter semantics affects transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff. The primary function is front-loaded, and the usage note is appended succinctly. Every word earns its place without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one optional parameter and no output schema, the description covers the core functionality and usage instruction. However, it omits the parameter's behavior (what null means) and gives no sense of the return format beyond a high-level description. Given how much an agent needs to call it correctly, this is a noticeable gap, but the tool is simple enough that it is not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter (campaign_id) with 0% description coverage, and the description does not explain its meaning or the effect of null. The parameter name is self-explanatory, but the description adds no clarity on whether null retrieves all campaigns or something else. With zero schema coverage, the description should compensate, but it does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states exactly what is retrieved: 'Campaign-level negatives + ALL shared negative keyword lists (with items and campaign associations).' The verb is implicit (get), but the resource is specific and the scope is clear. It also distinguishes from sibling add/remove tools by focusing on retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The instruction 'Always call before recommending/adding negatives' gives explicit when-to-use guidance, which is strong. However, it does not mention alternatives or exclusions (e.g., when not to use this tool, or that get_entities might also provide similar data). It is clear enough for a simple 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?
With no annotations, the description carries the full burden. It discloses a validation-only behavior, the lack of a parent field in the WSDL, and the verification status by scope ('Live-verified 2026-07-28 at ad_group scope; campaign scope not separately smoked'). This gives the agent confidence about reliability. It does not mention return format or error behavior, but the tool likely has a standard response pattern.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core action. The scope restriction is stated early, and additional notes (source of IDs, validation requirement, verification status) are appended in a structured manner. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations or output schema, the description covers the essential operational details: scope enum, ID source, campaign_id requirement, and testing status. It lacks explicit information about the result of the operation or error handling, but these may be inferred from similar tools. Overall, it provides sufficient context for an agent to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It clarifies that keyword_ids come from get_negative_keywords and that campaign_id is required for ad_group scope. It also enumerates scope values. However, it does not explain entity_id (whether it's the campaign, ad group, or shared list ID) or the relationship with campaign_id, leaving some ambiguity for a tool with 4 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the operation ('Draft negative removal by id') and the resource (negative keywords), and enumerates valid scopes. It distinguishes from sibling tools like remove_keywords by specifying 'negative' removal, though it does not explicitly contrast with similar tools such as remove_extension or add_negative_keywords. Overall, the core 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides concrete usage context: keyword_ids should come from get_negative_keywords, and scope='ad_group' requires campaign_id for consistency with add_negative_keywords. It also clarifies that the parent field is not in the underlying WSDL, so validation is manual. However, it does not explicitly state when to avoid this tool or when to prefer an alternative like remove_keywords, leaving some 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations at all, the description carries the full burden and delivers exceptionally. It documents the two-step order, the abort-on-batch-error case (nothing landed, nothing to reconcile), the mid-apply failure case (disassociated=True, deleted=False), and that a retry re-runs ALL steps. This is exactly the transactional nuance an agent needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose is front-loaded in the first line, and the failure-mode paragraphs are dense and genuinely useful. The 'Live-verified 2026-07-30' line is extraneous noise that does not help an agent call the tool, costing a point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex transactional tool with no annotations and no output schema, the description covers behavioral risks thoroughly and explains what the result carries on failure. It omits the success result shape and parameter semantics, but the self-evident param names keep the overall package complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description never mentions the parameters. The names campaign_id and extension_id are self-evident integers, and the two-step narrative implies their roles, but with zero schema descriptions the description should have compensated and does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The opening line 'Draft removal: disassociate from campaign, then delete from library' states a specific verb, resource, and two-step scope. The 'Draft' qualifier distinguishes it from sibling removal tools (remove_entity, remove_keywords, remove_geo_target) and pairs naturally with list_extensions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is only implied through 'Draft removal' — an agent can infer it applies to draft extensions that require disassociation before deletion. There is no explicit when-to-use vs alternatives guidance, no exclusions, and no mention of preferring this over remove_entity when an extension is not campaign-attached.
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?
With no annotations provided, the description carries the full burden and does substantial work: it discloses the 'Draft... on apply' two-phase semantics, the dedupe behavior (byte-identical re-uploads return the existing media id), and the unwrapped AddMedia response quirk. This is far beyond a bare 'upload' claim, though it does not state authorization or reversibility requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the primary purpose and enumerates media_type values as a scannable bullet list. The live-verification note and dedupe behavior add genuine value despite some verbosity in the fault-fixing narrative. Every major section earns its place, though it runs slightly long.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description correctly explains the return value (media id on apply) and documents the enum-like media_type values. But with 2 required parameters, file_path remains ambiguous (format, source, extension constraints), which could lead to incorrect calls, and the 'apply' step of the draft workflow is not connected to any sibling (e.g., confirm_and_apply).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It thoroughly documents media_type with aspect ratios and concrete dimension examples (1200x1200, 1200x628), which the bare string schema does not convey. However, file_path is left entirely to its name — the description never clarifies whether it is a local path or URL, or the allowed file formats beyond the passing note 'PNG/JPEG'. Compensation is partial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Draft an image upload to the account media library'), names the target use cases (image extensions / PMax asset groups), and specifies the return value (media id on apply). This clearly distinguishes it from sibling tools like draft_responsive_search_ad or create_custom_audience, which operate on different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context by scoping use to 'image extensions / PMax asset groups', which helps an agent know when this tool applies. However, it never explicitly names alternatives or states when NOT to use it (e.g., other asset types like video or HTML5), so exclusions are left implicit.
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?
With no annotations provided, the description carries the full burden and handles it well: it discloses that Summary aggregation raises InvalidTimePeriodColumnForSummaryReport when TimePeriod is present, constrains days to 7/14/30, requires start_date/end_date to be provided together or not at all, and notes there is no length restriction (live-verified with a 106-day pull). Return format and auth are not disclosed, but the failure-mode and constraint disclosures are substantive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense and technical but every sentence carries a constraint or rule — no filler. Purpose is front-loaded before parameter details. It is longer than minimal, but the length is justified by genuinely non-obvious constraints that an agent cannot infer from the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter tool with no annotations and no output schema, this is fairly complete: it explains the tricky validation rules, date-mode options, and the expected report_type format. The main gap is the return value shape, which is unforthcoming (no output schema). Given the complexity, it covers the critical calling constraints well even though output format is unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does 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 for most parameters: report_type (exact v13 request type, example given), aggregation (default and validity rules), days (allowed values 7/14/30), and start/end_date (format, pairing requirement, no length limit). Only 'columns' is left implicit, but it is largely self-evident and referenced via 'column set' and the TimePeriod exclusion rule.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Arbitrary report (replaces Google run_gaql for metrics pulls)', which names a specific verb, resource, and scope. It clearly distinguishes this generic metrics-report tool from the sibling-specific performance tools (get_campaign_performance, get_ad_performance) by positioning it as the arbitrary/flexible report option.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives context by naming the legacy tool it replaces (run_gaql) and implicitly frames itself as the generic metrics pull. However, it never explicitly states when to prefer this over sibling performance tools or what conditions would point elsewhere. The strong conditional parameter guidance (Daily vs Summary, days vs start/end_date) is about constructing the call, not 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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses the cap enforcement, the pre-rejection logic, the silent-ignore behavior of the underlying API, and the fact that the write path has never been live-verified. However, it does not mention what a successful call returns or whether the draft is actually applied, which would round out the behavioral picture.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy but each sentence carries essential caveats that are critical for correct use. It front-loads the primary purpose and then layers restrictions and known limitations. While not terse, the density is justified given the complexity and failure modes; it could be tightened but is well ordered.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a three-parameter tool with no output schema and no annotations, the description covers many important constraints and known limitations, including pre-rejection rules and live-verification status. However, it leaves gaps: it does not explain what the tool returns on success, and it fails to describe the parameters themselves (which is especially important given 0% schema coverage). These omissions make it incomplete for an agent that needs to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description was expected to compensate by explaining parameters, but it does not. It omits any per-parameter guidance: what units 'bid' uses, how 'keyword_id' and 'ad_group_id' relate, or any constraints. The parameter names are self-evident, but the description adds no extra semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Draft a keyword CPC bid change') and resource ('keyword bid') with an additional constraint (MS_ADS_MAX_CPC cap). It clearly distinguishes the tool from siblings like 'draft_keywords' (which creates keywords) and 'remove_keywords' (deletes them), so an agent can identify its unique function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when the tool is allowed ('ONLY when the ad group's effective bid strategy is in the MANUAL_BIDDING allowlist') and when it is not ('Pre-rejected for Smart Bidding'), including the reason (silent ignoring). It also describes the fail-closed behavior for unrecognized strategies, giving unambiguous guidance on when to call or avoid the tool.
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?
No annotations are provided, so the description carries the full burden. It discloses that it performs a token refresh and a get round-trip, implying network activity and potential token state mutation. However, it does not explicitly state whether it is read-only, what side effects occur (e.g., does token refresh persist?), or what the return value represents. For a health check, this level of disclosure is minimal but not misleading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no wasted words. It front-loads the core purpose ('Verify auth chain') and then adds specificity. Perfectly sized for a zero-parameter diagnostic.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters and no output schema, the description is largely sufficient. It explains the actions taken. However, it does not describe what the tool returns (e.g., a boolean success, a structured health report), which an agent might need to interpret the result. Since there is no output schema, this omission is a small gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema is empty with 100% coverage by default. The description does not need to explain parameters, so the baseline of 4 applies. No additional meaning is required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('verify') and a clear resource ('auth chain'), and clarifies the exact operations involved (token refresh + Customer Management GetUser round-trip). This sets it apart from all 45 sibling tools, which are focused on entity management, reporting, and ads – none of which are diagnostic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Verify auth chain' gives clear context for when to use it – after authentication setup or when debugging auth issues. While it does not explicitly mention alternatives, the tool's unique purpose among siblings (no other health check) eliminates ambiguity. Some exclusion guidance is absent but not critical given the uniqueness.
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?
With no annotations provided, the description carries the disclosure burden. It reveals a significant behavioral trait: the data comes from a locally cached file (30-day cache) rather than a live query API, which affects freshness. It also states the return value (location IDs). While it does not cover rate limits or error handling, for a simple search tool this is reasonably transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with zero waste. The primary action and the key caching trait are front-loaded, making it efficient for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter search tool with no output schema, the description covers the tool's purpose, data source, and return value. It does not explicitly mention result limits or error conditions, but these are less critical for a simple lookup. Overall, it provides sufficient information for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no description for the single 'query' parameter (0% coverage), so the description must compensate. It implies the query is a location name via 'by name', adding meaning beyond the raw schema. However, it lacks format details or examples, and only minimally compensates for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Search') and resource ('targetable/excludable locations'), and clarifies it returns location IDs for geo write tools. This clearly distinguishes it from geo write tools like exclude_geo_target and remove_geo_target. It is not a tautology and provides a concrete function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates the tool is a prerequisite for geo write tools ('Returns location ids for geo write tools'), giving clear context on when to use it. However, it does not explicitly mention alternatives or when not to use it, 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden for behavioral disclosure. It discloses the fail-closed rule for bid adjustments, notes that the read-side fault is non-applicable, and includes a live verification timestamp, which adds credibility and context. It does not cover idempotency or response format, but the key behavioral constraints are well documented.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is verbose but every sentence carries critical information: the core action, the namespace disambiguation, the bid adjustment constraint, and the verification note. It is appropriately structured, front-loading the purpose and then supporting details. Not excessively wordy for the complexity involved.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's 4 parameters, no annotations, and no output schema, the description covers the most complex aspects (bid adjustment rules, audience_type enum) adequately. It does not mention return value, but with no output schema that is not required. It also omits any mention of prerequisites (e.g., campaign must exist), but those are likely implicit. Overall, it is complete enough for an agent to call correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains audience_type as a namespace disambiguator and lists the valid enum values, and it explains the conditional semantics of bid_adjustment_pct. It does not explicitly describe campaign_id or audience_id, but their meaning is self-evident from the names and context. This is strong compensation given the schema offers no help.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Draft audience targeting on a campaign') with a specific resource (campaign) and distinct intent (adding audience targeting). It disambiguates the audience_type namespaces, which helps distinguish it from other audience-related tools like create_custom_audience, making its purpose 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context by explaining when bid_adjustment_pct is allowed (only with manual bidding strategies) and when it is rejected, which is a concrete usage condition. It does not explicitly mention alternatives or when not to use the tool, but the functional condition is a useful guide, and the 'on a campaign' phrasing implies an existing campaign context. Missing explicit comparisons to siblings prevents 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?
With no annotations provided, the description carries the full burden and delivers exceptional transparency: it discloses the duplicate-check behavior, the policy on blocklisted terms, the hard API fault condition for ad_group scope without campaign_id, and even a live-verification note with date and scope. This goes well beyond what a typical description offers.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, with the purpose and scope first, then key behaviors, and finally a verification note. The verification sentence is useful for trust but arguably optional. Overall it is well-organized and wastes little space, though formatting could be more structured with bullet points.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 parameters, no schema descriptions, no annotations, and no output schema, the description covers all critical operational aspects: accepted scopes, keyword format, duplicate handling, blocklist policy, parent campaign requirement, and verification status. Nothing an agent needs to invoke it correctly is missing, making it highly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description compensates fully: it explains the scope enum options, the exact keyword object format ({text, match_type: Phrase|Exact}), and the campaign_id requirement for ad_group. The entity_id is not explicitly explained but is inferable as the target ID for the chosen scope. Given the complete schema absence, this is exemplary parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool drafts negatives and clearly enumerates valid scopes (campaign, ad_group, shared_list) and the keyword structure. It implies the addition operation via the duplicate-check skip and reference to 'negating'. It is distinct from siblings by name and content, though the phrase 'Draft negatives' is slightly informal and could be more explicit that it actively adds.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides behavioral constraints that guide when to use the tool (e.g., duplicate-check rule, blocklist not applied, campaign_id requirement for ad_group scope) but does not explicitly mention alternatives or when to use get/remove instead. Usage context is largely implicit from the name and sibling set rather than explicitly stated.
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?
With no annotations provided, the description carries the full burden. It discloses that keywords are created paused, that blocklist (settings-configured blocked_terms) and bid cap (MS_ADS_MAX_CPC) are enforced, and includes a live-verification note. This covers key side effects and constraints, though it doesn't detail error handling or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loads the core purpose ('Draft new keywords under an ad group — created Paused'), then details the structure and constraints. The verification line adds some length but is informative. Overall, it is efficient without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 parameters, one open-ended array) and lack of annotations or output schema, the description covers the essential aspects: purpose, keyword structure, paused creation, and enforcement rules. It lacks details on error behavior or return values, but these are not critical for basic invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage and the keywords parameter lacks a defined structure (additionalProperties: true). The description compensates fully by specifying the array elements as {text, match_type: Broad|Phrase|Exact, bid: optional float}, providing essential parameter details that the schema omits.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Draft new keywords under an ad group' with the verb 'draft' and resource 'keywords', and specifies they are 'created Paused'. It also lists the array structure (text, match_type, bid) and mentions enforcement of blocklist and bid cap, distinguishing it from other keyword tools like update_keyword_bid or remove_keywords.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context that this tool is for creating new keywords in a paused state, which implies its use for drafting rather than activating. However, it does not explicitly state when to use this versus alternatives like discover_keywords or add_negative_keywords, nor does it provide exclusions. It's clear enough for an agent to infer, but not fully explicit.
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?
With no annotations available, the description carries the full burden of disclosing behavior. It reveals the exact API call, the scope (deletes whatever criterion id is passed, not just locations), and that it is a draft removal. It omits permission requirements and return value, but the substantive behavioral scope is well disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences efficiently pack the API, scope, and ID sourcing. The critical disambiguation about non-location targets is front-loaded, and the verification note adds credibility without bloat. No word is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple two-integer parameter schema and no output schema, the description covers the essential operational context: what it does, what it affects, and where to get the ID. It does not mention response behavior or error conditions, but for a simple removal tool the guidance is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description compensates by explaining the origin and meaning of criterion_id (from get_entities) and the scope of the operation. It does not elaborate on campaign_id, but the context makes it obvious, and the parameter list is short.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (draft removal), resource (campaign criterion), and the underlying API call. It explicitly clarifies that the target group covers multiple criterion types, not just Location, which distinguishes it from what the name might imply and from sibling tools like remove_extension.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use it (to delete a campaign criterion) and provides a concrete instruction for obtaining the criterion_id via get_entities. It does not explicitly state when not to use it or contrast with remove_entity, but the usage context is clear and actionable.
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?
With no annotations present, the description carries the full burden and delivers exceptionally. It discloses the silent-failure mode (matches-criteria omitted → goal 'creates successfully' but never records), the live-vs-WSDL discrepancy for goal_category (fault 3347), the category-collision fault (5667) with its tested-vs-inferred caveat, and the one-way-door reality (no DeleteConversionGoals; update no-ops; only Paused/ExcludeFromBidding as levers). This is far beyond what is typical and gives the agent honest model of side effects and failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well front-loaded (purpose first, then goal_type bullet list) and logically organized with clear warn-blocks. However, it is a dense wall of text with internal project references ('Task 25e probe', 'Task 25f') and deep fault-code archaeology that a general agent doesn't need verbatim. The information is valuable but could be trimmed to be more efficient without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a high-complexity tool (7 params, 0% schema coverage, no annotations, no output schema), this is near-complete: it specifies supported goal types, per-type required arguments, category constraints and defaults, the offline-conversion exclusion, the irreversible-creation warning, and documented backout levers. The only residual gaps are the undocumented 'value' parameter and the absence of a note on the expected success/confirmation response, both minor against the depth provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
At 0% schema coverage the description must compensate, and it does for 5 of 7 params: goal_type (three values, dev-account constraint), url_expression (UrlOperator=Contains), action_expression (ActionOperator=Contains), minimum_duration_seconds (required for Duration), and goal_category (enum values, default, live-verified validity across goal types). The only gap is the 'value' parameter, which receives no explanation at all — a minor omission for an otherwise thorough mapping.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action on a specific resource ('Draft a conversion goal') and immediately differentiates itself by spelling out the three supported goal_types and, crucially, what it deliberately does not do (OfflineConversion goals — 'create them in the MS Ads UI instead'). It is clearly distinct from siblings such as get_conversion_actions (read) and set_conversion_action_primary_status (post-creation status control).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use context: the three goal_type values and their required matching args, plus the lead-gen-meaningful category values. It explicitly states when NOT to use ('OfflineConversion goals are deliberately not created by this tool — create them in the MS Ads UI' with the double-counting rationale) and the one-way-door warning effectively tells the agent to use this only when a permanent, undeletable goal is acceptable. It doesn't name an in-toolset alternative for the offline path, but steers to the external UI, which is clear enough.
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?
No annotations are provided, so the description carries full burden. It discloses that the tool itself is not live-verified, but the underlying call has been live-probed via a related pattern, giving agents a sense of reliability. It also clarifies that it only returns a draft, so no direct mutation occurs. However, it does not mention required permissions or what happens on failure, though for a draft tool these are less critical. Overall, it provides more transparency than typical.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two paragraphs: the first covers purpose and usage, the second is a verification note. It is front-loaded with the key operational info. The second paragraph includes technical jargon like 'blank()-built' that might be noise, but it is brief and provides trust context. Overall, it is efficient and does not waste words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter tool with no annotations and no output schema, the description is fairly complete. It explains the draft-apply workflow, the tCPA constraint, and the verification status. It does not explicitly state what the response looks like (beyond 'returns a draft'), which is acceptable given the sibling confirm_and_apply exists. It also doesn't list prerequisites like campaign existence, but these are implicit. Minor gaps remain, but the description covers the essentials for an agent to call correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It maps the main parameters explicitly: budget (daily_budget), status with allowed values Active|Paused, and tCPA (target_cpa) with the constraint that it only works on PMax. This adds value beyond the bare schema. It does not detail value ranges for budget or units, but the essential meaning is conveyed. Given the low coverage, this is a strong effort, though not exhaustive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the specific verb 'Draft' and the resource 'campaign update' with the exact fields (budget / status / tCPA). It explicitly differentiates from sibling update_ad_group by noting that campaign-level tCPA is only operative on PMax. This makes the tool's purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear when-to-use guidance: tCPA at campaign level only for PMax, and for Search it directs to update_ad_group. It also explains the workflow ('Returns a draft; apply with confirm_and_apply'), telling the agent that this tool only drafts changes and another tool applies them. This is explicit routing and sequencing.
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?
With no annotations, the description fully carries the burden. It discloses that the campaign is created paused, defaults for time_zone, aborts the asset-group add if the campaign add fails, returns a draft, and details mid-apply failure behavior with landed IDs. It also includes live-verification status for different paths, adding significant behavioral context beyond any structured metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured and front-loaded with the core purpose. It progresses logically from defaults to rules, verification notes, and failure handling. Every sentence adds important context, so it is appropriately detailed rather than unnecessarily verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 10 parameters, 0% schema coverage, no annotations, and no output schema, the description is remarkably complete. It covers prerequisites (images, target CPA), defaults, failure semantics, retry guidance, and even the apply step. An agent has enough information to use the tool correctly and avoid common pitfalls.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains time_zone default, target_cpa requirement (including the setting to allow null), and image_media_ids constraints (must exist in media library, specific MediaTypes, unknown types raise). It does not explicitly describe headlines, long_headlines, descriptions, or business_name, but these are self-explanatory. Overall, it adds meaningful meaning for the most complex parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool drafts a Performance Max campaign plus its first asset group, created paused. This is a specific verb+resource that distinguishes it from siblings like draft_campaign, draft_responsive_search_ad, etc., even without naming them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides concrete usage context: target_cpa is required by default and how to enable a no-target path via settings; images are mandatory and must meet media library type requirements. It also explains failure handling and retry semantics. However, it does not explicitly mention alternative tools or when to use a different draft function, so a small gap remains.
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?
With no annotations, the description fully carries the behavioral disclosure burden. It reveals pagination behavior, the 1000-account safety cap, the meaning of the `truncated` flag, and even suggests a remediation (raise MAX_PAGES). This goes well beyond a generic summary and gives the agent a realistic model of the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. The main purpose is front-loaded, and the implementation detail is neatly parenthesized. Every clause adds value, from the scope ('ALL') to the practical advisory about MAX_PAGES.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and no output schema, the description covers the essential behavior: what it lists, the paging cap, and the `truncated` flag. It does not describe the shape of the returned accounts (e.g., IDs, names), which might be inferred from typical listing tools, but for a 0-param tool, the description is sufficient for a correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema contains no parameter documentation. Per the baseline for 0 parameters, a score of 4 is appropriate. The description does not need to add parameter semantics, as there are none. It does mention the output field `truncated`, which is not a parameter but does add context about the response.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states exactly what the tool does: 'List ALL advertiser accounts visible to the authenticated user'. It names a specific verb and resource, and the emphasis on 'ALL' distinguishes it from account-specific tools like get_account_info. The implementation note ('paged SearchAccounts under the hood') adds clarity without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly name alternative tools, but it clearly implies the scope: this is for listing all accounts, not for retrieving a single account's details. It provides practical usage guidance about the `truncated` flag and the MAX_PAGES safety cap, telling the agent what to do if that occurs. However, it could be more explicit about when to prefer this over get_account_info.
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?
With no annotations, the description fully owns behavioral disclosure. It reveals that the tool only drafts (does not apply), that the cpc_bid/target_cpa branches are not live-verified, and that policy rails are re-checked at apply. It also discloses the underlying UpdateAdGroups call is live-proven for status flips. This is exceptionally transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two focused paragraphs, front-loaded with purpose, and every sentence adds value—parameter semantics, constraints, workflow, and verification status. Nothing is redundant or padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and 0% schema description coverage, the description covers return behavior (draft), application flow (confirm_and_apply), parameter constraints, and live-verification status. It supplies everything an agent needs to decide whether and how to call it, with no critical gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description is the only source of parameter meaning. It thoroughly explains target_cpa (introduces an explicit tCPA) and cpc_bid (restricted to MANUAL_BIDDING, silently ignored under Smart Bidding). It also clarifies the interplay between these and the bid strategy, adding far more than the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it drafts an ad-group update, listing the specific fields (target_cpa, cpc_bid, status) it can modify. It explicitly distinguishes itself from update_keyword_bid by referencing the same guard, and makes clear it returns a draft to be applied later.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when each parameter is used (target_cpa for MaxConversions, cpc_bid only in MANUAL_BIDDING) and points to confirm_and_apply for the apply step. It implies usage context for ad-group updates versus keyword updates, but does not explicitly enumerate alternative tools or exclusions.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states 'PERMANENT deletion', 'Irreversible', and details the dependency on parent_id per entity type. It also discloses verification status, which is uncommon and highly informative. It fully communicates the destructive and irreversible nature of the operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: first sentence states the purpose and irreversibility, second sentence gives the alternative, third provides parameter details, and a final line on verification status. Every sentence adds value, no fluff, and it's easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with no annotations or output schema, the description covers purpose, irreversibility, parameter requirements, and verification reliability. It does not mention return values, but that's not expected without an output schema. It provides enough context for an agent to safely decide whether to call it and how to construct the call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains parent_id for ad_group and keyword/ad, and lists allowed values for entity_type ('campaign | ad_group | keyword | ad'). However, it does not explicitly define what entity_id represents (though it's implied by name), and it doesn't clarify that parent_id is optional or null for campaign entities. Slight gap but mostly sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('permanent deletion') and resource (campaign, ad_group, keyword, ad), and immediately differentiates itself from pause_entity by labeling the operation 'Irreversible' and recommending the alternative. This clearly distinguishes it from sibling tools like pause_entity and enable_entity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'prefer pause_entity' as the safer alternative, and gives precise conditional requirements: 'ad_group needs parent_id=campaign id; keyword/ad need parent_id=ad group id.' It also flags verification status ('Live-verified... NOT live-verified...') to warn about reliability. This gives the agent clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full behavioral burden. It fully discloses that this is a destructive operation (deletes existing DayTime criterions), that it returns a draft (not directly applied), and details the mid-apply failure mode including what error payload is returned. It also mentions the verification date and the retry behavior. This is excellent disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence adds critical value: the core behavior is front-loaded, the constraints are stated clearly, and the failure-recovery detail is essential. The verification note is extra but provides credibility. No fluff exists; each line earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, destructiveness, and the lack of output schema and annotations, the description is complete. It covers the required week shape, the destructive delete-then-add behavior, the return value (a draft), the mandatory follow-up with confirm_and_apply, and the failure reconciliation procedure. Nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must compensate. It does so thoroughly: it explains the week parameter as '7 dicts {day, from_hour, to_hour}' and the 0-23 hour clock semantics, including an example (to_hour=22 serves until 22:00). It also implicitly clarifies that campaign_id identifies the campaign whose schedule is replaced. This fully covers the parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'REPLACE a campaign's ad schedule', specifying the exact verb and resource. It further clarifies the operation by stating 'Deletes existing DayTime criterions then adds the new set', which distinguishes it from any other ad-schedule tool. The inclusion of 'apply with confirm_and_apply' clarifies the workflow context. This is unambiguous and fully differentiates from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: it mandates the week must cover all 7 days, explains the consequence of a partial week ('silently narrows delivery'), and instructs to apply with confirm_and_apply. It also gives detailed failure-recovery instructions, telling the agent to reconcile state before retrying. This is comprehensive guidance on when and how to use the tool.
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:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
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/wvuhskr/mcp-microsoft-ads'
If you have feedback or need assistance with the MCP directory API, please join our Discord server