pinbridge

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

Annotations already mark it readOnly, idempotent, and non-destructive; the description adds substantial behavioral detail: it returns a structured verdict, may be served from cache, skips when Pinterest is unreachable, never raises for a bad board, and fails with not_found only for unknown accounts. This goes well beyond annotation-only disclosure.

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?

The description is front-loaded with the core purpose, followed by clear usage guidance and a compact but valuable enumeration of return fields. Every sentence adds information, and the structure makes it easy for an agent to quickly identify what the tool does and when to use it.

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 check tool with no output schema, the description covers purpose, when to use it, the alternative, return values, failure modes, cache behavior, and edge-case behavior. No critical information is missing for correct selection and invocation.

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

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

Schema coverage is 100%, so the schema already documents account_id, board_id, and fresh. The description adds context about the cache source and unknown-account failure, but does not significantly expand the meaning of the parameters 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?

The description states a specific verb and resource: 'Check whether an account can publish to a board right now, and why not.' This clearly distinguishes it from sibling tools by framing it as a pre-publish access check rather than a publishing or board-management action.

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 explicit usage conditions: use before publishing to a board not used recently, or after a publish fails with a board_* code. It also names the alternative (create_pin with dry_run=true) for a full pin-level preflight, making the decision boundary clear.

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?

The description goes well beyond annotations by disclosing the return shape (board with id, name, description, privacy), and enumerating specific failure modes: forbidden (sandbox_board_limit), token_expired, and scope_missing with missing_scopes ["boards:write_secret"]. This gives the agent actionable context for handling errors, which the annotations (readOnlyHint=false, idempotentHint=false) do not provide.

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?

The description is front-loaded with the core purpose, then organized into usage guidance and failure modes. Every sentence is informative: the duplicate-name warning, the one-off pin alternative, the return format, and the sandbox/auth errors all earn their place. No filler or repetition.

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?

Given there is no output schema, the description's return-format disclosure is essential and fully covers what an agent needs. It also addresses the two main external failure categories (sandbox caps and auth/scope issues), making the tool self-sufficient for correct invocation and error handling. Sibling context is handled via the explicit list_boards reference.

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 each parameter already has a clear meaning in the schema. The description adds no new parameter-level semantics; its mention of SECRET permissions and missing_scopes echoes the privacy parameter schema rather than extending it. Per the calibration rule, a baseline of 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 opens with a specific verb-resource pair: 'Create a new board on a connected Pinterest account.' It clearly distinguishes this from siblings like update_board and delete_board by specifying 'new board', and the follow-up line about returning the board with id further anchors what the tool 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?

The description explicitly states when to use the tool: 'Use when no existing board from list_boards fits; check list_boards first, since Pinterest rejects duplicate names.' It also gives a when-not-to-use: 'Not needed for a one-off pin: publish to an existing board.' This names the alternative tool (list_boards) and the condition that selects 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 declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, so the description carries the burden of explaining side effects. It details return behavior ('Returns the pin with id and status "queued"'), error handling ('Fails fast with board_not_found / board_not_owned / board_access_denied...'), and idempotency semantics. It adds substantial behavioral context beyond the annotations, with no contradictions.

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

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

The description is well-organized in three short paragraphs: purpose and alternatives, usage guidance, and return/error behavior. It front-loads the core purpose and avoids redundancy, with every sentence contributing 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?

Despite 14 parameters and no output schema, the description covers the critical operational details: immediate vs. preflight, the mutual exclusion of media sources, idempotency handling, expected response shape, and error conditions. The schema covers parameter definitions, and the description fills the behavioral gaps, making it complete for an agent to call 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 coverage is 100% with each parameter documented, so baseline is 3. The description adds meaningful guidance: 'Provide either image_url or asset_id (from upload_asset), not both' and explains the idempotency_key reuse workflow, which is not fully captured in the schema. This raises the score to 4.

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 clearly states 'Publish a pin to Pinterest now, or preflight it with dry_run=true', specifying the verb, resource, and immediate vs. preflight modes. It explicitly distinguishes from sibling tools by noting 'for a future time use create_schedule, for many pins use create_pins_batch', so an agent can immediately differentiate it from related operations.

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 provides explicit when-to-use guidance: 'Use for a pin that should go out immediately; for a future time use create_schedule, for many pins use create_pins_batch.' It also instructs to run dry_run first and reuse the resolved.idempotency_key on the real call, giving clear operational steps and alternatives.

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 are minimal (only readOnlyHint, openWorldHint, idempotentHint, destructiveHint), so the description carries the full burden. It discloses failure modes (payment_required, quota_exceeded), per-entry error containment in results, and the idempotency behavior nuance (generated when omitted makes batch NOT safe to resend). This goes well beyond annotations and gives the agent accurate expectations.

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?

