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

Annotations declare readOnlyHint=false and openWorldHint=true; the description adds that it uses the configured token (auth context) and implicitly that it performs no input validation and surfaces raw failures, unlike dedicated tools. It stops short of describing error/response shape or rate-limit behavior, so it is strong but not exhaustive.

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?

Four tight sentences, front-loaded with the 'Escape hatch' framing and the base URL constraint last. Every sentence carries decision-relevant information with no padding.

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 no-output-schema, open-world escape hatch with full param coverage, the description supplies the routing rule, examples, and base URL an agent needs to call it. It omits only response/error shape and pagination, which are minor for this generic proxy.

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 all four parameters are already documented, including the path examples and method enum. The description only reiterates that the path is relative to the v5 root, adding no syntax or format detail beyond the schema, so the 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 (issue an arbitrary request) and resource (Pinterest API v5) and explicitly frames itself as an escape hatch distinct from the dedicated siblings. An agent immediately understands this is the generic fallback rather than one of the specialized tools.

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 explicit when-to-use (endpoints no dedicated tool covers, with concrete examples: ad accounts, catalogs, audiences, conversion events) and when-not (prefer the specific tools when one exists), plus the reason — dedicated tools validate input and explain failures. Nothing 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=false, so the safety profile is covered. The description adds substantive behavioral context beyond that: it explicitly notes "Makes no network call" (a concrete, non-obvious trait) and explains the full side effect chain (browser open, user approval, redirect with code).

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?

Three sentences, front-loaded with verb+resource, and every sentence earns its place by adding scope, flow, or a behavioral constraint. No filler or redundancy.

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 local URL-builder with 100% schema coverage and no output schema, the description supplies everything an agent needs: what it produces, how it is used, what happens after redirect, and that it performs no network I/O. Nothing material 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 description coverage is 100%, so the schema already documents all four parameters including the CSRF role of `state` and the env-var fallbacks. The description adds the returned `code` query parameter detail but does not extend meaning on the input params themselves; baseline 3 is appropriate.

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 (build) and resource (the Pinterest consent/authorization URL) and clarifies the operational mode with "Makes no network call." It also distinguishes itself from the sibling pinterest_exchange_oauth_code by naming it as the next step, so an agent can place it in the OAuth flow without opening any schema.

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?

Describes the usage flow explicitly: open in a browser, user approves, Pinterest redirects with a `code`, then exchange via pinterest_exchange_oauth_code. This gives clear context for when to call it, though it doesn't state prerequisites (e.g. needing a registered redirect_uri) or when-not-to-use beyond the implied sequence.

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 write (readOnly=false), non-idempotent, non-destructive, open-world behavior, so the bar is lower. The description still adds genuine value by disclosing required OAuth scopes (boards:write, and boards:write_secret specifically for SECRET boards), which the agent cannot infer from annotations alone.

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 tight sentences with the operation front-loaded and the scope caveat second; no filler or redundancy.

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 write tool with full annotation coverage and 100% schema descriptions, the entry covers purpose, auth scope, and the SECRET exception. It omits error behavior (e.g. duplicate board names) and the returned identifier, but with no output schema that omission is minor.

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 parameter-linked meaning: choosing privacy=SECRET changes the required scope to boards:write_secret. That links a schema enum to an auth consequence the schema itself does not mention.

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 ("Create a new board") plus the target account, which cleanly separates it from the update/delete/list/get board siblings. The scope clause further qualifies the operation for SECRET boards.

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 never states when to choose this tool over alternatives (e.g. update_board, create_board_section) or any precondition beyond scope. The scope line is auth context rather than a when-to-use guideline, so guidance is essentially absent.

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 the safety profile (not read-only, non-destructive, non-idempotent, open-world). The description adds the required OAuth scope ('boards:write'), which is genuine auth context beyond the annotations. It stops short of noting the ad_account_id shared-asset behavior or what a successful call returns.

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, with the action front-loaded and the scope constraint following immediately. Every word earns its place.

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, so return values need not be explained, and the schema fully documents all three parameters. However, for a mutation tool the description omits failure behavior, idempotency implications, and the business-account nuance already hinted at by ad_account_id, leaving it only minimally viable.

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 board_id, name, and ad_account_id are fully documented in the schema itself, establishing the baseline of 3. The description adds no parameter-level detail beyond what the schema already provides.

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 ('Add a section to a board'), which clearly distinguishes it from the update/delete/list section siblings by name convention. It does not explicitly name those siblings, so an agent must infer the create-vs-update distinction, but the purpose is unambiguous.

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

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

The description gives a prerequisite ('Scope: boards:write') but no when-to-use guidance, no conditions for choosing this over pinterest_update_board_section or pinterest_create_board, and no exclusions. Usage must be inferred entirely from the name.

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 convey that this is a non-read-only, non-idempotent, non-destructive, open-world write. The description adds genuinely new behavioral context: the exact scopes needed (pins:write, and pins:write_secret on secret boards) and the required inputs. It does not discuss failure modes or rate limits, so it stops short of 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?

