Tailwind App

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

Goes well beyond the annotations: it discloses billing semantics (never charged if cancelled), the resulting state (reads back as failed with failureCode generation-cancelled), the refusal condition, and a non-obvious transient 404 retry rule. The idempotentHint=true annotation is reinforced by 'retry the cancel, don't stop'.

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 and its precondition, then layered with failure-mode guidance; nearly every sentence adds a distinct operational fact. It runs long and the 404 artifact note is niche, but it is not 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?

An output schema exists so return values need not be explained, and the description still covers the full lifecycle: eligibility window, billing outcome, failure code, refusal behavior, and recovery paths. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100% and the single parameter is already documented as 'Generation ID returned by generate_pins_from_url', which the description restates rather than extends. Baseline 3 applies since the schema carries the parameter 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 ('stop a Pin generation started by generate_pins_from_url') and ties it to the exact sibling that creates the object. An agent can distinguish it from get_generation_status and delete_post 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 ('while the generation is still queued'), when-not ('after that the credits are committed and the cancel is refused'), and named alternatives for each fallback path (poll get_generation_status, then delete_post on unwanted drafts). This is a complete routing decision tree.

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 say this is a non-read-only, non-idempotent, open-world write; the description goes far beyond them by disclosing daily polling cadence, per-Pin SmartPin credit consumption by design tier, that Pins arrive as unscheduled drafts, that a baseline snapshot suppresses existing posts, that duplicate feeds return a conflict, and that disconnected accounts are rejected. It also notes connecting itself costs no credits, which resolves the most likely user objection.

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 purpose and the ongoing-automation framing before cost and edge cases, and nearly every sentence carries decision-relevant information. It runs long (roughly eleven sentences) and folds cost, baseline, and error behavior together without structural signposting, which makes it slower to scan than it needs to be.

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 an output schema, full parameter descriptions, and annotations, the description supplies exactly the behavioral context structured fields cannot express: recurring credit cost, draft status, baseline snapshot, conflict and disconnected-account failure modes. Nothing an agent needs before calling is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: feedUrl must be a genuine feed URL with preview_feed as the fallback, accountId must be a currently connected account because a disconnected one fails silently, and the account choice must be confirmed with the user. It leaves designTier, premiumStyle, autoRegenerate, and generationFrequency entirely to the schema.

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

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

States a specific verb and resource — subscribes to a feed and assigns its generated Pins to one Pinterest account — and immediately disambiguates it from one-time imports and from the preview/update siblings. An agent can distinguish it from connect_pinterest_account, generate_pins_from_url, and update_feed 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 the triggering condition (user wants automatic Pin creation from a blog/RSS feed), an explicit non-use case (not a one-time import), a routing rule to preview_feed when only a site URL is available, and a pre-call clarification step with list_accounts when multiple accounts exist. Exclusions and alternatives are both named.

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?

Adds substantial behavior beyond the annotations: it returns a browser link, no account/billing change occurs until the user completes the browser flow, new-account checks can fail before returning a link, and the browser must be signed into the correct Tailwind organization and Pinterest account. This is consistent with readOnlyHint, openWorldHint, and idempotentHint.

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 triggering conditions, then explains return behavior, the accountId branch, gating, and browser prerequisites. Every sentence contributes operational context for a tool with a multi-step external flow.

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?

Complete for this tool: annotations cover safety and openness, an output schema exists, and the description still supplies the critical external-flow prerequisites and gating behavior that structured fields do not capture.

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 schema already documents accountId as the Tailwind account ID from list_accounts for re-authorization and omission for adding a new account. The description reinforces that distinction but does not add much parameter meaning beyond the schema.

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

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

States a specific verb and resource: connect a Pinterest account to Tailwind. It also explicitly references list_accounts and get_account for detecting unauthorized tokenStatus, so an agent can distinguish this action from the read-only 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?

Gives explicit triggers: user wants to connect another Pinterest account, asks about plan account limits, or has an unauthorized tokenStatus. It also explains the accountId branch clearly: pass it to re-authorize an existing account, omit it to add a new one, and notes the admin/plan-room precheck for new accounts.

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 mutation/safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description's job is to add context — which it does with the credit-cost fact and the cache-lag caveat for list_boards. It stops short of stating permissions/scope requirements or failure modes for the create call itself.

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?

Content is front-loaded on the trigger and return value, and every sentence carries operational information (credits, cache behavior, account disambiguation). It is on the long side for one tool but has 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 an output schema present the description needn't detail the return shape, yet it still names boardId and its downstream consumers (create_post, schedule_post). Combined with the annotated safety profile and full schema coverage, 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?

Schema coverage is 100%, so the schema already documents name, privacy, accountId, and description. The description only reinforces the accountId source, adding no new semantics for privacy or the description field beyond what the schema states.

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?

Opens with a precise verb+resource+scope ('creates a board on their account') and makes the return value explicit (numeric boardId). It is clearly distinguishable from create_board_section, create_board_list, and list_boards by naming what it does and where its output goes.

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 trigger ('when the user wants a new Pinterest board'), the prerequisite path (accountId from list_accounts), and an explicit disambiguation/instruction to ask the user when multiple accounts exist rather than choosing. It also routes the agent away from the list_boards alternative for retrieving the new 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 only flag non-read-only, non-idempotent, non-destructive; the description goes well beyond that by disclosing that the action is Tailwind-local and changes nothing on Pinterest, is free (no Pin credits), and that duplicate calls create duplicate lists. The retry guidance and the 20-board interval-pinning limit are exactly the behavioral context annotations cannot carry.

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

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

Front-loaded with the trigger condition, then progressively adds cost, ordering, return value, idempotency, and account selection — a sensible priority order. It is on the long side and the "it is free — it does not consume Pin credits" clause is slightly redundant, but no sentence is 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 3-parameter write tool with an output schema, nothing material is missing: the data source for boardId, ordering semantics, cost, side-effect scope, duplicate-call risk, retry path, and account ambiguity are all addressed, so an agent can call it correctly without further inference.

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 already 100%, so the baseline is 3; the description adds meaning by specifying that boards must be supplied in publishing order and that boardId values come from list_boards or a just-created create_board, plus noting the returned boardListId. It stops short of covering name constraints or the per-board section option, which the schema already handles.

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?