The description is compact yet richly informative: front-loaded purpose, then usage conditions, then output and failure summary. Every sentence earns its place, with no fluff or redundancy. Formatting with line breaks improves scanability.

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?

The description covers return fields (created_count, existing_count, failed_count, results, headroom), failure modes, prerequisite quota check, and idempotency guidance. No output schema exists, so this self-contained description is complete for an agent to call correctly. It addresses all critical aspects for a batch write operation.

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 schema itself explains each field thoroughly, including the idempotency_key caveat. The description adds only a usage-style hint about supplying a key when resending, which is already implied by the schema. No new parameter semantics are added beyond what the schema provides, so a 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 clearly states the verb and resource: 'Publish several pins in one call' with per-entry outcomes. It explicitly distinguishes from create_pin by instructing 'otherwise call create_pin per pin', making it unmistakable which tool to select for bulk operations.

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 explicit when-to-use conditions: 'Use for bulk publishing (up to 100 pins) when the workspace has the bulk_imports feature; otherwise call create_pin per pin.' It also adds a prerequisite: 'Check get_billing_status for quota first' and advises on idempotency_key usage. This leaves no ambiguity about alternatives or prerequisites.

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?

Goes well beyond annotations by disclosing non-idempotency ('A repeat call creates a second schedule'), preflight timing ('The board is preflighted now, not at run time'), dry_run behavior, and a categorized list of error codes (validation_error, board_*, quota_exceeded). This gives the agent a clear mental model of side effects and failure modes.

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?

Each sentence carries distinct information—purpose, usage, parameter constraint, behavior, idempotency, return value, and error modes. There is no fluff or repetition; the description is dense but well-organized and front-loaded with the core purpose.

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 complex 11-parameter tool with no output schema, the description covers the return format (schedule with id and status, or dry_run validation result), all relevant error categories, the preflight nuance, and the image/asset exclusivity. The agent can confidently invoke this tool without additional context.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds a critical constraint not present in the schema: 'Provide either image_url or asset_id, not both.' It also reinforces that run_at must be in the future and timezone-aware, which is already in the schema but repeated concisely. The added exclusivity rule earns a 4.

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 ('Schedule a pin to publish at a future time') and explicitly differentiates from the sibling create_pin ('for an immediate publish use create_pin'). The agent knows exactly what this tool does and when it applies.

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 explicit when-to-use guidance ('Use when the pin should go out later or when spreading many pins out after rate_limited') and names the alternative (create_pin). It also advises checking list_schedules before retrying after a timeout, addressing a common failure pattern.

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?

Beyond the annotations (mutation, non-idempotent, non-destructive), the description discloses the default events, the returned fields, validation_error failure for bad URLs or short secrets, and implies duplicate registration is not deduplicated by advising a list_webhooks check. No contradiction with annotations.

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

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

Three compact sentences front-load the core purpose and immediately give routing guidance, defaults, return values, and failure modes. Every sentence earns its place with no filler or repeated schema 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?

Despite having no output schema, the description enumerates the returned fields (id, url, events, is_enabled, created_at) and the main validation failures. Combined with full schema coverage and sibling routing, an agent has everything needed to invoke and interpret the result.

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 input schema already documents all four parameters (100% coverage), so the baseline is 3. The description adds value by spelling out that URL must be valid http(s), that defaults are pin.published and pin.failed, and the secret length rule tied to validation_error, though it partially duplicates schema constraints.

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 opens with a concrete verb and resource ('Register an endpoint PinBridge calls when a pin publishes or fails'), and the sibling comparisons ('Check list_webhooks', 'use update_webhook') make it distinct from other webhook tools. No ambiguity about what this tool 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?

It explicitly says to use this instead of polling get_pin when callbacks are possible, tells the caller to check list_webhooks first to avoid duplicate URLs, and routes changes/pausing to update_webhook. This is explicit when-to-use and when-not-to-use guidance with named alternatives.

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 destructive/idempotent/readOnly status, but the description adds substantial context beyond them: irreversibility, that public_url stops working, that unpublished pins fail to publish, and two named failure modes (not_found, insufficient_scope) tied to a required scope. This is exactly the behavioral disclosure a destructive tool needs.

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

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

Front-loaded with purpose and the irreversible warning, then usage and return/failure details in scannable paragraphs. Dense but every sentence carries decision-relevant information; slightly verbose for a two-parameter tool.

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

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