Three short, front-loaded sentences with no filler; the core action comes first and the constraints follow. The middle sentence is mildly redundant with the schema's required list, which is the only thing keeping it off a 5.

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 10-parameter create tool, the description correctly delegates the complex media_source variants to the schema and covers the points the schema cannot express (scope requirements). With no output schema, it could have hinted at what is returned (e.g. a pin id), which is the one 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 description coverage is 100%, and the media_source union already documents all four variants and their required fields in detail, so the schema carries the parameter burden. The description's mention of board_id and media_source only restates what the schema already marks as required, adding no new semantics.

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 (create a pin) and scopes it to "one of the authenticated user's boards." It does not, however, distinguish itself from the very similar sibling pinterest_save_pin, which an agent must choose between.

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?

It gives the prerequisites for calling (a board_id and a media_source must be supplied) and the OAuth scopes required, which is useful context. But it never says when to prefer this over pinterest_save_pin or pinterest_update_pin, so tool selection between near-identical 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 already declare destructiveHint=true, so the safety profile is covered structurally. The description adds genuinely non-redundant context: irreversibility ('This cannot be undone') and the cascade delete of all contained pins, plus the required OAuth scope. It stops short of return format or error behavior, but for a deletion call this 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.

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

Three short sentences, front-loaded with the destructive scope, then the irreversibility warning, then the auth requirement. No filler.

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 destructive tool with no output schema, the description covers the two things an agent most needs to know before calling: the cascade effect and irreversibility. Only return/error semantics and when-to-use are absent.

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 both parameters are documented in the schema, including the ad_account_id business-account nuance. The description adds nothing param-specific, so 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 (delete) plus resource (board), and explicitly names the cascade consequence ('AND every pin saved to it'). This distinguishes it from siblings like pinterest_delete_pin and pinterest_delete_board_section.

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?

No when-to-use guidance, no mention of alternatives (e.g., pinterest_update_board for reversible changes), and no stated prerequisites beyond the scope string. The agent gets no routing help.

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 destructiveHint=true and idempotentHint=true, and the description adds the non-obvious consequence that pins are not deleted but moved to the board root. It also names the required scope (boards:write), which is valuable auth context beyond annotations.

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

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

Three short sentences, front-loaded with the action, then the side effect, then the scope requirement. Every sentence earns its place with no redundancy.

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?

Covers the operation, the side effect on pins, and the required scope. No output schema exists, but the return isn't needed because the operation is a delete. It stops short of noting prerequisites like auth or whether the board must be owned, but is largely complete for a destructive tool.

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 only 33%, with board_id and section_id undocumented in the schema, but their names and required status make their purpose inferable. The description adds no parameter syntax or format details, and the optional ad_account_id has schema description coverage. Marginal value beyond 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+resource ('Delete a board section') that clearly identifies the operation and distinguishes it from sibling tools like delete_board or delete_pin. It doesn't explicitly name a sibling alternative, but the resource is unambiguous.

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?

Implied usage from the verb and resource, and the note about pins moving to board root gives useful post-condition context. However, no explicit when-to-use vs. alternatives (e.g., update_board_section, delete_board) is provided.

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 destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description reinforces irreversibility ('This cannot be undone') and adds a behavioral fact the annotations do not carry — the required OAuth scope 'pins:write'. That auth requirement is genuinely additive context.

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?

Three terse sentences with the action, the irreversibility warning, and the required scope — all front-loaded, zero filler.

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 two-parameter delete with full schema coverage and rich annotations, the description covers action, irreversibility, and auth scope, so an agent can call it safely. Only a brief note on the response (nothing returned on success) is missing, which is minor given the absence of an output schema.

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% and both parameters (pin_id, ad_account_id) are documented in the schema, including the nuanced ad-account delegation rule. The description adds nothing parameter-specific, so the baseline of 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 and resource ('Permanently delete a pin'), which cleanly separates it from the sibling delete_board and delete_board_section tools despite the shared 'delete' verb. The adverb 'Permanently' also signals irreversibility up front.

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 destructive nature and the required 'pins:write' scope imply when this is appropriate, but the description never names alternatives or states when NOT to use it (e.g. versus update_pin or save_pin). Usage is inferable from the purpose, not explicitly guided.

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 declare the write/idempotency profile, but the description adds genuinely new behavioral context: token lifetimes (~30 days vs ~1 year) and the instruction to store both securely. It still omits whether the code is single-use or what error conditions look like, so it stops short of 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 short sentences with no padding, front-loading the core action before the token-lifetime detail. Every clause carries information the agent would otherwise lack.

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 usefully names the return values (access and refresh tokens) plus their lifetimes, which is the key missing output information. It could go further on failure modes or re-use of the code, but it is solid for a simple four-parameter tool.

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 all four parameters (including the app_id/app_secret fallbacks and the redirect_uri must-match constraint) are already documented in the schema itself. The description adds no syntax or format detail beyond restating that `code` comes from the redirect URL, matching the baseline of 3.

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 (exchange) and resource (OAuth code → access/refresh tokens), which is clearly distinct from siblings like pinterest_build_oauth_url and pinterest_refresh_access_token. It does not explicitly name those siblings to draw the boundary, 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.

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