Opens with a specific verb and resource ("create a saved board list") and immediately defines the resource: "a named, ordered grouping of their boards." It also ties the object to a downstream use (create_post's intervalBoards), which distinguishes it cleanly from siblings like update_board_list, list_board_lists, and delete_board_list.

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 trigger ("Use this when the user wants a saved board list"), names the alternative for the ambiguous-retry case (check list_board_lists before retrying), and routes account disambiguation to list_accounts with instructions to ask the user rather than choose. Exclusions and prerequisites are both present.

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 mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the lower bar applies. The description still adds non-obvious context beyond them: section creation consumes no Pin credits, and collaborator-owned board structure is immutable. It does not cover behavior on duplicate section names or failure modes, which would be needed for 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 sentences, each carrying distinct and necessary information: purpose plus return value, cost, then the account-selection precondition. No filler and no restatement of the name or schema fields.

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?

An output schema exists, so return values need no elaboration, and the description still names the section ID. With annotations covering the mutation profile, the description supplies the remaining decision-critical context: valid boardId source, cost, and account-selection behavior.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond it by constraining which boardIds are valid — those from list_boards, excluding collaborator entries — a selection rule the schema does not state. It adds nothing about the name parameter's 180-character limit or accountId resolution, but that is already in the schema.

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

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

States a specific verb and resource ("creates a named section on a board") with the identifying key (boardId) and the return value (section ID). It is clearly distinct from create_board, update_board_section, and delete_board_section in the sibling list.

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?

Opens with an explicit trigger ("Use this when the user wants to add a section to a Pinterest board") and adds a real exclusion: boards that appear as collaborator entries in list_boards cannot be used. It also gives a concrete disambiguation rule for accountId when list_accounts returns multiple accounts, telling the agent to ask rather than guess.

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 (readOnlyHint=false, idempotentHint=false, openWorldHint=true), it discloses that the upload is single-use, that uploadId binds to exactly one Pin, that expiry windows differ for uploadUrl vs uploadId, that the URL is write-only, and that creating an upload costs no credits. It also explains the two internal modes and exactly when a PUT is or is not required.

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 critical routing information (when to use, when not, alternative) is front-loaded, and the mode explanation follows logically. It runs long for a two-parameter tool, and restating the return payload slightly duplicates the output schema, but most sentences carry operational weight.

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?

An agent has everything needed to call it correctly and to chain into create_post, and the two-mode branching (host attachment vs. extension + PUT) is fully spelled out. With an output schema present, the description need not explain returns, yet it adds useful framing about expiry ordering.

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 already 100%, but the description adds the mode-level framing: `file` is host-supplied only and triggers server-side download during the call, while `extension` alone stages nothing until an HTTP PUT with the matching Content-Type. That is real semantic value, though some of it duplicates the schema's own text about omitting `file` and using `extension`.

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 — creating a single-use media upload in Tailwind's staging — and immediately scopes it to user-owned files without a public URL. It explicitly contrasts with create_post/mediaUrl, so an agent can distinguish it from siblings 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?

It gives concrete when-to-use examples (Canva export, photo or video on disk) and an explicit when-not: media with a public URL should go to create_post as mediaUrl. It even tells the agent which sibling consumes the output (create_post's uploadId input), 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 declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), and the description adds the non-obvious consequences: a draft exists only in Tailwind and never reaches Pinterest, scheduling is the charged step with a per-billing-model cost breakdown, uploadId is single-use, and each intervalBoards entry becomes its own charged Pin. Nothing here conflicts 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?

It is front-loaded correctly — prose before scheduling before media before sibling routing — but at roughly 600 words it over-runs what a tool description needs. The keyword paragraph wanders into Saved Keywords behavior and two other tools' semantics, and the modular/legacy/winback billing breakdown is longer than the decision it supports.

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 19-parameter mutation tool this leaves nothing material unsaid: draft vs. publish semantics, required field combinations, carousel constraints, section placement, cost model, account disambiguation, and the return value (postId, also covered by the output schema). An agent has everything needed to call it correctly on the first attempt.

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?

With 100% schema coverage the schema already documents each parameter, so per the baseline this would be a 3. The description earns one more by adding cross-parameter semantics the schema states only locally: the media source must be exactly one of mediaUrl/uploadId, boardSectionId goes alongside boardId and must belong to that board, and intervalBoards requires intervalType plus sendAt or useNextOpenSlot. The carousel ratio/mixed-source rules are also restated in prose form an agent can act on.

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 opening sentence names a specific verb and resource (create a Pinterest Pin) and immediately splits the two modes — draft vs. scheduled — with the exact parameter condition distinguishing them. It also names the siblings it is not (schedule_post, update_post, delete_post, create_media_upload, create_post called per-Board), so an agent can place it in the toolset without opening a 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?

Explicit routing rules throughout: use useNextOpenSlot when the user named no time, reserve sendAt for an explicitly named time, use intervalBoards rather than calling create_post once per Board, use update_post for edits and delete_post plus a fresh create_post only for an image change, and ask the user which account when list_accounts returns several. Each alternative comes with 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?

Adds substantial behavior beyond annotations: asynchronous return of a batchId with background creation in order, per-entry failure states readable via get_post_batch, all-or-nothing refusal on insufficient funds, per-entry charging with free drafts, 7-day duplicate-batch dedupe, and the placeholder-image limitation that the tools cannot change a Pin's image. The dedupe behavior is a useful nuance alongside idempotentHint=false and does not contradict it.

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 trigger condition and batch size, but the remainder is a single dense run-on paragraph mixing charging, dedupe, retry, and account-selection rules. Every sentence carries information, yet splitting into shorter statements would improve scannability without loss.

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=false, non-idempotent bulk mutation with an output schema, the description covers what an agent needs: batching limits, async result model, failure recovery, cost side effects, and account disambiguation. Nothing essential to a correct first call is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds value by stating that entries take create_post's fields minus intervalBoards and carouselItems, that draft entries may omit the image while scheduled ones may not, and how retryOfBatchId overrides the duplicate-batch shortcut. It stops short of clarifying per-field nuances beyond the schema, so it earns a 4 rather than a 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?

Opens with a specific verb+resource+scale ('many Pinterest Pins created at once... up to 175 Pins in one call') and immediately differentiates from the sibling create_post for entries that can't be batched. An agent can distinguish create_posts from create_post, schedule_post, and create_media_upload without opening a 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?

Explicitly names alternatives and conditions: intervalBoards/carouselItems go through create_post one at a time, larger imports split into batches of 175, failed entries retried via a new create_posts with retryOfBatchId, and the account must be confirmed with list_accounts when ambiguous. This is when-to/when-not coverage rather than implied usage.

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?

Far beyond the annotations, it discloses that the operation is free (no credits), that there is no duplicate check and calling twice leaves two slots — behavior consistent with idempotentHint=false — and that each call adds exactly one slot. It stops short of describing the response payload, but the output schema covers 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?

The trigger, the negative scoping, and the alternatives are front-loaded, and every paragraph carries actionable content. It runs long at four paragraphs, and the 'spreading a clustered schedule' sentence restates the one-slot-per-call point, but nothing is 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 four-parameter creation tool with full schema coverage, annotations, and an output schema, the description covers everything an agent needs: trigger, exclusions, alternatives, duplicate behavior, prerequisite reads, and account disambiguation. Return values are legitimately left to the 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 coverage is 100%, so the schema already documents day numbering, HH:MM formatting, and timezone omission. The description adds practical semantics on top: one slot per call so a spread-out schedule needs multiple calls, and the instruction not to pick an accountId on the user's behalf.

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 first sentence states a specific verb and resource — 'creates one smart schedule timeslot on the given day at the given time' — and immediately scopes it to recurring weekly scheduling rather than Pin publishing. It explicitly contrasts itself with create_post and schedule_post, so an agent can route correctly 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?

It gives an explicit trigger ('when the user wants to add a posting time'), an explicit exclusion ('this does not schedule a Pin'), and named alternatives (create_post or schedule_post with useNextOpenSlot). It also adds prerequisites: read list_timeslots first for existing schedules, and ask the user which account when list_accounts returns multiple.

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, and the description goes well beyond them: irreversibility, that Pins are destroyed rather than moved or archived, that Tailwind cannot restore them, and that the call is refused without confirm=true. It also discloses the response contents and warns that list_boards' Pin count is a cached snapshot that may understate the true number at risk.

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?

It is long, but front-loaded with the hard constraint first, then exclusions, then the confirmation protocol. Some redundancy exists — the confirm requirement is stated in the description and again in the schema — but nearly every clause carries operational weight.

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, open-world mutation with three required params, the description covers authorization/confirmation, irreversibility, ID provenance, multi-account disambiguation, and return shape. An output schema exists, and the description still summarizes the response appropriately without duplicating 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%, so the baseline is 3, but the description adds real meaning: boardId must come from list_boards and must never be a collaborator board, and confirm is a refusal gate rather than a mere flag. The accountId ambiguity rule (ask the user when list_accounts returns multiple) adds genuine selection semantics beyond the schema text.

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 deletes a Pinterest board) plus the scope of the deletion (the board AND every Pin on it). It also distinguishes itself from adjacent sibling operations by excluding collaborator boards and pointing to list_boards as the ID source, so an agent can separate it from delete_board_list, delete_board_section, and delete_post.

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 gate ('Use this ONLY when the user has explicitly asked to delete a Pinterest board'), an explicit exclusion (collaborator entries belong to someone else and cannot be deleted here), and a pre-call disambiguation rule for multi-account users via list_accounts. When-not and alternative-selection guidance are both present rather than inferred.

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, but the description adds critical context they cannot convey: the deletion is irreversible ('cannot be restored'), the underlying boards/Pins are unaffected, and the call is mechanically refused unless confirm=true. This is exactly the extra information an agent needs before a destructive call.

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?

It is a single dense paragraph but front-loads the most important constraint (ONLY when explicitly asked) before the destructive semantics and confirmation mechanics. Every sentence carries operational weight; only the account-selection sentence is slightly tangential, though still relevant to correct invocation.

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 and all three required parameters fully documented, the description only needs to cover prerequisites, side effects, and ambiguity handling — and it does all three. Nothing an agent needs to call this destructively and safely 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% and the parameter descriptions are already strong, so baseline 3 applies. The description still adds value by stating where boardListId comes from (list_board_lists) and framing confirm as a conversation-dependent gate rather than a plain flag; the accountId ambiguity guidance is likewise beyond the schema.

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

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

States a specific verb and resource (deletes the saved grouping by boardListId) and immediately clarifies the scope boundary: boards and Pins on Pinterest stay, only Tailwind's grouping is removed. That distinguishes it from delete_board and delete_board_section in the sibling list without the agent needing to open a 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?

Explicit gating: 'Use this ONLY when the user has explicitly asked to delete one of their board lists', plus a required confirmation step and refusal behavior. It also supplies a fallback procedure when accountId is ambiguous (ask the user, never choose). Both when-to-use and when-not are stated.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds the single most decision-relevant fact they cannot express: the Pins inside the section are NOT deleted and move back to the board. It also pre-empts a destructive misselection by contrasting the blast radius with delete_board, and adds an account-ambiguity safety rule.

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 use case, then the critical side effect, then the disambiguation, then the escalation rule — each sentence carries a distinct decision-relevant payload with no restatement of the name 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?

With an output schema, full annotation coverage, and 100% parameter documentation, the remaining burden is behavioral and routing context — exactly what the description supplies. An agent has everything needed to call this safely and 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% and each parameter already documents its source tool (list_boards, list_accounts, list_board_sections), so the schema carries the semantics. The description only echoes the sectionId provenance and adds account-choice guidance rather than new per-parameter meaning. 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 ('deletes a section by sectionId') plus the scope ('from a Pinterest board'), and explicitly distinguishes itself from delete_board. An agent can identify the operation and its argument source without opening the 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?

Opens with an explicit when-to-use trigger ('when the user wants to remove a section'), names the sibling it must not be confused with ('not the same as delete_board'), and gives a concrete pre-call protocol for ambiguous account selection. Nothing about tool selection 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 and idempotentHint=false, but the description adds real substance beyond them: what survives the delete ('SmartPins the feed already generated are left alone'), which only future Pins stop, and the not-found failure mode with its implication (success means it really was removed). That's strong; the main omissions are auth/permission requirements and whether the removal is reversible or recoverable.

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 and its effect, then consequences, then the alternative, then the safety caveat — a sensible order of decreasing call-criticality. Every sentence carries distinct information; nothing repeats the schema or annotations verbatim.

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?

This is a destructive one-param tool with an output schema and full annotation coverage, and the description still covers effect scope, data preservation, error semantics, the temporary alternative, and a confirmation policy. Nothing an agent needs to call it safely 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% and the schema already documents feedId's sources (list_feeds, connect_feed, get_feed), so the baseline is 3. The description earns above baseline by tying feedId to an organization-scoping failure ('Fails with a not-found error if the feed is not this organization's'), which the schema does not say.

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 ('Removes the subscription') plus the concrete consequence ('the daily check stops and no further Pins are generated'). It also distinguishes itself from update_feed (pause) and from cancel_generation in the sibling set, so an agent can route correctly without opening the 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?