No output schema exists, yet the description enumerates the return fields (asset_id, deleted, requires_confirmation, referenced_pin_count, freed_bytes) and the confirm=false no-op state. Combined with failure modes, an agent has everything needed to call and interpret this destructive tool 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 coverage is 100%, so the baseline is 3, but the description goes further by explaining the confirm=false vs confirm=true semantics in terms of consequences (nothing deleted vs deletes anyway and detaches) and the referenced_pin_count meaning. The added meaning is real but largely overlaps the schema's own confirm description.

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 ('Delete an uploaded image or video from PinBridge storage') with clear scope, distinguishing it from sibling delete_pin/delete_board/delete_schedule by naming the asset origin (upload_asset). An agent can identify this tool 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?

Gives explicit when-to-use ('clean up media from upload_asset that is no longer needed'), the alternative edge case (published pins keep their image on Pinterest), and a precondition ('tell the user which ones first') before destructive confirmation. Routing and sequencing guidance is fully spelled out.

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?

Beyond the destructiveHint annotation, the description discloses irreversibility and the need to confirm first, the side effect on PinBridge's records, exact success return shape, and all relevant failure modes including scope and token issues. This is substantial behavioral context that annotations alone do not provide.

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

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

Front-loaded with the action, scope, and irreversibility; then usage guidance, side effects, and error cases are clearly separated. Every sentence adds operational value, and the structure makes it easy to scan.

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?

Despite lacking an output schema, the description provides the return format and error names. It also covers the destructive side effect and the account-scope context. An agent has everything needed to select and invoke this tool 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%, and both parameters are already documented with provenance (from list_boards / list_pinterest_accounts). The description adds no new parameter-level detail, so the baseline score 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 ('Delete a board on Pinterest'), clarifies the scope ('together with every pin on it'), and explicitly names the sibling it is not ('to remove one pin use delete_pin'). An agent can distinguish this from delete_pin and similar tools 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?

Gives an explicit when-to-use condition ('Use only when the whole board should go') and the alternative for the other case ('to remove one pin use delete_pin'). This is direct, unambiguous 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 declare destructiveHint=true, but the description adds crucial context: it is irreversible, requires confirmation, and details the return values and failure modes (not_found, insufficient_scope, and reasons when nothing was removed upstream). This goes well beyond the annotation metadata and fully discloses the operation's side effects and 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?

The description is organized into a brief lead sentence followed by usage guidance and return/error details. Every sentence adds value, and the most important information (irreversibility, primary action) is front-loaded. It is concise given the behavioral complexity it must convey.

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 fully explains the return payload and error conditions. It covers usage, exclusions, and scope requirements, leaving no critical gap an agent would need to guess. The description is complete for a destructive operation with subtle edge cases.

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

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

Schema coverage is 100%, so the schema already documents both pin_id and delete_from_pinterest with their meanings and defaults. The description does not add additional parameter semantics beyond what the schema provides, so a baseline 3 is appropriate since the schema carries the burden.

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) and resource (pin), and immediately clarifies the default behavior of also removing from Pinterest. It explicitly differentiates from delete_board and update_pin by naming when each alternative is appropriate, so an agent can disambiguate without inspecting sibling 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?

Gives explicit conditions for use (pin should not exist, or replace a published pin that cannot be edited) and explicit exclusions (before publishing, use update_pin; never use delete_board for a single pin). This fully covers when and when-not, including naming the correct alternative.

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?

Goes well beyond the destructiveHint/idempotentHint annotations by disclosing irreversibility, the pending-status precondition, the side-effect boundary ('does not touch the pin'), and the exact error codes (not_found, bad_request, insufficient_scope). This is rich behavioral context an agent cannot get 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?

Front-loads the core action and irreversibility warning, then usage routing, then return/error contract. Every sentence 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?

With no output schema, the description supplies the return shape ({"deleted": true, "schedule_id": ...}) and the failure modes, so an agent has everything needed to call it and interpret results.

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

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

Schema coverage is 100% including a description pointing at list_schedules/create_schedule as sources for the UUID, so the schema already carries parameter meaning. The description adds only indirect semantics via the not_found error on unknown ids, 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+resource ('Delete a finished schedule record') and immediately narrows scope to non-terminal-status records. It is clearly distinguishable from siblings like cancel_schedule and delete_pin, which it explicitly references or implicitly excludes.

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 says when to use it ('clean up history') and when not to ('A pending schedule cannot be deleted: use cancel_schedule first'), naming the alternative tool by name. 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 flag destructiveHint=true and idempotentHint=true, but the description goes further with the immediate delivery cutoff, irreversibility, the exact success payload, and named failure modes not_found and insufficient_scope. That is meaningful context beyond the structured hints.

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

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