Phrases like 'the code from the OAuth redirect' imply this is the step after the authorization redirect, which gives reasonable context. However, it never states the sequence relative to pinterest_build_oauth_url or when pinterest_refresh_access_token should be used instead, leaving the workflow 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 and openWorldHint, so the safety profile is covered. The description adds genuinely useful non-annotation context: the required OAuth scope (boards:read) and a hint about the returned payload (pin/follower counts), which no output schema supplies.

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, front-loaded with the action and the scoping scope detail last. Nothing is redundant or padding.

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 simple two-parameter read with no output schema, the description covers the action, identifier source, auth scope, and partial return contents. It stops short of describing error/not-found behavior or the full response shape, but the essentials are present.

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%, including the note that board_id comes from pinterest_list_boards and that ad_account_id is only for shared-asset business accounts. The description adds nothing parameter-specific, so the baseline of 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 and resource ("Fetch a single board by id") and notes the returned data (pin and follower counts). The word "single" implicitly separates it from pinterest_list_boards and the get/update/delete board family, though no sibling is 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?

The presence of "by id" implies the tool requires a known board id, and the scope line signals read permission requirements, but there is no explicit when-to-use or when-not-to-use guidance (e.g., use list_boards to discover ids first, or get_board when you already have one).

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 the safety profile is covered. The description adds real behavioral value by disclosing the status progression registered -> processing -> succeeded (or failed) and the pins:read scope requirement, though it says nothing about rate limits or how to interpret a failed terminal state.

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?

Three short, front-loaded sentences with zero filler: purpose, state machine, and scope. Every clause earns its place and the core action is stated first.

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 reasonably conveys the meaningful return concept (the status field and its possible values), which is the key information an agent needs. It is slightly thin on what a failed result contains or whether other fields are returned, but it is complete enough for a single-parameter status tool.

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% and there is a single parameter, so the schema already documents media_id and its origin from pinterest_register_media. The description adds no syntax or format detail beyond that, matching the baseline for schema-driven params.

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 ('Check a registered upload') and reinforces it with the status state machine, which clearly separates it from pinterest_register_media (creates) and pinterest_list_media (enumerates). An agent can tell exactly what this does.

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?

Implies the usage context by tying it to 'a registered upload' and describing the status lifecycle, telling the agent this is a polling/verification call after registration. It does not explicitly name alternatives or state when not to use it, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the required auth scope ('pins:read'), which is genuinely useful context not present in structured fields, but it discloses nothing about rate limits or result shape. With annotations carrying the safety burden, a 3 is appropriate.

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

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

Two tight sentences with no waste; the batching benefit and the sibling comparison are front-loaded, and the scope constraint is appended compactly.

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 batch analytics tool with full schema coverage and no output schema, the description covers purpose, routing, and auth scope adequately. Only minor gaps remain, such as return format or batching cost behavior, none of which would cause a misinvocation.

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 all six parameters, including the 90-day window constraint and enum values, are already documented in the schema. The description's only added detail, the 100-pin cap, merely restates maxItems. Baseline 3 is correct when the schema does the heavy lifting.

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+scope ('Analytics for up to 100 pins in one call') and explicitly names the sibling it replaces (pinterest_get_pin_analytics). An agent can distinguish it from pinterest_get_pin_analytics and pinterest_get_user_analytics without opening any schema.

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?

Names the alternative tool and gives the condition that favors this one ('far cheaper than looping pinterest_get_pin_analytics'), which is the key routing signal. It stops short of stating when NOT to use it (e.g., for a single pin), so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered; the description still adds the required OAuth scope (pins:read) and the default response contents, which the annotations do not convey. It omits error behavior and whether a 404 is returned for missing pins, keeping it short of 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?

A single front-loaded sentence naming the operation and returned fields, followed by a terse scope clause. Nothing is redundant or padded.

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 single-object read with no output schema, the description tells the agent what the response contains and what scope it needs; the only mild gap is that it does not indicate whether the optional pin_metrics flag changes the payload, which the schema does cover.

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 pin_id, pin_metrics and ad_account_id are already fully documented in the schema. The description adds no syntax or format detail beyond the schema, so the 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 (Fetch) and resource (a single pin by id) and enumerates what the payload contains (media, link, board). The word 'single' implicitly separates it from list_pins and search_my_pins, though no sibling is 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?