Explicitly names the trigger ('when the user wants Tailwind to stop watching a feed for good') and the alternative for the temporary case ('pause it with update_feed'). It goes further with a confirmation rule for feeds the user did not explicitly name, which is exactly the kind of operational 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?

The description adds substantial behavioral context beyond the annotations: deletion is permanent and cannot be undone, only unpublished Pins are eligible, and published Pins cannot be deleted through Tailwind. It also warns against arbitrarily choosing an account, which is important for a 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?

The description is front-loaded with the primary action and scope, followed by clear alternative-tool routing and account-selection guidance. Despite its length, every sentence carries useful decision or safety 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?

Given a destructive mutation with rich annotations, a complete input schema, and an output schema, the description covers the key risks, eligibility constraints, and alternative tools. Nothing material for correct invocation appears to be missing.

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

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

Schema coverage is 100%, so both parameters are already well documented. The description repeats that postId comes from create_post or list_posts and adds account-selection guidance, but does not add much semantic detail about the parameter values themselves beyond 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 states a specific verb and resource: permanently deletes an unpublished Pin by postId. It immediately clarifies the critical scope restriction — only unpublished Pins, not published ones — which distinguishes it from generic delete tools and makes the operation 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?

It gives explicit when-to-use guidance and names alternatives: use update_post to change metadata, create_post for image changes, and unschedule_post to keep a scheduled Pin. It also specifies an account-selection workflow when multiple accounts exist, leaving little 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 and idempotentHint=false, so the safety profile is covered. The description adds genuine value beyond that: the not-found failure mode when the id is not on the user's list, and the guarantee that a successful result means the keyword really was removed. A user-confirmation norm is also surfaced.

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, front-loaded with the triggering condition, then the parameter convention, then the failure semantics, then the safety caveat. Nothing is redundant and each sentence adds a distinct piece of 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?

A single-parameter destructive tool with full schema coverage, complete annotations, and an output schema needs little more. The description covers trigger, id sourcing, failure behavior, and confirmation — everything required to invoke it safely and 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% and the schema itself documents keywordId, so the baseline is 3. The description goes slightly further by stressing the id comes from list_saved_keywords and explicitly not the keyword text, which prevents a common misuse of a string identifier parameter.

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 ("remove or delete one keyword from their saved list") and the singular "one keyword" implicitly distinguishes it from the sibling delete_saved_keywords bulk tool. An agent can tell exactly which operation this performs without opening the 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?

"Use this when the user asks to remove or delete one keyword" gives a clear triggering condition, and the confirmation guidance ("Confirm with the user before deleting keywords they did not explicitly name") adds a concrete usage rule. It stops short of explicitly naming delete_saved_keywords as the alternative for bulk removal, so the contrast is inferred rather than stated.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, but the description adds non-obvious semantics the schema cannot express: all-or-nothing atomicity, the fact that ownership failure aborts the whole batch, and that the error enumerates the unknown ids. That directly answers an agent's biggest risk question for a bulk destructive call.

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 sentences, all load-bearing: trigger, id source, atomicity contract, and the confirmation requirement. Usage guidance is front-loaded and the destructive-action caveat lands before an agent commits to the call.

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?

Output schema exists so return shape needs no explanation, and the description covers the remaining risks for a destructive bulk tool: batch limits, validation failure mode, and required user confirmation. Nothing an agent needs to invoke this safely 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% and the schema already documents keywordIds as 'id fields from list_saved_keywords, up to 100 per call' plus min/max items. The description repeats that same information for the id source and the 100 cap rather than adding new meaning, 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 and resource ('remove several keywords from their saved list at once'), and the phrase 'several ... at once' implicitly carves it out from the singular delete_saved_keyword sibling. It stops short of naming that sibling explicitly, so the differentiation relies on inference.

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 triggering condition ('when the user asks to remove several keywords'), points to list_saved_keywords as the id source, caps the batch at 100, and adds a required precondition (confirm the specific keywords with the user first). An agent has everything needed to decide whether to call this.

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, but the description adds genuinely new behavioral context: existing scheduled Pins are neither unscheduled nor deleted, only future placement stops. It also discloses cost ('Free') and an irreversibility-avoidance protocol (confirm before calling, state which day/time is removed).

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?

Purpose is front-loaded in the first clause, followed by the consequential behavior. It is on the long side and the account-selection guidance reads as a general policy appended to this tool, costing some tightness, but no sentence is 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 destructive two-parameter delete with an output schema and rich annotations, the description covers trigger, side-effect boundaries, alternative tool, confirmation protocol, and account disambiguation. Nothing needed 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 coverage is 100% and both parameters are described there, so the schema does the heavy lifting. The description only adds the provenance hint that timeslotId comes from list_timeslots; accountId usage is addressed but only as a selection policy, not as parameter semantics. 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 and resource: 'removes a single smart schedule timeslot by timeslotId'. It also names the source of the ID (list_timeslots) and implicitly contrasts with update_timeslot and rebuild_schedule, so the agent can distinguish it from siblings without opening a 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?

Explicit trigger ('when the user wants to stop posting at one recurring time'), an explicit alternative with the condition that selects it ('deleting the specific slots they dislike is safer than rebuild_schedule'), a confirmation requirement, and a disambiguation rule for multiple accounts. That is unusually complete 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?

Goes well beyond the annotations: discloses that calls are metered against plan credits, non-idempotent in a costly way ('every call generates and charges again'), asynchronous with sub-minute latency, and that output persists to Ghostwriter history visible in the dashboard. It also clarifies org scoping and that no accountId is required — none of which the annotation block conveys.

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 sentences, front-loaded with what it does, then when to use it, then the operational constraints that most affect a wrong call (cost, async polling), then the negative scope. Each sentence carries distinct information with no 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?