Front-loaded with the destructive effect, then usage routing, then return/error contract — every sentence earns its place. Slightly denser than needed but no waste worth cutting.

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 supplies the return shape and the two error conditions, and the mutation risk is fully covered. An agent has everything needed to call and interpret it.

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 the single parameter is documented in the schema ('UUID of the webhook, from list_webhooks'). The description adds no parameter-level 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 and resource ('Delete a webhook endpoint') and immediately qualifies scope with 'deliveries stop immediately. Irreversible.' This clearly separates it from sibling update_webhook and the other delete_* 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?

Explicit when-to-use ('Use when the endpoint is retired') plus an explicit alternative and its condition: 'To pause temporarily use update_webhook with is_enabled=false instead.' This is exactly the when/when-not/alternative guidance the dimension asks for.

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 mark readOnlyHint=true and idempotentHint=true, and the description consistently describes a read operation. It adds meaningful behavioral detail: return fields, the effect of include_daily, the stored/live source behavior with data_as_of, and failure modes like not_found, token_expired, and scope_missing. No contradiction with annotations.

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

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

The description is compact and well-structured: it front-loads the purpose, gives routing guidance, summarizes return shape, and lists key error cases. Every sentence contributes useful information 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?

There is no output schema, so the description compensates by enumerating the returned fields and daily-row behavior. It also covers error conditions and clarifies the stored vs live source semantics. For a read-only analytics tool with rich parameter schema, this is complete enough for correct invocation.

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 each parameter already has detailed descriptions including defaults, formats, and behavior. The description adds only slight reinforcement around include_daily and source, but does not provide substantial meaning beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource: 'Pinterest performance metrics for a whole connected account over a date range.' It clearly distinguishes itself from siblings by specifying account-level reporting over all pins and explicitly naming get_pin_analytics and get_rate_meter as different 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?

Explicitly says when to use this tool ('Use for account-level reporting'), what it covers ('all pins, not only ones published through PinBridge'), and when to use alternatives ('For one pin use get_pin_analytics; for publish headroom use get_rate_meter'). This leaves no ambiguity about selection.

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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful context beyond this, including the specific returned fields and the reliability claim that it 'Never fails for a valid key.' This goes beyond what annotations provide.

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

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

The description is longer than average but well-structured: primary purpose first, then usage guidance, then alternatives, then return fields. The enumeration of return fields is justified because there is no output schema, and no sentence is wasted.

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, parameterless tool with rich annotations, the description is complete. It explains why and when to call it, what it returns in detail, how it relates to relevant siblings, and its failure behavior, leaving no significant gap for an agent deciding to invoke it.

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 tool has zero parameters and the schema is entirely covered by an empty properties object. Per calibration, a 0-parameter tool gets a baseline of 4; there is no parameter-level meaning for the description to add.

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 opens with a specific verb and resource: 'Return the workspace's plan, monthly publish quota, usage and feature flags.' It clearly distinguishes itself from sibling tools by naming get_rate_meter and get_account_analytics as alternatives for different purposes.

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?

Explicit guidance is given: use before a large create_pins_batch, after quota_exceeded, or to check plan features before upload_asset and create_pins_batch. It also explicitly routes the agent to get_rate_meter for per-account publish rate and get_account_analytics for pin performance, providing clear when-to-use and when-not-to-use instructions.

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 idempotentHint=true, and the description adds substantial behavioral detail beyond that: hourly vs. daily granularity by range length, the 366-day limit, full return-field semantics, how outcomes are counted, API version differences, and specific error names. This goes far beyond what the annotations provide.

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

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

The description is front-loaded with a one-sentence purpose, then alternatives, then behavior and return details in a logical order. Despite its length, every sentence carries meaningful information and there is no filler or repetition of schema text.

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 the description correctly compensates by enumerating the full return shape, including nested fields like series, queue, schedules, and import_jobs. It also covers error conditions and edge cases such as old API versions, making it complete enough for an agent to invoke the tool 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 the schema already documents tz, start, end, and account_id well. The description adds complementary semantics about range length affecting granularity, the meaning of start/end inclusivity, and the invalid_date_range failure condition, which improves parameter understanding beyond the schema alone.

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 opens with a specific verb and resource: 'Summarize publishing activity over a period: how many pins went out and how it went.' It clearly distinguishes this tool from siblings by naming get_account_analytics for engagement metrics and list_pins for failed-pin details, so an agent can identify the right tool immediately.

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 explicitly states when to use the tool ('how did publishing go this week / today / last month') and gives concrete alternatives with conditions: use get_account_analytics for Pinterest engagement and list_pins with status=failed for individual failed pins. This is exactly the kind of when-to-use-versus-siblings guidance an agent needs.

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 idempotentHint=true, and the description adds substantial behavioral detail: return fields per state, error_code/error_message on failure, pinterest_pin_id once published, removed_from_pinterest_at behavior, and not_found for unknown ids. This goes well beyond the structured 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?