The 'Scope: pins:read' clause tells the agent the authorization requirement, which is genuinely useful usage context, but there is no statement of when to prefer this tool over pinterest_get_pin_analytics or pinterest_list_pins. Usage is implied rather than directed.

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 the safety profile is covered. The description adds the required OAuth scope ('pins:read'), which is genuinely useful auth context not present in the annotations. It does not mention rate limits or what a partial/failed window returns.

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 tight sentences with zero filler; the resource and window constraint are front-loaded, and the auth scope is appended as a short clause. Nothing could be trimmed without losing content.

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 analytics fetch with a fully documented schema and no output schema, the description covers the essentials: single-pin scope, window bound, and required scope. It stops short of clarifying what 'daily' granularity returns or how split/metric parameters shape the response.

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 the schema already documents all seven parameters including the date constraints, enum values, and metric list. The description's only added parameter-relevant fact is the 90-day window, which the schema already states for both dates. 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?

Specific verb+resource: 'Daily analytics for a single pin over a date window of up to 90 days.' The word 'single' implicitly distinguishes it from sibling pinterest_get_multi_pin_analytics and pinterest_get_user_analytics, though no sibling is 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?

The description states scope ('single pin', 'up to 90 days') but gives no when-to-use guidance, no conditions that route the agent to get_multi_pin_analytics or get_user_analytics, and no exclusions. Usage must be inferred from the tool name alone.

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 the safety profile is covered. The description adds genuinely useful non-schema context by naming the required scopes (user_accounts:read, pins:read), but it says nothing about pagination, rate limits, or what happens at the 90-day boundary.

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?

A single dense sentence with the core action and the usage cue front-loaded, then the permission scope. No filler, though it is arguably terse given 11 parameters.

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 should carry more of the return-value and routing burden. It explains the ranking concept and permissions, but omits sibling disambiguation and any sense of what a ranked result contains, leaving a meaningful gap for a tool with this many parameters.

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 73%, so the schema already documents most parameters including sort_by, the date bounds, and metric_types. The description only paraphrases "by a metric over a date window," adding no format or constraint detail beyond what the schema carries. Baseline 3 is appropriate.

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?

The description uses a specific verb ("Rank") and resource ("the account's pins") with the mechanism ("by a metric over a date window"). However, it never distinguishes itself from the very close sibling pinterest_get_top_video_pins, which an agent could easily swap in.

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 tool to reach for when asked what is working" gives a scenario, which is more than nothing. But there are no conditions for choosing among the analytics siblings (get_top_video_pins, get_pin_analytics, get_multi_pin_analytics) and no when-not guidance.

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. The description adds the required OAuth scopes (user_accounts:read and pins:read), which is useful behavioral context for a read tool. It does not describe pagination, result ordering behavior beyond metric sorting, or rate limits.

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

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

Two tight sentences with no waste; the operation and scope are front-loaded. Efficient, though the scope sentence is somewhat boilerplate.

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 11 parameters, no output schema, and only 55% schema coverage, the description is thin. It covers the core operation and auth scope but leaves many parameters (sort_by, metric_types, filtering enums, ad_account_id) for the agent to infer solely from schema.

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 55%, with the required date params and metric_types documented in the schema. The description adds no parameter detail — no mention of date-window constraints, sort_by metric values, or defaults. Baseline 3 given partial schema coverage and the description carrying little of the gap.

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: 'Rank the account's video pins by a video metric over a date window' — clearly identifies ranking operation over video pins. It doesn't explicitly differentiate from the sibling pinterest_get_top_pins, which is a near-identical tool for non-video pins, but the 'video' qualifier does imply the distinction.

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?

Implied usage: 'Rank the account's video pins by a video metric over a date window' tells you what it does but not when to choose it over pinterest_get_top_pins or pinterest_get_pin_analytics. No exclusions or alternatives named despite several analytics siblings.

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 the safety profile is covered. The description adds the required scope (user_accounts:read), which is genuine auth context beyond the annotations, though it says nothing about rate limits or error behavior.

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?

Three tight sentences, front-loaded with what is returned, then the pragmatic use case, then the scope requirement. No filler; every clause earns its place.

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 no-required-param read tool with no output schema, the description supplies the return fields, the scope prerequisite, and the motivating use case. An agent has everything needed to call it correctly.

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?

