Pinterest MCP

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

readOnlyHint and openWorldHint already declare the safe-read, open-web nature, so the description only needs to add context. It contributes one genuinely useful constraint — the board must be public — but says nothing about pagination limits, rate limiting, or what happens with an invalid/private board URL, which is the main failure mode for an open-world read tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, zero filler, and the core action is front-loaded ahead of the input-format tip. Nothing extraneous.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 5-parameter list tool with full schema coverage and no output schema, the description covers purpose, access scope, and input sourcing adequately. It doesn't preview the shape of the response (pin fields, next_bookmark paging), but the schema's bookmark description carries that.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every parameter, including the board URL vs. '<user>/<board>' formats, is already documented in structured form. The description restates the board format without adding syntax or edge-case detail, so baseline 3 is correct.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — 'List the pins saved on a public board' — with the important scope qualifier 'public'. An agent can distinguish it from pinterest_search or pinterest_get_pin without opening the schema, though sibling tools are never named explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear context for when this is the right tool and where the required input comes from ('e.g. one found in a search result's board.url'), and the word 'public' implicitly excludes private boards. It stops short of naming an alternative for keyword-based discovery (pinterest_search) or single-pin lookup (pinterest_get_pin).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=true, so safety profile is partly covered. The description adds meaningful behavior beyond that: files are written to disk at a default path (/root/Downloads/pinterest-mcp/<folder>), resolution falls back to 736px when originals are unavailable, and saved paths are returned. It omits overwrite/duplicate-name behavior, which keeps it from a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two compact sentences with the core action and destination front-loaded, then the return value. Every clause carries information; minor dash/semicolon density is the only cost.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 4-parameter file-producing tool with no output schema, the description covers destination defaults, resolution behavior, accepted URL types, and return value ('saved file paths'). Only overwrite/naming behavior for repeated downloads is left unspecified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds value beyond the schema: it clarifies that image_urls accepts both image_url and video_url (*.pinimg.com) values and explains the resolution fallback semantics tied to the 'size' parameter. The 'directory'/'folder' relationship is only lightly implied (via the shown default path).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Save pin images ... and videos ... to disk') and disambiguates by scope from the read-only siblings (search, get_pin, related_pins, board_pins, preview_images). An agent can immediately tell this is the write-to-disk tool rather than another pin lookup.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage ('image_url or video_url values from other tools') but never explicitly states when to call this versus pinterest_preview_images, nor any prerequisite such as running a search first. The up-front 'values from other tools' hint is useful but the alternative routing is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds non-obvious behavior beyond that: the failure mode for e1_ prefixed ids and the fact that the payload is a full single-pin detail record. It does not say what happens on an invalid or missing pin, but the additions are substantive for an annotated read tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero waste. The capability and its returned fields come first, and the exclusion caveat follows, which is the right ordering for an agent scanning for fit.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the inline enumeration of returned fields carries the return-value contract and does so adequately. With annotations covering safety and the schema covering both parameters, nothing an agent needs to call this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description goes further by constraining the 'pin' argument — it is a link or numeric id, and e1_ style ids are invalid. That value-level restriction is not expressed in the schema and prevents a predictable error.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Get full details for one pin') and enumerates the returned fields (description, image, source, board, creator, saves, comments), so the agent knows exactly what it gets back. It also explicitly distinguishes itself from the listing/search path by ruling out anonymous e1_ ids.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear negative case — anonymous search ids cannot be looked up because their data is already in the search result — which steers the agent away from a wasted call. It does not name a sibling tool explicitly (pinterest_search, pinterest_related_pins) as the alternative, leaving that inference to the agent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnlyHint, openWorldHint), and the description adds genuinely non-structured context: the result is visual content the agent can actually perceive, and URLs are meant to come from other tools. It does not cover failure modes for invalid/non-pinimg URLs or what happens with fewer than the max items.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the core action and purpose, with the batch limit trailing. No filler to remove.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, and the description does explain what comes back (small thumbnails the agent can view), which is the key unknown for a multimodal tool. It could say more about behavior on partial failures or oversized batches, but nothing essential to a correct call is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds provenance ('image_url values from other tools') that tells the agent where legitimate inputs originate, which the schema's 'i.pinimg.com image URLs' does not fully convey. The size parameter's tradeoff is left entirely to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a concrete verb and resource ('Fetch small thumbnails of pin images') and clarifies the intent ('so you can see them'), which separates it from text-returning siblings like pinterest_get_pin. It never names pinterest_download, which is the obvious alternative for full-size images, so sibling differentiation is implied rather than explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

'so you can see them' implies the scenario (visual inspection) and the parenthetical points at chained calls, but there is no explicit when-to-use/when-not statement and no named alternative such as pinterest_download for full-resolution images. Usage is inferable rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and openWorldHint, so safety and scope are covered; the description adds the similarity-based nature of results. It says nothing about pagination (the bookmark parameter) or that results are ranked by visual/topical proximity — useful context the annotations do not carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, zero waste, with the core purpose front-loaded and the prerequisite last. Readers get the intent and the input constraint in one pass.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only, single-required-param query tool with full schema documentation and no output schema, the description covers what is needed to call it correctly. A note on paging through bookmark or how similarity ranking behaves would close the remaining gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so every parameter including limit, media, bookmark and previews is already documented. The description restates the pin-accepts-link-or-id rule from the schema without adding format or edge-case detail. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource+relation: find pins visually and topically similar to a given pin, with the "More like this" gloss making the semantics unmistakable. It implicitly distinguishes itself from pinterest_search (keyword discovery) and pinterest_get_pin (fetch one pin), though it never names a sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Adds one real usage condition — "Needs a real pin link or numeric id" — which warns the agent it must first resolve a pin before calling. There is no explicit when-not or named alternative (e.g. "use pinterest_search for keyword discovery"), so routing between siblings is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare readOnlyHint and openWorldHint; the description adds substantial behavior: promoted pins are filtered out, pins under 500px are flagged low_res, video pins carry video_url and video_seconds, and pagination flows through next_bookmark. That is exactly the operational context annotations cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and return shape, then behavior, then parameter guidance, then tips — a sensible ordering with no filler sentences. It is dense but long for a single paragraph; the field enumeration could be tightened slightly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the return-value burden and does so fully: field list, video extras, low_res flag, filtering of promoted pins, and paging. An agent has everything needed to call it and interpret results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, but the description adds intent behind parameters — media="video" is tied to motion/interaction references, previews to judging style/layout/colour, and bookmark to paging. The 500px low_res threshold also adds semantics not present in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Search Pinterest pins by keyword'), plus the scope qualifier 'any language' and the intent ('for visual inspiration'). This is clearly distinguishable from siblings like pinterest_board_pins or pinterest_get_pin, which retrieve pins by board or id rather than keyword.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete conditional guidance: set media to "video" for motion references, skip low_res pins when a full-size reference is needed, use next_bookmark to page further, and steer style with keywords like "ui" or "poster". It never explicitly routes to or excludes a sibling tool (e.g. board_pins vs keyword search), which keeps it from a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.