The description is front-loaded with the core purpose and then organized into usage guidance and return behavior. Each sentence earns its place, and the structure makes the information easy to scan without being bloated.

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 one-parameter read tool, the description is complete: it explains when to poll, what each outcome returns, how deletion is reflected, and how unknown ids fail. No output schema exists, so the description correctly carries the burden of explaining return values.

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 schema already documents pin_id as 'UUID of the pin, from list_pins or create_pin' with 100% coverage, so the description adds little new parameter-level meaning. It does mention not_found for unknown ids, which is useful behavioral context, but does not further clarify the parameter itself.

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 opens with 'Fetch one pin's current status, Pinterest ID and any publish error,' which names a specific verb, resource, and scope. It clearly distinguishes itself from siblings by explicitly naming list_pins, get_pin_analytics, and retry_pin for other use cases.

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 explicitly states when to use this tool: 'Use to poll a pin from create_pin until it is published, failed or deferred, or to read why it failed.' It also provides exclusions and alternatives: 'To find pins without an id use list_pins; for impressions and clicks use get_pin_analytics; to fix a failure use retry_pin.'

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

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

Annotations already mark the tool as readOnly and idempotent, but the description goes well beyond: it explains stored vs live reads, zeroed daily metrics, lifetime counts for comments/reactions, deleted-pin fallback behavior, specific error cases, and sandbox behavior. There is no contradiction with the 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?

The description is long but appropriately sized for a six-parameter read tool with no output schema. It is front-loaded with purpose and usage, then return fields, then exceptions. Each clause carries distinguishing information rather than 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?

With no output schema, the description supplies the return field list, daily-row behavior, source semantics, and failure modes. Combined with the fully documented input schema, an agent has everything needed to invoke and interpret the tool 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 coverage is 100%, so the baseline is 3, but the description adds decision-relevant meaning beyond the schema: use source=live for comments and reactions, pass include_daily=false when totals suffice, and the implications of stored history vs live reads. Metrics and date syntax are already fully covered by 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?

The description opens with a specific verb and resource: 'Pinterest performance metrics for one published pin over a date range.' It also explicitly distinguishes itself from get_account_analytics and get_pin, so an agent can tell which tool to choose among many siblings.

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 explicit timing ('Use after a pin has been published for a while'), names the alternatives for account-level metrics and publish status, and even advises when to pass include_daily=false. This is clear, actionable when-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description adds meaningful behavioral context: it returns account and global token buckets with fields, explains that tokens_available of 0 defers publishing, and documents not_found for unknown accounts. This is valuable beyond the 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?

The description is front-loaded with the core action and then provides usage guidance, return shape, and failure behavior, all in a compact set of sentences. Every sentence earns its place without 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, the description compensates by specifying the return fields and their semantics, including what zero tokens means. It also covers the failure case and the decision context, making the tool complete enough for an agent to call 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 parameter account_id is fully documented by the schema, including its source from list_pinterest_accounts. The description does not add additional parameter-level meaning beyond the schema, so the baseline of 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 and resource: 'Return how many Pinterest publishes an account can make right now.' It clearly distinguishes itself from get_billing_status, which covers the PinBridge monthly quota, and from the scheduling workflow. An agent can tell exactly what this tool is for.

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 says when to use it: before publishing many pins at once or after rate_limited, to decide between publishing now or spreading pins out with create_schedule. It also names the alternative for monthly quota, get_billing_status. This gives the agent clear 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?

Beyond the read-only/idempotent/non-destructive annotations, the description reveals the exact return shape ('status, run_at, pinterest_account_id, payload ... pin_id and last_error') and failure behavior ('An unknown id fails with not_found'). Since there is no output schema, this behavioral disclosure is especially valuable.

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?

The description is front-loaded with the core action, then gives usage context, alternatives, return details, and error semantics in compact, purposeful sentences. No sentence is redundant or 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 single-parameter read-only retrieval tool, the description covers what the tool does, when to use it, what it returns, how to act on the result, and what happens on a bad id. With no output schema, this is fully sufficient for an agent to invoke and interpret the call 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 schema already provides 100% coverage for schedule_id, including its UUID type and provenance ('from list_schedules or create_schedule'). The description adds only the generic 'by id', so it does not meaningfully improve on 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?

The description uses a specific verb and resource: 'Fetch one scheduled pin ... by id' and defines what a scheduled pin is. It clearly distinguishes this tool from list_schedules and get_pin, matching its place among the sibling 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?

It explicitly states when to use the tool ('check whether a schedule is still pending, has published, failed or was canceled') and routes to alternatives: 'To browse schedules use list_schedules' and 'follow the resulting pin with get_pin using pin_id.' This gives an agent unambiguous selection criteria.

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 signal read-only, idempotent, and non-destructive behavior. The description adds substantial behavioral context beyond that: it documents the return shape, pagination via next_cursor, null cursor on the last page, validation_error for malformed cursor/since, and empty-page behavior for unknown filters. No contradiction with annotations.

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

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