The single optional ad_account_id parameter is fully documented in the schema (100% coverage), so the schema does the heavy lifting. The description never references it, adding no meaning beyond the structured field — baseline 3.

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 (fetch) and resource (the authenticated user's account), and enumerates exactly what comes back: username, id, account type, profile image, follower counts. This clearly distinguishes it from siblings like pinterest_list_followers or pinterest_get_user_analytics, which cover related but different resources.

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 concrete use case ('The fastest way to verify a token works'), which tells the agent when this cheap read is the right choice. It stops short of naming alternatives or exclusions, so it is clear context without full routing guidance.

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 establish readOnlyHint and openWorldHint, so the lower bar applies. The description still adds non-structured context: the required OAuth scopes and the 90-day date-window ceiling. It omits rate-limit or pagination behavior, but the auth-scope disclosure is exactly the kind of added value credited at this level.

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 with zero filler, and the most important scoping fact (daily, account-level, 90-day window) is front-loaded ahead of the permission note.

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 is the only place that could characterize the returned metrics, and it stops at 'daily account-level analytics' without describing the shape of the response or the split_field behavior. Combined with read-only annotations and a fully documented 10-param schema, this is adequate but leaves a real gap for a reporting tool.

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% across all 10 parameters, including enum meanings and the 'omit for all available' behavior of metric_types, so the schema carries the semantics. The description adds only the 90-day window constraint, which is already echoed in the start_date/end_date schema text, so 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 (get) and resource (account-level analytics) plus the granularity (daily) and window limit (up to 90 days). The 'account-level' qualifier implicitly separates it from per-pin siblings like pinterest_get_pin_analytics, but no sibling is 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?

Usage is only implied: an agent can infer this is for aggregate account reporting rather than per-pin reporting. It does add a prerequisite signal by naming the required OAuth scopes (user_accounts:read, pins:read), but it never says when to prefer this over pinterest_get_pin_analytics, pinterest_get_multi_pin_analytics, or pinterest_get_top_pins.

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 the safety profile is covered. The description adds the required OAuth scopes (pins:read, boards:read), which is genuinely useful auth context, but says nothing about pagination behavior, rate limits, or result shape for a list tool that exposes a bookmark cursor.

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 that are front-loaded with the core action, followed by the scope requirement. Nothing is wasted and no preamble delays the substance.

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?

Parameters are fully documented and no output schema exists, so return-value explanation is not required. However, for a list tool sitting among several similarly named listing siblings, the definition omits the routing guidance and pagination context an agent needs to pick and invoke it confidently.

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 all six parameters (board_id, bookmark, page_size, pin_metrics, ad_account_id, creative_types) are already documented in the schema. The description adds no parameter-level detail beyond that baseline.

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 (List) and resource (pins saved to a board), so the core action is unambiguous. It does not, however, differentiate itself from close siblings such as pinterest_list_board_section_pins or pinterest_list_pins, leaving the agent to infer the distinction.

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 offers no when-to-use guidance, no exclusions, and no mention of alternatives among the many sibling list tools. The agent must infer that this is the board-wide (non-section) listing from the name alone.

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

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

Annotations already declare readOnlyHint/openWorldHint, so the safety profile is covered. Beyond that, the description adds real behavioral context: sort order (newest first), the exact OAuth scopes required, and the fact that a bookmark cursor is returned when more pages exist — useful details the annotations cannot express.

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?

Three short sentences, front-loaded with the operation and scope, then pagination. Every clause earns its place with no filler.

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 list tool with no output schema, the description covers scope, ordering, scopes, and pagination behavior adequately. It could be slightly more complete by clarifying the relationship to sibling list/search tools, but nothing essential for correct invocation 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 description coverage is 100%, so all four parameters (privacy, bookmark, page_size, ad_account_id) are already well documented in the schema. The description's note that boards:read_secret is needed for secret boards duplicates the schema's own privacy note, adding no new parameter semantics. Baseline 3.

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 ('List the authenticated user's boards') plus a meaningful ordering guarantee ('newest first'). It clearly scopes to the authenticated user, which implicitly separates it from general searches, but it never names the closest sibling (pinterest_search_my_boards) to make the distinction 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?

The description states required scopes, which functions as an implicit precondition for use, but it gives no when-to-use/when-not guidance and does not route the agent to alternatives like pinterest_search_my_boards or pinterest_get_board. Usage context is only implied.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds the required OAuth scopes (pins:read, boards:read), which is exactly the auth context annotations do not supply. It stops short of describing pagination behavior, but the bookmark/page_size parameters carry that.

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, purpose first and the scope requirement second. No filler; every clause conveys information.

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 list tool with no output schema, the description plus annotations plus the bookmark/page_size schema fields are nearly sufficient. The minor gap is that it never signals the response is paginated or that ads delegation is possible, though those live in the schema.

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 67%, with board_id, section_id, and pin_metrics essentially undocumented. The description adds no parameter-level detail (no mention of bookmark pagination, page_size, or the ad_account_id delegation case), so it neither compensates for the gap nor duplicates 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 (List) and resource (pins saved inside one section of a board), which cleanly separates it from pinterest_list_board_pins and pinterest_list_board_sections. It does not explicitly name those siblings, so routing relies on the reader noticing the 'section' scope.

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?

Usage is implied by the scope ('one section of a board'), so an agent can infer when it applies, but there is no explicit when-to-use/when-not or named alternative (e.g., use pinterest_list_board_pins for the whole board).

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 the safety profile is covered. The description usefully adds the required auth scope (boards:read), which is genuine context beyond the annotations, though it omits pagination behavior (documented in schema) and 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.

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

Two compact sentences with zero waste; the core action is front-loaded and the scope requirement follows succinctly.

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 list tool with full schema coverage, no output schema, and annotations carrying the safety profile, the description is nearly complete. Naming the scope is a helpful addition; little else is required for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so all four parameters (board_id, bookmark, page_size, ad_account_id) are fully documented in the schema. The description adds no parameter-level meaning beyond that, making the baseline 3 appropriate.

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 (List) and resource (sections within a board), which is clearly distinct from list_board_pins and list_board_section_pins. It does not explicitly name which sibling it differs from, but the resource scope is unambiguous.

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 does not state when to prefer this over alternatives (e.g. list_board_section_pins) or any exclusions. It does disclose the required OAuth scope (boards:read), which serves as an implied prerequisite for calling it.

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 is covered without the description. The description adds the required scope (user_accounts:read) and the verification-status return content, but says nothing about pagination behavior beyond what the schema implies, nor about empty results.

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

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

Two clauses, front-loaded with the action and resource, zero waste. The scope note is efficiently appended.

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 no-required-param read tool whose annotations and schema carry the structure, this covers purpose and scope, but there is no output schema and the description does not explain the return shape beyond naming verification status, leaving moderate gaps.

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 both parameters (bookmark, page_size) are fully documented in the schema. The description adds no parameter 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 (list claimed websites) and adds the extra content it returns (verification status). It does not name a sibling or distinguish itself from pinterest_get_user_account, but the resource is unambiguous.

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?

Usage is implied by the read-only 'list' nature and the required user_accounts:read scope, but there is no explicit when-to-use/when-not guidance and no alternative named from the large sibling set.

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 the safety profile is covered. The description adds a genuinely useful non-schema detail, the required OAuth scope (user_accounts:read), but says nothing about pagination behavior or rate limits beyond what the schema already documents.

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 with zero filler; the operation is front-loaded and the scope constraint is appended compactly. Every clause earns its place.

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 paged list, the description plus annotations and a fully documented schema cover what an agent needs to invoke it correctly. Nothing explains the shape of returned account objects, but that gap is minor for a simple listing tool with no output schema.

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%, with bookmark and page_size fully documented in the schema itself, including defaults and ranges. The description adds no parameter meaning beyond that, so the 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?

The description states a specific verb and resource ('List the accounts following the authenticated user'), which correctly frames the follower direction and implicitly distinguishes it from the inverse pinterest_list_following. It stops short of naming that sibling explicitly, so an agent must infer the distinction.

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?

There is no when-to-use guidance and no mention of pinterest_list_following, the obvious inverse operation an agent could confuse this with. The only cue is the phrasing 'following the authenticated user,' which is left for the reader to interpret.

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 is covered. The description adds a genuine behavioral fact beyond the annotations: the required OAuth scope (user_accounts:read), which tells the agent what auth the call needs. It stops short of noting pagination behavior or rate limits, hence not 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 short sentences with zero filler; the core action and resource come first, followed by the scope requirement. Nothing is redundant with the title or schema.

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 paginated list with fully documented parameters and no output schema, the description covers purpose, scope, and limitations adequately. It could add a note on result shape or the meaning of a returned bookmark, but nothing critical to a correct invocation 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 description coverage is 100%, so bookmark, feed_type, and page_size are each fully documented in the schema, including the enum values and 1-250 range. The description adds no parameter-level detail, which is the expected baseline when the schema carries the load.

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 (List) and resource (users and boards the authenticated user follows), clearly identifying the outbound-follow relationship. It does not explicitly name pinterest_list_followers as the inverse operation, so an agent must infer the direction distinction from the wording alone.

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?

Usage is implied by the description's directionality ('who the authenticated user follows'), which is enough to distinguish it from list_followers. However, there is no explicit when-to-use statement or guidance on choosing among the many list_* siblings (list_boards, search_my_boards, etc.).

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 the safety profile is covered. The description adds the required OAuth scope, which is real value, but says nothing about pagination, ordering, or what 'status' values look like. Adequate but not rich.

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

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

Two short sentences, front-loaded with the action and scope constraint, with no filler or redundancy.

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 listing tool with full parameter coverage and no output schema, the description covers what is returned (uploads and their statuses) and the auth requirement. Minor gaps around pagination and result shape, but nothing an agent needs in order to call it correctly is missing.

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

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

Schema description coverage is 100%: bookmark and page_size are both fully documented in the schema, including the 1-250 range and the default of 25. The description adds nothing about parameters, so the 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 (List), resource (the account's registered media uploads) and an extra detail (their statuses), which distinguishes it from the singular pinterest_get_media and the write-side pinterest_register_media. It does not name those siblings explicitly, 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.

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

The 'Scope: pins:read' note tells the agent the required permission, which is genuinely useful context, but there is no explicit when-to-use guidance or routing to pinterest_get_media for a single upload. Usage is only implied by the plural 'list' framing.

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 cover readOnlyHint and openWorldHint, so the safety profile is already known, but the description adds real context: results are ordered newest first and the call requires pins:read with pins:read_secret for secret-board pins. It does not mention pagination mechanics, though the bookmark parameter schema carries that.

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, with the core action and ordering stated first and the auth scope second. Every clause earns its place.

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 an 8-parameter, zero-required listing tool with no output schema, the description covers scope and ordering but is silent on pagination behavior and the shape of results. Adequate as a minimum, but not fully sufficient given the parameter surface.

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 63%, leaving several parameters (pin_type, creative_types, include_protected_pins) undocumented, and the description adds no parameter meaning at all. With 8 parameters and no compensating detail, this falls below the baseline-3 case.

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 (List) and resource (the authenticated user's pins), and the 'authenticated user's' framing implicitly separates it from board-scoped siblings like pinterest_list_board_pins. It does not name a sibling explicitly, so it stops short of a 5.

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

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

There is no when-to-use guidance and no routing to alternatives such as pinterest_search_my_pins or pinterest_list_board_pins. The only scoping statement is the auth requirement, which is not usage guidance.

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 convey the safety profile (readOnlyHint=false, destructiveHint=false, non-idempotent, open-world). The description adds the key operational trigger (401 failures), which is the behavior an agent most needs. It does not mention token lifetime or whether the old refresh token is rotated, which would be a useful extra.

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 tight sentences: the mechanism first, the trigger second. No filler, everything front-loaded.

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 simple token-exchange tool with full schema descriptions and no output schema, this covers what an agent needs to call it correctly. The remaining gap is return-value shape, which is not strictly required since no output schema exists.

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 all four parameters are already documented, including fallback behavior for app_id/app_secret and the scope-narrowing semantics. The description adds nothing beyond the schema, so the 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?

Specific verb ('Trade') and resource ('refresh token for a fresh access token'), and it clearly distinguishes itself from the OAuth siblings (build_oauth_url, exchange_oauth_code) by naming the refresh-token exchange.

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?

Explicitly states the triggering condition: 'Use this when calls start failing with 401.' That gives the agent a concrete signal for when to invoke this rather than retry or re-authorize.

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, idempotentHint=false and openWorldHint=true, so the write/non-repeatable/open-world profile is covered. The description adds genuinely new behavior: credentials are one-time, require a multipart POST to an external S3 endpoint, and progress must be confirmed by polling another tool. It stops short of describing credential expiry timing or failure/retry behavior, so not 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?

One dense sentence front-loads the step number and outcome, then chains the follow-up actions with zero filler. It is slightly run-on and would read better split into two sentences, but every clause carries actionable information.

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 compensates by naming what comes back (one-time S3 form fields / upload_url / upload_parameters) and how to use it. Combined with the scope note and the poll-then-create handoff, an agent has everything needed to complete the video upload workflow without guessing.

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?

Only one parameter (media_type, const 'video') and schema coverage is 100%, so the schema fully documents the input; the description adds nothing about it. Baseline 3 applies. The only extra semantics, source_type 'video_id' and the S3 fields, belong to downstream tools rather than this 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+resource ('register an upload') and immediately positions it as 'Step 1 of video pin creation', distinguishing it from the read/list siblings and from pinterest_create_pin. An agent knows exactly what this call produces: one-time S3 form fields.

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 the full when-and-what-next chain: POST the video to upload_url with the returned upload_parameters, poll pinterest_get_media until status is 'succeeded', then hand media_id to pinterest_create_pin with source_type 'video_id'. It also names the required scope (pins:write), so an agent can pre-check authorization.

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, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description usefully adds the required auth scope ('pins:write'), which annotations do not convey, but says nothing about duplicate-save behavior or what a repin returns.

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?

One tight sentence plus a scope tag; the operation is front-loaded and no words are wasted. Appropriate size for a simple two-required-param mutation.

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-param non-idempotent write with full schema coverage and no output schema, the description covers purpose and auth scope adequately. It could additionally note duplicate-repin handling, but nothing essential for invocation 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 description coverage is 100%, so all four parameters (pin_id, board_id, ad_account_id, board_section_id) are already documented in the schema. The description adds no parameter-level detail, making the baseline 3 appropriate.

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 an existing pin') and clarifies the domain term as a repin, which implicitly separates it from pinterest_create_pin. It does not name any sibling explicitly, so it falls just 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.

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

The phrase 'existing pin' implies this is for repinning rather than creating, which edges toward usage context, but there are no explicit when/when-not statements or named alternatives. A single added clause about create_pin vs save_pin would raise this materially.

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 the safety profile is covered. The description adds genuinely useful auth context ('Scope: boards:read'), but says nothing about pagination behavior or result shape beyond what the schema implies.

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 with zero waste; the core action and scope are front-loaded before the auth note.

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 search tool, annotations carry the safety profile and the schema fully documents inputs, so little is missing. No output schema is present, but the returned boards and cursor semantics are self-evident enough that the definition is adequate.

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%, with each of the four parameters fully documented (including the bookmark cursor and page_size range). The description adds no parameter detail, so the 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 (full-text search) and resource (boards) scoped to the authenticated user's own boards, which separates it from pinterest_list_boards (enumeration) and pinterest_search_my_pins (pins). It distinguishes reasonably from siblings but never names them 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?

The 'own boards' scoping plus full-text qualifier implies when this is appropriate versus a plain list, but there is no explicit when-to-use/when-not guidance or named alternative. Usage 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 and openWorldHint, so the safety profile is covered. The description adds non-obvious behavioral context beyond that: the required OAuth scope ('pins:read') and the API-level limitation that only the user's own pins are searchable.

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 tight sentences with zero filler; the core scope is front-loaded and the limitation and required scope follow immediately. Every clause earns its place.

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 search with no output schema, the description covers purpose, scope, and auth requirement adequately; pagination and result format are handled by the schema's bookmark/page_size documentation. Only minor detail about result shape or default behavior is absent.

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 all four parameters (query, bookmark, page_size, ad_account_id) are documented in the schema itself. The description adds no syntax or format detail about them, which matches the baseline for fully-covered schemas.

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 ('Full-text search') and resource ('the authenticated user's own pins'), and explicitly rules out global discovery search. This distinguishes it cleanly from siblings like pinterest_list_pins and pinterest_search_my_boards without opening either schema.

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?

Provides a clear usage boundary ('This does NOT search Pinterest globally — the v5 API exposes no public discovery search'), which tells the agent when the tool is and isn't applicable. It does not, however, name or route to sibling alternatives such as list_pins for browsing versus searching.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value beyond them by stating that unpassed fields are left untouched and that the boards:write scope is required, which tells the agent this is a safe, partial, non-destructive mutation.

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?

Three short, front-loaded sentences: capability, mutation semantics, then scope. Every clause carries information and there is no redundancy.

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 and a simple 5-parameter update, the description covers the essentials: which fields mutate, partial-update behavior, and the required OAuth scope. Minor gaps remain around the privacy options and error/edge behavior, but nothing critical to invoking it 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 description coverage is only 40% (only board_id and ad_account_id are documented), so the description must compensate. It partially does by naming the three updatable fields, but it adds nothing about the privacy enum semantics or the ad_account_id 'shared asset' requirement, which the schema only briefly covers.

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?

The description gives a specific verb+resource ('Update a board') and enumerates the exact mutable fields (name, description, privacy), so an agent knows precisely what the tool changes. It does not explicitly differentiate itself from siblings like pinterest_create_board or pinterest_update_board_section, which keeps it just 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.

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

'Only the fields you pass are changed' clarifies partial-update semantics and the 'boards:write' scope states a prerequisite, which is real usage context. However, it never says when to choose this tool over pinterest_update_board_section or pinterest_create_board, so usage is only implied.

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, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the mutation and safety profile is covered. The description adds the required OAuth scope (boards:write), a genuinely useful behavioral detail not present in annotations, but says nothing about what the rename affects or whether the section must already exist.

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 with the action stated first and the scope constraint second; no filler or redundancy.

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 mutation tool with annotations present and no output schema, the description covers the action and permission scope but leaves the required identifiers and the business-account ad_account_id nuance entirely to the schema. It is minimally adequate rather than complete.

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 only 50% - name and ad_account_id are documented in the schema, while board_id and section_id carry no description anywhere. "Rename" loosely implies name is the target value, but the description adds no semantics beyond the schema and does not compensate for the two undocumented identifier parameters.

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?

The description gives a specific verb (rename) and resource (existing board section), which clearly separates it from create_board_section and delete_board_section. However, it does not name or contrast any sibling tool explicitly, so it stops short of full differentiation.

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?

"Scope: boards:write" implies the prerequisite permission, which gives the agent a usable gating condition. There is no explicit when-to-use guidance or comparison against alternatives such as pinterest_update_board or pinterest_create_board_section, so usage is only implied.

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 safety profile: readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds valuable context by disclosing the required OAuth scope (pins:write) and the immutability of media after creation. It does not, however, clarify partial-update behavior or whether unspecified fields are preserved.

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?

Three concise sentences front-load the core action, then add the media constraint and auth scope. Every sentence earns its place with no redundant restatement of the title or schema.

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 nine-parameter mutation tool with no output schema, the description covers purpose, media immutability, and the required scope. It leaves partial-update semantics and some parameter-level detail unstated, but annotations and schema fields fill much of 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 description coverage is 44%, below the 50% threshold, so the description must compensate. It groups parameters into text fields, link, and board placement, which helps map the nine inputs, but it does not explain individual parameters such as alt_text, title, note, board_section_id, or ad_account_id beyond what the schema already partially documents.

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?

The description uses a specific verb (Update) and resource (a pin's text fields, link or board placement), and explicitly excludes media changes. It distinguishes itself from pinterest_create_pin by noting that media cannot be changed after creation, so an agent can tell the tools apart without opening schemas.

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?

It clearly states what can be updated and notes that media cannot be changed after creation, which is an implied when-not condition. However, it does not name explicit alternatives (e.g., pinterest_create_pin for media changes or pinterest_delete_pin for removal) or give full when-to-use guidance beyond the field scope.

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