Apple Ads MCP

Server Quality Checklist

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

Latest release: v1.0.1
Disambiguation5/5
Each tool targets a distinct resource and action, with clear prefixes like adgroups_, campaigns_, targeting_keywords_, etc., so there is no ambiguity between tools.
Naming Consistency5/5
All tool names follow a consistent snake_case verb_noun pattern (e.g., adgroups_create, campaigns_list, custom_reports_create), with very few deviations like delete_single, which is still clear.
Tool Count4/5
With 74 tools, the count is high but appropriate for the comprehensive Apple Search Ads API covering many resources and operations. Each tool serves a specific purpose, though the number exceeds typical well-scoped servers.
Completeness5/5
The tool set covers all major workflows: CRUD for campaigns, ad groups, ads, keywords, negatives, creatives, budget orders; reporting; app and geo search; org management. The escape hatch handles any missing endpoints, ensuring no dead ends.
Average 3.2/5 across 74 of 74 tools scored. Lowest: 2/5.
See the Tool Scores section below for per-tool breakdowns.
- 0 of 1 community issues answered or closed in the last 6 months
- 0 commits in the last 12 weeks
- Last stable release on May 3, 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.
This repository includes a glama.json configuration file.
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.
View related servers

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?
With no annotations provided, the description carries the full burden of disclosing behavior. It states 'Delete' but does not elaborate on side effects, irreversibility, permission requirements, or cascading effects on related entities like keywords or creatives.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
While the description is extremely short, it is not effectively concise because it fails to convey any valuable information beyond the tool name. It sacrifices substance for brevity, resulting in a low-value statement.
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?
Given the simplicity of the tool (delete a resource by two required IDs) and the absence of an output schema, the description is insufficient. It does not explain the required parameters, the optional override, the response behavior (e.g., success indication), or any prerequisites like having an active campaign.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has only 33% field descriptions (only orgId has a description via the schema). The tool description adds no parameter-level information, leaving campaignId and adGroupId completely unexplained when their types and purposes are critical for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete an ad group' is a tautology that merely restates the tool name. It does not provide additional context about the specific operation or distinguish it from sibling tools like adgroups_update or adgroups_get.
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 given on when to use this tool versus alternatives. For example, it does not mention that this deletes a specific ad group within a campaign, nor does it advise against using it without proper authorization or understanding of 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?
The description implies a destructive action but does not disclose any side effects, irreversibility, or required permissions. With no annotations to compensate, the description is insufficient.
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 (3 words) but lacks structure or front-loading of critical information. It is concise but at the expense of informativeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 4 parameters (3 required), no output schema, and no annotations, the description is drastically insufficient. It fails to explain return values, side effects, or how the request is processed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 25% (only orgId has a description). The description adds no explanation for campaignId, adGroupId, or adId, leaving the agent without semantic context for these required parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete an ad' clearly states the verb and resource, distinguishing it from other ad operations like create or update. However, it lacks detail on how the ad is identified (requires campaignId, adGroupId, adId), which is provided only in the schema.
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 'ads_delete' is redundant but siblings like 'ads_update' or 'ads_create' exist. No context on prerequisites or 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only indicates pagination via the parenthetical 'paginated,' but does not discuss sorting, default pages, or whether it is read-only. Key traits like potential large result sets or empty results are omitted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single phrase, 'List campaign-level negative keywords (paginated).' While concise, it is too minimal to provide value. It lacks complete sentences and structure, and could be expanded to include key details without verbosity.
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?
Given no output schema, the description should at minimum hint at the structure of returned items or mention common fields. It also does not clarify default pagination values, error handling, or that it lists all negative keywords for a given campaign. The context of sibling tools and required parameters suggests more information is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds 'paginated' implying use of limit/offset, but the input schema already documents three of four parameters. The campaignId parameter lacks a description in both schema and tool description. The description provides little additional 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 tool lists campaign-level negative keywords and mentions pagination. It distinguishes from sibling tools that create, delete, or update negative keywords, and the name clarifies the campaign level versus adgroup level.
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 campaign_negative_keywords_find or adgroup_negative_keywords_list. The description does not mention any context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It only states the action without disclosing behavioral traits such as read-only nature, required permissions, or any 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (6 words), but this brevity sacrifices necessary detail. It is appropriately structured but incomplete.
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?
Given no output schema or annotations, the description fails to provide a complete picture. It omits required parameter context, return value, and proper usage conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only 1 of 4 parameters (orgId) has a description in the schema, and the description adds no parameter details. The phrase 'by ID' is ambiguous about which parameter is the ID.
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 ('Fetch') and resource ('single ad') and implies identification by ID. However, it does not mention that three IDs (campaignId, adGroupId, adId) are required, which could lead to confusion with other ads tools.
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 siblings like ads_find_in_campaign or ads_list. The agent is given no context for choosing this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It does not mention that this is a read-only operation, that pagination or filtering is supported, or what data is returned. The description is too brief to inform the agent about important behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (one sentence) but lacks essential details. It could be longer to include usage context and behavioral notes. It is not overly verbose, but it sacrifices completeness.
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?
Given the complexity of the tool (12 parameters, nested objects, no output schema), the description is insufficient. It does not explain the purpose of the report, how to interpret results, or any limitations. The agent would need to rely solely on the schema and context signals.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 58% schema coverage, the description adds no additional meaning beyond what is in the input schema. The parameter descriptions in the schema already explain usage, but the tool description does not highlight any critical parameters or constraints, leaving the agent to infer from the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states it is a 'search-terms report scoped to a single ad group', which clearly identifies the resource and scope. It distinguishes from sibling tools like 'reports_search_terms_in_campaign' but lacks an explicit verb (e.g., 'get' or 'list'), slightly reducing clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/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. It does not mention when not to use it or reference related tools like 'reports_search_terms_in_campaign' or 'reports_keywords_in_adgroup'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations available, the description carries full burden for behavioral disclosure. It only states the action without detailing side effects, authorization requirements, idempotency, or what happens on duplicate entries. For a creation tool, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (one sentence) and front-loaded with the key action. However, it may be overly brief, lacking necessary detail. Every sentence earns its place, but some context is missing.
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?
Given no output schema, no annotations, and low schema coverage, the description is incomplete. It does not explain return values, error handling, rate limits, or any prerequisites. It fails to provide agents with enough context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (25%: only orgId described). The description adds no additional meaning to parameters beyond the schema. It does not explain the role of campaignId, adGroupId, or the keywords array structure, leaving ambiguity.
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 (bulk-create) and the resource (negative keywords on an ad group). It distinguishes from sibling tools like delete, get, list, and update. However, it could be more specific about the scope (ad group level) and what 'bulk' entails.
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., campaign_negative_keywords_create for campaign-level, or targeting_keywords_create). The description does not mention prerequisites, limitations, or scenarios where this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the full burden. It states 'Fetch', implying read-only, but omits details about authentication, rate limits, or any side effects. The list of fields includes 'etc.', indicating incompleteness.
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?
One sentence, directly states purpose and examples. Efficient, though the trailing 'etc.' adds vagueness. Could be slightly more structured but overall 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?
No output schema, so the description should fully describe return values. It lists several fields but includes 'etc.', leaving incompleteness. For a simple fetch tool, it's marginally adequate, but lacks error handling or edge case context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not mention the parameters (adamId and orgId) at all. With only 50% schema description coverage, the description should compensate but fails to clarify what these parameters are or how to use them.
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?
Clearly states the action 'Fetch' and the resource 'App Store metadata for an app'. Lists example fields to specify what metadata is returned. However, it doesn't explicitly differentiate from sibling tools like apps_assets_find or apps_locale_details, leaving some ambiguity.
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. There are many sibling tools with similar purposes (e.g., apps_assets_find, apps_locale_details), but the description provides no context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavioral traits. It merely states 'Bulk-update' without explaining if it merges, replaces, or idempotently updates by id. It omits permission requirements, error handling, and side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler, achieving conciseness. However, it is perhaps too terse, omitting important details that could be included without losing brevity.
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?
Given the tool performs a bulk update with nested objects and no output schema, the description lacks completeness. It does not explain update semantics (merge vs replace), response format, or error scenarios, leaving an agent under-informed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 3 parameters, but only orgId has a description. The description does not elaborate on the meaning of campaignId or the keywords array structure (e.g., that 'id' is required for updating). Schema coverage is low at 33%, and the description adds no compensatory context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('update') and resource ('campaign-level negative keywords'), and the context of sibling tools (e.g., campaign_negative_keywords_create, delete, get) clearly distinguishes this tool for updating. However, it lacks nuance on whether the update is additive or replaces 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 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 campaign_negative_keywords_create or delete. There is no mention of prerequisites (e.g., campaign existence) or context for when this update is appropriate over other keyword operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits beyond the fact that it creates a resource. For example, it does not mention mutability, idempotency, required permissions, error conditions, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences, front-loading the key action and definition. However, it could be more structured with a summary of parameters or usage.
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?
Given the complexity of 6 parameters (including nested objects and conditional fields) and no output schema, the description falls short. It does not explain return values, error handling, or how parameters like 'type' affect behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 33% of parameters with descriptions (productPageId and orgId). The description adds no additional parameter-level details beyond the general statement about creatives. It does not clarify the role of name, adamId, type, or extra.
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 creates a creative and defines it as a reference to a default product page, custom product page, or creative set. It also explains that ads bind to creatives via creativeId, which distinguishes it from sibling tools like creatives_find or creatives_get.
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, such as when to create a creative versus using existing ones. It lacks contextual cues like 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.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description carries the full burden of behavioral disclosure. It fails to mention that the tool is read-only, required permissions, rate limits, or any side effects. The description is entirely silent on 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 a single, front-loaded sentence with no fluff. It is concise and to the point, though it could be expanded slightly to include more useful context without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (12 parameters, nested objects, no output schema), the description is severely incomplete. It does not explain the output format, required parameters, or how to use the selector. An agent cannot fully understand the tool's behavior or prerequisites from this description alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 58% schema description coverage, the baseline is 3, but the description adds no additional meaning beyond the schema. Parameters like campaignId, adGroupId, and endTime lack description in both schema and description. The description does not explain the report output or how parameters affect results.
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 is a keyword report scoped to a single ad group, which is a specific verb+resource combination. It distinguishes from sibling tools like reports_keywords_in_campaign (campaign scope) and reports_search_terms_in_adgroup (search terms, not 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 guidance is provided on when to use this tool versus alternatives. It does not mention conditions for use, exclusions, or related tools, leaving the agent without context for proper selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description only implies a destructive operation. It fails to disclose potential side effects, error behavior, permissions needed, or idempotency—all unsupported by either annotations or description.
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, consisting of a single sentence. It is efficiently written but lacks structure (e.g., sections or bullet points) to improve readability.
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 tool with four parameters and no output schema, the description fails to cover important details such as return values, error handling, prerequisites, or relationships to sibling tools. It is incomplete for an agent to use effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 25% schema description coverage and no additional explanation in the description, the meaning of parameters like campaignId and adGroupId remains unclear. The description adds no value beyond the schema's names and types.
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 (bulk-delete) and resource (targeting keywords by ID), distinguishing it from the sibling 'targeting_keywords_delete_single'. However, it omits the required context of campaign and ad group, which may lead to confusion.
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., 'targeting_keywords_delete_single' or other delete tools). No context for scenarios or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description only states 'Fetch', implying a read operation, but does not disclose any behavioral traits like authentication, rate limits, or side effects. It carries full burden due to missing annotations but provides minimal information.
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?
Single short sentence, very concise. However, it could include more detail without becoming verbose; still effective for a simple getter.
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?
Given no output schema and low schema description coverage, the description should provide more context about return values, required structure (campaignId, adGroupId necessary to identify keyword), and relationship to sibling tools. It falls short.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25% (only orgId described). The description adds no parameter meaning beyond the schema, not even linking 'by ID' to the keywordId parameter. It does not explain the role of campaignId and adGroupId.
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 verb 'Fetch' and the resource 'targeting keyword by ID', but does not specify that the ID is the keywordId parameter. It also does not differentiate from sibling tools like 'targeting_keywords_list' or 'targeting_keywords_find'.
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 'targeting_keywords_list' or 'targeting_keywords_find'. The description does not mention prerequisites 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?
No annotations provided. The description 'Fetch' implies read-only, but does not disclose behavior such as what happens if the ad group is not found, authorization requirements, 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise at one sentence, but at the cost of omitting important details. While front-loaded, it lacks completeness for an effective tool description.
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?
Given the simplicity of the tool (3 params, no output schema), the description is insufficient. It does not mention required identifiers or return value, leaving the agent with incomplete context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 33% (only orgId described). The tool description adds no explanation for campaignId or adGroupId, which are required and lack documentation. The description fails to compensate for low 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 'Fetch a single ad group' clearly specifies the action and resource, distinguishing it from sibling tools like adgroups_list (multiple) and adgroups_create (mutation).
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 (e.g., adgroups_find_in_campaign, adgroups_list). The description does not mention prerequisites 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?
No annotations provided, and the description does not disclose behavioral traits such as pagination, permissions, rate limits, or whether it lists all pages or requires additional parameters beyond adamId.
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?
Extremely concise single sentence, front-loaded with action and resource. No wasted words.
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?
Given the simplicity (2 params, no output schema), the description is too sparse. It does not mention return type, pagination, or filtering capabilities. A more complete description would include what the response contains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description adds no parameter-specific meaning beyond the schema. The adamId lacks description in schema, and the tool description does not clarify it. The orgId parameter has a schema description but the tool description repeats 'for an app' without further detail.
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?
Description states 'List Custom Product Pages for an app' which is a clear verb+resource combination. It distinguishes from siblings like cpp_get and cpp_locale_details, but could be more specific about scope.
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 like cpp_get or cpp_locale_details. The description lacks explicit context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must convey behavioral traits. It only states 'Find' which implies read-only, but does not explicitly confirm non-destructiveness, discuss permissions, pagination behavior beyond schema, or error conditions. The agent cannot infer safety or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but may be too brief. It front-loads the action and scope, but omits important context. It earns its place but could be expanded slightly to improve completeness 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?
Given the complexity of nested parameters, multiple sibling find tools, and lack of output schema, the description is incomplete. It does not clarify how the selector works at a high level, what 'across the org' entails, or how it differs from other find tools. The agent cannot fully understand the tool's role.
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% (both parameters have descriptions), so the tool description does not need to add much. It adds no further semantics beyond the schema. The selector object's description in the schema covers its role adequately.
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 ('Find'), the resource ('creatives'), and the scope ('across the org'). It distinguishes from list tools by mentioning a selector, but does not explicitly contrast with other find tools (e.g., adgroups_find_org_wide), though the resource name provides differentiation.
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 creatives_list, creatives_get, or other find tools. The description fails to mention prerequisites, scenarios, or trade-offs, leaving the agent without decision 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?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It only states 'Bulk-update', implying mutation, but fails to mention side effects, authorization needs, rate limits, or behavior on partial failures. This is insufficient for a mutation tool.
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 short and to the point with two sentences. No unnecessary words. However, it could be considered under-specified given the tool's complexity.
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 bulk update tool with four parameters, nested objects, and no output schema, the description is too minimal. It lacks context about error handling, partial success, idempotency, or expected behavior for each field. Sibling tools like 'adgroup_negative_keywords_create' have similar brevity, but this doesn't excuse the gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 25% (only orgId described). The description repeats the schema requirement that each entry must include 'id', adding no new meaning. It does not explain the purpose or constraints of 'text', 'matchType', or 'status', which have enums in the schema but no 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 'Bulk-update' and the resource 'ad-group-level negative keywords', distinguishing it from sibling tools like create, delete, find, get, and list. The resource and action are 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 update vs alternatives (e.g., create or delete). There is no mention of prerequisites, when not to use, or context about batch operations. The description only reiterates the required 'id' field.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description should disclose behavioral traits. It only mentions pagination but omits details on rate limits, authorization requirements, error handling, or side effects, leaving significant gaps for an agent.
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 concisely captures the core functionality and pagination. No unnecessary words or irrelevant details.
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?
Given the tool has 4 parameters, no output schema, and no annotations, the description is too brief. It fails to explain pagination details, return format, or how to handle errors, making it insufficient for complex use cases.
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 75% (3 of 4 parameters have descriptions). The description itself does not add any extra meaning beyond the schema, so it meets the baseline for this coverage level.
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 (List), resource (ad groups), and scope (in a campaign), and mentions pagination. However, it does not differentiate from the sibling tool 'adgroups_find_in_campaign', which likely performs a similar function.
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 'adgroups_find_in_campaign' or 'adgroups_get'. The description does not specify any prerequisites or context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavioral traits. It states 'Update' implying mutation but does not mention side effects, required permissions, idempotency, or error behavior. Lack of disclosure beyond the operation itself.
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 with no waste. However, given the complexity of the schema, a slightly expanded structure (e.g., noting partial update behavior) would be beneficial.
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?
With a complex input schema (nested objects, 4 params) and no output schema, the description is too minimal. It does not explain return values, error conditions, or the partial update behavior beyond a brief hint. Incomplete for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 25% (only orgId has a description). The tool description adds no meaning to individual parameters; the phrase 'Pass only the fields you want to change' is generic. The schema itself has richer descriptions in nested objects, but the tool description does not leverage or summarize them.
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 'Update an ad group' clearly states the verb (update) and resource (ad group). It distinguishes this tool from siblings like create, delete, find, 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?
The description only says 'Pass only the fields you want to change,' which is a usage hint but does not explicitly state when to use this tool versus alternatives like adgroups_create or other update tools. No guidance on when not to use or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description bears full burden. It mentions status is read-only and that no delete endpoint exists, but it does not disclose whether updates are partial or full, auth requirements, or error behaviors.
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 concise sentences front-load the purpose and add relevant notes. No unnecessary words, though the note about no delete endpoint is tangentially useful.
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?
Given the complexity of nested parameters and no output schema, the description is too minimal. It does not explain return values, partial update behavior, or how orgIds interact, leaving the agent with significant ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low (25%), with only orgId having a description. The description adds no parameter-specific details beyond what the schema shows, failing to explain the meaning or constraints of fields like budget or supplySources.
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 'Update a budget order' and adds that most fields are editable while status is read-only, distinguishing it from read-only operations. However, it does not explicitly differentiate from create or list 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 modifying existing budget orders and warns that delete is not available, but it lacks explicit guidance on when to use this tool versus create or other update tools for different entities.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the action (delete) without mentioning implications like irreversibility, required permissions, rate limits, or impact on campaigns. 'Bulk-delete' hints at multiple deletions but adds no further context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the essential action. It is concise and avoids fluff, though it might be too brief given the complexity of the operation. Still, it earns points for efficiency.
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?
Given the complexity (delete operation, 3 parameters, no output schema, no annotations), the description is incomplete. It does not explain return values, error messages, or the effect on related data. The agent lacks information to assess success or handle failures.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema coverage is low (33%, only orgId has a description). The description says 'by ID,' which loosely refers to keywordIds but does not explain the role of campaignId or how keywordIds are used. It fails to compensate for the lack of parameter descriptions in the schema, especially for campaignId and keywordIds.
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 'Bulk-delete campaign-level negative keywords by ID,' which specifies the verb (delete), resource (campaign-level negative keywords), and method (by ID). It distinguishes from sibling tools like adgroup_negative_keywords_delete or targeting_keywords_delete_single by explicitly mentioning 'campaign-level'.
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 campaign_negative_keywords_find or campaign_negative_keywords_update. The description lacks context about prerequisites, workflow, or when not to use it (e.g., if using adgroup-level deletion).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided and description does not disclose behavioral traits such as rate limits, authentication requirements, or side effects. Only states what the tool does.
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?
Very concise single sentence, but lacks context that could be included without losing conciseness. Adequate but minimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Description is grossly incomplete for a complex tool with 11 parameters, nested objects, and no output schema. Does not explain return values, constraints, or how to effectively use the report.
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 high (64%), so baseline is 3. Description adds no additional parameter meaning 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?
Description clearly states it is an ad-group-level report within a single campaign, using specific verb and resource. It differentiates from siblings like reports_campaigns and reports_ads_in_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. Lack of explicit when-to-use or when-not-to-use instructions amidst many sibling report tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description only states it is a 'rolled up' report, failing to disclose behavioral details such as read-only nature, auth requirements, or what happens with empty results.
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?
Single sentence is very concise and immediately understandable, but it omits key information that could be included without much bloat.
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?
Given the tool's complexity (11 parameters, nested objects, no output schema), the description is far too brief. It lacks details on return structure, pagination, filtering, and how to interpret the aggregated data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 64% schema description coverage, the description adds no value beyond the schema. It does not explain important parameters like campaignId, startTime, or the selector object.
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 indicates it provides a keyword report aggregated across all ad groups in a campaign, distinguishing it from per-adgroup or campaign-level reports 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternatives are provided, but the purpose implies it is for campaign-level keyword metrics. Sibling tool names help infer 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?
With no annotations provided, the description carries full burden for behavioral disclosure. It only states 'bulk-delete' and 'by ID', but omits details like whether deletions are reversible, permissions required, or what becomes of associated 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 sentence effectively conveys the core purpose. No redundant words.
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?
Given no output schema and low parameter coverage, the description is incomplete. It lacks information about idempotency, error handling, immediate vs. eventual deletion, or what the response contains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only 25% of parameters have descriptions in the schema (orgId). The description does not add meaning to the parameters beyond what the schema provides. For example, it doesn't explain how keywordIds are used or the format of campaignId/adGroupId.
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 (bulk-delete), resource (ad-group-level negative keywords), and method (by ID). It distinguishes this tool from siblings like create, update, find, and list.
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, such as targeting_keywords_delete or campaign-level delete. No exclusions or context are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It only states that the tool 'finds' with a selector, omitting important details such as whether the operation is read-only, any required permissions, rate limits, or what happens if no matches are found.
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 front-loads the purpose. It avoids unnecessary words, but could benefit from breaking into two sentences or adding structure for readability.
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?
Given the tool's complexity (3 parameters, nested selector object, no output schema) and absence of annotations, the description is too brief. It does not explain return values, pagination behavior, or error conditions, leaving significant gaps for the 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 description coverage is 67% (2 of 3 parameters have descriptions). The tool description does not add meaning beyond the schema; it merely restates the selector concept. The baseline score of 3 is appropriate since the schema already documents most 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 verb 'Find', specifies the resource 'ad-group-level negative keywords', and clarifies the scope 'across all ad groups in a campaign'. It distinguishes from siblings like 'adgroup_negative_keywords_get' (single) and 'adgroup_negative_keywords_list' (likely simpler listing) by mentioning the use of a selector.
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 like 'adgroup_negative_keywords_list' or 'campaign_negative_keywords_find'. It does not specify prerequisites or scenarios where this tool 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?
With no annotations, the description carries the full burden. It only says 'Fetch', indicating a read operation, but provides no details on error behavior, permissions, or response format.
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 a single short sentence, which is concise but too brief for a tool with 4 parameters. It sacrifices clarity for brevity.
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?
Given the lack of output schema, no annotations, and 4 parameters, the description is incomplete. It does not explain parameter relationships, return value, or usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 25% (only orgId described). The description says 'by ID' but does not clarify which parameter is the ID (keywordId). It adds little meaning beyond parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Fetch' and the resource 'single ad-group-level negative keyword by ID', distinguishing it from list or mutation 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?
No explicit when/when-not or alternative tools are mentioned. The description implies use for fetching a specific keyword by ID, but does not guide selection among siblings like find or list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavioral traits. It only mentions pagination, omitting details like default ordering, required permissions, or effects of missing pagination parameters. The minimal detail is insufficient.
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 single sentence is efficient and front-loaded with the verb. It imparts purpose and a key behavioral note (paginated) without wasted words.
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?
Given the lack of an output schema and moderate parameter coverage, the description is incomplete. It does not describe the return format, pagination metadata, or how it differs from 'adgroup_negative_keywords_find', leaving gaps for correct agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While 60% of parameters have schema descriptions, the tool's description adds no extra meaning. It does not explain the crucial 'campaignId' and 'adGroupId' parameters or their relationship, leaving the agent to infer from context.
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 ('List') and resource ('ad-group-level negative keywords') with a key feature ('paginated'). This distinguishes it from sibling tools like 'get' (single) and 'find' (search).
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 'adgroup_negative_keywords_get' for a single result or 'adgroup_negative_keywords_find' for filtered searches. The description lacks context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It only states the action (create) and the binding concept, lacking details on side effects, error handling, rate limits, or auth requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the core purpose. It is front-loaded with the action, though additional structure (e.g., bullets) could improve readability.
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?
Given no output schema and a complex nested input, the description is insufficient. It does not explain what the tool returns (e.g., ad ID) or provide completeness for a creation operation. Required fields and allowed additional properties are unmentioned.
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 description adds meaning for 'creativeId' and 'creativeType' by explaining the creative binding and wrap types. However, schema coverage is low (25%), and other parameters (campaignId, adGroupId, ad.name, ad.status) lack description, leaving gaps.
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 creates an ad and describes its binding to a creative. It distinguishes from sibling tools like ads_delete or ads_update, but does not explicitly differentiate from ads_create's own sibling set.
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 context (creating an ad in an ad group) but provides no guidance on when to avoid this tool, prerequisites, or alternatives. Sibling tools for ad management are present but not referenced.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It only says 'with a selector' but doesn't disclose read-only nature, pagination behavior, rate limits, or any side effects. The schema has pagination details but the description omits them.
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. It is concise but could be more structured; however, for a simple find operation it is sufficiently brief.
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?
Given the complex nested selector and no output schema, the description is too brief. It does not mention that results are paginated, how the org override works, or what the return format is, leaving gaps in 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 coverage is 100% with good descriptions for both parameters (selector and orgId). The description adds no additional meaning beyond what is already in the input schema, so baseline score 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 ('Find'), resource ('ads'), and scope ('across the entire org'), effectively distinguishing it from sibling tools like ads_find_in_campaign which are scoped to a 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?
The description provides no explicit guidance on when to use this tool versus alternatives like ads_find_in_campaign or ads_list. The scope is implied but not directly stated as a selection criterion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description omits behavioral traits like pagination, ordering, or response format; does not explain what 'list all' means in terms of scope or limits.
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?
Single sentence, no redundancy; short and to the point, but could include more detail without sacrificing conciseness.
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?
No output schema, and description does not mention return format, pagination behavior, or edge cases (e.g., empty result). Incomplete for a list endpoint.
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 60%, and the description adds no parameter info. However, campaignId and adGroupId are self-explanatory, and schema descriptions for limit, offset, and orgId are 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?
The description clearly states it lists all ads within an ad group, specifying the resource and scope. It distinguishes from sibling tools like ads_create, ads_get, and ads_delete.
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 over alternatives such as ads_find_in_campaign or ads_find_org_wide; lacks context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description carries full burden but only states 'Fetch', implying a read operation without confirming safety, error handling, 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded and efficient, but could be slightly expanded without losing conciseness (e.g., noting read-only behavior).
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?
Adequate for a simple fetch tool: identifies resource and key ID, but lacks details on return format, error conditions, or orgId usage. No output schema to compensate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 50% (orgId described), and description does not clarify the required budgetOrderId parameter beyond 'by ID', nor the optional orgId's purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Fetch', resource 'budget order', and scope 'single', distinguishing it from sibling tools like budget_orders_list (multiple) and budget_orders_create (mutation).
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 (e.g., list, update). Missing explicit context for selection among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. It only states 'Create a new campaign' and lists minimal fields, failing to describe idempotency, success/error responses, rate limits, or side effects beyond creation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with two sentences. It front-loads the action and provides a quick list of key fields. No wasted words, though it could be slightly more structured with bullet points.
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 18 parameters and no output schema, the description only provides a minimal set of required fields. It omits return value explanation, error handling, or any behavioral context. This is insufficient for a complex creation 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 description coverage is 94%, so the input schema already explains most parameters in detail. The description adds only that the listed fields constitute a 'minimum useful body', offering minimal semantic value 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 explicitly states 'Create a new campaign' with a clear verb and resource. It lists the minimal required fields, distinguishing it from sibling tools like campaigns_list or campaigns_update.
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 vs alternatives, no prerequisites, and no exclusions. The sibling tools are not referenced, leaving the agent without context for choosing this over other campaign-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It mentions pagination but lacks details on ordering, filtering, rate limits, authentication requirements, or that the operation is read-only.
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. It is appropriately concise, though front-loading the scope and pagination could be slightly improved.
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?
Given no output schema, the description should inform about return format or fields. However, it only states pagination, leaving the agent unaware of the response structure. The 3 parameters are all optional, which is fine, but completeness is lacking.
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 'paginated' context, but the schema already documents limit, offset, and orgId adequately. No extra 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?
The description clearly states the action 'List', the resource 'creatives', and the scope 'in the org', with an explicit pagination note. This distinguishes it from sibling tools like 'creatives_find' and 'creatives_get'.
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 'creatives_find' for filtered searches. No exclusions or context for selection are 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?
No annotations provided; description only states what the tool does, not behavioral traits like pagination, authentication needs, or return structure. Lacks depth for safe invocation.
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?
Single sentence, front-loaded with key action and resource, no redundant information. Could expand slightly 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?
No output schema; description fails to mention pagination, response format, or that orgId overrides default org. Insufficient for a 3-parameter list endpoint.
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 100% of parameters with descriptions; description adds no extra meaning beyond 'list all'. Baseline score 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?
Description clearly states verb 'List' and resource 'Impression Share reports', distinguishing it from sibling tools like custom_reports_create (create) and custom_reports_get (get single).
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 exclusions or context provided. Agent must infer usage from sibling tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden but only mentions pagination. It does not disclose rate limits, authentication requirements, effects of missing ad group, or error behavior. The orgId parameter hints at org override but is not explained in the description.
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, front-loaded sentence that communicates the core purpose and a key trait (paginated). Every word is necessary and no extraneous information.
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?
Given no output schema, no annotations, and a moderate number of parameters with incomplete schema coverage, the description lacks details on pagination behavior, ordering, response format, and error scenarios. It is insufficient for an agent to fully understand the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 60% (3 of 5 params have descriptions). The description adds no parameter details beyond the schema. For undocumented params (campaignId, adGroupId), the description provides no clarity, failing to compensate for the schema gap.
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 ('List'), resource ('targeting keywords'), and scope ('on an ad group'), and includes the pagination detail. This distinguishes it clearly from sibling tools that create, delete, find, get, or update 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?
The description provides no guidance on when to use this tool versus other list/find tools, no prerequisites, and no alternative suggestions. The agent is left to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description only says 'update' without disclosing behavioral traits like permissions, idempotency, or return values.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with verb. Efficient but lacks depth.
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?
No output schema and minimal description. Lacks information on return values, partial update behavior, and handling of unspecified fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only 20% schema description coverage. Description adds meaning for 'ad' fields but leaves campaignId, adGroupId, adId, and orgId unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates an ad and lists typical fields (status, name, creativeId). It differentiates from sibling tools like ads_create and ads_delete.
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?
Implies use for updating existing ads, but no explicit guidance on when to use this vs alternatives or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only mentions pagination, but does not specify idempotency, data scope (e.g., read-only), or default pagination behavior beyond what the schema provides.
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?
Very concise single sentence, front-loaded with verb and resource. No wasted words, though could be slightly expanded without losing conciseness.
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?
No output schema, but return format is typical for list endpoints. Description lacks details on response structure or field inclusions. Acceptable but could be more 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 description coverage is 100%, so baseline is 3. The description adds minimal value ('paginated') which is already captured in schema descriptions for limit and offset.
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 budget orders with pagination. It distinguishes from sibling tools like budget_orders_get (single) and budget_orders_create/update.
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 budget_orders_get for individual orders or filtering by other criteria. Usage context is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states it fetches a keyword, but does not disclose if it is read-only, any side effects, authorization requirements, rate limits, or error handling. The agent has no behavioral insight beyond the stated 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 one clear, front-loaded sentence with no extraneous words. It is concise, though it could be slightly more informative without losing brevity (e.g., clarifying the output).
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?
Lacking an output schema and annotations, the description does not explain what the tool returns, error conditions, or how it fits with sibling tools. The parameter documentation is minimal, leaving the agent with significant unknowns for a precise fetch operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% (orgId has a description; campaignId and keywordId have none). The description does not add any parameter details beyond the obvious. With three parameters and little schema documentation, the description should have elaborated on the IDs or usage, but it does not.
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 ('Fetch'), the resource ('a single campaign-level negative keyword'), and the identifier ('by ID'). It distinguishes this from sibling tools like list, create, delete, update, and find, which operate on collections or have different behaviors.
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 is implied: use this tool when you have a specific keywordId for a campaign. However, no explicit guidance is given on when not to use it or alternatives (e.g., list or find) are not mentioned. The description lacks context for distinguishing from sibling 'get' or 'find' tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the read-only nature ('Fetch') but lacks additional behavioral details such as error handling, response structure, or any side effects. With no annotations, the description carries the full burden, which it does not meet.
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 a single sentence, but it could include more useful information without becoming verbose. It is front-loaded but leaves out context that would help the agent.
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?
Given no output schema and minimal description, the tool fails to explain what the response contains (e.g., full creative details, subset of fields). It also does not differentiate from siblings effectively, leaving the agent with gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool description does not add meaning beyond the input schema. The schema covers 50% of parameters with descriptions (only orgId). The description fails to explain that 'by ID' refers to creativeId or clarify the purpose of orgId further.
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 'Fetch', the resource 'a single creative', and the identifier 'by ID'. This distinguishes it from sibling tools like creatives_list and creatives_find, which have different purposes.
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 is given on when to use this tool vs alternatives. While the description implies using it when you have a known creative ID, it does not mention when not to use it or suggest alternatives like creatives_list for browsing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full burden. It only states what is returned, with no information on side effects, authentication requirements, rate limits, or behavioral traits like whether results are paginated or aggregated. This is insufficient for a mutation-free report tool.
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 without redundancy. However, it could be more structured by separating purpose from usage notes.
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?
Given 11 parameters, nested objects, no output schema, and complex filtering/pagination options, the description is incomplete. It does not explain the response structure, how 'rolled up' affects data, or constraints like the groupBy/granularity interaction noted in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no meaning beyond the input schema. With 64% schema description coverage, some parameters lack documentation, and the description does not clarify them (e.g., groupBy restrictions, selector structure). A baseline of 3 would require coverage >80%, so 2 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 'Ad-level performance (per Custom Product Page / creative variation) rolled up across the campaign,' specifying the resource (ads), scope (campaign), and granularity (custom product page/creative variation). It distinguishes from sibling tools like reports_adgroups (adgroup-level) and reports_campaigns (campaign-level).
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 ad-level performance across a campaign but provides no explicit guidance on when to use this tool versus alternatives like reports_adgroups or reports_search_terms. No when-not or alternative tools are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full burden. It does not disclose any behavioral traits such as data freshness, default aggregation, sorting, pagination behavior, or limitations. The description is too high-level to inform the agent about the tool's actual behavior.
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 sentences with no filler, very concise. However, it could be slightly more structured (e.g., mention parameters or output). Still, it earns high marks for efficiency.
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?
The tool has 11 parameters including a complex selector, no output schema, and moderate schema coverage. The description is too brief; it doesn't explain the output type or schema, nor how to interpret the report. It leaves significant gaps for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 64% (moderate). The description adds no context about parameters; it doesn't mention required inputs (campaignId, dates) or explain optional fields like granularity or groupBy. It fails to compensate for schema gaps.
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 is a search-terms report aggregated across all ad groups in a campaign, and explains the value ('reveals what users actually typed'). It effectively distinguishes from sibling tools like reports_search_terms_in_adgroup (ad-group level).
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 use cases (harvest new keywords or negatives) but does not explicitly state when not to use this tool or mention alternatives. Siblings like per-adgroup search terms or keyword reports are not noted as alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose all behavioral traits. It only mentions the HTTP method variant but omits idempotency, error behavior, or side effects of deletion.
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 a technical note, very concise and front-loaded. It could be slightly longer to include parameter context.
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 delete tool with no output schema and four parameters, the description lacks details on expected behavior, error responses, prerequisites, and results of the operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 25% (only orgId described). The description adds no parameter meaning beyond 'by ID'. It doesn't explain campaignId or adGroupId, which are required.
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 'Delete a single targeting keyword by ID', specifying the verb, resource, and method. It distinguishes from sibling tools like 'targeting_keywords_delete' by emphasizing 'single'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'by ID' and 'single' indicate when to use this tool versus batch alternatives. However, it does not explicitly mention when not to use or provide alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It says 'bulk-update' but does not explain whether the update is partial or full replacement, what happens to omitted fields, error handling, or authorization needs. The schema indicates up to 1000 items but this is not mentioned in the description.
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 is front-loaded and to the point. It could include a bit more detail without becoming verbose, but overall it is appropriately concise.
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?
Given the tool's complexity (4 parameters, nested objects, no output schema, no annotations), the description is insufficient. It lacks details on return values, error scenarios, or the update behavior (e.g., whether fields are merged or replaced). This makes it hard for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25%, yet the description adds only that 'Each entry must include id' and lists the editable fields. It does not explain the structure of 'bidAmount' or the meaning of enums like 'matchType'. The description fails to compensate for low 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 includes a specific verb ('bulk-update'), identifies the resource ('targeting keywords'), and lists the updatable fields (status, bid, text, matchType). This clearly distinguishes it from sibling tools like create or delete.
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 states that each entry must include 'id', implying that updates are for existing keywords. However, it does not explicitly state when to use this tool vs alternatives, nor does it mention prerequisites like having the campaign and ad group IDs (though they are in the schema).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only states 'Create' implying mutation, but does not detail side effects, authentication needs, rate limits, or what the response contains. Insufficient transparency for a creation tool.
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 sentences (12 words) and front-loads the core action and constraint. Every word earns its place, with no unnecessary content.
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?
Given the tool's complexity (12 params, nested objects, no output schema), the description lacks critical details such as return value, error conditions, prerequisites, or validation rules. This is insufficient for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (33%), but the description adds no extra parameter meaning beyond listing the tool's action. The description does not compensate for the gap, leaving many parameters without semantic guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (create) and resource (budget order), includes a specific constraint (LOC accounts only), and mentions wrapping Apple's envelope. It is distinct from sibling budget_orders_get/list/update.
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 provides a usage restriction (LOC accounts only) but does not specify when to use this tool versus alternatives like budget_orders_update, nor does it include when-not-to-use or explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states the action and scope. It does not disclose any behavioral traits such as idempotency, error handling, permission requirements, or side effects. The schema provides some constraints (max 1000), but description adds no behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that includes the action, resource, and key differentiator. It is front-loaded and contains no extraneous information. Every word contributes to understanding.
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?
Given the lack of annotations and output schema, and low parameter coverage, the description covers only the basic purpose and scope. It omits usage guidance, behavioral details, and parameter explanations, leaving significant gaps for an agent to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 33% (only orgId has a description). The description does not explain parameter meanings or usage beyond implying bulk creation. For example, matchType values (BROAD, EXACT) are not semantically described. The description adds minimal value over 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 (bulk-create), the resource (campaign-level negative keywords), and distinguishes from ad-group siblings by noting 'apply across all ad groups'. This provides immediate clarity on scope and usage.
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 (for campaign-level negatives) via the phrase 'apply across all ad groups', but does not explicitly state alternatives (e.g., adgroup_negative_keywords_create) or exclude conditions. The context is clear but lacks explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only states 'find... with a selector' and does not mention read-only nature, required permissions, rate limits, pagination behavior, or what happens if the campaign does not exist. This is insufficient for an agent to predict tool behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear, front-loaded sentence with no extraneous information. Every word serves a purpose, making it highly efficient.
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 (nested parameters, no output schema), the description is too brief. It does not explain return format, pagination behavior, or error scenarios. An agent would need additional context to use this tool reliably.
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 covers 67% of parameters with descriptions. The tool description adds marginal value by confirming the selector's role. However, the campaignId parameter lacks schema description and is not clarified in the tool description. Overall, the description does not significantly 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 verb 'find', the resource 'campaign-level negative keywords', the scope 'within a single campaign', and the mechanism 'with a selector'. It effectively distinguishes from sibling tools like 'adgroup_negative_keywords_find' and 'campaign_negative_keywords_list'.
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 does not provide guidance on when to use this tool versus alternatives, such as 'campaign_negative_keywords_list' or 'adgroup_negative_keywords_find'. No when-not or alternative usage scenarios are mentioned, leaving the agent uninformed.
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 explicitly states the action is permanent and irreversible, which is a key behavioral trait. However, it omits other important behaviors such as cascading effects on child entities, required permissions, or rate limits. With no annotations, more detail is expected.
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, consisting of two well-placed sentences. The action is front-loaded, and the critical behavioral detail (irreversibility) follows immediately. No superfluous words.
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 destructive operation, the description lacks important context such as what happens to associated adgroups/ads, whether deletion is immediate, or expected return values. Given no output schema, the description should cover these gaps but does not.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool description does not mention or explain any parameters. The schema provides description for orgId but not for the required campaignId. With 50% schema coverage, the description fails to compensate by adding parameter context.
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' and the resource 'campaign', emphasizing permanence. It distinguishes from update or read operations on campaigns and from deletion of other entities like adgroups.
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., pausing a campaign) or prerequisites (e.g., campaign existence, permissions). The description does not mention any context for safe usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description should disclose behavioral traits such as read-only nature, error handling, or authentication needs. It only states the core function, omitting important context.
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, clear sentence with no extraneous words. It is appropriately concise and front-loaded.
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?
Given the lack of output schema and low parameter coverage, the description should provide more context about return values or parameter details. It is incomplete for a tool with three parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33% (only orgId has a description). The tool description does not explain the other two parameters (adamId, productPageId), leaving their meaning to be inferred from names. It fails to compensate for low 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 fetches a single Custom Product Page by ID, using a specific verb and resource. It distinguishes itself from sibling tools like cpp_list which lists multiple pages.
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 retrieving a specific page by ID, but does not provide explicit guidance on when not to use it or mention alternative tools. It is adequate but lacks depth.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral transparency. It indicates a read operation (list) but does not disclose any side effects, authentication requirements, or scope of data returned (e.g., pagination, format). For a listing tool, this is minimal disclosure.
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 is clear and front-loaded with the purpose. It is concise but could benefit from a brief note on usage context without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has three parameters (two required) and no output schema. The description covers the high-level purpose but does not explain the return format or what 'localized assets' means. Given the simplicity, it is minimally adequate but lacks depth for a complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (33%, only for `orgId`). The description does not explain `adamId` or `productPageId`, which are required. The `orgId` parameter has a schema description, but the description adds no additional 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?
The description clearly states the tool's action ('List the locales available for a Custom Product Page') and includes contextual detail ('with localized assets per locale'). It distinguishes itself from siblings like `cpp_get` and `apps_locale_details` by specifying 'Custom Product Page' and 'locales'.
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 vs. alternatives. The description implies usage when needing locales for a specific CPP, but it does not mention `apps_locale_details` or other `cpp_*` tools. The context is clear but lacks 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?
No annotations are provided. The description correctly discloses async behavior and the polling mechanism, which is essential. However, it omits details on side effects, permissions, rate limits, or error scenarios.
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, using two sentences to convey purpose and output. Every word adds value, with no redundancy or fluff.
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?
Given the tool has 7 parameters, nested objects, and no output schema, the description is insufficient. It fails to explain parameter usage, defaults, or return value structure, leaving significant gaps for a complex creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not add any parameter-specific meaning beyond what the input schema already provides. Although schema coverage is 57%, the description lacks details on required parameters like name or how granularity and dateRange interact, leaving gaps.
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 an Impression Share report, specifies it is asynchronous, and explains the polling pattern using custom_reports_get. It distinctly identifies the resource and action, differentiating it from sibling report tools.
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 like reports_adgroups or other report creation tools. It does not mention prerequisites, conditions, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states 'bulk-create' and a limit, but fails to explain response behavior (e.g., what is returned, whether existing keywords are overwritten, error handling). For a creation tool, the response (like created keyword IDs) is critical missing context.
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 concise (one sentence) and front-loaded with the key action. However, it sacrifices completeness for brevity. It could include a note about response or prerequisites without significant length increase.
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?
Given the complexity (bulk create with nested objects, up to 1000 items, no output schema), the description is incomplete. It omits response behavior, does not clarify that it only creates positive keywords (though it says 'positive'), and lacks guidance on required fields beyond the schema. The presence of sibling negative keyword tools increases the need for disambiguation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 25% (only orgId has a description). The tool description adds no parameter details beyond the bulk nature and the 1000 limit. It does not explain campaignId, adGroupId, or the keyword structure beyond what's in the schema. With low coverage, the description should compensate but does not.
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 'Bulk-create', resource 'targeting (positive) keywords', and scope 'on an ad group'. This distinguishes it from siblings like targeting_keywords_update, targeting_keywords_delete, and negative keyword 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 provides a clear usage constraint: 'Pass up to 1000 per call'. This helps the agent understand capacity limits. However, it does not explicitly contrast with alternatives or specify when not to use this tool (e.g., for single keyword creation). The bulk-create nature is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full burden. It only states the basic creation purpose with no disclosure of side effects, permissions, idempotency, rate limits, or error behavior. This is insufficient for a mutation tool.
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 no extraneous content. The first sentence immediately states the tool's purpose, providing a clear front-load.
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?
The tool is complex with 13 parameters, nested objects, and no output schema. The description only gives a high-level purpose, omitting return values, required fields (beyond schema), and error handling. This is inadequate 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 62%, moderate. The description adds no parameter-specific information beyond the schema; it merely reinforces that bid and targeting are involved. It does not compensate for the 38% of undocumented 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?
Description clearly states the action: 'Create an ad group within a campaign.' It distinguishes from campaign-level tools by noting that bid and targeting are set here, not on the campaign, helping differentiate from siblings like campaigns_create.
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?
Description implies that bid and targeting should be set at the ad group level rather than campaign, providing some context. However, it does not explicitly state when to use this tool versus other ad group tools (e.g., adgroups_update) or any prerequisites/alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only states function and output, missing details on auth, rate limits, or failure behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with key information, no filler.
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 complexity (nested selector, no output schema), description omits guidance on crafting selector or typical use cases, leaving 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?
Description adds meaning about return use (assetGenIds for creatives/rejected assets), but parameters (adamId, selector, orgId) are not explained beyond schema's own 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?
Description clearly states it finds App Store screenshots/app-preview assets for an app and returns assetGenIds for creatives or auditing, distinct from sibling tools targeting 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides usage context (authoring creatives, auditing rejected assets) but no explicit when-to-use vs alternatives like creatives_find or apps_get.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so description carries full burden. It states it returns localized details per locale, which is basic. No mention of side effects, rate limits, or authentication.
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 redundancy. Front-loaded with key action.
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?
Lists returned fields (subtitle, short description, screenshots, app preview), but lacks differentiation from sibling cpp_locale_details. No output schema, so description should be more comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (only orgId described), but description does not add any parameter meaning beyond schema. It does not explain adamId or orgId.
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 action (get), resource (localized default product-page details for an app), and scope (per locale). It distinguishes from siblings like cpp_locale_details and apps_get.
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. No mention of context, prerequisites, or 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behaviors. Only states 'Fetch' (implying read), but no details on error behavior, authentication, rate limits, or return format.
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, straight to the point, 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?
Tool is simple (get by ID), but missing output schema and any mention of return value or error conditions. Adequate but could provide more context for smooth agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Parameter description coverage is 50% (only orgId described). Description adds no extra meaning for campaignId beyond what schema provides; orgId is already well-documented in 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 action 'Fetch', resource 'campaign', and method 'by ID', distinguishing it from list/find siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage for a single campaign by ID, but no explicit guidance on when to use this vs campaigns_find or campaigns_list, nor any 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?
No annotations are provided, so the description must cover behavioral traits. It correctly implies a read-only operation ('Find' and 'audit'), but lacks details on side effects, rate limits, or authentication requirements. The minimal information is adequate for a simple retrieval tool.
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 efficient: two sentences that convey purpose, filterable fields, and intended use. No redundant or unnecessary 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?
Given the complexity (nested selector with filtering options) and lack of output schema, the description could be more complete by indicating the result structure (e.g., list of reasons with fields). However, the core purpose is clear, and the schema details the input adequately.
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 already provides descriptions for both parameters (selector and orgId). The tool description adds value by listing specific filterable field names (adamId, productPageId, etc.) not detailed in the schema, aiding the agent in constructing queries.
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 finds ad-creative rejection reasons and mentions specific filterable fields. However, it does not explicitly distinguish this tool from the sibling 'product_page_reasons_get', relying on the name suffix 'find' vs 'get' to imply the difference.
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 a use case ('audit why a creative was rejected') but no guidance on when to use this tool versus alternatives, such as 'product_page_reasons_get' for retrieving a single reason. No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only indicates a read operation ('Fetch') but does not disclose required permissions, error states, 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 a single sentence that conveys core functionality 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?
For a simple get-by-ID tool, it is minimal. It lacks information about the return value, and since there is no output schema, the agent lacks context on what data is retrieved.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no detail about parameter usage or constraints. Schema covers orgId (50% coverage) but productPageReasonId lacks description; the tool description does not compensate.
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 ('Fetch') and resource ('rejection reason') and specifies it is by ID, differentiating it from sibling product_page_reasons_find that likely lists multiple.
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 versus alternatives like product_page_reasons_find. It implies single-record retrieval but lacks guidance on 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Only mentions Apple's lowercasing quirk for countrycode. No disclosure of rate limits, auth requirements, or other behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two sentences that efficiently convey the tool's purpose and a key usage nuance. 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?
While description covers basic search behavior, it lacks details on response format, pagination behavior (limit/offset are in schema but no usage context), and error handling. More context would help, given no output schema.
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 83% description coverage (5 of 6 parameters described). Description adds value by clarifying Apple's case sensitivity for countrycode and noting v5 entity support. Beyond schema, it provides practical usage context.
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?
Description clearly states it searches geo entities by name, listing supported types. It adds context about the countrycode quirk. However, it does not explicitly differentiate from sibling tools like geo_lookup.
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?
Provides guidance on using countrycode to scope searches, but lacks explicit when-to-use vs alternatives or when not to use. No exclusion criteria for sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description lacks behavioral details such as whether it reads data, requires special permissions, or handles pagination. It only states what it does, not how it behaves.
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?
A single, front-loaded sentence that is concise and to the point. Could include more context, but it is not 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?
Given the complexity (nested objects, pagination, optional orgId) and lack of output schema or annotations, the description is insufficient. Missing return format, pagination behavior, and authorization hints.
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 descriptions for both parameters (selector and orgId). The description adds no extra meaning beyond the schema, 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?
Description clearly states it finds ad groups across the entire org using a selector. The verb 'find' and resource 'ad groups' are specific, and the scope 'across the entire org' distinguishes it from sibling tools like 'adgroups_find_in_campaign'.
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?
Implied usage is for org-wide queries, contrasting with campaign-scoped tools. However, no explicit when-not-to-use or alternatives are mentioned. The scope is clear from the name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description fails to disclose any behavioral traits such as read-only nature, authorization requirements, or pagination behavior. The description carries the full burden and is insufficient.
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 verb and resource, with no unnecessary words.
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?
Given the complexity of the selector and the lack of output schema, the description does not cover what the tool returns, pagination details, or how the selector works, leaving gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 67% schema coverage, the baseline is 3. The description adds no additional parameter-level meaning beyond what is in 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 'Find', the resource 'ads', and the scope 'across all ad groups in a campaign', distinguishing it from siblings like ads_find_org_wide.
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?
Usage is implied by the name and scope; it's clear you use it to find ads within a specific campaign. However, it does not explicitly mention when not to use or compare with 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?
No annotations are provided, so the description carries the full burden. It states the action and scope, but does not disclose behavioral traits such as permissions required, read-only nature, or pagination behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the core purpose, and contains 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?
Given the complexity of the selector object and the lack of an output schema, the description is minimal. It does not explain what fields are filterable, nor does it describe the return type, leaving the agent to infer from 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 67% (descriptions for selector and orgId). The description adds no additional meaning beyond the schema; it only mentions 'using a selector' which is already clear from the schema. 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 verb 'Find', the resource 'ad groups', and the scope 'within a single campaign', which distinguishes it from the sibling tool 'adgroups_find_org_wide' that searches org-wide.
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 use when you need ad groups in a specific campaign, but does not provide explicit when-not-to-use guidance or mention alternatives like 'adgroups_find_org_wide' or 'adgroups_list'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It states that authentication and org context are handled, but does not mention potential side effects, rate limits, or that the tool can be destructive (as an escape hatch). An 'escape hatch' implies power and risk, but the description fails to elaborate, leaving the agent without crucial safety warnings.
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: three sentences, no wasted words. It front-loads the purpose and immediately follows with the usage guideline. Every sentence earns its place, achieving efficiency without sacrificing clarity.
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?
Given the complexity (6 parameters, no output schema), the description is incomplete. It does not explain the return format, error behavior, or how to construct the 'path' parameter (beyond the schema's note on leading slash). The agent lacks context on what the response looks like or how to handle failures.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (3 of 6 parameters described). The description adds no parameter-specific meaning beyond what the schema provides, repeating only 'method + path'. It does not clarify the purpose of 'body', 'query', or 'noOrgContext', failing to compensate for the low 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 identifies this tool as an escape hatch for any Apple Search Ads endpoint, using method and path. It distinguishes itself from sibling tools by explicitly stating it should only be used when no dedicated tool covers the endpoint. The verb 'call' and resource 'any Apple Search Ads endpoint' are precise.
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 provides explicit guidance: 'Use only if no dedicated tool covers the endpoint you need.' This tells the agent when to use this tool and implies when not to (when a dedicated tool exists). No alternatives are listed, but the condition is sufficient for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden. It implies a read-only listing operation with no destructive behavior, but it does not disclose potential issues like pagination, error handling, or permission requirements. It is adequate but not rich.
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 is concise, front-loaded, and contains no unnecessary words. Every piece of information 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 low complexity (one optional parameter, no output schema), the description is complete. It clearly states what the tool returns and any additional context about languages is sufficient.
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 description for orgId, so the schema already explains the parameter. The description does not add additional parameter meaning beyond what is in the schema, 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 (List), the resource (supported countries/regions), and the data returned (default and supported product-page languages). It is specific and distinct from sibling tools like geo_lookup or search_geo.
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, no prerequisites, and no context for when not to use it. It simply states what it does.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavioral traits. It implies a read-only operation by stating 'Returns rows', but fails to mention pagination, authentication requirements, rate limits, or any side effects. This gap is significant for a report tool with 10 parameters.
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 focused sentences: the first defines purpose and output, the second adds a key usage hint. No wasted words, front-loaded with essential information. Perfectly 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?
Given the complexity (10 parameters, nested objects, no output schema), the description is minimally complete. It covers purpose and groupBy but omits guidance on date parameters, granularity, timeZone, and the selector object (filtering, sorting, pagination). The schema helps, but behavioral context is lacking.
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 description adds value beyond the input schema by explicitly mentioning the groupBy parameter and its effect ('pivot by country, device, age, gender'). The schema already covers groupBy with enum and description, but the description reinforces and provides concrete usage context. Schema coverage is 70%, so the description compensates partially.
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 is a 'Campaign-level performance report' and lists the specific metrics returned (impressions, taps, installs, etc.), distinguishing it from sibling report tools like `reports_adgroups`. The verb 'Returns' is implied, making the purpose specific and actionable.
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 indicates it is for campaign-level data but provides no explicit guidance on when to use this tool versus siblings like reports_adgroups or reports_ads_in_campaign. There are no exclusions or alternative suggestions, leaving the agent to infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden. It only states 'Find', implying a read operation, but lacks disclosure of behavioral traits such as rate limits, authentication requirements, or return format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently conveys the purpose and key filterable fields without any wasted text.
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?
While the description covers purpose and filterable fields, it lacks details on return values, pagination behavior, or limitations. No output schema exists, so the description should ideally provide more context; it falls short of full completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 67% coverage, and the description adds value by listing specific filterable fields (supplySource, countryOrRegion, deviceClass, state) that correspond to nested schema properties, aiding parameter understanding beyond the schema alone.
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 'Find' and the resource 'app-eligibility records', and lists specific filterable fields (supplySource, countryOrRegion, deviceClass, state), distinguishing it from other sibling find 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 finding app eligibility records with a selector, but provides no explicit guidance on when to use this tool versus alternatives or 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It implies a read operation but does not explicitly state read-only, no side effects, or permissions. It also does not describe the return format or any limitations.
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 that front-load the main action ('Resolve geos by raw IDs') and provide essential details without 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?
For a simple lookup tool with no output schema, the description explains the request format and use case adequately. However, it lacks any description of the response structure (e.g., what names are returned), leaving the agent to infer the output.
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 covers 50% of parameters with descriptions (entity enum, orgId). The description adds crucial meaning by specifying the id format ('CountryCode|adminArea|locality') and the entity values, which is not present in the schema for the 'id' field.
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 resolves geo IDs to names, specifies the request format with id and entity, and implies the output is human-readable names. It distinguishes from sibling 'search_geo' by focusing on resolution rather than search.
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 'Useful when a report returns geo IDs you want named,' giving clear context. However, it does not mention when not to use it or provide alternatives like search_geo for searching.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It correctly identifies this as a read operation returning user info, but does not mention any side effects, permissions, or response format beyond the two listed fields.
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, well-structured sentence that conveys purpose and key output fields without any redundant words. It earns its place entirely.
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 simplicity (no params, no output schema), the description covers the basics but is not fully complete. It does not specify the response structure (e.g., that it returns a JSON object) or whether more fields exist. Adequate for a minimal tool but leaves some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the description's role is to explain what the tool returns. It explicitly lists userId and parentOrgId, adding meaningful context beyond the empty schema. According to guidelines, this warrants a baseline of 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 uses a specific verb ('Return') and resource ('information about the calling API user'), and explicitly lists key fields (userId, parentOrgId). This clearly distinguishes it from all sibling tools, which focus on ad groups, campaigns, etc.
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: call this tool when you need the current user's ID and org ID. However, it does not provide explicit guidance on when not to use it or mention any alternatives, even though no direct alternatives exist among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does not explicitly state the operation is read-only or list side effects. However, it does disclose a key behavioral trait: Apple does not expose a per-ad-group find, which is useful context. This adds value beyond the schema but lacks full transparency on safety or output behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, each serving a distinct purpose: the first states what the tool does, and the second provides an important behavioral note. No extraneous words, and critical information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is missing information about return values (no output schema) and potential edge cases. It does cover the key contextual point about the lack of per-ad-group find, which is critical for correct usage. Given the tool's complexity (selector with pagination, multiple parameters), the description provides important context but leaves some aspects (e.g., default fields, error handling) unspecified.
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 67% (selector and orgId have descriptions). The description adds marginal parameter guidance by suggesting using the selector's conditions to filter by adGroupId, which helps agents understand the selector's purpose. It does not elaborate on campaignId or orgId beyond what's in the schema. Baseline 3 is appropriate given coverage and limited added detail.
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 finds targeting keywords across all ad groups in a campaign with a selector, specifying the scope (all ad groups) and mechanism (selector). It also distinguishes from per-ad-group find by noting Apple's lack of such an API, which differentiates it from sibling tools like targeting_keywords_list or adgroup-level find 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 explicitly addresses a common use case: needing per-ad-group filtering. It advises filtering by adGroupId in the selector, providing clear context. However, it does not directly contrast with sibling tools like targeting_keywords_list or specify when to use this tool versus alternatives, leaving some inference to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, but the description states 'search' which implies read-only. It details supported operations but doesn't explicitly confirm no 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?
Single sentence, front-loaded with key info, no fluff.
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?
Covers purpose and key features. No output schema, so description could mention return type, but 'search campaigns' implies a list. Nested objects are addressed.
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 parameters. The description adds context that the selector supports conditions/orderBy/pagination but doesn't go beyond the schema's detail.
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 searches campaigns using a selector with conditions, orderBy, and pagination. It distinguishes from siblings like campaigns_list and campaigns_get.
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 is implied (search with filters/sorting/pagination) but no explicit when-to-use or alternatives mentioned. Sibling tools like campaigns_list exist for simpler listing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavior. It indicates a read-only list operation. However, it does not detail pagination, limits, or return format. Adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence with a concrete example. Every word earns its place. No fluff.
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?
Lacks output schema, but the description implies a list of device-size mappings. For a simple list tool with no required parameters, it covers the essential context.
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 the orgId parameter. The description does not add extra meaning beyond the schema's own description. Baseline 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?
Description clearly states 'List supported app-preview device-size mappings' with examples. The verb and resource are specific. No sibling tool overlaps, so distinction is inherent.
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?
Includes usage context: 'Used when authoring creatives or interpreting screenshot/preview metadata.' This guides when to invoke, though no explicit exclusions or alternatives are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden for behavioral disclosure. It mentions the return fields but does not specify that the operation is read-only, does not discuss rate limits, pagination behavior (though schema has limit/offset), or authentication requirements. The description provides some transparency but is not comprehensive.
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 sentences: one states purpose and outputs, the other provides critical context (need for adamId). Every word adds value with no redundancy. The structure is front-loaded 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 no output schema, the description covers the key aspects: purpose, return fields, and subsequent use of adamId. It does not explain pagination, error scenarios, or response format, but these are partially addressed by the input schema (limit/offset). Overall, it is complete enough for an AI agent to use the tool effectively.
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 all parameters are described in the schema. The description adds value by mentioning the return fields (adamId, name, developerName, country availability), which indirectly clarifies the query parameter's intent. However, since the schema already provides descriptions, the additional semantic contribution is modest, earning a 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 tool searches the App Store for apps to target/advertise, listing specific return fields (adamId, name, developerName, country availability). The verb 'search' and resource 'App Store' are specific, and the description distinguishes from siblings like 'apps_get' which retrieves a specific app.
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 indicates when to use the tool (to find apps for advertising) and emphasizes the need for adamId for campaign creation. It does not explicitly mention alternatives or when not to use, but the context is clear enough for an AI agent to understand the primary use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. It reveals one behavioral detail (clearing ad-group geo targeting on country change) but omits others like mutation side effects, permissions, or reversal. The added detail is helpful but insufficient for a mutation tool with no additional metadata.
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, no fluff, front-loaded with the action. Every sentence adds distinct value: purpose, partial update pattern, and a critical behavioral flag. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is complex (nested objects, many fields, no output schema), yet the description is bare. It lacks return value information, error handling hints, prerequisites, or restrictions. The partial update guidance and geo flag help, but overall completeness is minimal for the complexity level.
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 high (75%), so baseline is 3. The description adds value by clarifying partial update behavior and the `clearGeoTargetingOnCountryOrRegionChange` parameter's semantics, which is not fully explained in the schema. This goes beyond mere repetition.
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?
Clear verb 'Update' with resource 'a campaign', distinct from siblings like create, delete, get, list. The description explicitly states the action and the resource, 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidelines: use partial updates ('pass only fields you want to change') and a specific flag for geo targeting changes. While it doesn't list alternatives or exclusions, the guidance is directly actionable and covers a key use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full burden. It discloses pagination but lacks other behavioral traits like read-only nature, rate limits, or safety hints. The word 'list' implies read, but the description could be more explicit.
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. The purpose is front-loaded in the first sentence, and the alternative is provided succinctly in the second.
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 is adequate for a simple list tool with three parameters. It covers pagination, scope, and alternative tool. However, it does not specify the return format (e.g., list of campaign objects), which would enhance completeness.
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 provides descriptions for all three parameters (100% coverage). The description adds no extra meaning beyond the schema, so baseline score of 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 clearly states the verb 'list', the resource 'campaigns', and scope 'in the org (paginated)'. It distinguishes from the sibling tool 'campaigns_find' by mentioning it offers richer filtering.
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 provides when to use this tool ('List all campaigns') and directs to an alternative ('For richer filtering use campaigns_find'), giving clear guidance on tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description discloses the polling behavior and expected output fields. It implies a read operation but does not cover rate limits, error states, or authentication requirements.
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 with no unnecessary words, front-loading the action and providing critical details (polling and columns) efficiently.
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?
No output schema exists, but the description lists the columns and polling requirement. It lacks information on errors, retries, or limits, but is sufficient for a simple polling fetch.
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 50% (orgId has a description, reportId does not). The description does not elaborate on either parameter, leaving reportId unexplained. Baseline is 3 due to moderate coverage, but no added value.
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 fetches a single Impression Share report and mentions polling until COMPLETED, with specific column names. It distinguishes itself from sibling tools like `custom_reports_create` and `custom_reports_list`.
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 poll until state=COMPLETED to read rows, which is a key usage guideline. However, it does not mention when not to use this tool or alternative approaches for filtering or other report types.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It describes a read-only list operation, mentions returned fields, and states authentication requirements. Does not discuss pagination or limits, but acceptable for likely small result set.
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 clearly states action and output, second provides usage advice. No unnecessary words, perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with no output schema, description adequately explains return fields and usage context. Covers all necessary information without gaps.
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, so schema coverage is 100%. Baseline score of 4 applies as description adds no parameter info 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?
Description explicitly states it lists org-level ACLs, specifies returned fields (orgName, currency, paymentModel, roleNames), and explains its purpose to discover the orgId. No sibling tools deal with ACLs, making it unique.
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?
Clearly advises using this tool to discover orgId for ASA_ORG_ID, and notes it does not require X-AP-Context. Lacks explicit when-not-to-use guidance, but for a simple list tool this is sufficient.
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:

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

Score Badge

Copy to your README.md:

[![apple-search-ads-mcp MCP server](https://glama.ai/mcp/servers/AppVisionOS/apple-search-ads-mcp/badges/score.svg)](https://glama.ai/mcp/servers/AppVisionOS/apple-search-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/AppVisionOS/apple-search-ads-mcp'

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