The description is compact and front-loaded: purpose first, usage guidance second, return/error behavior last. Every sentence earns its place, and there is no filler or repetition of what the annotations already communicate.

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 the description correctly takes responsibility for explaining return values and pagination. It also covers key failure modes, making it complete enough for an agent to invoke the tool and interpret its results 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?

Input schema coverage is 100%, so the schema already documents all seven parameters. The description adds minor references to cursor and since behavior in error cases, but it does not substantially enrich parameter meaning beyond the schema's own descriptions. A baseline of 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 states a specific verb and resource: 'Read the workspace audit trail: who did what, when, with what outcome.' It clearly distinguishes this tool from other list tools by framing it as an audit trail rather than a current-state listing, and it explicitly names alternatives like get_pin/get_schedule later.

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 explicit when-to-use guidance: reconstruct past events or see changes made outside the session. It also names the alternative for current state ('For current state use get_pin / get_schedule instead'), making the selection logic unambiguous.

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, idempotentHint, and destructiveHint, but the description adds valuable behavioral details: error conditions (not_found, account_not_permitted, token_expired/token_revoked/scope_missing) and the return shape (id, name, description, privacy). This goes beyond annotation safety to inform agents about failure modes and output, which is exactly what is needed. No contradiction.

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

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

The description is three well-structured sentences: primary purpose, usage context with alternatives, and return/error information. It is front-loaded with the main action, then gives practical guidance, then technical details. No wasted words; every sentence 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 simple list operation with one parameter and an output schema, the description is complete: it states the purpose, when to use it, alternatives, return fields, and error handling. It also connects to related tools and even provides a manual fallback URI. An agent has everything needed to invoke it correctly and interpret results.

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

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

The single parameter account_id is fully described in the schema with context (UUID from list_pinterest_accounts), and schema coverage is 100%. The tool description does not add extra meaning to the parameter itself; it only references account_id indirectly. Per rules, baseline of 3 is appropriate since the schema handles parameter documentation.

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 clearly states the tool lists boards an account can publish to, using the specific verb 'List' and resource 'boards'. It distinguishes from board mutation tools (create/update/delete) and explicitly ties to downstream use cases (picking board_id for create_pin/create_schedule). It also names a sibling tool (check_board_access) for a different purpose, so an agent can differentiate them.

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 explicitly states when to use the tool: to select a board_id for pin creation/scheduling or after board_not_found. It also directs agents to check_board_access when testing a single board's publishability, providing a clear alternative. It even references a non-tool alternative (pinbridge URI) for reading boards, giving full context.

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 operation read-only, idempotent, and non-destructive. The description adds substantial behavioral context beyond that: pagination semantics (items, total, limit, offset, has_more), the fact that total counts all matching pages, a version-specific quirk (total null on PinBridge API older than 1.34), error conditions (account_not_permitted, validation_error), and the size trade-off of detail='full'. This far exceeds the annotation baseline.

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?

The description is front-loaded with a clear one-sentence purpose and then organized into use cases, return structure, pagination, and error behavior. It is long, and the return-field enumeration is partly redundant given an output schema exists, so it loses one point. However, nearly every other sentence earns its place with actionable detail.

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 12-parameter tool with a full input schema, output schema, and safety annotations, the description is complete. It covers pagination, counting patterns, edge cases (older API versions, allow-list failures), and error handling. Nothing an agent needs 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%, so the baseline is 3. The description goes further by showing parameter combination patterns: using q to find a pin's id, status=failed with since and limit=1 for counts, and offset = offset + limit for pagination. It doesn't redefine individual params (schema already handles that), making 4 appropriate rather than 5.

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 opens with a specific verb, resource, and scope: 'List pins in this workspace, newest first, with search, filters and sorting.' It then clarifies the core use cases (find pin id, audit published/failed pins, review one board or account), which differentiates it from siblings like get_pin, list_schedules, and get_dashboard_summary. This is a clear, non-tautological statement of function.

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 explicitly names alternatives and the conditions that route to them: 'For one known pin use get_pin; for scheduled (not yet published) pins use list_schedules; for totals over a period use get_dashboard_summary.' It also gives concrete scenarios like 'how many pins failed this week?' with the parameter combination to use. This is exemplary when-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds valuable behavioral details: it counts against the workspace's Pinterest read limit, fails with rate_limited (with retry_after_seconds) when spent, and returns not_found for unknown accounts. This goes beyond the annotations and helps the agent anticipate failures.

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?

