pinterest-ads-mcp-server

Server Quality Checklist

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

Latest release: v1.0.0
Disambiguation3/5
Several tool pairs overlap at the edges—catalog_inventory vs catalog_diagnostics, delivery_metrics vs platform_resources, and multiple run_* report tools—cover closely related Pinterest API areas. The descriptions are detailed and do disambiguate, but an agent must read carefully to avoid selecting the wrong endpoint.
Naming Consistency5/5
All tools use the consistent pinterest_ prefix and follow snake_case verb_resource naming like get_*, list_*, run_*, validate_*, and estimate_*. The small get/list variation is conventional rather than inconsistent.
Tool Count3/5
At 26 tools, the server sits just over the 16–25 'heavy' band, so the count is high. The breadth of Pinterest Ads read-only surfaces gives each tool a reason to exist, but consolidation around report/export runners would make the set easier to navigate.
Completeness5/5
The set covers the major read-only Pinterest Ads domains: accounts, reporting, catalogs, targeting, audiences, creative, business, billing, organic, trends, and platform readiness. Since the tools are explicitly non-mutating, missing write operations are by design rather than a gap.
Average 3.4/5 across 26 of 26 tools scored. Lowest: 2.6/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 2 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under Apache 2.0.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

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

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

How is the quality score calculated?

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

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

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

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

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does state that the tool returns certain data and notes that period performance is available 'when available,' which is useful. However, it does not disclose behaviors such as required ad account context, date range handling, pagination, whether results are limited by default, or what happens when no assets match.
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 compact sentence that front-loads the main action and resource. It packs several return categories into a list without excessive wording. It loses one point because the phrase 'when available' is vague and the long enumeration is slightly unfocused, but overall it is 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?
For a tool with 7 parameters, 2 required parameters, no output schema, and no annotations, the description is too sparse to support correct invocation. It does not explain date formats, which filters are supported, what 'period performance' means, or how the response is structured. An agent would likely need to inspect sibling tools or make assumptions to call this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides almost no parameter meaning. Required fields startDate and endDate are not explained, and optional filters like adGroupIds, campaignIds, adAccountId, and onlyWithPeriodDelivery are not mentioned. The phrase 'period performance when available' could relate to onlyWithPeriodDelivery, but it is too vague to count as meaningful parameter semantics.
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 a specific verb ('Fetch') and resource ('Pinterest creative assets'), and lists what is returned: ads, pins, media, context, catalog signals, and classifications. This makes the tool's basic purpose obvious, though it does not explicitly differentiate it from siblings like pinterest_get_lead_assets or pinterest_get_organic_inventory.
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 about when to use this tool instead of alternatives, nor are exclusions or prerequisite context given. The phrase 'when available' hints at a conditional but does not explain what conditions matter. Among many sibling tools, the description does not help an agent decide between them.
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 that the report is 'async' and names the API endpoint, which are useful behavioral signals. However, with no annotations and no output schema, it does not explain what the tool returns, whether it merely submits a job that must be polled, what side effects occur, or any rate or data 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 with an active verb up front, no filler, and the key scoping information placed early. Every word contributes to understanding the tool's core action and object.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a 16-parameter async report tool with no annotations, no output schema, and no parameter coverage in the schema description. The one-sentence description does not explain required inputs, how to specify an ad account, how results are retrieved, or how this tool fits among the many run_* and validate_report siblings, making it far from complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the 16 parameters. It adds meaning for the `conversionProductBreakdown` parameter by listing brand, category, brand+category, SKU, and SKU group, but it says nothing about required dates, ad account, filters, windows, granularity, columns, or attribution, leaving most parameters unexplained.
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 a specific verb ('Run'), a clear resource ('Pinterest async conversion product reporting'), and names the breakdown dimensions plus the API endpoint. It is clearly differentiated from generic reporting by the 'conversion product' focus, though it does not explicitly distinguish itself from sibling report tools like pinterest_run_catalog_report or pinterest_run_targeting_report.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to choose this tool over the many sibling report tools, no mention of prerequisites such as an ad account ID, and no exclusions or alternative names. The usage context is only implied by the name and the phrase 'conversion product reporting.'
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 behavioral burden. The verb 'Read' clearly signals a non-mutating operation, and the permission requirement plus the enumerated response categories add useful context. However, it does not disclose pagination, error behavior, rate limits, or how the response is structured for the various modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one sentence, front-loaded with the action and resource, and contains no filler. The long comma-separated list is dense but each item contributes to the scope. It could be broken into clearer clauses, so it is concise but not perfectly structured.
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 11 parameters, no output schema, and no annotations, this description is too thin to fully orient an agent. It establishes the general intent and permission requirement but does not clarify how mode drives the request, what query parameter to use, or what the returned inventory looks like. The schema fills some gaps, but a complex tool like this needs more operational 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?
With only 36% schema description coverage and 11 parameters, the description needed to compensate but does not. The category list loosely maps to the mode enum values, adding some conceptual grouping, but it does not explain query, adAccountId, allowCrossBusinessRead, includePersonalIdentifiers, or other parameters. The schema already provides the mode enum, so the description mostly repeats rather than enriches it.
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 ('Read') and names a clear resource ('Pinterest Business Access inventory'), then lists the scopes: employers/linked businesses, assets, members, partners, assigned assets, received audiences, and invites. However, it does not differentiate this from sibling tools like pinterest_get_account_entitities or pinterest_get_audiences, so it falls short of a full 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a prerequisite ('requires the corresponding business-management permissions') but does not explain when to choose this tool over alternatives. It neither names a sibling nor specifies exclusions, leaving the agent to infer appropriate use from the resource 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 are present, so the description carries the full burden of behavioral disclosure. It says only that the tool 'runs' reporting, without mentioning whether it returns data synchronously, creates an export, requires specific permissions, or how results are delivered. Lacking any side-effect or output behavior, this is a weak disclosure for a reporting 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 two concise sentences with no filler. It front-loads the core action and breakdown dimension, then lists use cases. Minor jargon like 'Performance+ catalog' and 'Shopping-like reports' could be clarified, but overall the structure is efficient.
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 8 parameters, no annotations, and no output schema, the description is substantially incomplete. It omits date format, account identification, column selection, limit behavior, filtering by IDs, and return format. An agent cannot reliably construct a correct call without resorting to external knowledge or the schema's limited type/enum hints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for undocumented parameters. It only hints at breakdown and product group/product item concepts, but does not explain startDate, endDate, adAccountId, columns, limit, productGroupIds, or productItemIds. This leaves most of the eight parameters unexplained.
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?
States a specific verb and resource: 'Run Pinterest catalog reporting' with breakdown by PRODUCT_GROUP or PRODUCT_ITEM. It also lists concrete use cases like catalog product groups and product item attributes, which helps distinguish it from generic report tools. However, it does not explicitly contrast with similar siblings such as pinterest_run_conversion_product_report, so it is clear but not fully differentiated.
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 gives an explicit 'Use for...' list of scenarios, which implies intended usage. It stops short of telling the agent when NOT to use this tool or which sibling to choose instead, such as pinterest_run_report or pinterest_run_conversion_product_report. Some guidance exists, but exclusions and alternatives are absent.
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 burden of behavioral disclosure. It does state that the tool is read-only and that financial data is returned only when the token has account access, which is useful. However, it does not explain what happens without access, pagination behavior, or mode-dependent behaviors, leaving significant gaps.
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 tight sentences with no filler. It front-loads the tool's core purpose in the first sentence and adds a key access caveat in the second. Every word earns its place.
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?
This is a complex tool with 6 parameters, 9 mode enum values, a nested query object, and no output schema or annotations. The description covers only the broad resource types and an access condition, leaving out critical operational details such as required parameters per mode, response shape, and pagination behavior. It is not adequate for reliable 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 at 33%, and the description does not compensate by explaining how the listed resources map to the `mode` parameter or how `query`, `entityId`, and `pageSize` should be used. The description adds almost no meaning beyond the schema, leaving the agent to guess parameter semantics for most options.
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's scope with a specific verb ('Read') and enumerates the resources involved: billing profiles, invoices, order lines, ads-credit discounts, and SSIO account/order status. It is unambiguous about what the tool does, but it does not explicitly differentiate it from sibling tools, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this tool versus siblings like pinterest_get_account_entities or pinterest_get_business_assets. The only contextual note is about token access, which is a requirement rather than a usage-selection guideline. There are no exclusions or alternative conditions.
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 bears the full burden and does convey that this is a read operation ('Read') and explicitly calls out that ITEMS is a read-only POST lookup. However, it omits other behavioral details such as whether some modes require special permissions, how pagination works across modes, or whether any action has side effects. It adds some transparency but not deep 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 two sentences with no wasted words. The core purpose ('Read deep catalog inventory and diagnostics') is front-loaded, followed by a compact enumeration of covered entities and a useful behavioral note about ITEMS. It is dense but appropriately sized for a broad multi-mode tool.
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?
This is a complex tool with ten parameters, nested objects, multiple modes, no output schema, and no annotations. The description lists what can be read but does not explain mode-specific parameter requirements, return value shape, pagination behavior, or how it differs from overlapping siblings. An agent would likely need external documentation to invoke it correctly with confidence.
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 20%, so the description needed to compensate for the ten parameters and mode enum. It does not explain how mode maps to the listed resources or when adAccountId, catalogId, feedId, productGroupId, or processingResultId are required. The only parameter-related hint is that ITEMS is a read-only POST lookup, which is not enough given the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Read') and a clear resource ('deep catalog inventory and diagnostics') and enumerates the covered entities: catalogs, feeds, processing results, item issues, product groups, products, and available filters. This distinguishes it from simpler inventory tools by breadth, though it does not explicitly differentiate it from the similarly named sibling pinterest_get_catalog_inventory.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to choose this tool over siblings such as pinterest_get_catalog_inventory, pinterest_run_catalog_report, or pinterest_get_organic_inventory. The description only lists capabilities and notes that ITEMS is a read-only POST lookup, but does not state conditions, prerequisites, or alternatives. An agent would have to infer usage from the mode enum.
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 verb 'List' communicates a read-only operation, and 'optional product samples' hints at the includeProductSamples behavior. However, with no annotations, the description does not disclose pagination, ad-account scoping, rate limits, or return shape, sharing the full burden on the description rather than shared structured metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every word contributes to the core purpose and scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations, no output schema, and undocumented parameters, this description is too thin. An agent cannot tell how sampleProductGroups affects results, what ad account context applies, or how this differs form catalog diagnostics/report tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. Only 'optional product samples' maps to includeProductSamples. adAccountId and sampleProductGroups are not semantically explained beyond their property names and default/constraint values, so an agent lacks context for those 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 states a specific verb and resource: 'List Pinterest catalog inventory surfaces' and enumerates the surfaces (catalogs, product groups, product group promotions, optional product samples). It clearly describes what the tool does, though it does not explicitly contrast with sibling catalog tools like diagnostics or 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?
There is no guidance on when to use this tool versus alternatives. The description implies a listing use case, but it gives no exclusions or routing cues relative to sibling tools such as pinterest_get_catalog_diagnostics or pinterest_run_catalog_report.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description carries the full behavioral burden. It explicitly signals a read-only operation with 'Read' and adds one useful constraint: country metrics accept up to 2,000 keywords per request. However, it does not disclose pagination behavior, rate limits, or mode-to-parameter prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two tight sentences: the first identifies the core scope and modes, and the second adds the most operationally important limit. There is no filler or redundancy.
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 13-parameter tool with no annotations, no output schema, and zero schema description coverage, this description is not complete enough for correct invocation. It does not specify which parameters each mode requires, what the response contains, or how pagination works.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does little to compensate for the 13 undocumented parameters. It references the modes and mentions the keywords limit, but does not explain how mode, term, terms, keywords, adGroupId, campaignId, countryCode, matchTypes, or bookmark relate to each other or when each is required.
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 the specific verb 'Read' and names concrete resources: assigned targeting keywords, country-level keyword metrics, suggested terms, and related terms. It is clear about what the tool returns, though it does not explicitly distinguish these from sibling tools like pinterest_get_targeting_options or pinterest_get_trends.
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 about when to use this tool versus alternatives, and does not state which mode serves which use case. The mode enum in the schema hints at variants, but the description itself gives no context for choosing among them.
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. The word 'Read' implies a non-mutating operation, but it does not disclose behavior like endpoint selection via mode, response shape, pagination, rate limits, or whether some modes require additional query parameters. This is thin coverage for a complex 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, waste-free sentence that front-loads the resource and then lists all supported content types. It is appropriately compact, though a slightly structured breakdown of the mode-to-data mapping would improve scannability.
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—16 parameters, 6 enum modes, nested query objects, no output schema, and many sibling tools—a one-sentence overview is not sufficient. An agent cannot reliably determine which parameters apply to each mode, what the returned data looks like, or which sibling to prefer.
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 6%, so the description must compensate, but it fails to explain most parameters. The list of growing/monthly/yearly/seasonal keywords maps indirectly to the trendType and mode enums, yet region, productRegion, productLookbackDays, includeKeywords, featuredInterest, and the generic query object are left undocumented in both schema and description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource ('Read Pinterest Trends') and then enumerates the distinct output categories: keywords by growth period, product categories and details, featured topics, and editorial articles. This clearly separates it from sibling tools like get_keyword_intelligence, audience insights, or pin analytics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: whenever you need Pinterest Trends data in any of the listed forms. However, it does not explicitly state when not to use it, which mode to pick for a given need, or how it compares with sibling tools such as get_keyword_intelligence or get_targeting_options.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description does the transparency work: it declares the operation is read-only, reveals that old/wide or async requests are auto-routed, and warns that column names are raw Pinterest names. These are non-obvious, useful behavioral facts. It stops short of covering pagination, error handling, permissions, 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?
Three short sentences with no filler. The most important fact, read-only Pinterest Ads report, is front-loaded, followed by the key routing behavior and the column-name caveat.
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 17 parameters, no output schema, and no annotations, this description is too thin to allow correct invocation. It does not explain date formats, filter/entityIds shapes, return payloads, or how raw column names map to results. It provides safe selection-level context but not execution-level completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description needs to compensate for 17 parameters. It only hints at two: raw column names for 'columns' and async/auto routing for 'executionMode'. It provides no meaning for required dates, level, filters, entityIds, or attribution 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 states a clear verb and resource: 'Run a read-only Pinterest Ads report.' It adds useful distinguishing details like auto-routing to async for old/wide requests and raw Pinterest column names. However, it does not explicitly differentiate itself from the many sibling report tools such as run_targeting_report or run_catalog_report.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains some internal routing behavior ('old/wide or explicit async requests') but gives no guidance on when to choose this tool over sibling report tools. There are no exclusions, prerequisites, or explicit use-case instructions, leaving selection to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It clearly labels the operation as 'Read' (non-destructive) and explicitly discloses pagination behavior by saying it returns one API page and its bookmark. This is meaningful behavioral context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: it begins with the action, then lists the covered entities, then states the return behavior. Every sentence adds information, though the word 'configuration' is slightly vague.
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?
This is a 9-parameter tool with no output schema, no annotations, and low schema coverage. The description explains scope and pagination, but does not clarify how to choose between list vs detail fetches, how to continue pagination with the bookmark, or what the query object should contain. An agent would likely need to inspect external docs to invoke it confidently.
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 22%, so the description must compensate for poorly documented parameters. It only gives meaning to the entity enum and the pagination concept; it does not explain entityId, query, pageSize, adAccountId, adGroupIds, campaignIds, or entityStatuses. This leaves most parameters under-specified.
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 a specific verb ('Read') and a concrete resource ('Pinterest ad-account entities and configuration'), and enumerates the entity types covered. It doesn't explicitly contrast with sibling tools, but it is specific enough for an agent to identify its core purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Returns one API page and its bookmark for predictable live queries' implies when this tool is appropriate—live, paginated entity reads rather than report or export tools. However, it does not name alternatives or state which sibling tools should be used instead for analytics, audits, or reporting.
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 behavioral burden. It discloses that this is a read operation and that metric names are passed through to the Pinterest endpoint selected by mode, but it does not mention required authentication scopes, rate limits, endpoint-to-mode mapping, behavior on unsupported metric names, pagination, or response shape. For an analytics tool with this complexity, that is a significant transparency gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two dense sentences with no filler, and the core read/analytics purpose is front-loaded in the first sentence. The second sentence earns its place by giving a key usage instruction about metric names.
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, no annotations, no output schema, and very low schema coverage, so a complete description would need to explain endpoint selection, required account/date parameters, granularity defaults, and metric-name behavior. The current two sentences provide an overview but leave too much for the agent to infer when actually invoking 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 only 18%, so the description needed to compensate for the many undocumented parameters. It adds useful meaning only to 'metrics' ('raw metric names supported by the selected endpoint') and indirectly to 'mode', but it leaves pinId vs pinIds, adAccountId, campaignId, granularity, sortBy, and query semantics 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 uses a specific verb ('Read') and names concrete resource types: paid Pin analytics, organic multi/single-Pin analytics, user-account analytics, top Pins, and top video Pins. This makes the tool's scope immediately clear and distinguishes it from sibling tools focused on delivery metrics, audiences, billing, or catalog operations.
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 through the mode-specific analytics categories and instructs the caller to pass raw metric names for the selected endpoint, but it never states when to prefer this tool over sibling analytics/reporting tools. There are no explicit alternatives or exclusions, so the usage guidance is only implied rather than actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It explicitly labels the tool 'non-mutating' and states that START 'creates only a report/export artifact; it never updates delivery entities,' which is strong side-effect transparency. It does not cover async polling behavior or permissions, so it is not a perfect 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two compact sentences with the core action and scope front-loaded. Every clause adds useful information, and there is no repetition of schema fields or 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?
This is a complex 7-parameter tool with nested objects, no output schema, and no annotations, but the description gives no START-vs-STATUS parameter matrix, no per-exportType payload guidance, and no return behavior. An agent can grasp the tool's purpose but is not equipped to confidently construct valid calls for all variants.
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 43%, yet the description does not explain the roles of request, adAccountId, includeDetails, bulkRequestId, or token relationships. It only loosely maps export categories to the exportType enum, so it fails to compensate for the undocumented 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 uses specific verbs ('Start or inspect') and states a concrete resource: non-mutating Pinterest data jobs for MMM, bulk advertiser entity downloads, or catalog diagnostics. It is clear about the tool's scope, though it does not explicitly differentiate it from closely named siblings like pinterest_run_catalog_report or pinterest_get_catalog_diagnostics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool by naming its three export categories and the START/STATUS operations. However, it provides no explicit when-not-to-use guidance and names no alternatives among the many sibling reporting tools, leaving the agent to infer selection.
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 behavioral transparency burden. It discloses that the tool is read-only via 'Read', which is useful safety context. However, it does not describe pagination behavior, authentication needs, response shape, or mode-specific side effects, leaving significant behavioral details to the schema or external knowledge.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with a colon-separated list of resource categories. There is no filler, and every listed item corresponds to meaningful mode behavior. It is concise while covering the tool's breadth.
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—7 parameters and 10 modes—the description plus schema provides enough to select a mode and invoke basic calls. The schema documents date for METRICS_READY_STATE, entityId for detail modes, and query as additional parameters. However, there is no output schema and no description-level guidance on response formats, pagination, or the exact semantics of WESITES, reportType, and pageSize, so it is only minimally 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 only 43%, and the required mode parameter has no description in the schema. The tool description adds plain-language meaning to several mode values, such as 'supported ad-account countries', 'delivery metric definitions', and 'authenticated user account'. However, it does not explain WESITES, MEDIA_ITEM, bookmark, pageSize, reportType, or how query interacts with each mode, so it only partially compensates for the coverage gap.
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 reads Pinterest platform metadata and readiness resources, and it enumerates the major categories that map to the mode enum values. It is specific about the resource types, but it does not explicitly distinguish itself from sibling tools like pinterest_get_delivery_metrics, which could overlap with the DELIVERY_METRICS mode.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: when you need platform metadata or readiness resources rather than reports, audiences, or analytics. However, it provides no explicit alternatives or conditions, and it does not clarify when to choose this over sibling tools with similar names like pinterest_get_delivery_metrics or pinterest_health_check.
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?
Since no annotations are provided, the description carries the behavioral disclosure burden. It clearly states the operation is non-mutating and that no campaign or ad group is created or changed, which is the most critical side-effect information. It does not cover auth or rate-limit behavior, but the core behavioral profile is 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?
The description is two sentences with the primary purpose front-loaded and concrete mode examples immediately following. The second sentence adds a meaningful side-effect guarantee and schema note, so each clause contributes without 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?
Given the nested request object, the mode-driven behavior, three parameters, no output schema, and no annotations, this description is too sparse for confident invocation. It lacks the mode-specific request contract, mention of optional `adAccountId`, and any indication of the response shape, leaving significant gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description needed to compensate for the opaque `mode`, `request`, and `adAccountId` parameters. It only says the request body follows the selected Pinterest v5 schema and lists high-level computation types; it does not describe how to construct `request`, which modes require what fields, or the role of `adAccountId`.
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 and resource: 'Run non-mutating Pinterest planning computations' and then enumerates concrete outputs such as audience size, bid floors, and delivery estimates. This maps directly to the mode enum and clearly differentiates the tool from the many get/report 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?
The description establishes a clear context: planning/estimation computations rather than historical reads or report generation, and it stresses that nothing is mutated. However, it does not explicitly name alternative tools or state when not to use this tool, leaving the when-to-use comparison mostly implicit.
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 does disclose a genuine quirk beyond the schema — Pinterest fixes the observation window and the tool ignores custom date ranges — and signals read-only intent via 'Read.' It does not, however, address response shape, aggregation specifics, or any auth/rate-limit caveats, leaving the behavioral picture only partially drawn.
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 tight sentences with no filler. The first sentence front-loads the verb, resource, and scope options; the second delivers the single most important behavioral caveat. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has four parameters, one nested free-form query object, no output schema, and no annotations, so the description must do heavy lifting. It covers the enum semantics and the fixed-window caveat well, but leaves no hint about what the insights response actually contains (e.g., demographics, interests) and does not enumerate the accepted query parameters, which remain 'additionalProperties: {}' in the schema. Adequate but with clear gaps for a tool this complex.
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 only 25%, so the description must compensate, and it partially does: the prose explains the audienceInsightType enum values ('your total or engaged audience, Pinterest's total audience') and the mode enum ('scope/type endpoint'). However, it says nothing about adAccountId and leaves the opaque 'query' object undescribed despite the date-range caveat being the only hint about its constraints. The compensation is real but incomplete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource ('Read aggregated Pinterest Audience Insights') and enumerates the three distinct scopes: advertiser total/engaged audience, Pinterest's total audience, and the scope/type endpoint. The closing clause explicitly distinguishes it from a custom date-range report, which helps an agent separate it from reporting siblings like pinterest_run_report. This is neither tautological nor vague.
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 statement 'it is not a custom date-range report' provides an implicit exclusion that hints an agent should not select this tool when date-range flexibility is required. However, no explicit alternatives are named and there is no positive guidance on when to choose audience insights over overlapping siblings such as pinterest_get_keyword_intelligence or pinterest_get_trends. The usage context is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the safety burden, and it does state that the operation is read-only and non-mutating. However, it does not mention required authentication/permissions, pagination, or endpoint behavior for the different mode values. It provides a baseline behavioral profile but not rich operational transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One tight sentence, front-loaded with the verb and resource, then a short non-mutation qualifier. No filler; it is an appropriate length for the information it conveys.
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 12 parameters, no output schema, and low schema coverage, the description omits how mode selects the fixed endpoints, which parameters are required/valid per mode, and what the response contains. An agent cannot reliably construct a valid call from this text alone; it would need to reverse-engineer 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?
Only 2 of 12 schema properties carry descriptions (17% coverage), and the description adds no direct parameter guidance. The audience/customer-list/sharing terms hint at mode enum values, but the agent gets no help choosing values for mode, query, bookmark, pageSize, adAccountId, businessId, or ownershipType. Low schema coverage demands compensation that the description does not provide.
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?
Begins with 'Read', names the exact resources (audience, customer-list, sharing, Business-received audience inventory), and explicitly frames it as inventory retrieval. This distinguishes it from write-oriented audience tools and from sibling pinterest_get_audience_insights (insights vs inventory).
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?
States a clear context: reading audience-related inventory. The phrase 'without uploading or changing audience membership' sets a when-not boundary and rules out mutation use cases, but it does not explicitly name an alternative tool for those cases. Enough to guide selection among sibling get tools, though not as explicit as a named alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations available, the description carries the full disclosure burden and does state a crucial behavioral guarantee: 'This never sends or deletes conversion events.' It stops short of covering pagination, rate limits, or authentication requirements, but the most important side-effect profile (read-only) is 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 tightly scoped sentences front-load the purpose and then add the key safety qualifier. No filler or repetition of schema details appears.
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 eight parameters, no output schema, and no annotations, the description is too high-level: it omits parameter semantics, default behavior, return shape, and pagination. The purpose is clear, but an agent cannot fully infer how to use the optional filters or interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only indirectly clarifies the surfaces parameter by listing the same category names; the other seven parameters (adAccountId, lookbackPeriod, sourcePlatform, ingestionSource, includeDeletedTags, pageSize, bookmark) receive no semantic explanation. The description does not compensate for the absence of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Inspect') with a clear resource ('Pinterest conversion measurement configuration') and enumerates the exact configuration categories, which directly matches the surfaces enum values. It also explicitly distinguishes this read-only inspection tool from mutation or reporting 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?
The read-only inspection intent is implied by 'Inspect' and 'never sends or deletes,' but there is no explicit when-to-use guidance or comparison to sibling tools such as pinterest_run_report or pinterest_get_delivery_metrics. An agent must infer when this tool is the right choice rather than being told.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden. It clearly states it is a read operation ('Read organic Pinterest content') and clarifies the semantic nature of the data (inventory metadata, not proof of paid delivery). This sufficiently discloses its read-only behavior and the caveat that it is not a delivery proof tool. It does not mention rate limits or auth, but for a read-only tool this is acceptable.
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, each earning its place. The first sentence front-loads the primary purpose and the second adds a critical caveat. There is no fluff or repetition, making it easy to scan.
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 7 parameters, an enum mode with multiple modes, a nested 'query' object, no output schema, and no annotations. The description only provides a high-level overview and a caveat, but does not explain the mode-parameter relationships, pagination (bookmark/pageSize), or the structure of the returned metadata. For such a complex tool, this is insufficient for an agent to call it correctly without external knowledge.
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 14% (only 'query' has a description). The description does not explain any parameters beyond listing content types that roughly map to the 'mode' enum, but it fails to clarify which parameters (pinId, boardId, searchTerm, bookmark, pageSize) apply to which modes or their conditional requirements. Given the low schema coverage, the description should compensate, but it does not provide meaningful parameter semantics.
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 (read), the resource (organic Pinterest content), and explicitly lists the covered content types (Pins, boards, Pins on a board, Pin product tags, search results). It also distinguishes itself from siblings like 'get_catalog_inventory' by explicitly saying 'organic inventory' and 'not proof of paid delivery', making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context ('used alongside ads') and provides an exclusion ('not proof of paid delivery'), but it does not explicitly name alternative tools or provide when-to-use/when-not-to-use guidance. The exclusion is helpful but not comprehensive; an agent would still need to infer which of many get_* siblings this replaces.
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 carries the full burden. It only restates the action without adding behavioral context such as pagination, output format, permission requirements, or side effects. For a read-only list tool, some detail about return structure would be 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 a single sentence with no filler. It front-loads the verb and resource, and is appropriately sized for a simple tool with no parameters.
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 zero-parameter, read-only list tool, the description is mostly adequate but does not specify the return shape (e.g., names, IDs, metadata) or any unusual behaviors. Since no output schema exists, a little more detail would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema provides no meaningful constraints. Per the baseline rule for zero-parameter tools, a score of 4 is appropriate. The description does not need to explain parameters since there are none.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'List Pinterest ad accounts accessible to the configured credentials.' It clearly identifies the tool's function and scope, and distinguishes it from siblings that focus on other entities like audiences or business assets.
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: use this tool when you need to see which ad accounts the current credentials can access. However, it does not explicitly mention alternatives, exclusions, or when not to use it. The purpose alone gives basic contextual 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, the description must carry behavioral disclosure on its own. It adds 'live' and the sync-window concept, but does not disclose read-only nature, permissions, report generation side effects, return shape, pagination, or rate limits. For a report operation with no annotation coverage, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each earning its place: the first states the core function, the second handles the alternative routing. It is front-loaded with the actionable verb and resource, with no filler or repetition of schema fields.
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?
This is a 15-parameter report tool with no annotations and no output schema. The description captures the high-level purpose and one routing rule, but does not explain the required parameters, what kind of result is returned, sync-window semantics, or how to choose between this and the many sibling report tools. It is far from complete enough for reliable 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 only 7%, so the description must compensate for the 15 parameters. It does provide some meaning for targetingTypes and level by mentioning age/gender/location dimensions and ad-account/campaign/ad-group/ad levels, but it leaves startDate, eendDate, entityIds, granularity, attribution windows, timezone, and other required/optional parameters 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 states a specific verb ('Run'), resource ('targeting analytics for an ad account, campaigns, ad groups, or ads'), and the breakdown dimensions (age, gender, location, etc.). It also differentiates itself from pinterest_run_report by calling out the 'live' nature and sync-window boundary.
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 says when NOT to use this tool: for data older than the sync window, use pinterest_run_report with targetingTypes and executionMode=async. This gives an agent a clear routing rule and an alternative in the sibling set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral disclosure. It clearly states what the tool does not do (call performance endpoints) and lists what it returns: sync/async routing, endpoint, level, columns, attribution settings, and warnings. It stops short of disclosing read-only side-effect status, error behavior, or permission requirements, but still offers solid transparency for a validation/preview 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?
One tight sentence front-loads the action and purpose, then lists the key scoped outputs with zero filler. Every clause earns its place and the description remains easy to scan.
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 14 parameters, no schema descriptions, no annotations, and no output schema, the description is too sparse. It mentions some return categories but does not clarify required parameter semantics, date handling, default interactions, or what warnings look like. A complex validation tool like this needs more context to be invoked reliably.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for 14 parameters. The description only names broad groups like level, columns, attribution settings, and sync/async routing. It does not explain critical parameters such as startDate, endDate, entityIds, adAccountId, granularity, viewWindowDays, clickWindowDays, or conversionReportTime, leaving most of the parameter space semantically opaque.
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-resource pair: 'Validate and preview how a Pinterest report will execute.' It also distinguishes itself from execution tools by saying it returns routing and settings 'without calling performance endpoints,' which separates it from pinterest_run_report and similar 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrasing implies this is a pre-flight check before running a real report, especially via 'without calling performance endpoints.' However, it never explicitly names pinterest_run_report or states 'use this when you want to preview, use run_report when you actually want data.' Usage context is clear but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. Saying the tool 'Read's and that it inspects 'metadata' conveys a read-only, non-mutating operation. It doesn't describe output format, pagination, or authorization, but for a simple metadata look-up this is moderate transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two focused sentences with no filler. The action and resource come first, and the usage context follows directly, making it easy to scan and process.
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?
This is a low-complexity tool with a single optional and fully-described parameter. The description gives enough context for an agent to call it correctly and choose whether to pass reportType. The main gap is the lack of detail about the returned metadata structure, but the high-level 'metadata' statement partially mitigates that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully describes reportType with an enum and an 'Optional report type filter' description, so the baseline is 3. The description's mention of 'sync or async reports' aligns with the enum values and adds mild context, but it doesn't add substantial new meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Read') and a concrete resource path ('Pinterest resources/delivery_metrics'), and states that its purpose is to inspect official delivery metric metadata for sync or async reports. This makes the tool's function clear and distinguishes it from report-execution siblings, though it doesn't explicitly name an alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Use this to inspect...' provides an explicit use case, and 'for sync or async reports' clarifies the intended context. However, it doesn't discuss when to prefer other delivery-related siblings such as estimate_delivery or run_report, so exclusion guidance is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does well: it explicitly declares the operation is 'Read-only' and states it does not expose OAuth tokens, which addresses a key trust concern. It also lists the specific verifications performed. It does not describe error behavior or partial-failure semantics, but the security and side-effect transparency is strong.
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 compact sentence that front-loads the most important trait ('Read-only'), then efficiently lists what is verified and the security guarantee. Every phrase earns its place; there is no redundancy or 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?
For a simple health-check tool with one optional parameter and no output schema, the description covers purpose, scope, side-effect profile, and a security guarantee. It could add what the response looks like or what happens when checks fail, but the essential information an agent needs to decide to invoke it is present.
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% for the only parameter, adAccountId, and the schema already explains that it is optional and defaults to PINTEREST_AD_ACCOUNT_ID when configured. The description adds only a passing reference to 'configured credentials' and 'default account readability,' so it adds little beyond the schema. Baseline 3 is appropriate.
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 a specific action ('verifies') and a clear resource ('Pinterest Ads health check'), and enumerates what is checked: credentials, account access, delivery metrics access, and default account readability. It is clearly distinct from report-running or data-fetching siblings, though it does not name a specific alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied: it is a health check for verifying configuration and access before working with Pinterest Ads. However, the description does not explicitly say when to use this tool versus siblings like pinterest_validate_report, pinterest_list_ad_accounts, or pinterest_get_conversion_setup, and gives no exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It states the operation is read-only via 'Read' and transparently explains that lead-record export is intentionally excluded due to PII concerns. This gives meaningful behavioral context beyond the tool name, though it omits details like authentication needs or rate-limit 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 with no filler. The primary purpose is front-loaded, and the important PII exclusion is stated clearly as a secondary point. Every sentence earns its place.
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, no output schema, and no annotations, the description is too thin. It clarifies the broad purpose but leaves the agent without guidance on how to select modes, which parameters are required in which context, or what a successful response looks like.
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 14%, so the description must compensate for the 7 undocumented parameters. It only broadly maps to two categories (lead-form definitions vs. subscription configuration), which helps interpret the mode enum but does not explain adAccountId, leadFormId, subscriptionId, bookmark, pageSize, or the query object. This is insufficient for agents to reliably construct calls.
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 ('Read') and names the exact resources: lead-form definitions and lead subscription configuration. It also explicitly states what is excluded (lead-record export), which clarifies scope and differentiates this tool from potential data-export siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates that this tool is for reading lead-form definitions and subscription configuration, and it explicitly warns that lead-record export is not included. However, it does not name an alternative tool for lead-record export or specify conditions for when to use this over other Pinterest tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Read' signals a non-mutating operation and 'official catalog' signals the data source, but the description does not disclose output shape, pagination, rate limits, or authentication requirements. That is adequate for a simple read-only tool but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The primary purpose is front-loaded, and the secondary interest-ID resolution is added concisely. The description is easy to parse and does not repeat information already visible in the schema.
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 four parameters, no output schema, and no annotations, this description covers the core purpose and one important parameter but leaves 'query' and 'adAccountId' effectively unexplained. No parameters are required, so a minimal call is possible, but an agent needing a non-default or account-specific call would have insufficient guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema itself only documents the generic 'query' object, leaving schema description coverage at 25%. The description adds useful semantics by mapping the targeting categories to the targetingType enum and by indicating that interestId resolves a specific interest. However, it does not explain 'query' or 'adAccountId', so it only partially compensates 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 uses a specific verb ('Read'), identifies a precise resource ('Pinterest's official targeting option catalog'), and enumerates the supported categories: app type, gender, locale, age, location/geo, interest, keyword, or audience. It also adds the secondary capability of resolving a specific interest ID, which makes the tool's function clear and distinct from sibling report-generation tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool: when an agent needs targeting options for any of the listed categories, or needs to resolve a single interest ID. It does not explicitly name alternatives or exclusions, but the sibling context is mostly report/analysis tools, so the intended use is still reasonably unambiguous.
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:

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

Score Badge

Copy to your README.md:

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

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/getmcpads-com/pinterest-ads-mcp-server'

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