For an async, metered generation tool this covers everything an agent needs: cost model, latency, the returned generation id plus the sibling to poll, org scoping, and output persistence. Return shape is handled by the existing output schema, so no gap remains.

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 topic, cta, keywords, contentType, and priorOutputs are already fully documented in structured form. The description adds only the org-scoping fact ('no accountId needed') rather than any parameter mechanics, 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 — writes Pin titles and descriptions via Tailwind's Ghostwriter — and explicitly bounds scope: 'Pinterest Pin copy only; it does not write blog posts, emails, or product listings.' That exclusion plus the named polling sibling makes it unmistakable against neighbors like generate_pins_from_url or regenerate_pin_design.

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 trigger ('when the user asks for Tailwind or Ghostwriter to write their Pin copy, or for copy in their saved brand voice') and an explicit anti-pattern ('poll the id you have rather than re-calling'), naming get_copy_generation_status as the alternative. 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 only say readOnly=false, idempotent=false, openWorld=true; the description goes far beyond by disclosing that the call is asynchronous, metered with per-tier credit costs (~3/~7/~1, resolved server-side), takes 1-3 minutes, and charges the user. It also explains the deduplication nuance — in-flight repeats return the SAME generation with deduplicated: true and cost nothing, while post-completion repeats start and bill a NEW generation — which clarifies rather than contradicts idempotentHint=false.

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 'use this when' trigger, then ordered by operational need: cost, latency, polling, dedup, account selection. Dense but almost every clause carries a distinct operational fact; the parenthetical credit breakdown is the only mildly redundant part.

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 full async lifecycle an agent needs: prerequisites, cost, latency, polling target, where results surface (list_posts with matching generationId), and the retry hazard. An output schema exists, so return-value detail is correctly omitted.

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 url, title, keywords, accountId, designTier and premiumStyle. The description adds only the accountId provenance (list_accounts) and reiterates tier credit costs already present in the schema; keywords and title get no narrative treatment. 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?

