microsoft-ads-mcp

Server Quality Checklist

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

Latest release: v0.4.0
Disambiguation4/5
Most tools have distinct purposes, with clear CRUD patterns for each entity. A few tools like get_effective_url_settings and get_account_url_options are closely related but well-differentiated in descriptions. Overall, an agent can reliably distinguish tools.
Naming Consistency5/5
All tool names follow a consistent verb_noun pattern using snake_case. Examples include search_accounts, get_campaigns, create_campaign, delete_campaign, add_negative_keywords. No mixing of conventions.
Tool Count3/5
66 tools is on the higher end, but given the comprehensive coverage of Microsoft Advertising (campaigns, ad groups, keywords, ads, extensions, conversion goals, reports, etc.), the count is borderline. It may be slightly heavy but not excessive.
Completeness4/5
The tool set covers a wide range of operations: account management, CRUD for campaigns, ad groups, keywords, ads, extensions, conversion goals, location targeting, ad schedules, device adjustments, reports, and bulk operations. Minor gaps exist (e.g., no single entity getters), but core workflows are well-supported.
Average 4.1/5 across 66 of 66 tools scored. Lowest: 3.1/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 33 commits in the last 12 weeks
- Last stable release on June 27, 2026
- 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.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

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

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

How is the quality score calculated?

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

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

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

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

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, so the description adds minimal extra behavioral context. It mentions polling but does not disclose details like whether it's synchronous, how long polling takes, what gets destroyed, or authorization 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently states the action and polling behavior without wasted words. It could be slightly improved by front-loading the purpose more prominently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description does not explain the polling mechanism, return format, or error states. For a bulk upload tool, this lacks completeness for an agent to fully understand the behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the parameter description already explains the CSV rows and expected output. The tool description adds context about applying to the account but does not add meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it applies ready-made Bulk CSV rows to the account and polls to completion, specifying the verb and resource. However, it does not differentiate from the sibling 'bulk_download' tool, which is for downloading.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when CSV rows are ready and the tool will poll to completion, but it does not explicitly state when to use this tool versus alternatives or provide exclusion criteria.
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?
Annotations indicate readOnlyHint=false, implying destruction, and the description says 'delete', which is consistent but adds no additional behavioral context like irreversibility, permissions, or cascading 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise (6 words), efficient, and front-loaded. However, it could include slightly more context without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation, the description lacks important details such as whether the delete is soft or permanent, idempotency, and what the output schema contains. Minimal completeness given the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Scema coverage is 100% with clear descriptions for both parameters. The description adds no extra meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes one or more ad groups by ID, which is specific and distinguishes it from sibling tools like delete_keyword or delete_campaign.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, such as update_ad_group or other operations. No exclusions or context 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?
The description discloses the action (add) but provides no additional behavioral traits beyond the annotation's readOnlyHint=false. It does not mention whether duplicates are handled, the impact on existing keywords, or any rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It efficiently conveys the core action and scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description is too brief. Given the tool's complexity (7 parameters), it lacks guidance on when to use it, prerequisites, and limitations, leaving an agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter is already described in the schema. The tool description adds no extra meaning beyond what the schema provides, earning the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Add keywords' and the resource 'ad group', along with the status '(Active)'. This distinguishes it from sibling tools like 'update_keyword' or 'add_negative_keywords'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives. It does not mention prerequisites like the ad group must exist or be active, nor does it compare with 'update_keyword' or 'add_negative_keywords'.
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?
Beyond the annotation indicating mutation (readOnlyHint: false), the description only states deletion. It does not disclose side effects on related entities, reversibility, or error behavior, which would be valuable for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words, front-loaded with the action. Slightly too brief for optimal clarity but concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple deletion tool with one parameter and existing annotations/output schema, the description is adequate but lacks details on permissions, side effects, or error handling. Sufficient for minimal understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents the parameter. The description adds no additional meaning beyond 'by id', but is consistent and minimally sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb (delete), resource (campaigns), and method (by id), distinguishing it from other campaign-related tools like create_campaign, update_campaign, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, such as prerequisites, idempotency, or limitations on the number of campaign IDs. Does not mention when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only nature is clear. The description adds no extra behavioral context beyond the basic listing action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, concise and front-loaded. It conveys the essential purpose without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and annotations, the description is adequate for a simple list tool. However, it lacks information about pagination or filtering, which might be valuable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, campaign_id, has a description in the input schema ('The campaign id.'). The tool description adds no further meaning, so it does not exceed the baseline for 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List ad groups in a campaign' clearly states the verb (list) and resource (ad groups), and implies the scope (within a campaign). It distinguishes from sibling tools that list other entities like keywords or ads.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as search_accounts or get_campaigns. The description does not mention any constraints 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?
Annotations indicate readOnlyHint=false, so the description's 'Create' is consistent. The paused state is a helpful behavioral detail. However, no other behavioral traits are disclosed (e.g., auth requirements, rate limits, overwrite behavior). The description adds minimal value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (one sentence) and front-loaded with key info. However, it is arguably too terse for a complex tool with 9 parameters, lacking contextual detail that would aid understanding without extra scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of an output schema and full schema parameter coverage, the description doesn't need to explain return values. However, it fails to provide high-level context such as validation rules, required permissions, or relationship to other tools (e.g., ad groups). It meets the minimum but is not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all parameters and their descriptions. The tool description adds no additional meaning beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create'), the resource ('Responsive Search Ad'), and the initial state ('PAUSED'), which distinguishes it from the sibling tool 'update_responsive_search_ad'. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 alternatives (e.g., when to create an active ad instead of paused, or prerequisites like ad group existence). The description lacks any contextual usage tips.
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?
Annotations already indicate readOnlyHint=false. The description adds no additional behavioral context beyond 'delete', such as irreversibility, permissions needed, or effect on related data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, clear sentence with no unnecessary information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with two parameters and an output schema, the description is adequate but lacks mention of batch behavior, error handling, or permission requirements.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters described. The description does not add extra meaning beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (delete), resource (keywords), and method (by id). It effectively distinguishes from siblings like add_keywords and update_keyword.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., delete_campaign). No context about prerequisites or exclusions is given.
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?
Annotations already show it's not read-only; description adds no extra behavioral insights like side effects, idempotency, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, clear sentence with no wasted words, front-loading the action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Simple tool with two parameters and output schema present; minimal description is adequate but lacks context on behavior when status is unchanged or error states.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%; description does not add beyond schema. Mentions status values which are already in schema, so baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Set a campaign Active or Paused' clearly specifies the verb and resource, and distinguishes from siblings like update_campaign by focusing solely on status change.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like update_campaign, or when not to use it. Sibling tools exist but no differentiation is 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?
Annotations only set readOnlyHint=false, so description carries the burden. It says 'update in place' but does not disclose potential side effects, permission requirements, or error behavior (e.g., what happens if tag_id is invalid).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence of 12 words, front-loaded with verb and resource. No extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool with 3 params and an output schema, the description is adequate but could mention that the tag must exist and that the tag_id comes from get_uet_tags (schema notes this implicitly). No mention of return value, though output schema likely covers it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for each parameter. The description reaffirms that name and/or description can be updated but adds little new meaning beyond the schema. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb 'Update' and the resource 'UET tag', specifying the fields 'name and/or description'. It clearly distinguishes from sibling tools that update other resources like campaigns or ad groups.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives, no prerequisites or exclusions mentioned. For example, it does not indicate that one should first retrieve a tag ID via get_uet_tags.
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?
The description only restates that the tool adds keywords, without disclosing behavioral details such as whether it appends or overwrites existing negatives, or any rate limits. The readOnlyHint=false annotation already indicates mutation, so the description adds little beyond that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately conveys the tool's purpose. It is appropriately sized but could be slightly more structured to include brief usage hints.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description does not need to detail return values. However, it lacks context about error conditions, idempotency, or limits. For a mutation tool, this is adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Since schema description coverage is 100%, the baseline is 3. The description does not add any additional meaning beyond what the schema already provides for the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('attach negative keywords') and the target resource ('campaign or ad group'), distinguishing it from sibling tools like 'add_keywords' or 'remove_negative_keywords'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide guidance on when to use this tool versus alternatives like 'remove_negative_keywords' or 'add_keywords'. It also lacks context about prerequisites (e.g., the entity must exist) or when to choose campaign vs. ad group.
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?
The description straightforwardly states the delete operation, which aligns with the annotation readOnlyHint=false. However, it adds no behavioral details such as whether deletion is irreversible, cascading effects, permissions required, or confirmation steps. The annotation already covers the write nature, so the description adds minimal value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no superfluous information. Every word is necessary and efficiently communicates the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with two well-described parameters and an output schema, the description is largely sufficient. It lacks only minor context about return format or confirmation, but the output schema likely covers that. The sibling tools provide contrast, but the description does not address when alternatives are appropriate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes both parameters (ad_ids and ad_group_id) with clear descriptions, and coverage is 100%. The tool description does not add any additional meaning beyond what the schema provides, meeting the baseline expectation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete one or more ads by id' precisely states the action (delete), the resource (ads), and the scope (by id). It clearly distinguishes from sibling tools like delete_keyword or delete_ad_group.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., deleting campaigns or ad groups) or under what conditions deletion should be performed. There is no mention of prerequisites or consequences.
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?
Annotations already declare readOnlyHint=true. The description 'List' is consistent but adds no additional behavioral context (e.g., data freshness, pagination, permissions). There is no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the verb and resource. No extraneous words. Extremely concise and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple listing tool with one required parameter and an existing output schema, the description is adequate. It could briefly mention what the response contains, but the output schema likely covers that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter (campaign_id) already described in the schema. The description does not elaborate beyond 'The campaign id.' Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'List' and clearly identifies the resource as 'location targets/exclusions on a campaign'. This is specific and distinct from sibling tools like 'add_location_targets' or 'remove_location_targets'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., set_location_intent, add_location_targets). The description is a bare statement without context or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds no further behavioral details (e.g., pagination, error states). With annotations, the bar is lower; a score of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no extraneous words. It is front-loaded and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one parameter, an output schema, and readOnlyHint annotation, the description is minimally adequate. However, it lacks context like expected results or typical use case, which could improve usability among many siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'ad_group_id' is already well-described in the schema ('The ad group id.'). Schema description coverage is 100%, so the description adds no extra meaning beyond the schema. Baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List keywords in an ad group' uses a specific verb ('List') and identifies the resource ('keywords in an ad group'). It clearly distinguishes from sibling tools like get_negative_keywords or get_keyword_ideas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. Among many sibling tools related to keywords (e.g., get_keyword_ideas, estimate_keyword_bids), there is no mention of prerequisites or typical use cases.
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?
The description merely states 'Create' which aligns with annotations (readOnlyHint: false), but adds no further behavioral context (e.g., permissions, limits, side effects). Key behavioral details are relegated to parameter descriptions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words. Front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a creation tool with an output schema (not shown), the description adequately covers the core action and optional attachment. It implicitly covers context given the sibling list and parameter count.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Since schema description coverage is 100%, the baseline is 3. The description adds no extra meaning beyond the schema's already detailed parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Create a call extension' with a specific verb and resource, and distinguishes from sibling tools like 'update_call_extension' and 'add_callout_extension'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives such as 'update_call_extension'. The description implies usage for creation but lacks exclusions or context.
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?
Annotations indicate readOnlyHint: false (write operation), which the description confirms. However, the description adds minimal behavioral context beyond creation and optional attachment. It does not disclose prerequisites (e.g., needing a campaign/ad group), side effects of attachment, or limits on the number of extensions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence (13 words) that front-loads the essential information. Every word is meaningful, with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists (reducing the need to explain return values), the description is fairly complete for a creation tool. It covers the core action and optional attachment. However, it could briefly mention the pairing constraint for descriptions, though the schema already handles that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description does not add any extra meaning beyond what the schema already provides for parameters like entity_id, final_url, etc.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create'), the resource ('sitelink extension'), and the optional association ('optionally attach to a campaign or ad group'). It effectively distinguishes from sibling tools like update_sitelink_extension (modify) and other extension tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for creation, but lacks explicit guidance on when to use this tool versus alternatives (e.g., when to attach vs. create unattached, or comparisons with other extension creation tools). No when-not or exclusion criteria 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?
Annotations already declare readOnlyHint=true, indicating a safe read operation. The description adds no additional behavioral context beyond the annotation, missing potential details like pagination, rate limits, or result limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that conveys the tool's purpose without extra words, earning its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and the tool has low complexity, the description is sufficiently complete. No critical missing information is apparent, though pagination details could be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single parameter described. The description does not add meaning beyond the schema, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists text and responsive-search ads in an ad group, specifying the verb 'List' and resource 'ads' with a scope that distinguishes it from sibling tools like get_campaigns and get_ad_groups.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (to list ads in an ad group) but does not provide explicit guidance on when not to use it or mention alternatives among siblings, such as create or update ad tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states a write operation ('Remove'), which aligns with the annotation 'readOnlyHint: false'. However, it does not disclose additional behavioral traits such as whether the removal is permanent, if it affects active campaigns, or any required permissions. The description is adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no unnecessary words. It is front-loaded with the core action and specific detail, making it highly concise and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the availability of an output schema, the description does not need to explain return values. The description covers the essential action and parameters. It could mention relationships with sibling tools (e.g., 'replace_ad_schedule') but remains reasonably complete for a straightforward deletion tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% description coverage for both parameters. The description adds no extra meaning beyond what the schema already provides (e.g., 'criterion_ids' described as 'Campaign criterion ids (from get_ad_schedules)'). Thus, baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Remove' and the resource 'ad-schedule (dayparting) windows', and specifies the method 'by criterion id'. This distinguishes it from sibling tools like 'add_ad_schedules' and 'replace_ad_schedule'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'replace_ad_schedule'. The description lacks context such as prerequisites or scenarios where removal is preferred.
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?
The annotation readOnlyHint: false indicates a mutation, which the description confirms. However, the description adds no new behavioral traits beyond the schema, such as side effects, permission requirements, or reversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It efficiently conveys the action and key input.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the presence of an output schema, the description is complete enough. It identifies the essential input (criterion IDs) and action, though it could briefly note that IDs come from get_location_targets, which is already in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both parameters clearly documented. The description adds no additional meaning beyond referencing the criterion IDs, so it meets the baseline but does not enhance understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Remove' and the resource 'location targets/exclusions from a campaign', specifying the method 'by criterion id'. This distinguishes it from sibling tools like add_location_targets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used when removing location targets by criterion IDs, but it does not provide explicit guidance on when to use vs. alternatives, nor does it mention prerequisites or scenarios to avoid.
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 indicate readOnlyHint=false, consistent with 'Create'. The description adds optional attachment context but no further behavioral traits like required permissions or side effects. Adequate but minimal given no annotation contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences front-loaded with main action. The example is helpful but not strictly necessary; still compact with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given output schema exists and schema descriptions are thorough, the description is complete for a create operation. It lacks mention of authentication context, but that is likely shared across sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions. The description adds an example but does not provide additional semantic meaning beyond the schema, so baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create' and the resource 'structured snippet extension', and optionally attaching to campaign/ad group. It distinguishes from siblings like update_structured_snippet_extension and other add_* extensions by specific naming.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for creating new extensions but does not explicitly state when to use this vs. alternatives (e.g., update). No exclusions or prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate mutation (readOnlyHint=false). The description adds behavioral detail about optional attachment to a campaign or ad group, but does not disclose potential side effects, idempotency, or limits beyond what the annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, concise sentence that covers the core functionality with no extraneous words. Front-loaded with the primary action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with 3 parameters and an output schema exists, so the description is largely adequate. However, it could mention that callout extensions are a type of ad extension and that there might be limits, but these are not critical gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions already present. The description adds no new parameter-level information beyond what the schema provides, so it meets the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the resource ('callout extension'), and it distinguishes the tool from sibling tools that create other extension types like sitelinks or structured snippets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus alternatives (e.g., other extension types), nor does it mention prerequisites or when not to use it. The usage context is implied but not clarified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description indicates a mutation operation (target or exclude), consistent with the readOnlyHint=false annotation. However, it lacks details on how existing targets are affected (e.g., overwrite or append) and any potential 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences with no wasted words. It is front-loaded with the core action and provides a useful prerequisite in the second sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of an output schema, the description does not need to explain return values. It could provide more context on how bid_adjustment interacts with targeting vs. exclusion, but overall it is reasonably complete for a well-documented tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the schema already documents all parameters. The description adds minimal semantic value beyond the schema, only hinting that location_ids should come from resolve_postal_codes.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool targets or excludes Microsoft LocationIds on a campaign, using a specific verb and resource. However, it does not explicitly differentiate from sibling tools like remove_location_targets, which is a minor gap.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a clear prerequisite (resolve ZIPs to LocationIds first with resolve_postal_codes), helping the agent understand the required sequence. It does not explicitly state when not to use this tool, but the context is adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the initial paused state, which adds value beyond the annotation (readOnlyHint=false). However, it does not mention other behaviors like validation requirements, side effects, or auth needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that conveys the core purpose without any unnecessary words. It is well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is an output schema and the tool is relatively simple (create with 2 required parameters), the description is complete enough. It could mention activation after creation but is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds no extra parameter details beyond what the schema already provides; it only mentions the initial state.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Create an ad group (PAUSED)' with the resource and an important initial state. It distinguishes from sibling tools like update_ad_group or delete_ad_group.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for creating a new ad group but does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives 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?
The description aligns with annotations (readOnlyHint=true), confirming a read-only operation. However, it does not disclose additional behavioral traits such as pagination, performance characteristics, or scope limitations beyond what annotations already provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no wasted words. It front-loads the action and resource, making it immediately clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of an output schema (context: true) and comprehensive parameter documentation, the description sufficiently covers the tool's purpose. It might benefit from mentioning that entity_ids can be campaign or ad group IDs, but the schema already handles that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with all three parameters documented. The description adds no extra meaning beyond the schema; it merely restates the resource type. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List negative keywords attached to campaigns or ad groups' uses a specific verb ('list') and resource ('negative keywords'), with clear context. It distinguishes from sibling tools like get_keywords (positive keywords) and add_negative_keywords (write operation).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied (reading negatives), but there is no explicit statement on when to use this tool versus alternatives like add_negative_keywords or remove_negative_keywords, nor any when-not conditions. The description provides minimal guidance beyond the basic purpose.
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 declare readOnlyHint=false, consistent with a mutation tool. The description adds that it is a partial update ('Only the fields you pass change'), which is useful. However, it lacks details on side effects, permissions, idempotency, or whether unchanged fields remain untouched (implied but not explicit). The transparency is adequate but not exceptional.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, information-dense sentence. It front-loads the key action and behavior, with no extraneous words. Every part adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 100% schema coverage and existence of an output schema, the description is reasonably complete for a straightforward partial update tool. It covers the primary behavior, though it could briefly mention required parameters (campaign_id, ad_group_id) or preconditions (ad group must exist). Still, it provides sufficient context for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each parameter described in the schema. The description reinforces partial update semantics but does not add meaning beyond what's already in the schema. The baseline 3 applies as the description does not compensate for missing schema information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update'), the resource ('existing ad group'), and the key behavior ('in place', 'Only the fields you pass change'). This distinguishes it from siblings like create_ad_group (creation) and delete_ad_group (deletion). The verb+resource+scope is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool vs alternatives (e.g., creating, deleting, or other update tools). However, the name and partial update hint imply its purpose. No concrete usage boundaries or when-not-to-use guidance 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?
The description discloses partial-update behavior ('Only the fields you pass change'), which adds value beyond the annotations (readOnlyHint=false). However, it does not detail other behavioral traits such as idempotency, error handling, or the effect on unpassed fields. Annotations already indicate it's a write operation, so the burden is partially met.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, two sentences, and front-loaded with the key behavior. 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.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 13 parameters and an output schema, the description is minimal but sufficient. It conveys the essential behavior (partial update) and the output schema handles return value documentation. The description does not cover authentication or prerequisites, but those are often implicit. Overall, it is adequately complete for this complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond what the schema already provides for each parameter. The schema itself is detailed, so no extra description is necessary.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates an existing campaign in place, specifying that only passed fields change. This distinguishes it from sibling tools like create_campaign and delete_campaign, and aligns with the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used when updating campaign fields, but provides no explicit guidance on when to use it versus alternatives like update_campaign_status or when not to use it. The usage is implied but not clearly contrasted with siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond the readOnlyHint annotation by explaining the polling behavior and file size reasoning. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with purpose and outcome, no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low complexity (one optional param), existing output schema, and clear behavioral description (polling, file size), the description is complete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'entities' is fully described in the input schema (100% coverage). The tool description does not add further semantic meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Export the account to a Bulk file') and the outcome ('returns the result file URL when ready'). It distinguishes from siblings like bulk_upload but does not explicitly differentiate from other read tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that it polls and returns a URL due to file size, but does not provide explicit guidance on when to use this tool versus alternatives (e.g., individual get_* tools). No when-not or alternative references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only indicate readOnlyHint=false. The description adds value by disclosing that the campaign is created in a PAUSED state for safety, a behavioral trait important for the agent to know.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the core action, and contains no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (10 parameters, output schema exists), the description is minimal but covers the essential action and the paused default. The output schema likely provides return details, so the description is adequate but not rich.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with all parameters described. The description does not add any additional meaning beyond the schema, meeting the baseline expectation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a Search campaign' with a specific verb and resource, and adds the notable default state 'PAUSED by default for safety', which distinguishes it from sibling update/delete tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when creating a new Search campaign, but provides no explicit guidance on when to use this tool versus alternatives like creating ad groups or updating campaigns, nor prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the tool is safe. The description adds no additional behavioral traits such as pagination, rate limits, or data freshness. Without annotations, this would be a gap, but with annotations, it meets the baseline.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the key information. Every word earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description does not need to explain return values. However, it lacks nuances like filtering by account or campaign type. For a simple listing tool with good annotations, this is adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the include_deleted parameter having a clear description. The tool description does not add any parameter-level details beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List Search campaigns in the configured account' clearly states the action (list), the resource (Search campaigns), and the scope (configured account). This distinguishes it from sibling tools like get_ad_groups or get_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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context for use (listing campaigns in the current account) but does not explicitly state when not to use or mention alternative tools. However, the purpose is clear enough that an agent can infer the appropriate scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond the readOnlyHint annotation by detailing that estimates are per-match-type with modeled metrics, account-scoped, and may be null. It does not contradict annotations. Could mention more about data sourcing or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with four sentences, front-loading the purpose and efficiently covering output, scoping, and nulls. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters, output schema, and annotations, the description covers the main behavioral aspects (return structure, scoping, nulls). It is slightly incomplete regarding how to interpret estimates or handle edge cases, but overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are already well documented. The description adds an example for keywords but does not provide additional semantics beyond what the schema offers, meeting the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool estimates the bid to reach first page or mainline for keywords, using a specific verb and resource. It is distinct from siblings like 'get_keyword_traffic_estimates' which estimate traffic, and 'check_first_page_bids' which checks current bids, though it does not explicitly differentiate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (to estimate bids for first page/mainline) but does not provide explicit guidance on when not to use it or how it compares to similar siblings like 'check_first_page_bids'. The context is clear but lacks exclusions or alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a write operation (readOnlyHint=false). The description adds that deletion is by id, not text, which is a key behavioral detail. However, it does not disclose whether the operation is reversible, what permissions are needed, or any side effects. Given the minimal annotations, the description carries more burden and adds moderate value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two concise sentences with no wasteful words. It front-loads the verb and resource, immediately conveying the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential flow (resolve ids then remove) and the scope. Given that an output schema exists (context signal true) and annotations are minimal, the description is sufficient for an AI agent to understand the tool's operation. It could mention permanence or permissions, but it is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description mentions that deletion is by id for keyword_ids and that entity_id corresponds to campaign/ad group id, but the schema already describes these parameters. No additional semantic meaning beyond the schema is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Remove', the resource 'negative keywords', and the scope 'from a campaign or ad group, identified by id'. It distinguishes itself from sibling tools like 'add_negative_keywords' and 'get_negative_keywords' by specifying that deletion is by id, not text.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'Resolve ids first with get_negative_keywords (deletion is by id, not text).' This tells the agent when to use this tool and what prerequisite steps are needed. It could be more explicit about when not to use it (e.g., if you have text instead of ids), but the guidance is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as readOnlyHint=true, so the tool is safe and non-destructive. The description adds that it 'downloads and caches Microsoft's geo-locations file on first use', which is a valuable behavioral detail beyond annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences that front-load the primary purpose and provide essential behavioral context. No redundant words; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a known output schema (not shown but present), the description doesn't need to explain return values. It covers the tool's main action and caching behavior. Could mention that it processes multiple codes at once, but this is implied by the array input.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear parameter descriptions (including example for postal_codes). The description adds context ('Resolve ... to LocationIds') but does not significantly enhance parameter understanding beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('resolve'), the resource ('ZIP/postal codes'), and the output ('Microsoft LocationIds'). It also specifies the use case ('for location targeting'), which distinguishes it from sibling tools like get_location_targets or add_location_targets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (when needing to convert postal codes for targeting) but does not explicitly state when to use this tool over alternatives like get_location_targets or add_location_targets. No exclusions or context about when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description notes that the criterion is 'updated in place' and mentions the default, but with annotations lacking destructive hint, it could more explicitly state it's a write operation that modifies campaign settings. It is adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise: one sentence for purpose and one for behavioral context/usage hint. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main action, parameter options, default condition, and a usage hint. With output schema present, it is sufficiently complete for a simple update tool, though it could mention error conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the schema already describes both parameters well. The description adds context about the default value and the deprecated option, but does not fundamentally enhance parameter understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Set') and the resource ('location intent' for a campaign). It distinguishes from siblings by referencing the read counterpart get_location_intent and explaining the default value.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises to read the current value first with get_location_intent, providing a clear usage flow. However, it does not mention circumstances where this tool should not be used or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation (false), the description adds that updates are partial ('Only the fields you pass change') and happen in place. This provides useful behavioral context without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at two sentences, front-loads the action clearly, and contains no redundant information. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity with 9 parameters and an output schema, the description effectively conveys the core behavior (partial update). It omits some specifics like required parameters, but these are covered in the schema, making it sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes all parameters and their defaults. The description does not add additional meaning beyond what the schema provides, meeting the baseline expectation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it updates an existing keyword in place, using a specific verb and resource. It distinguishes itself from siblings like add_keywords or delete_keyword by specifying modification rather than creation or deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you want to modify a keyword, but does not explicitly state when to use this tool over alternatives or provide context about prerequisites such as requiring the keyword to exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds context beyond the annotation (readOnlyHint=false) by specifying the scope (account-level) and effect (removes objects entirely), but does not detail destructive consequences or prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no extraneous information, effectively front-loading the core purpose and behavioral nuance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and an output schema, the description covers purpose and key behavior, leaving no significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds no additional meaning beyond the schema's parameter description, meeting the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes account-level ad extensions by ID and emphasizes that it removes the extension objects entirely, distinguishing it from other operations that might only remove associations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (to remove entire extension objects vs. just associations) but does not provide explicit guidance or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description does not need to restate read-only nature. It adds value by specifying exactly what data is returned (daily budget and shared-budget id), providing useful behavioral context beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the core purpose ('Per-campaign budget view') followed by parenthetical specifics. No extra words, perfectly sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema (not shown but signaled) and zero parameters. The description succinctly covers what the tool returns, which is sufficient for a read-only view. No gaps are apparent given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist in the input schema, so schema coverage is 100%. With zero parameters, the baseline is 4; the description does not need to add parameter info, and it does not detract.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool provides a per-campaign budget view, detailing the specific data returned: daily budget and shared-budget id. This verb+resource is specific and distinguishes it from sibling tools, which are mostly about campaigns, ads, or other entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. With many sibling tools, including get_campaigns and others, the description does not specify context or exclusions, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already declares the tool as read-only. The description adds that it lists or fetches tags, but does not disclose additional behaviors like error handling or performance. This is adequate given the annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose. Every word is necessary and no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list/fetch tool with full schema coverage, annotations, and an output schema, the description covers the essential behavior. No additional details are necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a well-described parameter. The description ('Pass tag_ids to fetch specific tags') largely mirrors the schema description and adds minimal new meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List UET tags' with a specific verb and resource, and distinguishes between listing all tags and fetching specific ones via tag_ids. This is distinct from sibling tools like update_uet_tag or other get_* tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing all or specific UET tags. While it does not explicitly mention when not to use it or provide alternatives, the context is clear and no other sibling tool serves the same purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true. Description adds significant behavioral detail: walks inheritance chain (keyword > ad > ad group > campaign > account), returns null for inherited values, includes source fields and msclkid_auto_tagging_enabled. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is efficiently structured, front-loaded with purpose and inheritance explanation. Slightly long but every sentence adds value. Could be more concise but not overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given annotations, schema, and output schema, the description fully covers tool behavior: inheritance logic, source tracking, and additional field. No missing context for an agent to correctly invoke and interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for both parameters. Description does not add further parameter-level meaning beyond what schema already provides, meeting the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool resolves effective URL tracking settings (tracking template, suffix, custom parameters) and identifies which level set each. It explicitly distinguishes from sibling tools like get_account_url_options by explaining it returns effective values with source, avoiding manual cross-referencing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states use case: 'answer what tracking template actually applies here, and where is it set?' before activating a campaign. Also explains it avoids manual cross-referencing across per-entity reads. Does not explicitly state when not to use, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already include readOnlyHint=true, and the description adds useful behavioral context by detailing the submission, polling, downloading, and parsing steps. It does not contradict annotations and provides insight into the end-to-end process.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences front-load the purpose and then explain the difference from a raw submit. Every sentence adds value without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 optional parameters, output schema exists), the description covers the core workflow but omits potential edge cases like timeouts or error handling. However, the output schema provides return type information, making the description reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the baseline is 3. The description does not mention any parameters or add meaning beyond the schema, so it neither improves nor degrades the semantic understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs a performance report end-to-end and returns parsed rows. It uses a specific verb (run) and resource (performance report), and distinguishes itself from a raw submit by explaining the workflow. This uniqueness is maintained among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear contrast with a 'raw submit' (indicating when to use this tool for convenience), but does not explicitly list alternatives or when not to use it. However, the context is sufficient for the agent to understand its primary use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, and description adds that OAuth credential remains unchanged and only scopes are rescoped. Clearly explains a mutation behavior without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with front-loaded main action. No wasted words; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With output schema present and low complexity (2 params, no nesting), description covers the core purpose, pre- and post-steps. Minor gap: no mention of error states.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters documented. Description adds the context of switching accounts, but does not provide additional nuance beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Switch' and the resource 'account', specifying it affects subsequent tool calls and is session-only. This distinguishes it from siblings like search_accounts and account_health.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to use search_accounts to find IDs and to confirm with account_health before writes. Provides clear workflow context, though no explicit alternatives are 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?
Annotations already indicate readOnlyHint=false, and the description adds that 'Only the fields you pass change,' which clarifies partial update behavior beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, no unnecessary words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the full schema coverage and output schema presence, the description is adequate. It covers the main intent and use cases, though it could mention return values or error handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description does not add meaning beyond the schema, meeting the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it updates an existing Responsive Search Ad, with specific verb 'update' and resource 'Responsive Search Ad'. It distinguishes from siblings like create_responsive_search_ad and delete_ad by implying modification in place.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit use cases are given: 'repoint a Final URL or refresh copy without recreating the ad.' While it doesn't explicitly list when not to use, the context and sibling tools imply alternatives.
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 provide openWorldHint (true). The description adds that the tool saves a refresh token, indicating state change. This adds value beyond annotations but does not detail other behaviors like side effects or persistence.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, perfectly front-loaded with the core action. No superfluous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists (not shown but indicated in context signals), the description does not need to explain return values. It fully covers the required context for an auth completion tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of the parameter, but the description adds crucial context: the URL comes from the browser after completing get_auth_url. This goes beyond the schema's description of 'the full URL the browser landed on.'
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: finish sign-in by exchanging a redirect URL for a refresh token. It uses a specific verb+resource and distinctly differs from all sibling tools (e.g., get_auth_url).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to call this after get_auth_url and with the URL the user pastes back, providing clear context and sequencing. No explicit when-not-to-use, but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description aligns with the readOnlyHint annotation, confirming it is a read-only operation. It adds the detail that it lists 'every' account, implying completeness. No contradictions, though additional context like pagination or error handling is absent but acceptable given the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence of 10 words, front-loading the key action and resource. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no parameters and an output schema available, the description sufficiently conveys the list operation and scope. No additional context is necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so per guidelines the baseline is 4. The description does not need to add parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List', the resource 'Microsoft Advertising accounts', and specifies the scope 'reachable by the authenticated user'. It distinguishes itself from sibling tools like set_active_account which deals with account selection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
While the purpose is clear, there is no explicit guidance on when to use this tool versus alternatives (e.g., get_campaigns for campaign-level data). The description implies use for discovering accounts, but doesn't provide when-not-to-use or alternative scenarios.
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?
Annotations already declare readOnlyHint=true. The description adds rich behavioral context: it explains the meaning of exclude_from_bidding and its relationship to bidding, lists other fields, and confirms the read-only nature. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is detailed but efficient, front-loading the main purpose. Each sentence adds value: first states purpose, then explains key field, lists other fields, and gives usage advice. It is well-structured and not overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists, the description doesn't need to detail return values. It provides key field explanations and a usage warning, making it complete for a simple, read-only tool with one optional parameter. The context signals indicate low complexity, and the description covers all necessary aspects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter (goal_ids), with a clear description. The tool's description adds 'Pass goal_ids to fetch specific goals,' which is similar to the schema description. It does not add significant extra meaning beyond what the schema already provides, so the score is at baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists conversion goals, with the verb 'List' and resource 'conversion goals'. It specifies all types and the option to fetch specific ones via goal_ids. This distinguishes it from sibling tools like create_conversion_goal and update_conversion_goal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description tells the agent when to use the tool (list goals) and provides a specific guideline: confirm exclude_from_bidding is false before relying on a goal to drive spend, and points to update_conversion_goal as the sibling to flip it. It could be more explicit about when not to use it, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. The description adds behavioral context beyond that: it details what each idea reports ('avg_monthly_searches', 'suggested_bid', 'competition bucket') and explains the expand_ideas behavior ('Expand beyond the seeds to related keywords'). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three sentences covering purpose, output details, and a key constraint. It is front-loaded with the purpose. Minor improvement could be more structured formatting, but it earns its sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 7 parameters, full schema coverage, annotations, and an output schema (not shown but indicated), the description provides sufficient context: purpose, return fields, input requirements, and behavioral notes (expand_ideas). No gaps for the intended use case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds value by stating the constraint 'Provide at least one of `keywords` or `url`' and clarifies that when 'expand_ideas' is False, 'keywords' is required. This aids correct parameter selection beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Discover keyword ideas from seed phrases and/or a landing-page URL (Keyword Planner).' It specifies the verb (discover) and resource (keyword ideas via Keyword Planner), and distinguishes it from sibling tools like 'get_keywords' which retrieve existing 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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states a key usage constraint: 'Provide at least one of `keywords` or `url`.' While it does not explicitly list when to use or avoid this tool versus siblings, the context from sibling names (e.g., 'get_keywords', 'estimate_keyword_bids') implies this is for discovery, not retrieval or estimation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, consistent with a listing operation. The description adds transparency about merging scopes, deduplication, and default behavior, which is beyond what annotations provide. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two well-structured paragraphs. The first paragraph states the core purpose, and the second provides necessary behavioral details. Every sentence adds value without repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, annotations are present, and parameters are fully described, the description covers all needed context: default behavior, filtering options, and a practical tip about scoping. It is complete for a listing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds valuable context beyond the schema: it explains why the default association_type merges all scopes and why Account alone may look empty. This enriches understanding beyond parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists ad extensions with examples of types (call, callout, sitelink) and explains the default merging behavior, making the purpose specific and distinguishable from sibling tools like get_campaigns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the default (all scopes merged) and when to narrow with association_type, and warns that scoping to Account alone often looks empty. It does not explicitly mention alternative tools but provides clear context for effective usage.
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?
Explains bid_adjustment range (-100 to 900) and meaning of empty list, plus clarifies Microsoft's terminology for mobile. These details add value beyond the readOnlyHint annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, front-loaded with the core action, no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple read operation, existing output schema, and annotations, the description fully covers expected behavior, output interpretation, and cross-references the write counterpart.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with description 'The campaign id.' The tool description does not add extra semantic meaning beyond the schema, which is adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it reads device bid adjustments for a campaign, lists specific devices (Computers, Smartphones, Tablets), and distinguishes from the sibling set_device_bid_adjustment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly mentions the sibling tool for setting adjustments, guiding when to use this read tool. However, no explicit when-not scenarios, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses return values including possible enum options and mentions legacy behavior (deprecated value). This adds significant context beyond the readOnlyHint annotation. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences front-loaded with the core purpose, followed by essential return detail and note on legacy. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 param, read-only), with an output schema presumably detailing the return, the description fully explains what the tool does and what it returns. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with campaign_id described. The description does not add extra parameter-level details beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads a campaign's location-intent setting, specifies the returned values (intent_option with possible options), and distinguishes it from the sibling tool set_location_intent which writes the same setting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly informs when to use the tool (to check location-intent setting) but does not explicitly contrast with alternatives like get_location_targets, which returns broader location targeting details. However, the context shows siblings include that tool, and the description's clarity on what this tool returns helps differentiate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. Description adds context about the nature of exclusions (negative sites) and their effect, enhancing transparency without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first defines purpose, second adds context and sibling tools. No wasted words, front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Simple tool with one parameter and output schema exist. Description fully covers purpose, usage context, and relationship to siblings, leaving no gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage for the single parameter campaign_id, so baseline is 3. Description does not add additional parameter meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'List' and resource 'website / mobile-app-id exclusions (negative sites) blocked on a campaign', distinguishing it from sibling tools add/remove_website_exclusions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly explains that exclusions prevent ads from serving and directs users to add_website_exclusions/remove_website_exclusions for modifications, providing clear when-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?
Beyond annotations (readOnlyHint=false), the description details the read-modify-write mechanism, ensuring other exclusions are retained, and clarifies removal by URL (case-insensitive) rather than ID. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, no redundant words. Each sentence adds value: purpose, behavior, and usage hint. Front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given simple parameters and existence of output schema, the description fully covers usage, behavior, and prerequisites. Complete for this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already covers both parameters with descriptions. The description adds minor context (URL matching, case-insensitivity) but does not significantly improve understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'unblock' and resource 'previously excluded websites/app ids on a campaign'. Differences from sibling tools like get_website_exclusions and add_website_exclusions are implied by naming and explicit mention of removal by URL.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description advises to 'List the current exclusions first with get_website_exclusions' and explains the read-modify-write behavior. It implicitly provides context but does not explicitly state when not to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool fetches the current extension when a parameter is omitted, enabling safe partial updates. This adds behavioral insight beyond the readOnlyHint annotation (false), which only indicates write 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with purpose and followed by necessary behavioral context. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (update with partial support), the description covers all essential aspects: purpose, behavior, parameter handling, and safety. Output schema exists, so return details are not needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, parameters are well-documented. The description adds value by clarifying that 'header' and 'values' are always required conceptually but omitting them is safe due to automatic fetching.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates an existing structured snippet extension with verb 'update' and specific resources 'header or values'. It is distinguished from sibling tools like 'add_structured_snippet_extension' and 'delete_ad_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/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the update behavior (Microsoft replaces whole snippet) and how the tool safely handles partial updates by fetching current values. This guides correct invocation but does not explicitly contrast with alternatives.
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?
Describes key behaviors beyond annotations: goals created active, paused goal silently fails, cannot be deleted, and the relationship between offline conversion goals and apply_offline_conversions. Annotations only indicate not read-only, so description adds significant context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three paragraphs, front-loaded with key behavior. Efficient but slightly longer than absolutely necessary; still clear and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given high complexity (23 parameters, output schema exists), the description covers creation behavior, deletion constraint, status override, and relationship to offline conversions. Complete enough for correct agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 65%, which is moderate-high. The description does not elaborate on parameter semantics beyond what the schema provides. It adds context for some parameters indirectly (e.g., name for offline conversion), but overall parameter meaning is adequately covered by the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a conversion goal, with specific verb 'Create'. It distinguishes itself from sibling tools like update_conversion_goal and apply_offline_conversions by explaining the offline conversion workflow and deletion constraints.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance on when to use: create conversion goals, with notes on status override, deletion impossibility, and the specific path for offline conversion goals using apply_offline_conversions. Clearly differentiates from alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotation indicating a write operation, the description details the selective update behavior ('Only the fields you pass change'), explains the critical exclude_from_bidding parameter's effect on bidding and reporting, and notes that revenue fields are merged. This adds significant value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with no extraneous information. It front-loads the core purpose, then provides focused details on the most important parameter. Every sentence contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 9 parameters and an output schema (not shown but noted), the description covers essential behavioral aspects and usage context. It could be slightly more complete by mentioning the output format, but the output schema likely handles that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 9 parameters have schema descriptions (100% coverage), so baseline is 3. The description adds extra meaning by highlighting exclude_from_bidding as the 'key bidding lever' and clarifying the merge behavior for revenue fields, raising the score to 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update a conversion goal in place' which specifies the verb (update) and resource (conversion goal). It distinguishes itself from create_conversion_goal and get_conversion_goals, as noted in sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises to 'Read the current values first with get_conversion_goals' before updating, providing clear context on when to use this tool. It also warns about the exclude_from_bidding parameter being the inverse of the UI checkbox, though it doesn't explicitly state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description details returned fields (read_only, environment, auth_state, needs_interactive_auth) and their meanings, including advice to branch on needs_interactive_auth rather than message strings. This adds significant value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the main purpose. It uses a structured format with field names in backticks, making it easy to parse. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters, the presence of an output schema, and annotations, the description fully explains the output fields, their interpretation, and provides actionable guidance for error handling. It is complete for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No input parameters exist. Schema coverage is 100%, so baseline is 4. The description does not need to add parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Validate credentials and report the environment and write mode.' It distinguishes itself from siblings by being the tool to call first for auth checks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs 'Call this first,' indicating when to use it. It also explains how to interpret results, but does not explicitly mention when not to use it or provide 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?
Beyond readOnlyHint annotation, description details return fields (windows with days/times, bid adjustments, time_zone, use_searcher_time_zone) and explains behavior based on use_searcher_time_zone flag. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with verb and resource, no wasted words. Essential information efficiently presented.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description still lists return fields, which adds context. Includes sibling reference for removal. Adequately covers all necessary information for a simple read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter (campaign_id) with schema coverage 100%; description does not add additional semantic meaning beyond what the schema provides. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Read a campaign's ad-schedule windows' with specific verb 'Read' and resource. Distinguishes from siblings (add/remove/replace) by implying read-only nature and explicitly mentioning removal tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly names 'remove_ad_schedules' as the tool for removal, providing direct guidance on when to use sibling tool. Context implies use for viewing dayparting settings.
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?
Annotations already indicate readOnlyHint=true and openWorldHint=true. The description adds valuable context: the URL targets an identity provider, the flow includes a code= parameter, and the token is persisted and auto-refreshed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is 5 sentences, well-structured: summary, details of the OAuth flow, and usage context. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters, existing annotations, and an output schema, the description fully covers purpose, step-by-step workflow, and when it is needed. It is complete for its context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters (100% coverage). The description does not need to add parameter details, and it appropriately focuses on the tool's purpose and usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool returns an OAuth sign-in URL and distinguishes it from the sibling tool 'complete_auth', which is called afterward.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'Only needed once, when no refresh token is configured' and advises to call 'complete_auth' after. It does not explicitly state when not to use, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so no contradiction. The description adds behavioral details: it provides a min..max bracket at the supplied max_cpc and match type, and mentions the output fields (clicks, impressions, cost, position). This adds value beyond the readonly hint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two paragraphs. The first sentence front-loads the core purpose, and the second paragraph provides usage guidance. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (6 parameters, 2 required), the presence of an output schema, and the annotations, the description provides sufficient context. It covers purpose, usage, and behavioral details, making it complete for an AI agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all parameters are described in the schema. The description adds context about the bracket nature and the bid input, which helps understanding. However, it does not add detailed semantics beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'estimate' and the resource 'keyword traffic', listing the specific metrics (clicks/impressions/cost/position). It also distinguishes itself from the sibling tool 'estimate_keyword_bids', providing differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool (to gauge search volume and likely spend before launching) and when not (when you want traffic at a bid you choose rather than first-page suggested bid). It names the alternative tool 'estimate_keyword_bids' and explains the difference.
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?
Discloses destructive nature and partial failure scenarios (removal succeeds but addition fails), beyond the minimal readOnlyHint annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two succinct sentences front-loading purpose, followed by well-structured explanation of necessity and behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers rationale, prerequisites, parameter origin, failure modes, and safe behavior; adequate given output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers parameters fully; description adds only procedural context (e.g., 'criterion_id from get_ad_schedules') but not new parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it replaces an ad-schedule window by removing old and adding new, distinguishing from add/remove sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly explains when to use (no in-place edit possible), how to get criterion_id, and the safe sequence with failure outcomes.
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?
Description discloses critical behaviors: Microsoft replaces the whole sitelink, the tool fetches current extension for partial updates, and the requirement that description1 and description2 must be provided together. This adds context beyond the readOnlyHint=false annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise with two paragraphs. First sentence states purpose, second provides behavioral details. No wasted words, front-loaded key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool complexity (mutation, 5 params, output schema exists), the description covers the safe partial update mechanism and important Microsoft constraints. Could mention error handling or prerequisites, but overall complete enough for agent selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage with clear 'omit to keep current' descriptions. The description adds important constraints: display text and final URL are always required (though optional in schema due to fetch) and description pair requirement. This enriches understanding beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an existing sitelink extension in place', specifying the verb (update), resource (sitelink extension), and scope. It distinguishes from siblings like add_sitelink_extension by implying this is for modifying existing ones.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the safe partial update behavior due to fetching, but does not explicitly contrast with add_sitelink_extension. It gives context for using this tool vs alternatives, though a clearer when-to-use statement would improve it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation (false), the description details additive behavior, granularity of minutes (0/15/30/45), time zone handling, the no-overlap rejection with ok=false partial error, and the need for ordered operations. This fully informs the agent of all 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into two logical paragraphs: first about schedule semantics and time, second about constraints and workaround. Each sentence adds value without redundancy. Slightly verbose but acceptable for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (additive windows, constraints, error behavior, and interaction with three sibling tools), the description covers all necessary aspects: granularity, time zone, duplicate prevention, overlap handling, error response format, and alternative workflows. Output schema is not provided but the description mentions the return format (ok=false). This is complete for an AI agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage, so baseline is 3. The description adds meaning by explaining the additive nature of schedules, the 15-minute granularity, and the time zone fallback logic. It also provides practical context like reading existing windows and overlapping rules, which the schema alone does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Add ad-schedule (dayparting) windows' with a specific verb and resource. It distinguishes from siblings like remove_ad_schedules and replace_ad_schedule by naming them in the context of handling duplicates and changes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises reading existing windows first with get_ad_schedules to avoid duplicates, explains the no-overlap rule, and provides step-by-step instructions for modifications: remove first then add, or use replace_ad_schedule. This gives 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?
Beyond the readOnlyHint: false annotation, the description provides rich behavioral details: read-modify-write semantics, URL stripping, exclusion of Microsoft sites, cap of ~2500 sites, and partial error returns. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, each adding distinct information. Front-loaded with purpose, then additive behavior, then formatting details, then constraints/error handling. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 2 simple parameters and an output schema (present but not shown), the description covers behavior, constraints, error handling, and sibling tool for reading. It is self-contained and leaves no major gaps for a typical use case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with basic descriptions, but the description adds significant value by specifying formats (bare domains, paths, mobile-app ids) and that leading http(s):// is stripped. This helps the agent format inputs correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'block' and the resource 'websites/mobile-app ids on a campaign'. Distinguishes from sibling tools by mentioning additive nature and referencing get_website_exclusions for viewing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states the additive behavior (never clobbers), constraints (Microsoft sites cannot be excluded, 2500-site cap), and error handling (partial_errors). Mentions viewing with get_website_exclusions but does not explicitly compare to remove_website_exclusions or state when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotation (readOnlyHint: false), the description reveals key behaviors: device criterion set creation on first use, Microsoft terminology mapping, and the effect of bid_adjustment values (e.g., -100 excludes the device). This adds significant context for safe usage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (3 short sentences plus a recommendation) and front-loaded. Every sentence adds essential information without redundancy. It is well-structured, starting with the primary action, then terminology, then behavioral nuance, and finally a usage tip.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists (not shown), the description adequately covers core behavioral aspects and parameter details. It lacks mention of error conditions or prerequisites (e.g., campaign existence), but these are minor omissions. Overall, it provides sufficient context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers 100% of parameters, so baseline is 3. The description adds value by explaining device aliases (mobile -> Smartphones, etc.) and the set creation behavior, which is not in the schema. This enhances understanding beyond the schema's field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence clearly states the tool's purpose: 'Set a campaign's bid adjustment for one device.' It differentiates from the sibling tool get_device_bid_adjustments by specifying it is a write operation. The description also clarifies Microsoft-specific terminology, leaving no ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises to read current values first with get_device_bid_adjustments and explains the set creation behavior (first use creates other devices at neutral 0). This provides clear guidance on when and how to use the tool, including a critical prerequisite.
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?
Annotations indicate mutation (readOnlyHint=false), and the description expands on behavioral aspects: returns partial_errors, no ids, requires post-creation wait, and details the record attribution logic. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise paragraphs with no fluff; first sentence captures purpose, then details usage and constraints. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 1 parameter (array), 100% schema coverage, output schema (partial_errors), and thorough description covering purpose, usage, timing, error handling, and parameter details, the tool is fully specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. The description adds significant meaning beyond schema: explains click_id as MSCLKID, conversion_name must match goal, conversion_time as ISO-8601, and value/currency_code relationship.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool imports offline conversions against an OfflineConversion goal keyed by MSCLKID, and distinguishes it from siblings by specifying its use for bid-eligible phone call conversions, referencing create_conversion_goal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use (after creating a goal, for qualifying calls) and when not to (wait ~2 hours before uploading to avoid rejection), and notes the alternative of creating a goal first.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains the internal logic: looks up Keyword Planner first-page bid estimate, compares it to effective bid, and lists under-bid keywords with details. This adds significant value beyond the readOnlyHint annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured, starting with the core purpose, then explaining the algorithm and output. Every sentence adds value without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description adequately covers the purpose, usage, and behavioral details. It mentions the result structure (under-bid keywords with fields and counts), making it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. However, the description adds context on how parameters like campaign_id are used (to read the ad group's default bid), which goes beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Flag keywords whose bid is below the estimated first-page bid.' It is specific and distinguishes from sibling tools by focusing on a unique diagnostic action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage guidance is provided: 'Use it when diagnosing low impressions, or before activating a campaign, to find keywords that won't reach the first page at their current bid.' This clearly indicates when 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description aligns with readOnlyHint=true by starting with 'Read.' It adds behavioral context beyond annotations, explaining that per-entity values typically inherit from account level and that msclkid_auto_tagging_enabled appends the Microsoft Click ID. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise yet comprehensive, front-loading the main purpose and then detailing components and usage guidance. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters, an output schema exists, and annotations are clear, the description fully explains what the tool returns (tracking template, final URL suffix, msclkid auto-tagging, parallel tracking) and why it matters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so the description cannot add parameter-level meaning. Baseline for 0 parameters is 4, and the description provides no parameter info, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads account-level URL tracking settings, listing specific components (tracking template, final URL suffix, msclkid auto-tagging, parallel tracking). It distinguishes from sibling tools like get_effective_url_settings and set_account_url_options by name and purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool: to answer 'where is the tracking template set?' and to confirm tracking configuration before activating paused campaigns. It also provides exclusions and alternatives: for resolved values, use get_effective_url_settings; to change, use set_account_url_options.
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?
Annotations indicate readOnlyHint=false (mutation). The description adds that changes are account-wide and inherited, only touched fields are modified, and suggests a workflow to read before writing. This goes beyond basic mutation 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences: first defines purpose and scope, second explains use case with alternatives, third clarifies partial update, fourth advises workflow. No wasted words; each sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 optional parameters, 100% schema coverage, and an output schema (not shown but present), the description covers purpose, usage, behavior, and workflow. It is complete for an agent to understand and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 4 parameters with 100% description, including defaults and clearing behavior. The description groups parameters (tracking template, Final URL suffix, msclkid, parallel tracking) and adds context that only passed fields change, complementing the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'sets account-level URL options/tracking template' and specifies it applies 'account-wide; every campaign inherits them.' It contrasts with editing individual campaigns/ad groups, distinguishing it from sibling tools like get_account_url_options and get_effective_url_settings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises reading current values first with get_account_url_options and using get_effective_url_settings to confirm. States 'the cleanest way' to apply settings across the whole account instead of per-campaign/ad/keyword, and clarifies that only passed fields change.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint=false annotation, the description details the replacement behavior and the fetch mechanism for omitted fields, giving full transparency on the tool's actions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences that cover purpose, behavioral implications, and safe usage with no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 100% schema coverage, annotations, and an output schema, the description completes the picture by focusing on the key nuance (whole replacement) that is not obvious from structured data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds critical context beyond the schema, clarifying that country_code and phone_number are required in the API even though the schema allows null defaults, and explains the behavior when omitted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Update an existing call extension' with specific examples (brand's phone number or tracking), differentiating from sibling tools like add_call_extension and delete_ad_extension.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly explains that Microsoft replaces the whole extension and that phone number and country code are always required, while also providing the safe toggle behavior for partial updates via fetching current values.
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:

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

Score Badge

Copy to your README.md:

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

Latest Blog Posts

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

MCP directory API

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

curl -X GET 'https://glama.ai/api/mcp/v1/servers/shinypebble/microsoft-ads-mcp'

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