The description is three sentences of concise, front-loaded content. It leads with the purpose, then usage context, then return value and error behavior. Every sentence adds distinct value, with no filler or redundancy. The structure is clear and scannable.

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?

Despite the absence of an output schema, the description specifies the return structure (id, related_term_count, related_terms_list) and error conditions. Combined with the schema's parameter documentation and annotations' safety profile, an agent has all necessary information to invoke the tool correctly. Nothing critical is missing.

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

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

Schema coverage is 100% – all parameters are fully described in the input schema. The description mentions 'seed keywords' which aligns with the terms parameter but adds no new semantic meaning beyond the schema. Since the schema already documents parameters comprehensively, the baseline of 3 is appropriate; the description does not compensate for any 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?

The description clearly states the tool's purpose: 'Look up the search terms Pinterest associates with your seed keywords.' It uses a specific verb and resource, and immediately distinguishes itself from create_pin by explaining it's for drafting descriptions or choosing related_terms. This differentiates it from other tools like list_pins and create_pin without ambiguity.

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 provides explicit guidance on when to use the tool: 'Use while drafting a description or choosing related_terms for create_pin' and 'Not needed for publishing itself.' This gives clear context and excludes uses for publishing. However, it does not explicitly name alternative tools beyond create_pin, so it falls short of a perfect score for exhaustive alternatives.

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, idempotentHint, and destructiveHint; the description adds meaningful behavior beyond that: one-page result shape, total counting across pages, pagination loop via offset + limit, and error cases like account_not_permitted and validation_error. No contradiction.

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

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

Well-structured: a one-line summary, then use cases and alternatives, then return/pagination/errors. Despite its length, every sentence earns its place given the tool has 9 parameters and a paged response.

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 an output schema present, the description need not restate every return field, but it still covers the page envelope, pagination technique, filtering semantics, and failure modes. An agent has everything needed to call and page through results 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 coverage is 100%, so baseline is 3. The description adds contextual guidance over the schema, such as using status=scheduled with since/until and limit=1 to count matching schedules, and clarifying that run_at_asc lists the next run first.

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 ('scheduled pins'), scope ('in this workspace'), and default ordering ('latest run_at first'). It also distinguishes itself from siblings by explicitly naming get_schedule and list_pins as alternatives.

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 three concrete use cases: finding a schedule id by search, viewing queued items, and listing failed schedules to retry. It also explicitly routes to alternatives: 'For one known schedule use get_schedule; for pins that already published use list_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?

Beyond the readOnly/idempotent annotations, the description discloses the returned fields, the empty-list meaning, that secrets are never returned, and that it never fails for a valid key. These behavioral guarantees are genuinely additive.

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 short sentences deliver the operation, usage guidance, return contract, and failure behavior with no filler. The main action is front-loaded and every sentence 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?

With no parameters and an output schema present, the description only needed to cover listing scope, return content, and edge cases; it covers all three plus usage guidance. Nothing a caller needs to decide 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?

The tool has zero parameters, so the schema is trivially complete. The description adds no parameter details, but none are needed; the rubric baseline for 0-parameter tools is 4.

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?

Description begins with 'List every webhook endpoint registered in this workspace,' naming a specific resource (webhooks), the operation (list), and scope (workspace-wide). This distinguishes it from mutation siblings like update_webhook and delete_webhook.

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 explicit usage context: 'Use before create_webhook to avoid registering the same URL twice, or to find a webhook's id for update_webhook or delete_webhook.' This tells an agent exactly when to invoke it and ties it to relevant sibling tools.

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?

Although annotations already carry readOnlyHint=false and destructiveHint=false, the description adds meaningful behavioral detail beyond that: the return payload ('status quued'), the requirement to poll get_pin, the preflight check equivalent to create_pin, and the two explicit error conditions (not_found, conflict). It does not contradict any annotation (idempotentHint=true is plausible since re-queueing may be idempotent, though not stated). It could go further by noting idempotency behavior, but it already discloses the core outcomes.

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?

The description is compact but dense, organized into three purposeful paragraphs. The lead sentence states the purpose, the second covers usage constraints and alternatives, and the third covers behavior and errors. Every sentence contributes unique information; there is no fluff. It is longer than the shortest possible version, but the extra length is justified by the failure-mode detail and alternatives.

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 3-parameter mutation tool with no output schema, the description covers the essential context: return status, polling, preflight behavior, and failure modes. It omits explicit idempotency behavior, but that is already encoded in the idempotentHint annotation. It also does not mention authorization requirements, but that is likely tool-agnostic and covered elsewhere. Overall, it is sufficient for a competent agent 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?