Opens with a specific verb+resource+scope: 'create Pin drafts in Tailwind from a web page (blog post, product page, or article URL).' This cleanly separates it from generate_pin_copy (copy only) and create_post (single post creation) without needing the 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 strong prerequisites (accountId from list_accounts, ask the user when multiple accounts exist, don't pick for them) and a retry protocol (poll get_generation_status before repeating). It stops short of an explicit 'use X instead when...' contrast against similarly named siblings like generate_pin_copy or regenerate_pin_design.

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 read-only, idempotent, closed-world, and non-destructive behavior, so the description does not need to repeat safety basics. It adds meaningful behavioral context beyond annotations: the 404 meaning covers both ownership and disconnected-account cases, and the ambiguity rule prevents the agent from silently choosing an account.

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 primary use case, followed by the alternative, error meaning, and ambiguity handling. Every sentence contributes distinct operational guidance, with 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?

The tool has one required parameter, full schema coverage, annotations covering safety traits, and an output schema, so return-format details are unnecessary. The description covers selection criteria, alternatives, failure interpretation, and disambiguation policy, leaving no material gap 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 coverage is 100% and the single parameter's description already says it is a numeric Tailwind account ID returned by list_accounts. The tool description reinforces the provenance and adds failure semantics tied to that ID, so it provides modest value beyond the schema without being the primary 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 uses a specific verb and resource ('get_account') and names the exact details returned: username, display name, connection status, time zone, and claimed domain. It also explicitly distinguishes this from listing every account, so an agent can tell it apart from siblings like list_accounts.

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 when-to-use guidance ('when you already have an accountId') and when-not-to-use guidance ('Prefer list_accounts when you do not have an accountId yet'). It additionally handles the ambiguity case by instructing the agent to ask the user rather than guessing when multiple accounts exist.

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, it discloses cost ('free, consumes no credits'), hard API limits (90-day lookback and 90-day span), that the effective range is echoed back as startDate/endDate and should be reported rather than assumed, and that totals blend paid and organic by default. That is exactly the kind of behavior an agent cannot infer from 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?

Front-loaded with the core purpose and scoping constraints, and nearly every sentence carries operational value. A few clauses are mildly redundant with the schema (both dates required, UTC YYYY-MM-DD) and 'This is the account rollup' repeats the first sentence.

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?

Output schema exists, so return-shape explanation is unnecessary. Everything else an agent needs to invoke correctly is present: account disambiguation, default window, window limits, enum semantics, cross-tool comparability, and credit cost.

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 earns above that by explaining what the ORGANIC/PAID/ALL enum means relationally — get_pin_analytics numbers are organic-only and must be compared against ORGANIC totals, not the blend. Date pairing rules are restated from the schema rather than extended, so it stops short of a 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?

States a specific verb and resource with explicit scope: account-wide totals (impressions, engagement, saves, clicks) plus a per-day series, covering claimed and unclaimed content. It directly distinguishes itself from get_pin_analytics ('the account rollup') and list_top_pins, so an agent can pick it without opening a 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 alternatives and the condition that selects each: list_top_pins for best-performing Pins, get_pin_analytics for a single Pin. It also gives explicit routing rules for contentType (ORGANIC vs PAID vs default blend) and a disambiguation protocol — ask the user which account when list_accounts returns multiple.

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 it readOnly/non-destructive, and the description reinforces this with 'Free: this read spends nothing' — consistent, not contradictory. It adds behavior the annotations cannot: how credits are scoped per billing system (modular vs legacy/Shopify organization-wide pools that must never be summed), that unlimitedScheduling nullifies credit consumption, that postLimit is null on modular billing, and that this is a planning snapshot rather than an authorization check.

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 trigger condition before the billing nuance, and every clause is substantive. It is nonetheless long for a single-parameter read tool, and the instruction to 'read billingSystem, scope and unlimitedScheduling first' is slightly ambiguous about whether those values come from this call or from get_account.

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?

Output schema exists, yet the description still summarizes the payload (credits, allowance, reset, postLimit) so an agent knows what it will get. Given the genuine complexity of multiple billing models, it supplies the interpretation rules an agent needs to avoid misreading the numbers, and the annotations cover the safety profile.

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 schema already explains that accountId comes from list_accounts, so the baseline is 3. The description adds real meaning beyond that: it explains the account-scoping consequence (legacy/Shopify accounts share one pool and report identical numbers) and prescribes asking the user when multiple accounts exist, which materially affects how accountId should be chosen.

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 (returns/reports) and resource (remaining credits, monthly allowance and reset date, post allowance) rather than restating the name. It distinguishes itself from get_account/list_subscriptions by framing the output as a credit-and-post planning snapshot, and names related actions (connect_feed, scheduling Pins) that consume the resources it reports.

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: before any credit- or post-consuming action, especially bulk ones, or when the user asks how many credits/posts remain and when they refill. It also gives an explicit procedural guardrail — ask the user which account when list_accounts returns more than one — rather than letting the agent pick.

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 annotations: metering (one plan credit per scored call), that absent boards are not charged, that large boards are scored from a capped sample with a 'truncated' flag to relay, and that it reads real Pinterest Pins rather than only Tailwind-scheduled ones. These are cost, fidelity, and failure-mode details an agent cannot get from readOnlyHint/openWorldHint alone, and none of them contradict those 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 'Use this when' trigger, then each subsequent sentence carries a distinct operational rule (source of Pins, metering, absent handling, truncation, account ambiguity) with no restatement of the name or schema. Dense but 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?

An output schema exists so return shape needn't be explained, and the description covers the remaining agent-relevant gaps: cost per call, degraded/absent results, sampling truncation, and multi-account disambiguation. Nothing needed to call this correctly or interpret its output is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns a bump by adding account-selection semantics for accountId (don't pick an account on the user's behalf when multiple exist), which is a constraint the schema does not express. It says nothing extra about boardId or keyword, but those are already fully documented.

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 — scores a board's live Pinterest content against a keyword and returns the Pins with per-Pin relevance — which is distinct from siblings like list_board_pins (raw listing) or get_pin_analytics. The opening clause names the exact user question it answers, so an agent can route to it without inspecting the 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?

Explicit trigger ('user asks how well a board covers a keyword or topic', 'auditing whether a board is on-topic'), explicit anti-pattern ('score the board once and reuse the result rather than re-calling per question'), and explicit precondition (ask which account if list_accounts returns more than one). It also tells the agent what to do with an 'absent' result — report unknown coverage, never poor coverage.

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

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

Annotations already cover the read-only/idempotent safety profile, and the description adds real value beyond them: expected latency, poll cadence, the result.pins payload shape, and the scope boundary against get_generation_status. It only gestures at 'status is success' without enumerating failure/pending states or what to do if polling runs long, which is the one behavioral gap.

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, each doing distinct work, with purpose front-loaded and the sibling disambiguation last. Nothing repeats the schema or the annotations.

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 annotations, a 100%-documented single parameter, and an output schema, the definition covers everything needed to call the tool correctly and act on the result. Only the non-success status handling is left implicit.

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 jobId is fully documented as the ID returned by generate_pin_copy, so the schema carries the load. The description reinforces provenance but adds no new syntax or format information. Baseline 3 applies when the schema does the work.

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 (poll) and resource (a Pin copy generation started by generate_pin_copy), and explicitly rules out the confusingly similar get_generation_status used for generate_pins_from_url jobs. An agent can pick it apart from its siblings 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 the exact trigger (after calling generate_pin_copy), the polling recipe (~every 5 seconds, typically under a minute), and two concrete next actions on success (offer to user, or pass one to create_post). It also names the alternative tool 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 already cover the safety profile (readOnly, idempotent), and the description adds substantive behavior on top: the returned URL is NOT applied to the Pin, and the billing field reports charges plus refund state on failure. That is exactly the kind of context annotations cannot carry.

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

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

Four short sentences, front-loaded with purpose, then cadence, then the critical gotcha (not applied yet), then the return fields. Nothing is wasted and the most failure-prone detail is not buried.

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 output schema being present, the description still flags the two return fields that drive downstream decisions (variationUrl, billing), so an agent knows what to do on success and on failed regeneration. Nothing needed to invoke or interpret it is missing.

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

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

Schema coverage is 100%, so regenerationId is already documented as 'the id returned by regenerate_pin_design'. The description reinforces that lineage through its usage narrative but adds no format or constraint detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource — poll the status of a design regeneration — and ties it to the originating tool regenerate_pin_design, which cleanly separates it from get_generation_status, get_copy_generation_status and get_pin_design. An agent can pick this tool without opening the 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 polling cadence (~15 seconds, typically completes in a few minutes) and names the required follow-up: pass the returned variationUrl to select_pin_design_variation. The full lifecycle — start, poll, apply — is spelled out rather than 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?

The annotations already establish read-only, idempotent, non-destructive behavior, and the description adds useful operational context: what state fields can be inspected, what a not-found error means, and that the tool is org-scoped with no accountId required. This goes meaningfully 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 use case, then adds source, error semantics, and org scoping in compact sentences. Every sentence carries useful information and there is 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 single-parameter read tool with an output schema and rich annotations, the description covers the remaining ambiguities: when to use it, where feedId comes from, error implications, and org scoping. 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?

There is only one parameter and the schema description coverage is 100%, so the schema already explains feedId fully. The description repeats the feedId provenance from list_feeds/connect_feed and adds org-scoping context, but it does not add format or syntax details beyond 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 states a specific verb and resource: retrieve one feed's current state by feedId. It explicitly distinguishes this from listing feeds and enumerates the kind of state returned, so an agent can tell it apart from list_feeds or preview_feed.

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 a clear precondition (you already have a feedId) and the main alternative behavior (avoid listing every feed). It also says where feedId comes from, but it does not explicitly cover when to use update_feed, delete_feed, or preview_feed instead.

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 readOnly/idempotent/non-destructive, but the description adds substantial behavioral context the annotations cannot: completion timing, that retryable failures can hold processing for minutes, that a hung generation can sit ~25 minutes before a terminal generation-request-timed-out status, and that an early 404 is a transient indexing artifact rather than a real error.

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, then progressively more detailed timing/retry guidance, then the follow-up action. Every sentence supplies information an agent needs to poll correctly; nothing is filler despite the length.

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?

An output schema exists, so return values need not be explained. Given a polling tool with one required param, the description covers cadence, timeouts, false-negative 404s, and the downstream retrieval path — everything needed to use 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% and the single parameter's schema text already says it is the 'Generation ID returned by generate_pins_from_url'; the description's mention adds no syntax or format detail beyond that. Baseline 3 applies since 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 (poll) and resource (Pin generation status) and ties it to the originating tool generate_pins_from_url, which distinguishes it from siblings like get_copy_generation_status and get_design_regeneration_status. An agent can select it without opening the 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 polling cadence (~15s), a stop condition (~30 min ceiling with the reason), retry guidance for transient 404s, and a concrete next step (call list_posts with status draft and filter by generationId). When-to-use and what-to-do-after are both 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?

Far exceeds what the annotations cover. Annotations only say read-only, idempotent, open-world; the description adds that figures are organic-only, that a promoted Pin reads low here versus siblings and that gap is expected, that non-owned Pins return 404 (including shared boards) and must not be retried or blamed on a bad id, that 403 is permanent, and that calls consume no credits. These are exactly the traits an agent needs to interpret and recover from responses.

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 core purpose and the differentiator, then ordered by operational importance (data caveats, error semantics, parameter gotchas, account disambiguation). It is dense with no filler, but the postId/404 warning is restated in both the pinId paragraph and the error paragraph, which costs a little.

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?

Complete for a four-parameter read tool with a rich output schema: purpose, window semantics, data-scope caveats, error taxonomy, id-type confusion, and account disambiguation are all addressed. Since an output schema exists, the description is not obliged to enumerate return fields, and it isn't a gap that it doesn't.

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 constraints the schema does not carry: at most 90 days back and at most a 90-day span, both dates required together, dates are UTC, and the effective range is echoed back as startDate/endDate and should be reported rather than assumed. The pinId-vs-postId warning largely duplicates the schema text.

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 ('returns that Pin's totals over a window, a per-day series, and lifetime totals') and immediately differentiates itself: 'This is the only analytics tool that reports comments (totalComments) and reactions (totalReactions)... get_account_analytics and list_top_pins do not.' An agent can distinguish this from every analytics sibling without opening a 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?

Explicit about when to use it (user asks how a specific Pin performed), which alternatives to use instead (get_account_analytics, list_top_pins), and what to do with a multi-account situation ('ask the user which account to use before calling this — do not choose for them'). It also gives negative guidance on retries and on how to phrase failures to the user.

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 readOnly/idempotent annotations by naming the preconditions (needs a generationId) and the exact failure modes (design_not_found, post_already_published for status 'sent'). It also discloses that available operations vary by tier, which is behavioral context an agent cannot infer from annotations or schema.

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 purpose and the return payload, then layers prerequisites, error cases, and the account-ambiguity rule in a logical order. Slightly overlong because the 'Takes an accountId from list_accounts and a postId from list_posts' sentence duplicates the schema, but every other 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 read tool with full annotations and an output schema, the description covers what an agent still needs: sequencing, tier-dependent operation support, prerequisites, and known error states. Nothing material to a correct first call is missing.

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

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

Schema coverage is 100% and the schema already states accountId comes from list_accounts and postId from list_posts, so most of the description's parameter text is redundant. It does add real meaning for accountId by specifying the multi-account disambiguation behavior, which the schema does not express.

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 ('read the design of a Pin') with a precise scope: the AI-generated design, plus the returned fields (tier, variations, sourceImageCandidates, supportedOperations). It is clearly differentiated from siblings like update_pin_design, regenerate_pin_design, get_post, and get_post_image.

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 sequencing guidance ('Call this first and follow that list'), an exclusion rationale ('calling one the Pin does not support is rejected'), and a pre-call disambiguation rule for multi-account users ('ask the user which account to use ... do not choose for them'). This is about as actionable as usage guidance gets.

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 read-only/idempotent/non-destructive, yet the description adds substantial behavior: rules resolve like useNextOpenSlot, linked URLs report the base URL's rule with linkedToUrl naming it, null means spacing does not constrain the URL, and rules can only be changed in the dashboard. It also preempts a likely misconception by stating an explicit sendAt is not an exemption from later respacing.

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?

Trigger conditions are front-loaded and the routing alternative and account-selection caveat come at logical points. It is dense and runs long, with the sendAt and dashboard sentences sitting slightly off the core lookup purpose, but each still conveys usable behavior rather than 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 an output schema present, the description needn't enumerate return fields, yet it still explains the null case and the linkedToUrl field's meaning. For a two-parameter read tool, an agent has everything needed to call it correctly 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?

Schema coverage is 100%, so both parameters are documented structurally; the description adds meaning by tying url to the same value create_post accepts and explaining linked-URL base resolution. That is genuine added semantics, though it does not elaborate further on accountId beyond what the schema states.

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: returns the Pin Spacing rule (DEFAULT or CUSTOM) that Tailwind applies to Pins linking to a given URL, including spacing in days. It explicitly contrasts with list_pin_spacing_rules (all rules at once), so an agent can separate the two 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?

Opens with concrete trigger conditions ("how far apart Pins will be spaced," "why Pins land days apart," "whether Pin Spacing will get in the way of a planned cadence") and names the alternative tool for the adjacent need. It also gives an explicit procedural rule: if multiple accounts exist and the user did not pick one, ask rather than choose.

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 readOnly/idempotent/non-destructive, but the description adds real behavioral context beyond them: deleted Pins remain readable with status "deleted" for ~28 days before purge eligibility, purged or never-existent IDs return a not-found error, and the image is a Tailwind-only asset invisible to web/image search. That is exactly the kind of consequence-and-edge-case disclosure annotations cannot carry.

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

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

Front-loaded with the trigger condition and the returned fields, then layered with edge cases in rough priority order. It runs five sentences and includes a slightly rhetorical aside ('paging list_posts to hunt for it is not'), but every clause carries operational 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?

An output schema exists, yet the description still names the concrete fields and covers the failure modes (deleted-but-readable window, purge, not-found), the image-rendering caveat, and the account-selection prerequisite. For a simple 2-parameter read, 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 coverage is 100% and both parameter descriptions already state postId comes from create_post/list_posts and accountId comes from list_accounts, so the description is largely restating structured data. Its only added meaning is the multi-account disambiguation rule, which is usage guidance rather than parameter semantics. 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 (read one Pinterest Pin by postId) and enumerates exactly what comes back: status, media, title, description, destination url, board, and scheduled/published time. It also explicitly contrasts itself with list_posts, so an agent can distinguish it from the paging sibling without opening a 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 a concrete trigger (user asks about one Pin and a postId is already known) and names the provenance of that ID (create_post, schedule_post, list_posts). It also states an explicit anti-pattern ('paging list_posts to hunt for it is not' the precise way) and a prerequisite fork: if multiple accounts exist and the user didn't specify, ask rather than choose.

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 read-only, idempotent, non-destructive behavior, and the description adds substantial context beyond them: batches take a few minutes, completed means nothing is pending, failure reasons match create_post, and results are retained for 7 days. It also explains the special retry caveat for Pin-may-exist 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 front-loaded with the core purpose, then proceeds through result states, timing, retry guidance, and retention. Every sentence contributes operational information without 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 polling status tool with an output schema, the description covers what an agent needs: how to interpret statuses, how often to poll, how long results persist, and how to handle a failed entry before retrying. 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%, and the single batchId parameter is already documented as the batch id returned by create_posts. The description reinforces that context but does not add format or validation detail beyond 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 states a specific verb and resource: check on a create_posts batch and report entries as created, failed, or pending. It clearly distinguishes this status-check tool from create_posts and create_post by naming the batch workflow it belongs to.

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 usage guidance: use this after create_posts, poll every 10 seconds or so, and look up entries with a Pin-may-exist failure note using list_posts before resending. This routes the agent correctly and names an alternative when retry risk exists.

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 readOnly/idempotent/openWorld, yet the description adds substantial behavior the agent could not otherwise know: it returns an MCP image content block after a one-line summary, ChatGPT clients only surface the summary, Tailwind-hosted images are 1000px wide, and it fails with a URL-naming error for >4MB images, coverless videos, or refused fetches.

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 use case, then returns, then client caveat, then edge cases, then the account caveat — a sensible ordering. It is dense and long for a two-parameter read tool, but nearly every sentence carries distinct operational 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?

Even with an output schema present, the description covers the return shape, client-dependent visibility, sizing, and the full failure envelope, plus the multi-account prerequisite. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, and the description goes further by stating where postId comes from and adding an accountId disambiguation policy (ask the user if multiple accounts) that the schema does not express.

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 ('see what one Pinterest Pin's picture looks like', 'returns the Pin's image as an MCP image content block') and explicitly scopes it to cover images, not videos or design variations. This separates it from get_post and get_pin_design which are the plausible 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 explicit trigger conditions ('when you need to read the words in a graphic or match drafts to copy'), names the prerequisite ('a postId is already known') and its sources (list_posts, get_post, create_post). It also adds a when-not-to-decide rule: ask the user which account before calling if list_accounts returns multiple.

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 read-only/idempotent/open-world, and the description still adds substantial non-obvious behavior: no plan credits spent, promoted/ad content dropped, already-on-board Pins excluded, exclusion tracking through save copies, and empty-list meaning. It also clarifies provenance (these are other people's Pins, present as suggestions), which directly shapes how an agent should phrase the result.

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?

Trigger conditions are front-loaded in the first sentence and the workflow/alternatives follow in a logical order. It is long and a few clauses (the save-copy exclusion detail, the account-disambiguation note) could be tightened, but nothing is 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?

An output schema exists, so return shape needn't be explained, yet the description still covers ordering, per-item relevance rationale, and the empty-result case. Combined with the workflow ordering and prerequisite on account selection, an agent has everything needed to call and interpret 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 coverage is 100%, so boardId, keyword, accountId, and limit are all documented in structured fields; baseline 3 applies. The description does add indirect meaning about boardId (it drives the already-on-board exclusion) but says nothing about limit or accountId beyond what the schema states.

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 chain (search Pinterest public content, filter, rank) and a specific resource (candidate Pins for a board + keyword). It explicitly distinguishes itself from get_board_keyword_relevance, save_pins_to_board, and create_post, so an agent can place it 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 concrete trigger conditions ('user asks what Pins they should add to a board, how to fill a gap'), names the alternatives and when to prefer each (score first with get_board_keyword_relevance; use create_post for a brand-new Pin), and lays out the build-a-board-about-X sequence. It also states a prerequisite behavior: ask the user which account when list_accounts returns multiple.

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 the annotations by disclosing the read-then-write race condition: a slot open at read time may be taken before the write lands. It also documents the default 14-day window, the 60-day cap, and the account-ambiguity handling requirement, which are important behavioral traits an agent would not otherwise know.

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 definition is front-loaded with the use case and the sibling contrast, and most sentences carry real information. It is somewhat long and repeats schema details such as ISO 8601 formatting, the 14-day default, and the 60-day cap, which could be trimmed, but it avoids 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?

Given the presence of an output schema and rich annotations, the description is complete for this tool's complexity. It covers purpose, alternatives, date-window behavior, race-condition risk, and account-selection procedure, so 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?

Schema coverage is 100%, so the schema already documents from/to as ISO 8601 with their defaults and the 60-day maximum. The description adds value by tying those parameters to the default-window behavior and by giving explicit guidance on accountId: ask the user which account to use rather than selecting one automatically when list_accounts returns multiple accounts.

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 ('returns the account's schedule over a date window as concrete dated entries') and explicitly differentiates itself from the sibling tool list_timeslots by contrasting dated occupancy entries with recurring weekly rules. An agent can tell exactly what this tool does and how it differs 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?

It gives explicit triggering questions ('what is on their Pinterest schedule', 'when their next opening is', 'how full their queue looks') and a clear when-not-to-use rule: do not read an open entry and pass its time back as sendAt. It names the correct alternative workflow (useNextOpenSlot with create_post/schedule_post) and includes an account-selection prerequisite when multiple accounts exist.

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 readOnly/idempotent/non-destructive, and the description adds workflow-level behavior the annotations cannot: this is the prerequisite step for account-scoped tools, it surfaces connection status and a tokenStatus of unauthorized, and it instructs the agent to ask the user rather than pick an account. That is meaningful context beyond the structured safety 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?

The core directive (call this first) is front-loaded and every sentence carries routing information. The parenthetical listing five feed tools is dense and slightly bloats the middle, but it does prevent a real misrouting error, so the cost is defensible rather than 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?

An output schema exists, yet the description still names the returned fields (accountId, username, display name, connection status, time zone), which tells the agent what can be read off the response without opening the schema. Combined with prerequisite and multi-account guidance, nothing an agent needs is missing for this zero-param list 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. Its discussion of accountId refers to downstream tools' requirements rather than this tool's input, which is useful orientation but not parameter semantics here.

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 (lists) and a precisely scoped resource (Pinterest accounts connected to the user's Tailwind organization), plus the fields returned per account. It is distinguishable at a glance from siblings like list_feeds, get_account, and connect_pinterest_account.

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 to call this first because every account-scoped tool requires an accountId, names connect_pinterest_account for the connect/reconnect path, and carves out the org-scoped feed tools as exceptions while noting connect_feed does need an accountId. It even prescribes the behavior when multiple accounts come back and the user was ambiguous.

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 this a safe, idempotent read, so the description focuses on behavior the annotations can't express: lists are snapshots that can change, a list is not a passable target, boards must be passed as intervalBoards in the returned order, and entries whose board id is missing from list_boards are stale. That stale-reference and ordering guidance is genuinely beyond structured data.

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 'Use this when' trigger, then the definition, then the handoff to create_post. It is dense and slightly run-on in the middle section, but nearly every clause carries operational information rather than 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 one-parameter read with an output schema, this covers everything an agent needs: when to call it, what a list means, how to consume the ordered boards downstream, how to handle dangling board ids, which siblings mutate lists, and the account-selection prerequisite.

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 accountId parameter is fully documented in the schema, so the baseline would be 3. The description adds real semantic guidance by tying accountId to list_accounts output and specifying a disambiguation behavior when multiple accounts exist.

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 ('lists the account's board lists') and immediately defines what a board list is ('Tailwind's named groupings of boards, used to publish one Pin to several boards in order'). This distinguishes it from sibling readers like list_boards and list_board_sections, which an agent could otherwise confuse with it.

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?

Enumerates three concrete triggering situations (user asks about lists, auditing board organization, user names a list as a Pin destination) and names the sibling mutation tools (create_board_list, update_board_list, delete_board_list) that handle list management instead. It also gives an explicit precondition: if the account is ambiguous and list_accounts returns multiple, ask the user rather than choosing.

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, openWorldHint, and destructiveHint. The description adds substantive context beyond them: no credit cost, pagination semantics where a short or empty page may still include a cursor, non-strict newest-first ordering, and ID/link distinctions such as pinId being the Pinterest ID rather than a Tailwind postId.

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 purpose and use cases, then moves through return behavior, pagination, parameter semantics, and account handling. Although long, the sentences are information-dense and each addresses a real ambiguity.

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 still covers pagination termination, date filtering, section IDs, account selection, and ID types. That is enough for an agent to invoke the tool correctly in ambiguous 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 baseline is 3. The description adds meaning beyond the schema: startDate and endDate filter on createdAt when the Pin was saved, boardSectionId matches list_board_sections and is null for board-level Pins, and pinId is the Pinterest Pin ID used by get_pin_analytics and save_pins_to_board.

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 names a specific resource (Pins already saved on a Pinterest board) and scope (secret boards, sections, saved time), and distinguishes it from get_board_keyword_relevance. It does not explicitly differentiate from the sibling list_pins, so a 4 rather than 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?

It gives explicit trigger conditions ('when the user wants to see, audit, export or reorganize...') and a when-not case: get_board_keyword_relevance only scores against a keyword and spends a credit. It also handles account ambiguity by instructing to ask the user when multiple accounts exist.

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 read-only/idempotent/non-destructive, but the description adds substantive traits beyond them: the Pin count comes from a cached snapshot and lags (treat as lower bound), pinsModifiedAt is a staleness proxy, and a board with no description omits the field entirely rather than returning null. These are non-obvious data-quality caveats an agent could not infer from structured fields.

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?

Usage intent and the boardId-for-create_post rationale are front-loaded, and every sentence carries content. It runs long, though, and the audit/quiet-board framing drifts somewhat from the core 'list boards for an account' purpose, making it denser than it needs to be.

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?

An output schema exists so return values need not be explained, yet the description still supplies the interpretive caveats (staleness, absent description field, cached counts) that matter for correctly acting on the output. Nothing an agent needs in order to call and interpret this correctly is missing.

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

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

Schema coverage is 100% and the single accountId param is documented, so baseline is 3. The description adds value by tying accountId's provenance to list_accounts and by warning that board IDs are numeric and must never be substituted with a name or URL — guidance the schema does not state.

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 ("Lists the Pinterest boards on an account") and enumerates the returned fields. It is clearly separable from nearby siblings like list_group_boards, list_board_pins and list_board_sections, which target 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?

Explicitly names the triggering intent ("when the user wants to see their Pinterest boards") and the downstream consumer ("this is how to get the boardId values that create_post and schedule_post take"). It also gives an explicit disambiguation rule: if the account is unspecified and list_accounts returns multiple, ask the user rather than choosing.

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=false, so safety is covered. The description adds genuinely new behavioral context — that an empty list is a normal result for boards without sections — which prevents an agent from treating it as a failure. It does not describe pagination or volume limits, 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?

Front-loaded with the triggering condition, then the mechanism, then the edge case, then the account caveat. Four sentences, all functional, though the account-selection sentence is dense and could be split or trimmed.

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, return shape needn't be explained, yet the description still covers the one return behavior an agent must not misread (empty list). Prerequisites and account-ambiguity handling are covered; no meaningful gap remains for a two-parameter read 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 both parameters already document their source and format ("never a board name or URL"), so the schema does the heavy lifting. The description only repeats the boardId provenance, adding little beyond the structured fields.

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?

Uses a specific verb and resource ("lists the sections on a board by boardId") and scopes it explicitly against siblings by noting sections are subdivisions within a single board, so an agent won't confuse it with list_boards or list_board_pins. It also states the derived use case (obtaining a section ID).

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 trigger ("when the user asks about the sections on a Pinterest board, or when you need a section ID"), names the prerequisite source for boardId (list_boards), and includes a decision rule for the ambiguous-account case: ask the user rather than guessing.

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 read-only, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds behavior the annotations don't: newest-first ordering, the org-wide rather than account-gated scoping model, and cursor-based pagination with nextCursor. It stops short of any auth or rate-limit context, and some of the return-field detail overlaps the output schema.

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 trigger and purpose, and every sentence carries information. The accountId carry-over warning runs long and could be tightened to one sentence without losing meaning.

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 purpose, when to call, how to scope accountId, pagination mechanics, and what fields come back, while an output schema handles the return shape. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real semantics the schema can't: accountId narrows an org-wide list rather than gating access, unlike sibling account-scoped tools, plus an explicit warning not to carry over an unrelated accountId. That distinction is the single most likely invocation error and it is addressed directly.

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

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

States a specific verb and resource (list the organization's feed subscriptions) and immediately names what each entry contains. It explicitly distinguishes itself from list_accounts, list_boards and other account-scoped tools, so an agent can separate it from siblings without opening a 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 concrete triggers (user asks which feeds/blogs they have connected, or a feedId is needed for get_feed/update_feed/delete_feed) and names the sibling tools that consume the output. It also handles the non-obvious case: omit accountId for a general question even when an accountId is in 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 read-only/idempotent/open-world, but the description adds behavior the annotations cannot: caching with background refresh and the three-state `status` contract, including that `warming` must not be reported as 'no results'. It also warns that returned board ids are unusable downstream, which prevents a concrete misuse.

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 trigger, the sibling contrast, and the status contract in that order. The Communities/Turbo Groups paragraph is long relative to the tool's core job, but it earns its place by preventing misfires on unsupported requests.

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 an output schema existing (so return shape needn't be spelled out), the description still supplies the status semantics needed to interpret that output correctly. Safety, scope, alternatives, and failure modes are all covered.

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 only parameter's description already covers normalization, length limit, and niche-term guidance. The description adds only the 'matching a keyword from Tailwind's Group Board Finder' framing, so the schema does the heavy lifting — 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 and resource (list public Pinterest group boards), names the data source (Tailwind's Group Board Finder), and explicitly contrasts with list_boards. An agent can distinguish this from every sibling without opening the 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 trigger conditions (user wants to see public boards for a topic or benchmark naming/sizing), an explicit exclusion with the correct alternative (use list_boards for the user's own boards), and rules out create_post/schedule_post consumers. It also pre-empts two related-but-unsupported requests (Communities, Turbo Groups) and points to request_capability.

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 a safe read-only, idempotent operation, but the description adds substantial behavioral context: results are newest first, include secret-board Pins and Pins created by other tools, and each Pin carries isRepin, creativeType, boardId, destinationUrl with UTMs, and createdAt. It also discloses the important pinType edge case, pagination behavior with cursors, and that reading Pins consumes no credits.

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 use case and is organized logically from purpose to fields, pinType behavior, pagination, and account selection. It is somewhat long for a list tool and repeats the link/title lookup guidance, but nearly every sentence carries operational value.

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 an output schema and annotations that already cover safety, the description supplies everything else an agent needs: scope, sibling distinctions, field meanings, pinType edge cases, date filtering, pagination completion rules, ID semantics, credit cost, and account-selection ambiguity. Nothing material for correct invocation appears missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it explains that ORIGINAL and SAVED can both miss an account's own Pin saved to another board, that ALL plus isRepin is needed to count every save, that startDate and endDate may be supplied alone, and that pinId is a Pinterest ID rather than a Tailwind postId. It leaves limit and accountId mostly to the schema, so it is strong but not exhaustive.

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: every Pin on the Pinterest account, optionally within a date range, for inventory, export, weekly counts, or lookup by link/title. It explicitly distinguishes this from list_posts and list_top_pins, so an agent can select it confidently without opening 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?

It names the alternatives and the conditions that select them: list_posts covers only Tailwind-scheduled Pins and list_top_pins returns ranked winners, neither being a complete inventory. It also states there is no search filter, explains the pagination loop, and instructs the agent to ask the user which account to use when multiple accounts exist.

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?

Adds real context beyond the annotations: rules cannot be mutated here (only in the dashboard), matching ignores http/https and trailing slashes, and linked URLs inherit their base URL's rule. It also warns against client-side URL matching, which is a genuine behavioral pitfall. Minor gap: no note on result size or ordering, though the output schema covers shape.

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 trigger condition, then contents, then a domain definition, then the sibling alternative, then operational constraints. Every sentence carries distinct information; nothing is redundant 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 single-parameter read-only tool with a full output schema and rich annotations, the description covers triggers, alternatives, domain semantics, mutation limits, and account disambiguation. 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 coverage is 100% and the accountId description already points at list_accounts, so baseline is 3. The description goes further by mandating that the agent ask the user which account to use when multiple accounts exist rather than guessing, which is meaningful semantics the schema does not convey.

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 (lists the account-wide default rule, URL-specific custom rules, and linked URLs) and explicitly distinguishes itself from the sibling get_pin_spacing_rule. An agent can identify what this returns without opening the output 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 trigger ('when the user asks what Pin Spacing rules their account has'), a secondary trigger (planning a high-volume schedule across many URLs), and an explicit exclusion routing to get_pin_spacing_rule for single-URL lookups. It also specifies the account-disambiguation protocol before calling.

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/non-destructive annotations, the description discloses default status behavior, cursor pagination, date-range requirements, ordering rules, how missed Pins differ from get_post reporting, and the special handling of AI-generated drafts. It also states the account-selection prerequisite clearly.

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 core purpose and usage are front-loaded, but the description is very long and includes extended review-workflow guidance and draft-banner context that could be trimmed for a listing tool. Some draft-related details are repeated across sentences.

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 the tool's complexity and the presence of a full schema, annotations, and an output schema, the description is highly complete. It covers status semantics, date constraints, pagination, ordering, account disambiguation, and draft-review edge cases that an agent would otherwise miss.

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 all six parameters. The description still adds meaning beyond the schema: it explains the default queued status, the draft-assignment omission, the date-window matching rules for failed/missed/uploading Pins, and the ordering implications of status and dates.

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 (lists an account's Pins) and enumerates the statuses it can return. It distinguishes the tool from get_post, schedule_post, and delete_post by explaining that each Pin's postId is returned for those follow-up actions.

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 usage context ('Use this when the user wants to see their Pinterest Pins') and references alternatives for single-Pin retrieval, scheduling, updating, and deleting. It also gives a strong prerequisite for account selection, though it does not explicitly contrast list_posts with sibling list tools like list_pins or list_board_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/idempotentHint/non-destructive, so the safety profile is covered; the description adds genuinely new behavior: results are paginated newest-first and nextCursor must be threaded to read further. It reinforces read-only semantics ('only reads back what is already on their list'). Rate limits and page-size fallback behavior are left to the schema, keeping it just 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?

Front-loaded with the trigger condition, followed by purpose, then the negative boundary, then the url use case, then pagination. Every sentence contributes distinct information with no restatement of the name or the schema, and the 'NOT keyword research' clause is placed where an agent will read it early.

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?

An output schema exists, so return-shape detail is rightly omitted, and pagination plus cursor threading are covered. With four optional parameters across list/filter/page concerns, the description is essentially complete; only minor items such as default page size or total-count behavior are left to 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 coverage is 100% and the url parameter is fully documented there, so the baseline would be 3. The description still adds an operational use case for url the schema does not express — checking what a Pin's link already has before calling save_keywords — which meaningfully informs how to use the filter rather than merely restating it.

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?

Opens with a specific verb+resource ('Returns the organization's Saved Keywords list') and immediately bounds the scope. It explicitly distinguishes itself from keyword research AND from write-side siblings like save_keywords, so an agent can select it without opening the schema. Nothing about the intent is left ambiguous.

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

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

Gives concrete triggering conditions ('when the user asks what keywords they have saved', 'to write Pin titles... pick a board topic... plan content') plus an explicit exclusion ('This is NOT keyword research: it will not discover new keywords or report how a term is trending'). It also names save_keywords as the complementary write path in the context of the url check.

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 readOnly/idempotent/non-destructive, and the description goes further by stating it costs no credits, behaves identically across billing systems so no branching is needed, and that `entitled: false` with an empty list is a normal answer rather than an error. The last point is especially valuable because it prevents an agent from treating a valid negative result as a failure.

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 purpose is front-loaded in the first clause and each subsequent sentence adds usable information (output semantics, cross-billing-system invariance, empty-result normalization, credit cost, account disambiguation). It runs slightly long, with a minor redundancy in the 'so you never need to branch on that' clause, but nothing is 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 one-parameter read with an output schema, the description covers everything an agent needs: when to call, how to pick the account, what the returned fields mean, and that an empty result is expected. Return-value explanation beyond the output schema is a bonus rather than a gap.

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

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

Schema coverage is 100% and the single `accountId` parameter is fully documented as a Tailwind account ID from list_accounts, so the schema carries most of the load. The description still adds operative meaning by specifying how to resolve an ambiguous account selection before calling, which is not in the schema.

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

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

The description names a specific verb and resource — check whether a Pinterest account has active, paying access — and immediately ties it to the concrete output field (`entitled`). It is clearly separable from siblings like get_account, get_account_usage, or list_accounts because it is scoped to subscription entitlement rather than account metadata or usage.

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 trigger conditions (before a setup or launch flow that depends on a paid feature, or when the user asks what plan they are on) and an explicit prerequisite workflow: if the user did not specify an account and list_accounts returns more than one, ask the user rather than choosing. That is a when-to-use, a when-ambiguous rule, and a named sibling to consult.

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 a safe read, but the description adds substantive behavioral context beyond them: slots are recurring weekly, the read says nothing about which occurrences are occupied, and computing sendAt from them ignores occupancy and Pin Spacing rules. It also discloses the account-selection requirement when multiple accounts 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?

The description is front-loaded with the primary purpose and then layered with practical constraints. It is longer than average, but most sentences earn their place by preventing specific scheduling errors; there is some repetition around the do-not-schedule-Pins warning that keeps it just short of 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?

Output schema exists, so return value detail is not required. Given the scheduling pitfalls, the description covers the important context: what the tool returns conceptually, what it omits, how it relates to get_schedule, and how to obtain a timeslotId. Nothing material 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?

There is only one parameter and schema coverage is 100%, so the schema already documents accountId as the numeric ID from list_accounts. The description adds useful semantics by stating that if multiple accounts exist the agent must ask the user rather than choose one, which goes beyond the schema.

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

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

States a specific verb and resource (lists the account's smart schedule timeslots) and immediately clarifies that each slot is a recurring weekly time rather than a concrete date. It explicitly distinguishes itself from get_schedule and from create_post/schedule_post, so an agent can separate it from siblings 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 explicit when-to-use guidance (showing or explaining the recurring schedule), names the alternative for dated occupancy (get_schedule), and identifies itself as the source of the timeslotId needed by update_timeslot and delete_timeslot. It also provides an explicit when-not-to-use path: do not schedule Pins from these slots and do not compute sendAt manually; use useNextOpenSlot with create_post or schedule_post instead.

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