Schema coverage is 100% with descriptions for pin_id, board_id, and account_id. The description enriches these by giving the exact scenarios for board_id (original board deleted/inaccessible) and account_id (account reconnect needed). It clarifies that pin_id is required and originates from list_pins or create_pin, and ties the parameter choice to failure reasons. That adds value beyond the bare 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?

The description opens with a crisp verb-and-resource statement 'Re-queue a failed pin' and immediately scopes it with 'optionally on another board or account.' It actively distinguishes itself from siblings, notably retry_schedule ('for a failed schedule use retry_schedule') and contrasts with create_pin via the preflight mention. An agent can tell exactly what this tool does and what it is not for.

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 guidance is explicit: 'Use only for pins whose status is failed' states the precondition, and 'Published pins cannot be edited or retried' states a hard exclusion. It also tells when to pass board_id (deleted/inaccessible board, with a pointer to check_board_access) and when to pass account_id (needs reconnect). The alternative for failed schedules is named directly. This leaves no ambiguity about when to invoke this tool versus alternatives.

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

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

Annotations cover the safety profile (idempotent, non-destructive), and the description goes well beyond them: it explains the returned status semantics ("queued" vs "scheduled" and why), the pin re-publish side effect, and the two error conditions (not_found, bad_request when not failed). That is exactly the mutation/retry context 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?

Front-loads the core action and then layers routing, return semantics, and error modes in a logical order. It is dense and slightly long for a one-parameter tool, but each sentence carries distinct information about the retry branch, so little is wasted.

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 present, the description assumes responsibility for the return value and does so: it describes the returned schedule and its likely status. It also covers failure modes and the alternative tool path, so an agent has everything needed to call this 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 schedule_id is already fully documented (UUID from list_schedules or create_schedule) and the baseline is 3. The description references the id only indirectly via the not_found error and adds no new syntax or format meaning.

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 (re-queue) and resource (a schedule whose publish failed), and explicitly contrasts itself with the sibling retry_pin and with list_schedules. An agent can distinguish this from create_schedule, update_schedule, and retry_pin 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?

Gives an explicit entry condition (schedules in failed status, discovered via list_schedules with status="failed") and names the alternative tool (retry_pin) for the board/account-change case and for a directly-created failed pin. Both when-to-use and which-sibling-to-use are spelled out, leaving nothing 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 provide readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context beyond those flags by stating it requires no PinBridge scope and by enumerating the returned fields. This is useful safety and invocation context that the structured data does not capture.

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?

The description is three compact sentences with no filler. The core function is front-loaded, usage guidance follows, and the return summary and scope note are in the final sentence. Every sentence 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 zero-parameter, read-only informational tool with no output schema, the description is complete. It states the purpose, when to use it, what it returns, and its authorization requirement. An agent has everything needed 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?

The tool has zero parameters, so parameter-level documentation is unnecessary. The description adds relevant semantic context by clarifying that no PinBridge scope is needed, which indirectly reassures an agent that no authorization parameter or setup is required. This meets the baseline for a no-parameter tool.

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 opens with a specific verb and resource: 'Report this server's version, target PinBridge API and enabled capabilities.' It clearly identifies what the tool does and differentiates it from siblings like get_billing_status and get_rate_meter. An agent can immediately understand the tool's unique role.

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 explicitly states when to use this tool: when a client connects for the first time, or when a call fails unexpectedly, to confirm server reachability and whether write tools are enabled. It also names the alternative for workspace plan/quota inquiries: get_billing_status. This leaves no ambiguity about tool selection.

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

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

Annotations only signal that this is a non-read, non-destructive, non-idempotent action. The description adds substantial behavior: the 200 MB cap, plan-gated payment_required failure, validation_error for unsupported media, invalid_image for corrupted files, and the exact recovery instruction to re-encode the original bytes.

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?

The description is dense but efficiently organized: purpose first, then usage routing, then exclusivity constraint, return fields, and failure modes. Every sentence conveys actionable information without 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 tool with no output schema, five parameters, and failure-prone upload behavior, the description covers invocation conditions, parameter exclusivity, return format, file size limits, plan gating, and error recovery. Nothing essential is missing for correct use.

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 parameters are already documented, but the description adds meaning beyond the schema: exclusivity of content_base64 versus source_url, the requirement that videos be uploaded assets, practical MIME inference context, and the server behavior for source_url (no redirects, private hosts refused). It also documents the return fields no output schema 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: 'Upload an image or video to PinBridge and get an asset_id for create_pin.' The purpose is unmistakable and distinguishes this upload step from descendant pin-creation 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 conditions ('generated in this session or Pinterest cannot fetch it from a public URL'), an explicit alternative ('otherwise pass image_url to create_pin directly'), and a hard constraint ('Provide exactly one of content_base64 or source_url'). This fully routes an agent to the correct tool.

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