AdaptlyPost

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

The annotations already declare destructive=true, readOnly=false, and openWorld=true, but the description adds meaningful behavioral context: items are processed independently, one bad item fails alone, past scheduledAt values publish immediately, and repeated calls can create duplicates. It also discloses public publishing and requires showing every item plus accounts for confirmation.

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, validation step, item failure behavior, platform constraints, confirmation requirement, and duplicate warning are front-loaded and useful. The description is dense and somewhat long for a single paragraph, with some platform details repeated from the schema, but it remains readable and appropriate for the tool's complexity.

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

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

The description is complete for a complex batch mutation tool: it covers input sharing versus per-item overrides, independent processing and partial failures, validation, platform-specific requirements, draft limitations, confirmation, and duplicate risk. Since an output schema exists, it does not need to explain return formats further, though it helpfully mentions the result shape.

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 parameters in detail. The description still adds useful batch-level semantics by explaining which values are shared across all items and which platform configs can be overridden per item, plus limitations such as twitterKeepLinks and linkedinConfigs being unavailable in bulk.

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

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

The description clearly states the specific verb and resource: scheduling up to 100 posts in one call. It also distinguishes the batch operation from create_post and validate_bulk_posts, so an agent can tell when this tool is the correct choice.

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 routing guidance: call validate_bulk_posts first, use create_post for a single post or draft, call list_accounts first, and use list_posts before retrying after errors. It also states that this tool has no draft mode and requires user confirmation before publishing.

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 the external Facebook call, that a rejected token sets unauthorizedReason with Facebook's message, that a working token clears an earlier mark, the 400 failure for non-Facebook accounts, the accounts.manage permission requirement, the twice-daily automatic check, and that nothing is posted. Idempotency is already in annotations, so it's not repeated needlessly.

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 action, then failure semantics, scope, triggers, and prerequisites in a compact sequence. Every sentence adds decision-relevant information with no padding.

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

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

Output schema exists so return values need no explanation; the description instead covers side effects, permission requirements, failure modes, eligibility, and automation cadence. 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 accountId (id or pageId) and workspaceId are already fully documented in the schema. The description adds context about the stored token but no additional parameter syntax or constraint 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?

States a specific verb+resource: re-check a Facebook page live with its stored token and return fresh status. It is clearly distinguished from siblings like retry_failed_platforms or list_accounts by naming the re-verification behavior and the Facebook-only scope.

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

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

Gives explicit triggers: after the user reconnects or fixes a page, or when a Facebook post failed with a token error. It does not name an alternative tool that might also resolve token errors (e.g. retry_failed_platforms), so the when-not/alternative guidance is incomplete rather than absent.

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

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

Annotations flag destructiveHint=true and openWorldHint=true; the description adds that the fetch causes new items to be posted according to post mode, which is the concrete side effect an agent needs to understand before triggering. It also discloses the posts.draft permission requirement and 404 behavior for foreign ids. Only missing detail is whether the reschedule is reversible/undoable.

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, front-loaded sentences: action, side effect, when to use, verification step, error case, permission. Each sentence carries distinct information with no repetition of the name or title.

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 values need not be explained. The description still covers timing, side effects, error behavior, follow-up, and permissions, leaving nothing material for an agent to guess before invoking.

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 id and workspaceId are already documented in the schema, including sourcing and workspace consistency rules. The description adds only the 404 behavior for out-of-workspace ids, which is marginal incremental value over the schema baseline.

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

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

States a specific verb and resource ('Move an RSS feed's next check to now') with immediate effect spelled out (fetched within a minute, items posted per post mode). This clearly distinguishes it from pause_rss_feed, resume_rss_feed, and preview_rss_feed siblings.

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

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

Explicitly names the triggering situation ('when the user just published an article and does not want to wait for the interval') and the follow-up action ('Read list_rss_feed_items a minute later'). This gives when-to-use, an alternative-avoidance rationale, and the next step.

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: 7-day default lifetime, 1-hour-to-365-day bounds, that connected accounts surface in list_accounts, the returned url, and the required accounts.manage permission (and that Admin holds it). These are exactly the operational facts an agent needs before calling a non-destructive write.

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, then packs the default behavior and each option into a tight sequence of sentences. No filler and no repetition of schema-only details.

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 covers return values, and the description still states it returns the url. With annotations covering safety and the description covering lifetime, permissions, and follow-up tools, 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 baseline is 3, but the description adds behavioral meaning: PRIVATE limits what the client sees, allowedPlatforms limits what is offered, and maxAccounts makes the link stop working after that many connections. That is useful semantics layered over 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 (create a connect link) plus the exact scenario: a client connecting social accounts without an AdaptlyPost login. It also names the related tools (list_accounts, revoke_connect_link), so an agent can distinguish it from unrelated create_* siblings.

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

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

Explains the no-option default case and what each option changes, and points to revoke_connect_link for teardown. It stops short of explicitly saying when to use a different tool for connecting accounts, but the context is otherwise clear.

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

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

Annotations declare destructiveHint and openWorldHint but say nothing operational; the description adds the crucial non-obvious traits: publishing runs per platform in the background so the response is not the outcome (check list_post_results), each call creates a separate post so check list_posts after an error or timeout before retrying, and confirmation must precede any live or scheduled publish. That is exactly the idempotency and confirmation context an agent needs.

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

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

Dense but front-loaded: purpose, then draft-vs-schedule semantics, then confirmation, then inputs, then validation and retry guidance. For a 40-parameter tool this length is largely earned, though a few clauses (e.g. the pointer that platform options are 'described on each field') are meta-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 40 parameters, nested configs and an output schema, the description covers everything an agent needs to act correctly: prerequisites (list_accounts, upload_media), pre-flight validation, confirmation policy, async outcome handling, retry safety, and sibling routing. Return values are echoed briefly rather than needing explanation, which is fine since the output schema exists.

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

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

Schema coverage is 100% and per-field docs are extensive, so the description only needs to add cross-parameter meaning — which it does by explaining that accountIds can substitute for platforms plus the per-platform arrays, and by spelling out the scheduledAt/saveAsDraft interaction (draft planned date consumed later by publish_draft). Remaining detail is delegated to the schema, so it stops short of 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 and resource ('Create one post on the user's own connected social accounts') and immediately scopes the tool to a single post, distinguishing it from publish_draft, update_post and bulk_schedule_posts by name. An agent can tell exactly which creation path this is.

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

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

Explicit when-to-use branches: saveAsDraft vs future scheduledAt vs immediate publish; validate_post first to surface all problems; update_post/publish_draft/bulk_schedule_posts for the alternatives. It also states a required human-confirmation workflow before publishing or scheduling and that drafts need none.

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 mark this as destructive and open-world, and the description adds substantial context: existing items are recorded so only later items post, postLatestItem changes first-check behavior, checks repeat on checkIntervalMinutes, and SCHEDULE/PUBLISH publish without further confirmation. It also discloses specific 400 and 503 failure conditions and required permissions.

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 and key behavior are front-loaded in the first sentence, and nearly every sentence adds operationally important information about scheduling, confirmation, preview, errors, and permissions. It is dense but appropriate for a 16-parameter mutation tool, though bullets or shorter sentences could improve scanability.

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

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

Given the 16 parameters, destructive/open-world annotations, and an output schema, the description is complete enough for an agent to call the tool correctly. It covers setup behavior, ongoing checks, confirmation requirements, alternatives, permissions, and failure modes.

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 input schema already documents every parameter in detail, including enums, defaults, limits, and permission implications. The description reinforces the risk of postMode and the first-check behavior of postLatestItem, but it largely repeats rather than adding new parameter-specific semantics 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 opens with a specific verb and resource: connect an RSS or Atom feed so new items become posts on target accounts. It clearly distinguishes this creation tool from preview_rss_feed and the update/delete/list siblings by describing the ongoing posting behavior.

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

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

It explicitly recommends preview_rss_feed first and warns to confirm the feed, accounts, mode, and text with the user before SCHEDULE or PUBLISH. It also states the required permission scope and explains when errors such as duplicate feeds or workspace limits occur.

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 past the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false) by disclosing delivery headers, the exact HMAC signature construction, retry policy (5 attempts, exponential backoff), auto-disable after 20 consecutive failures, and the one-time-display property of the signing secret. It also names the failure modes (400 invalid URL/limit, 409 duplicate URL), which an agent needs to handle rather than guess at.

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 the dense remainder is all operational payload rather than repetition. It is a long, unstructured block, but virtually every sentence carries non-obvious information an agent would otherwise have to discover by error.

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 surfaces the single most important return-value fact — that the response is the only time the signing secret is exposed. Combined with error codes and permission requirements, an agent can call this correctly with no further context.

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

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

Schema coverage is 100%, so both parameters are already documented in structured form and the baseline is 3. The description adds only marginal parameter meaning — that the registered URL receives every event, and that an invalid URL yields 400 — while workspaceId scoping is left entirely to the schema.

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

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

Opens with a specific verb and resource — "Register a URL that receives every workspace event as an HTTP POST" — and enumerates the exact event types delivered. This separates it unambiguously from sibling lifecycle tools like update_webhook, test_webhook, and list_webhooks.

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 establishes the trigger (registering a new endpoint), the prerequisite permission (webhooks.manage, held by Admin and Editor), and the caller's follow-up duty (hand the secret to the user because it is shown only once). It stops short of explicitly routing to siblings, e.g. saying to use update_webhook for an existing endpoint rather than registering a duplicate.

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 destructiveHint=true, but the description goes well beyond them: it clarifies that deletion only drops AdaptlyPost's record while live COMPLETED/PARTIAL_FAILURE posts stay up, discloses the 409 state conflict, the access-denied response for out-of-workspace posts, and that the operation is irreversible.

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 action and use case, then layered with edge cases and constraints; nearly every sentence earns its place. The 'Returns { deleted: true }' line is redundant given an output schema exists, a minor efficiency 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 mutation tool this is complete: state-dependent behavior, error handling, access-control semantics, sibling alternative, and irreversibility are all covered, and the output schema carries return details.

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 on top of the schema by stating the workspace scoping consequence ('Only posts in the workspace... others return "Post not found or access denied"'), 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?

Clear specific verb + resource ('Delete a post record from AdaptlyPost by id') with the exact scope of what is affected. It explicitly names the sibling alternative (update_post) and distinguishes cancel-before-publish from removing live content.

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

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

Explicit when-to-use (cancel DRAFT/SCHEDULED before it goes out), when-not (prefer update_post instead of delete/recreate), plus the state-specific failure condition (PUBLISHING returns 409; wait for list_post_results). Nothing is left to inference.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description goes further by specifying exactly what is destroyed (series + upcoming scheduled post, past posts retained), that the action is irreversible, and that out-of-workspace ids return "Recurring post not found". It also reports the return shape ({ deleted: true }). Rates just under 5 only because it omits permission/auth requirements and any cascade effects on analytics or linked drafts.

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 destructive consequence and then layers routing guidance, error behaviour, return value, and irreversibility in short declarative clauses. No sentence is filler, despite covering a lot of ground.

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 tool with an output schema present, the description supplies everything the agent needs: scope of deletion, irreversibility, sibling routing, and error semantics. Return-value explanation is redundant with the output schema but harmless.

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 id and workspaceId are already documented, giving a baseline of 3. The description adds meaning beyond that by explaining the workspace-scoping consequence tied to workspaceId (ids outside the current workspace yield "Recurring post not found"), which helps the agent reason about cross-workspace misuse.

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

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

States a specific verb (Delete) and resource (recurring post), and immediately defines the scope of the deletion: the whole series stops permanently and the upcoming scheduled post is removed while already-published posts are kept. It distinguishes itself from the near neighbours delete_post and pause_recurring_post by name without the agent needing to open their 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 routing rules in both directions: prefer pause_recurring_post when the user might want the series back, and use delete_post to skip a single occurrence so the series continues. It effectively covers when-to-use and when-not-to-use with the alternatives 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?

Beyond the destructiveHint annotation, it discloses what survives (previously created posts), the error behavior for out-of-workspace ids (404), the required permission (posts.draft), and the response payload. That is the full behavioral picture an agent needs before an irreversible write.

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?

Six short clauses, front-loaded with purpose and preference, then constraints. Every sentence carries distinct decision-relevant information with no repetition of the schema.

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

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

For a two-parameter destructive delete, the description covers consequence, alternative, permission, edge-case error, and return value; the output schema exists so return detail is not required. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so both id and workspaceId are already documented, and the description does not restate their formats. It only adds indirect guidance via 'Ids outside the workspace return 404', which reinforces workspace scoping but does not explain the parameters themselves.

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

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

States a specific verb and resource ('Delete an RSS feed') plus the operational consequence ('it stops being checked for good'), which immediately separates it from pause_rss_feed. An agent can distinguish it from all listed 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?

'Prefer pause_rss_feed when the user may want it back' names the alternative and the exact condition that selects it, and 'Irreversible' closes the decision. No exclusions or prerequisites are left to inference.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, and the description adds context beyond them: the exact permission needed (webhooks.manage), that the operation is irreversible, and what the endpoint stops doing. This is the kind of consequence detail 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?

Four short clauses, front-loaded with the action, then the alternative, then prerequisites, then consequence. Nothing is padded and each sentence carries a distinct fact.

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

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

For a two-parameter destructive tool with an output schema, the description covers the alternative path, auth requirement, reversibility, and outcome. Nothing an agent needs in order 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 description coverage is 100%, with both id and workspaceId fully documented including where the ids come from. The description adds nothing about parameter meaning, so the schema does all the work and baseline 3 applies.

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

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

States a specific verb (delete) and resource (webhook endpoint), and immediately distinguishes itself from update_webhook, the sibling an agent might confuse it with. The contrast with pausing makes the scope 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?

Explicitly names the alternative (update_webhook with active: false) and the condition under which to prefer it, which is a genuine when-not-to-use-this-tool statement. Also states the required permission, a prerequisite no sibling list conveys.

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 far beyond the annotations: nothing is persisted or posted, requires ai.generate, names the roles that hold it (Admin/Editor/Contributor, not Viewer) with the exact 403 permission_denied code, and discloses the 2-credit cost per call, refund-on-failure, the bring-your-own-key exemption, and the no-credit failure path with 'do not retry automatically'.

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 what it does and what it returns, then layers permissions, credits and failure handling in a logical order with no filler sentences. It is a dense block, but nearly every clause carries actionable information.

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

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

An output schema exists, yet the description still names the return shape and, more importantly, covers the cost, auth, quota-exhaustion and no-side-effect semantics an agent needs before calling a generation endpoint. Nothing material is left to 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 100%, so prompt, platform and workspaceId are already fully documented in the schema — the platform character-limit line is essentially restated. The description adds no semantics beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Write a new social media caption from a prompt') plus the exact return shape ({ caption }, text only). It also separates itself from the two nearest siblings: the post-creation tools it feeds and refine_caption for reworking existing text.

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 the output must be passed to create_post, update_post or bulk_schedule_posts yourself, and names refine_caption as the alternative for reworking an existing caption. The instruction to check returned text against the platform character limit before posting is a concrete when-to-use caveat.

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

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

Goes well beyond annotations (readOnlyHint=false, openWorldHint=true): discloses the required ai.generate permission and which roles hold it (403 permission_denied for Viewer), credit costs per model, refund-on-failure behavior, typical 10–40s latency, and that an empty-credit failure must not be retried.

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 action and the 'nothing is posted' constraint, and every sentence carries operational information (polling, credits, permissions). It is a dense single paragraph rather than a wall of filler, though it is long enough that structure would aid scanning.

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 7-parameter mutation tool with an output schema, it covers the full lifecycle an agent needs: async return shape, polling cadence, terminal statuses, downstream consumption, permission failure mode, and credit accounting. Nothing required to invoke 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%, so the baseline is 3, but the description adds workflow meaning the schema lacks: sessionId is for keeping related images together across calls, and the returned imageUrl is the value that plugs into mediaUrls. It adds context beyond the field-level documentation without re-listing every enum.

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 ('Create an image from the user's prompt... save it to the user's own AI image studio') and immediately disambiguates from the sibling create_post with 'Nothing is posted.' An agent can distinguish this from publish/post tools 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 routes the agent: poll get_image_job with the jobId until completed/failed, feed imageUrl into create_post's mediaUrls, reuse sessionId for related images, and do not retry when credits are exhausted. Names both alternatives and the conditions that select them.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial context beyond that: per-platform coverage gaps, partialMetrics/null semantics, the 180-day import limitation, and a refresh cadence mediated by lastSyncedAt. Not a full 5 only because pagination/response-size behavior is unaddressed, though the existence of an output schema lowers that burden.

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 what the tool returns before any caveats, and every sentence carries relevant information. It is dense (a single long paragraph mixing return shape, coverage, retention and routing), so a small structural penalty is warranted, but nothing is genuinely filler.

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

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

For a read-only aggregate endpoint with five documented parameters and an output schema, the description covers what an agent needs: metric semantics, platform coverage limits, data freshness, and how to choose among the analytics siblings. 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 coverage is 100%, so the baseline is 3; the description still earns credit by explaining that the comparison window is the same length immediately before 'from' and that metrics are summed across selected platforms, which is derived behavior the schema alone does not convey. It does not add detail on connectionIds, but the schema already documents that fully.

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 (workspace-wide performance for a date window) and enumerates the exact metrics returned, including the { value, previousValue, deltaPercent } shape. It also names the siblings it is not (get_analytics_timeseries, get_platform_breakdown, list_post_analytics), so an agent can differentiate 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?

Gives an explicit use case ("how did we do this month" questions, follower counts) and explicitly routes the agent to alternatives for trends, platform comparison and per-post data. It also names a precondition (call trigger_analytics_sync first if the user just published).

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/non-destructive annotations by disclosing the sync state enum, the meaning of historyHorizonAt ('earlier dates have no data rather than zero activity'), lastErrorMessage, and the reconnect remediation including the instruction 'tell them, do not keep querying'. This is exactly the kind of 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 core purpose in one clause, and every subsequent sentence carries real information. The field enumeration is dense and somewhat list-like, and it partly duplicates the output schema, but nothing is wasted 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?

Covers purpose, triggers, sub-field meaning, failure states, and remediation, so an agent can both decide to call it and interpret the response. With an output schema present it need not explain return values, yet it does so usefully and consistently.

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 workspaceId parameter is fully documented in the schema (id source, omission behavior, cross-workspace consistency). The description only adds 'Takes only the optional workspaceId', which is redundant, 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?

Opens with a precise statement of what the tool reports ('How fresh the analytics are, per connected account') and enumerates the specific return fields, making it clearly distinct from get_analytics_overview and get_analytics_timeseries in intent. It stops short of explicitly naming those siblings as alternatives, so it lands at 4 rather than 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?

Gives concrete triggers: 'Call this when numbers look stale or empty, and after trigger_analytics_sync to see the run finish' — a clear when-to-use plus an explicit companion tool. It also implicitly says when NOT to keep calling (needsAnalyticsReconnect accounts), but does not contrast with the other analytics siblings.

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

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

The read-only, non-destructive, closed-world behavior is already fully covered by the annotations, but the description adds genuinely non-structured semantics: followers is a snapshot at the end of each bucket, while other counters sum posts published within it; metrics unsupported by the selected platforms return null. That aggregation behavior is valuable and non-obvious. However, it doesn't address the comparison window mentioned only in the schema, nor latency or staleness of analytics data, so it falls short of the richest tier.

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 three-sentence structure is deliberate: capability, return shape and aggregation semantics, then sibling routing. However, the opening sentence front-loads a long metric list before the distinguishing action, making the first read slightly dense rather than immediately front-loaded.

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

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

The tool has an output schema, so a full return contract is not required, yet the description still sketches the points array shape and per-metric aggregation rules. Combined with the explicit sibling routing and platform caveats, 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 description coverage is 100%, so the baseline is 3; the schema already documents from/to inclusivity, ISO 8601, the comparison window, and per-platform caveats. The description's 'day (default), week or month' restates the granularity enum default, and its platform-ignore note duplicates the platforms schema text, so it adds little beyond what the structured fields provide.

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 the exact metrics (views, likes, comments, shares, followers, posts published, engagement rate) and the bucketing dimension (day/week/month), so the verb, resource, and dimensionality are all explicit. It is clearly distinguished from get_analytics_overview (totals) and list_post_analytics (per-post), which are both named with their respective purposes.

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

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

The description gives concrete selection criteria ('for trend questions such as "how are views moving" or "when did followers jump"') and names both alternatives with the condition that routes to each: overview for totals, list_post_analytics for spike attribution. An agent can choose among the three analytics tools without inspecting the schemas.

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/destructiveHint=false, but the description adds substantial behavioral context: the status state machine, terminal failure semantics, member-scoped visibility, the ai.generate permission with 403 permission_denied and which roles hold it, and that reading spends 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?

Dense but front-loaded: purpose first, then return shape, lifecycle, usage cadence, and constraints. Every sentence carries operative information, though the explicit return-value enumeration partially duplicates the output schema.

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

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

For a polling tool, the definition covers lifecycle states, terminal conditions, polling cadence, permissions, visibility scoping, and cost. With an output schema present, the return description is a bonus rather than a necessity, so 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 description coverage is 100%, so the schema already documents jobId and workspaceId in detail; schema description even repeats 'jobId returned by generate_image.' The description adds only marginal meaning (same-member visibility constraints) beyond the structured fields, 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: 'Read the state of an image started with generate_image.' It explicitly ties the tool to its sibling generate_image as the producer of the job, so an agent can distinguish polling from generation 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?

Gives explicit when-to-use (poll every few seconds while queued/processing/generating), when-to-stop (after a couple of minutes), and when-not-to-use (a failed job is final, do not poll again). It also directs the agent to consume imageUrl via create_post.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: it discloses what information is returned, and the non-obvious constraint that an API key never holds more than its issuerRole.

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 content is dense but front-loaded with the resource being described, and each clause earns its place. The single long sentence is slightly hard to parse but not padded.

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

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

With an output schema present and annotations covering safety, the description needs only to convey purpose, usage timing, and key behavioral constraints — all of which it does, including the pre-emptive-check guidance and the issuerRole caveat.

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 description's 'Takes only the optional workspaceId' plus 'the current one unless workspaceId names another' largely restates the schema's default-behavior documentation. Baseline 3 is appropriate 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?

The description states a specific verb (describe) and resource (this connection in the workspace) and enumerates exactly what is returned: auth type, role, permission keys, draft/schedule/publish capabilities, and a summary. This clearly distinguishes it from workspace-oriented siblings like list_workspaces or account tools.

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

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

It gives explicit when-to-use guidance: 'Call this before an action the role may not allow, instead of trying and reading a 403.' That names the alternative behavior it replaces, though it does not explicitly point to sibling tools for workspace discovery or role management.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description adds genuinely non-obvious behavior beyond that — the absence of a platform filter, per-platform metric support via supportedMetrics, the instruction to compare only metrics both platforms list, and the Google Business Profile exception. Slight deduction because a chunk of the text restates return shape that the output schema already provides.

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

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

Front-loaded with purpose and use case, with the sibling routing at the end. The middle enumerates the return payload in detail, which duplicates the output schema and costs a little density, but nothing is misleading or padded.

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

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

For a read-only analytics aggregation with an output schema, full parameter documentation, and annotations, the description covers everything an agent needs: scope, selection criteria, the alternative tool, the platform-metric compatibility caveat, and the Google Business Profile edge case.

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 and the schema carries from/to/workspaceId/connectionIds semantics. The description still adds value the schema cannot express by explicitly stating that no platform-filter parameter exists and that connectionIds is the only narrowing mechanism.

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

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

States a specific verb+resource+scope: 'overview metrics split per platform for a date window.' It also names the contrasting sibling get_analytics_overview for the combined total, so the agent can distinguish it without reading 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 the selecting use case ('which platform performs best' comparisons) and an explicit alternative with its condition ('Use get_analytics_overview for the combined total'). It also states a limitation the agent would otherwise probe for: 'Takes no platform filter; connectionIds narrows it to some 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 cover the safety profile (readOnly, non-destructive, closed-world), but the description adds real behavioral context the annotations don't: visibility is scoped to the current or named workspace and out-of-scope ids return 'Post not found or access denied'. That error semantics is genuinely useful for interpreting failures, though nothing is said about payload size or performance limits.

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

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

Front-loaded with purpose and returned fields, then routing guidance; every clause is doing work. Slightly heavy for one paragraph, with some overlap between the field enumeration and the schema's id/workspaceId text, but no filler 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?

For a two-parameter read tool with an output schema and full annotation coverage, this is close to complete: what it returns, scope, error behavior, and sibling routing are all covered. The field-by-field enumeration is somewhat redundant given the output schema exists, but it does not leave gaps.

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

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

Schema coverage is 100% and both parameters are already well documented in the schema, including the workspaceId consistency caveat. The description restates the id provenance ('from create_post, bulk_schedule_posts, or list_posts') and workspace scoping, adding little beyond what the structured fields already 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 and resource ('Get one post's full record by id') and immediately enumerates the fields returned, so the agent knows exactly what this retrieves. It is clearly differentiable from list_posts (find ids) and list_post_results (per-platform outcomes).

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 ('inspect content before update_post or publish_draft') and names two alternatives with the precise conditions that select them (list_post_results for per-platform outcomes and platformIds for retry_failed_platforms; list_posts for finding ids by status/platform/date). It also names the upstream tools that produce valid ids.

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/non-destructive, so the safety bar is low; the description goes further by disclosing the exact fields returned, the semantic of nextOccurrenceAt (next slot not yet created; absent once ENDED), and the cross-workspace error message. It stops short of describing pagination or auth requirements, but for a read tool that is minor.

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

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

One dense but front-loaded sentence that leads with the verb/resource and then enumerates returned data. The field list is long, but each item is meaningful; nothing is padded with filler or restated boilerplate.

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

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

With an output schema present, the description needn't re-explain return values, yet it adds the semantics an agent needs (nextOccurrenceAt absence at ENDED, cross-workspace not-found behavior, id provenance). Nothing required to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so both id and workspaceId are already documented in the schema, giving a baseline of 3. The description reinforces id sourcing and workspace scoping but adds no syntax or format detail beyond what the schema already carries.

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

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

States a specific verb (Get) and resource (one recurring post/series) by id, and immediately differentiates from list_recurring_posts by scoping to a single record. An agent can tell it apart from the sibling list tool 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?

Explicitly tells the agent where valid ids come from (list_recurring_posts, create_post's recurringPostId, get_post/list_posts), which is the key prerequisite for calling it. It gives clear context but never states a when-not-to-use case or explicitly contrasts with list_recurring_posts.

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, non-destructive read, so the bar is lower; the description still adds real behavioral context the annotations lack—the required posts.read permission and a 404 for out-of-workspace ids. That cross-workspace failure mode is exactly the kind of detail an agent needs.

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

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

Front-loads the resource and payload contents, then adds only two short, high-value sentences on sibling scope and permissions. Every sentence earns its place; slightly list-like phrasing keeps it just below exemplary.

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 field enumeration in the description is a bonus rather than a requirement. Auth requirement and error behavior are covered; cross-workspace scoping is handled by the schema's workspaceId text, so little 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%, including detailed workspaceId semantics, so the schema carries the parameter burden. The description only repeats that lookup is by id and does not add format or sourcing detail beyond what the schema already says.

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

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

States a specific verb and resource ('Get one RSS feed by id') and enumerates exactly what it returns: settings, targets, status, pauseReason, lastError, last checked/posted timestamps. This clearly distinguishes it from list_rss_feeds and list_rss_feed_items 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?

Explicitly routes item-level inspection to list_rss_feed_items, which is the most likely alternative an agent would confuse it with. It does not explicitly contrast with list_rss_feeds or check_rss_feed, so the guidance is clear but not exhaustive.

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 readOnlyHint=false, destructiveHint=false, and openWorldHint=false. The description adds non-obvious behavior the annotations cannot express: the ticket has a 5-minute validity window and is issued per-file. It does not describe failure modes or auth requirements, 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?

Three short sentences: purpose, return/validity, and the routing exclusion. Front-loaded and every sentence carries distinct information with no repetition of the 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?

An output schema exists, so return values need no explanation. Combined with full schema coverage on the only parameter and explicit routing, an agent has everything needed to call it correctly or defer to open_upload_widget.

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% for the single workspaceId parameter, with rich guidance about defaults and cross-workspace id semantics, so the description correctly defers. It adds no parameter detail beyond the schema, which is the baseline-3 case.

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

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

States a specific verb and resource (authorize storing a file, returning an upload ticket) and ties it to a named sibling mechanism (the upload box shown by open_upload_widget). An agent can distinguish it from get_upload_urls and upload_media 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?

Explicitly states when-not: 'Do not call this yourself; call open_upload_widget instead.' It also specifies the call cadence ('once per file'), removing ambiguity about batching or looping.

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 far beyond the annotations by disclosing the two-step mint-then-PUT workflow, the exact failure mode ('Media file(s) not found in storage'), proxy/allowlist 403 behavior, the no-retry fallback, publicUrl reuse semantics, and retention until the last referencing post publishes. The annotations already mark this as a non-destructive, closed-world operation; the description adds the operational context an agent needs.

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

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

Front-loaded with purpose, return values, and the mandatory PUT confirmation, then moves to fallback and sibling preference. It is dense and largely earns its length given the workflow complexity, though the long sandbox-proxy sentence and the redundant 'provide fileName and mimeType' line could be tightened.

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, return semantics (uploadUrl vs publicUrl), mandatory confirmation, failure recovery, alternatives, supported types with platform caveats, and URL reuse lifetime. With an output schema present and 100% schema coverage, nothing material is missing 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%, so baseline is 3, but the description adds real meaning: the fileName extension matters because the post reads file type from it, and the supported MIME types carry platform-specific restrictions (GIF only on certain networks, PDF/Office documents only for LinkedIn DOCUMENT posts) not present in the enum. It does not mention the 20-file cap or workspaceId, but both are well documented 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 precise verb and resource: 'Get presigned upload URLs for direct file uploads,' and immediately clarifies that it only mints a URL rather than performing the upload. This cleanly distinguishes it from upload_media and open_upload_widget.

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 routes between siblings: prefer upload_media for public URLs and inline files under 30 MB; use this for larger self-held files; fall back to open_upload_widget when the PUT cannot reach storage. It also states the mandatory 2xx confirmation before create_post/bulk will accept the publicUrl.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond that: cross-workspace ids return 404 and the caller needs the webhooks.read permission.

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

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

Three short sentences, front-loaded with the core operation, followed by the two most relevant constraints (404 behavior and required permission). No sentence is wasted.

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

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

An output schema exists, so the description need not explain return values, and annotations cover the safety profile. The description supplies the key scoping and auth constraints, leaving it largely complete for a simple read-by-id tool.

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

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

Schema description coverage is 100%, and both the id and workspaceId parameters are documented richly in the schema itself. The description adds no additional parameter meaning beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description gives a specific verb and resource ('Get one webhook endpoint by id') and clearly scopes the operation to a single resource, distinguishing it implicitly from list_webhooks. It does not explicitly name the sibling tools it differs from, so it falls short of the top score.

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

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

The phrase 'by id' implies this is the tool to use when an id is already known, but it never states when to prefer this over list_webhooks or how to obtain an id beyond the schema note. Usage is implied rather than explicitly guided.

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

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

Beyond the readOnly annotation, the description discloses critical behavior: unauthorized accounts cause 400 errors in create_post until reconnection, should be excluded, and the user notified. It also covers platform-specific quirks such as Facebook page IDs, Google Business Profile displayName/username, and Instagram audio support.

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

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

The description is dense and front-loads the core purpose, but it is a long single paragraph mixing return fields, platform-specific caveats, and related tools. Most sentences earn their place, though a more structured format would improve scanability.

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

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

Given a simple list operation with one optional parameter and an output schema, the description is complete: it covers return fields, platform-specific behaviors, error conditions, and routing to alternatives. 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?

Only one optional parameter exists and schema coverage is 100%. The description notes 'Takes only the optional workspaceId' and clarifies the current-workspace default, but the schema already documents the workspaceId semantics in detail, so the description adds limited extra meaning.

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

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

The description opens with a specific verb and resource: 'List the social accounts connected to the workspace... across all thirteen platforms.' It clearly distinguishes this tool from post-listing tools and names the scope precisely.

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

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

It explicitly states when to call it ('before create_post, update_post, or bulk_schedule_posts'), alternatives for related needs ('check_account', 'remove_account'), and exclusions ('Not for post history or publishing status: use list_posts or list_post_results'). This leaves little ambiguity for an agent.

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

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

Annotations already declare readOnlyHint and destructiveHint=false, so the safety profile is covered; the description still adds value by stating 'they are read-only', naming the required analytics.read permission, and noting that metrics live in another tool. It does not cover pagination/volume behavior beyond what the schema provides.

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 with the defining scope in the first sentence and each subsequent sentence carries a distinct fact (read-only, metrics location, use cases, permission). Slightly dense but no filler 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?

An output schema exists, so return shape need not be described; the description covers scope, safety, permission requirement, and the sibling holding metrics. An agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so every parameter (from, to, limit, platforms, workspaceId, connectionIds) is already documented in the schema. The description only restates the window concept ('inside the window') without adding format or semantics beyond the schema, 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 with a precise scope: posts on connected accounts NOT published through AdaptlyPost, with listed fields (text, thumbnail, permalink, account, publish time). This clearly distinguishes it from list_posts (published via the tool) and routes metric needs to list_post_analytics.

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 use cases ('show what an account posted outside AdaptlyPost or to fill in the calendar') and names the sibling that holds the complementary data (list_post_analytics). It does not explicitly say when to prefer list_posts over this, but the scope statement makes the boundary inferable.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description goes further by disclosing the failure modes that matter operationally: 404 when accountId is not a Pinterest account, 400 when Pinterest refuses (usually a reconnect), and 400 on ambiguous/unmatched board names. It explicitly states the default-board behavior for posts that omit a board, which is a hidden side effect an agent would otherwise discover only by accident.

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

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

Front-loaded with purpose and return shape, then usage, then errors — a sensible ordering with no filler sentences. It is on the long side for a two-parameter read tool, and a couple of clauses describe downstream posting behavior (the AdaptlyPost default) that more properly belongs to create_post, though they are relevant for interpreting this tool's output.

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

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

With an output schema present, the description need not enumerate return values, yet it summarizes them anyway. Combined with the error semantics, the cross-account scoping rule, and the explicit 'Nothing is posted' reassurance, an agent has everything needed to call this 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 the baseline is 3; the description still adds meaning by clarifying that accountId maps to a Pinterest account from list_accounts, that a board belongs to exactly one account ('call it once per Pinterest account'), and that boardId/boardName are downstream-only fields. It does not add syntax detail for either parameter beyond the schema, hence not 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 ('List the boards of a connected Pinterest account') and immediately scopes it ('secret boards included'), which distinguishes it from sibling list_accounts and list_posts. The return shape is named up front, so an agent knows exactly what it gets.

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 ('call it before posting to Pinterest'), the user-interaction step (ask which board unless already named), and the exact target of the result (pinterestConfigs[].boardId in create_post, update_post, bulk_schedule_posts). It also rules out the mutually exclusive alternative: boardName instead, 'never both', and confirms there is no fallback on ambiguity.

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, it discloses source coverage (AdaptlyPost vs discovered posts vs Google Business Profile) and the consequence: GBP posts appear with null metrics, discovered posts have null postId/postPlatformId, and unreported metrics are null. This is exactly the kind of edge-case 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 purpose and use cases, and every sentence carries information. It is dense, however, and the long return-shape enumeration partially duplicates the existing output schema, adding length without new decision-relevant content.

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

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

This is a read tool with 8 parameters, null-heavy edge cases, and a sibling-heavy family. The description covers platform quirks, ID nullability, sorting intent, and cross-tool routing, leaving nothing an agent needs in order 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 carries parameter definitions and the baseline is 3. The description still adds interpretive value by explaining the sorting strategy (sort by a metric for a ranked list, PUBLISHED_AT default for chronological review), which tells the agent how to choose sortBy rather than just what it accepts.

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 ('Per-post metrics for posts published inside the window') and immediately scopes behavior: sort options and pagination. It explicitly separates itself from siblings by naming list_top_posts, list_post_results, and get_post, so an agent can pick correctly 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 concrete triggering questions ('top posts', 'which post got the most comments', 'how did post X do'), names the alternative (list_top_posts returns the top few in one call), and states an exclusion ('Not for publishing status: use list_post_results'). The when/when-not/alternative triad is fully covered.

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 safe-read profile, and the description adds substantial context beyond them: the asynchronous/polling behavior, the requirement to read every platform row rather than treat the post as one pass/fail, and the tiktokDraftFallback semantics with an actionable directive to tell the user to finish the draft in the TikTok app.

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 return shape and dense with actionable content; every sentence carries a directive. It is somewhat long and the tiktokDraftFallback sentence is heavily packed, but nothing is wasted.

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

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

For an asynchronous, per-platform results tool, the description covers the polling loop, row-level reading, failure handoff to retry_failed_platforms, and the special TikTok fallback. Even though an output schema exists, the behavioral guidance is complete 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%, so the schema already documents both 'id' and 'workspaceId'. The description adds no syntax or format detail beyond what the schema provides, 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 ('Get one post's per-platform publishing outcomes') and immediately names the sibling it is not ('Use get_post when you also need the content and schedule'). An agent can distinguish it from get_post and list_posts 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?

Explicitly states when to call it ('after create_post, publish_draft, or retry_failed_platforms'), why ('publishing is asynchronous and their responses only confirm queueing'), and the exact completion condition ('poll until no row is PENDING or PUBLISHING'). It also routes platformId extraction to retry_failed_platforms and points to get_post for the alternative need.

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/openWorld=false/destructive=false, and the description adds substantive context beyond them: default newest-first ordering, the aggregate return shape { posts, total, hasMore }, that each post carries status plus a per-platform platforms array, and that startDate/endDate bound scheduledAt or createdAt for unscheduled posts. Pagination contract (offset while hasMore) is spelled out.

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 action and scope, then return shape, then filters, then routing to siblings. No sentence is redundant despite covering a lot of ground.

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

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

For an 8-parameter, zero-required listing tool with an output schema, the description covers scope, ordering, filtering semantics, pagination, and sibling routing. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description still earns credit by explaining that platforms matches posts targeting ANY of the listed platforms and by restating the date-bound semantics and the 1-100/20 default. It adds meaning rather than merely echoing the schema, though most of the syntax detail already lives in the 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?

States a specific verb+resource (list posts), defines scope (current workspace unless workspaceId names another), default ordering, and return shape. It also explicitly distinguishes itself from get_post and list_post_results, so an agent can choose without opening another 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 positive use case ('find post ids or check what is already queued') and names the two alternatives with the conditions that select them: get_post for a full record, list_post_results for per-platform outcomes and retry ids.

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, non-destructive, closed-world profile, and the description adds substantial non-obvious behavior: only the next occurrence of an ACTIVE series exists as a SCHEDULED post (~24 hours ahead), and the five conditions that self-pause a series (3 consecutive failures, lapsed subscription, creator losing access, disconnected account, platform rejection) with pauseReason/lastError as the signal. That is exactly the kind of lifecycle context annotations cannot provide.

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

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

Front-loaded with purpose and return shape, then lifecycle and pagination detail. It is dense but nearly every sentence carries information; the one partial redundancy is restating the limit range and default that the schema already specifies.

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

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

For a read-only list tool with a full output schema, the description covers purpose, filtering, pagination, workspace scoping, and the lifecycle semantics an agent needs to interpret statuses and pause reasons. 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?

Schema description coverage is 100%, so limit, offset, statuses, and workspaceId are already documented in structured form. The description largely restates these (limit 1-100 default 20, paging with offset), adding little beyond the schema, so the 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 ('List the recurring posts (series) in the workspace') and immediately defines what a recurring post is (created by passing recurrence to create_post). This lets an agent distinguish it from get_recurring_post, list_posts, and delete_recurring_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 clear usage context: pagination via offset/limit while hasMore is true, workspaceId should be reused for related calls, and it points out that list_posts surfaces the scheduled next occurrence. It does not explicitly state when to prefer this over get_recurring_post (single series) or how it relates to the pause/resume siblings, so routing guidance is slightly incomplete.

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 a safe read, and the description adds substantial context beyond them: ordering, the exclusion rule for pre-existing items, the five-value status taxonomy with what each means, the 14-day skip threshold, and the required posts.read permission. That is exactly the behavioral detail an agent needs before calling.

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

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

Three compact sentences, front-loaded with the core behavior, then the status semantics, then the use case and permission. Every clause carries information; 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?

With an output schema present, return values need no explanation, and the description covers what matters for interpretation: status meanings, the postId link to get_post, and the auth requirement. Nothing an agent needs to call or interpret this tool 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%, with id, limit, and workspaceId all documented including defaults and cross-workspace id cautions. The description adds no further parameter detail (e.g., what happens at limit boundaries or pagination), 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 ('List the items an RSS feed has seen') plus scope details: newest-first ordering and exclusion of items that predate the feed's creation. This clearly separates it from list_rss_feeds (lists feeds) and preview_rss_feed (tests ingestion).

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 it to answer why an article was or was not posted' gives a concrete selection scenario tied to the status field. It does not explicitly name alternatives such as preview_rss_feed or check_rss_feed, so it stops short of full when-not guidance.

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

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

Annotations already declare readOnly/non-destructive/closed-world, so the bar is lower, yet the description still adds substantial context: the 20-feed cap, the feed-to-post relationship, the posts.read permission requirement, and the full set of pause states (FETCH_FAILURES, CONSECUTIVE_FAILURES, ACCESS_LOST, SUBSCRIPTION_INACTIVE, CONNECTION_REMOVED) with the note that pauseReason and lastError identify which. That is genuine behavioral disclosure an agent could not get from 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?

Purpose and scope are front-loaded in the first clause, and every sentence is information-dense. The pause-state enumeration is long for a listing tool and arguably belongs with the feed resource, but it earns its place by explaining pauseReason values.

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 values needn't be described, and the description still covers scope, ordering, limits, permissions, and the meaning of the pause fields. Nothing an agent needs in order 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% and the single optional workspaceId already documents the default-workspace behavior and cross-workspace id caveat, so the parameter is fully specified without the description. The description's 'the current one unless workspaceId names another' restates the schema rather than adding new semantics.

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

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

States a specific verb and resource ('List the RSS and Atom feeds'), scopes it to the workspace, and adds ordering ('newest first') and a hard cap ('at most 20'). This clearly separates it from get_rss_feed and list_rss_feed_items, which operate on a single feed or its items.

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

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

Usage is implied by the listing verb and the note that it takes only the optional workspaceId, so an agent can infer this is the enumeration call. However, no sibling is named (get_rss_feed, check_rss_feed, preview_rss_feed, list_rss_feed_items) and there is no explicit when-not guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered by structured data. The description adds genuinely new behavioral context: the required analytics.read permission, that results include posts discovered on connected accounts with null postId, and that ranking is descending.

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 what the tool returns and how it differs from the sibling, then packs coverage, scoping and permission notes into a compact paragraph. Slightly dense but no sentence is wasted.

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

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

With an output schema present, return values need not be explained, and the description covers permissions, data coverage (AdaptlyPost vs. discovered posts), scoping via connectionIds, and the ranking default. Nearly complete for a 7-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%, so defaults, enums, limits and ISO formats are already fully documented in the schema. The description only restates connectionIds narrowing and the default VIEWS metric, which the schema already states, so it adds little beyond the baseline.

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

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

States a specific verb+resource (top-performing posts ranked by one metric) and precisely distinguishes it from the sibling list_post_analytics by noting it returns 'the same rows ... without pagination'. An agent can pick the right tool 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?

Gives a concrete triggering example ('what were our top 5 posts this month') and names the alternative it shadows (list_post_analytics without pagination), so the selection is clear. It stops short of an explicit 'do not use when' condition, e.g. when you need the full paginated dataset.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered; the description adds real value beyond them by naming the required permission and roles and by stating what is returned (active flag, last success/failure). It says nothing about result volume or pagination, which is the remaining 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?

Three tight sentences, front-loaded with what is listed, followed by the return content and then the permission/parameter facts. Every clause carries information an agent would otherwise have to infer.

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 return shapes, and annotations cover the safety profile. What remains — permission requirements, workspace defaulting, and which fields matter — is all stated, so an agent can call this correctly without further reading.

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 workspaceId description already explains the id source and cross-workspace id hazard. The description still adds the useful default rule ("the current one unless workspaceId names another") and confirms it is the only, optional 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 ("List the webhook endpoints registered for the workspace") and even enumerates the returned fields (active status, last success/failure). The list-vs-single distinction against get_webhook is implicit rather than named, so it falls just short of explicit sibling differentiation.

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

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

Gives clear operating context: it needs webhooks.read (held by Admin, Editor, Viewer) and takes only the optional workspaceId. It does not explicitly say when to prefer get_webhook or list_posts-style alternatives, but for a simple enumerator the applicable conditions are covered.

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/openWorld/destructive hints, and the description goes beyond them with real behavioral context: the API-key scoping rule ('an API key belongs to one workspace, so it lists only that one') and the default-current-workspace behavior that governs every other tool. It does not mention pagination or result limits, which is the only notable omission for a cross-org list.

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 purpose, then the return shape, then the usage condition and cross-tool wiring; every sentence carries operational value. The trailing 'Takes no arguments' is mildly redundant against the empty schema, a small blemish on an otherwise tight structure.

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-field documentation is not strictly required, yet the description still summarizes the payload. Combined with the workspaceId routing rule and API-key exception, an agent has everything needed to call this tool correctly and to use its results in subsequent calls.

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?

Zero parameters, so the baseline is 4 per the rubric. The description confirms 'Takes no arguments,' which is consistent with the empty schema but adds no semantic detail beyond it, as expected for a parameterless tool.

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

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

States a specific verb and resource with scope: 'List the workspaces this sign-in can act in, across every organization the user belongs to.' It is immediately distinguishable from sibling list tools like list_accounts, and it even enumerates the returned fields so the agent knows the tool's identity 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 conditions are given ('when the user names a workspace, brand, client or organization, or when accounts or posts they expect are missing') along with the follow-up action ('pass the matching id as workspaceId to every other tool'). It also states the fallback semantics when no workspaceId is supplied, so the agent knows when this tool is required versus optional.

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 assert readOnlyHint=false, destructiveHint=false and openWorldHint=false. The description adds real behavior the annotations can't: nothing is uploaded until the user picks files, the box returns a message listing public media URLs meant for create_post/update_post/bulk_schedule_posts, uploaded files land at public URLs, and the widget only renders in MCP Apps hosts.

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 with the purpose before the conditions, and the size and type limits are packed into a single compact sentence. It runs long, and the parenthetical about ChatGPT attachments plus the repeated 'no public URL' framing cost a little density, 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?

It covers the host compatibility limit, the upload handoff, and the file-type and size limits (250 MB per file, 50 MB per image, 100 MB per document). Because an output schema exists, the description doesn't need to enumerate return fields, so nothing 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 one optional parameter (workspaceId) and schema description coverage is 100%, so the schema already explains the id source and the current-workspace default. The description says nothing extra about it, so the baseline of 3 applies.

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

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

The description opens with a concrete verb and resource: 'Show an upload box in the chat so the user can add photos, videos or documents.' It immediately frames the resource as the missing-URL case, which separates it from upload_media and get_upload_urls by name. 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?

It states the trigger ('when the user wants to post a file that has no public URL'), the exclusions ('a file attached in the chat that upload_media cannot read ... in ChatGPT, pass attached files to upload_media as attachments instead'), and the fallback ('elsewhere ask the user for a public URL and use upload_media'). The alternative tools are named explicitly.

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: the upcoming scheduled post is deleted, an in-flight publishing occurrence may still complete, already-published posts are kept, and skipped slots are never backfilled. It also documents the not-found error for out-of-workspace ids and the returned status/pauseReason, which the destructiveHint/idempotentHint annotations cannot convey.

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

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

Front-loaded with the core action and its immediate side effect, then the usage routing, then edge cases. Dense but every sentence carries distinct information; slightly long, though 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?

With an output schema present, the description need not restate the return shape, and it still summarizes status PAUSED/pauseReason USER. Combined with annotations (destructive, idempotent) and full schema coverage, an agent has everything needed to call it correctly and predict consequences.

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 explaining workspace scoping (ids outside the current/other workspace yield 'Recurring post not found') and reinforcing that id comes from list_recurring_posts. This goes modestly beyond the schema's own parameter 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+resource (pause a recurring post) and immediately clarifies the scope: it stops occurrence creation and deletes the upcoming SCHEDULED post. It explicitly contrasts with delete_recurring_post, resume_recurring_post, and delete_post, so an agent can distinguish it from every relevant sibling.

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

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

Gives explicit when-to-use ('when the user wants to hold the series'), when-not ('use delete_recurring_post to stop it for good'), and the alternative for a one-off skip (delete_post). The selection logic between pause vs delete vs single-skip is fully spelled out.

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

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

Annotations already declare non-destructive and idempotent, and the description goes well beyond them: existing posts survive including scheduled ones, cancelling requires delete_post, out-of-workspace ids return 404, and posts.draft permission is required. That is exactly the extra context annotations cannot supply.

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 action and effect, then side effects, then error and permission, then return value. Every sentence supplies information an agent would otherwise have to guess.

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 side effects, prerequisite permission, error behavior, and resulting state (status PAUSED, pauseReason USER) even though an output schema exists. Nothing material for a correct invocation is missing.

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

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

Schema coverage is 100%, so both parameters are already documented, and the description's only added parameter-level fact is the 404 for ids outside the workspace. Baseline 3 applies since the schema carries the load.

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

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

States a specific verb and resource ('Pause an RSS feed') plus the exact effect: it stops being checked until resume_rss_feed. This is unambiguously distinct from resume_rss_feed, check_rss_feed, and delete_rss_feed 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?

Names the counterpart tool (resume_rss_feed) as the way back and routes cleanup of scheduled posts to delete_post. Clear context for when to reach for this tool, though it stops short of stating an explicit 'do not use when you actually want X' exclusion.

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 readOnlyHint and openWorldHint annotations, it states that nothing is saved or posted, discloses the 400 and 503 failure modes with their meanings, and names the required posts.draft permission. That is far more than the annotations convey, and nothing conflicts with them.

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 what it does and returns, then failure modes, then permission. There is no redundancy; each sentence adds information the agent needs (scope, output, errors, authorization).

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 read-only annotations and an output schema handling return values, the description still covers the things structured data can't: no persistence happens, the item count, HTTP error semantics, and the required permission. Nothing material is missing for a correct call.

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 the template placeholders, truncation behavior, and workspaceId semantics in more detail than the description does. The description's 'text rendered from template' merely echoes that, 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 (fetch an RSS or Atom feed without saving it) plus the exact return shape: the 5 newest items with text rendered from the template. This separates it cleanly from create_rss_feed, get_rss_feed, and list_rss_feed_items.

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 frames the use case as previewing what posts would say before calling create_rss_feed, which tells the agent when to pick this tool. It doesn't contrast with the closer siblings check_rss_feed or list_rss_feed_items, so the routing guidance is good but not exhaustive.

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 far beyond the destructiveHint/openWorldHint annotations by disclosing that publishing is irreversible ('cannot be recalled'), the concrete state transition (clears stored scheduledAt, moves to PENDING, queues a job per platform), timing expectations, and specific failure modes (disconnected account, TikTok entry missing privacyLevel, 400 on publishNow+scheduledAt). This is exactly the 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?

High information density with zero filler and the primary behavior front-loaded, but the body is one long run-on block mixing the decision tree, side effects, and failure modes. Splitting the side effects and failure clauses into their own sentences/segments would improve scanability without losing content.

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

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

Covers everything an agent needs for a destructive, open-world mutation: allowed input states, the full branch logic for scheduling vs. publishing now, side effects, blocking preconditions, remediation path, and where to check results. With an output schema already present, no return-value explanation is required.

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 nonetheless adds decision semantics not obvious from the schema, e.g. that a past scheduledAt publishes now and that omitting scheduledAt falls back to the saved planned date. The publishNow/scheduledAt mutual exclusion is restated but reinforced with the error code.

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 (publish) and resource (a DRAFT/SCHEDULED post) and explicitly delineates the immediate-publish vs. schedule behaviors. It also names the sibling it is not ('Not for new content, use create_post'), so an agent can separate it from create_post and update_post without reading 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 preconditions ('Read the draft with get_post first and tell the user which of these will happen'), exclusions ('Other statuses fail with "Post is not a draft"'), and routes to the right follow-ups (update_post for fixes, create_post for new content, list_post_results for outcomes). The when-to-use decision tree is fully spelled out.

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

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

With annotations already covering side-effect safety, the description adds substantial context: it states that no post is saved or published, discloses the ai.generate permission and the exact 403 error, quantifies the cost at 2 AI credits including refund behavior and own-provider-key exemption, and instructs the agent not to retry when credits are exhausted. It also confirms cost parity with generate_caption.

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 text is front-loaded with the operation and return value, and each sentence carries operational value (permissions, credits, no-credit handling). The credit and permission material is dense and could be structured more crisply, but nothing is truly superfluous.

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 5 parameters, full schema coverage, annotations, and an output schema, the description fills the remaining gaps an agent needs: side-effect expectations, permission requirements, credit cost and refund rules, failure handling, and the return shape. Nothing material is missing 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%, so the baseline is 3, but the description adds workflow-level meaning beyond the schema: examples of prompt instructions and the specific use of partialText for continuing a partly written caption. The platform guidance largely duplicates the schema's own description, and workspaceId is not mentioned in the description, so it is not a full supplement.

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 ('Rewrite an existing caption following an instruction') and explicitly distinguishes it from generation of new captions by saying 'existing'. It also declares the return shape and that nothing is saved or posted, so an agent can tell exactly what this does versus siblings like generate_caption.

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

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

The description gives clear usage contexts: pass partialText to continue a draft, pass platform to hit a character limit, and check the output before posting. It also covers failure paths (403 permission_denied, exhausted credits -> explain and do not retry). It stops short of an explicit 'use generate_caption instead for new captions' routing statement, so it is not a full when/when-not/alternatives guide.

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, but the description adds substantial context beyond them: token deletion, removal from pending and recurring posts, plan-count impact, published posts remaining on the network, and the Facebook per-page scoping rule. It also names the required permission (accounts.manage, held by Admin), which annotations cannot convey.

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

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

Front-loaded with the core action and side effects, and nearly every sentence carries distinct information (side effects, status applicability, FB scoping, published-post exception, permission). It is on the long side at seven clauses and the reconnection sentence could be tighter, but nothing is redundant.

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 tool with an output schema already covering return values, the description covers what an agent still needs: irreversibility path, blast radius on scheduled content, permission requirement, and the confirmation ritual. 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 coverage is 100%, so the schema already documents both parameters and the baseline is 3. The description earns a bump by clarifying a semantic ambiguity the schema only hints at: for Facebook the identifier is the page, not the login, so only that page is affected. It says nothing extra about workspaceId, leaving that 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 ('Disconnect a social account from the workspace') and immediately anchors it to a familiar surface ('the same way the Connectors page does'). It also carves out the Facebook page-vs-login distinction, which is what would otherwise be confused with account removal at the login level.

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

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

Gives explicit conditions ('Works for accounts in any status, so an unauthorized account can be cleaned up without reconnecting it') and an explicit alternative path for reversal ('create_connect_link can send a link'), naming the sibling tool. It also states the required precondition of user confirmation.

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 (destructiveHint=true, openWorldHint=true, readOnlyHint=false) mark this as a state-changing, outward-facing call, and the description adds substantial extra context: missed slots are not published, the next occurrence becomes a SCHEDULED post ~24h ahead, ENDED is returned when the series is exhausted, and workspace-scoped ids yield 'Recurring post not found'. This is exactly the behavioral disclosure the 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?

The most decision-relevant facts (what resume does, when confirmation is needed) are front-loaded, and every sentence carries operational information. It is dense rather than padded, though the string of pauseReason enum values and ending-status note makes it slightly long for two parameters.

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

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

With an output schema present, the description does not need to enumerate return fields, yet it still names the returned statuses and nextOccurrenceAt. For a destructive, world-affecting mutation tool with two fully documented parameters, nothing an agent needs to invoke 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%, so the baseline is 3, but the description adds meaning beyond the field definitions by explaining that ids outside the named or current workspace return 'Recurring post not found' and by tying id provenance to list_recurring_posts. The workspace scoping rule is largely duplicated from the schema, keeping it 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 ('Resume a PAUSED recurring post') and the scope is tightened by 'PAUSED', which clearly separates it from pause_recurring_post and the generic get/delete recurring post siblings. An agent can identify the operation 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 clear when-to-use context ('confirm with the user first', fix the cause when pauseReason is CONNECTION_REMOVED/ACCESS_LOST/etc.) and describes the outcome when no slot remains. It does not explicitly name pause_recurring_post as the inverse alternative, but the preconditions are well specified.

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, the description discloses significant side effects: the feed posts new items as the resuming member, requires the posts.draft permission, checks within a minute, and returns 404 for out-of-workspace ids. It also warns about recurring pause if the cause is not fixed, which is valuable behavioral context for a destructive/open-world operation.

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

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

The description is front-loaded with the core action and proceeds through confirmation, permission, pause-reason caveats, and workspace scoping without filler. Every sentence contributes actionable information.

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

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

Given the output schema and annotations, the description covers all key gaps: side effects, permissions, required confirmation, edge cases around pause reasons, and workspace scoping. An agent has enough to decide whether and how 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 description coverage is 100%, so both id and workspaceId are already documented. The description only adds scoping detail (ids outside the workspace return 404) and does not explain parameter semantics 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?

The description states a specific verb (resume) and resource (paused RSS feed), and immediately clarifies the effect: clearing the pause reason and checking the feed within a minute. This clearly distinguishes it from sibling tools like pause_rss_feed and create_rss_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 explicitly says to confirm with the user first and gives conditions for when not to resume directly (pause reasons ACCESS_LOST, SUBSCRIPTION_INACTIVE, CONNECTION_REMOVED). It does not name an alternative sibling tool for those cases, but the when-to-use context is clear.

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

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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=true, openWorldHint=true) by disclosing state transitions (post moves to PUBLISHING), that retries are asynchronous, that content cannot change on retry, and the exact failure messages ('Unknown retry target', 'No failed platforms to retry'). This is unusually rich behavioral context for a mutation tool.

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

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

Front-loaded with the core action, then constraints, failure modes, and post-call guidance in a logical order. Dense and slightly long, but virtually every clause carries distinct 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?

An output schema exists, so return values need not be described. With error cases, state transition, async caveat, and the follow-up tool all covered, an agent has everything needed to invoke 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 baseline is 3. The description still adds value: it clarifies that platformIds accepts row ids, platform names, or omission, and specifies the failure behavior for values matching neither a row id nor a platform of the post.

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: re-queue publishing for a post's FAILED platforms. It scopes exactly which rows are affected ('Only rows with status FAILED are reset to PENDING'), which distinguishes it from siblings like publish_draft or update_post without needing to open their 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?

Explicit when-to-use and when-not: read each errorMessage first and retry only once the cause is fixed (reconnected account, replaced media), not for a platform-side restriction, 'which will just fail again'. It also routes the agent to list_post_results for the outcome, covering the follow-up step.

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; the description goes further by disclosing the non-obvious side effect (existing connections persist), the auth requirement (accounts.manage, held by Admin), and the return payload. This is context an agent cannot get from the 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?

Four short sentences, front-loaded with the action and its immediate effect, then side effects, permissions, and return value in descending order of importance. No filler.

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

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

For a destructive mutation with no output-schema ambiguity, the description covers effect, collateral behavior, required permission, and the follow-up tool, leaving nothing an agent needs before calling.

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

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

Schema coverage is 100%, including which tool produces the token ('returned by create_connect_link'), so the description correctly leaves parameters to the schema. It adds no extra meaning of its own, which is the baseline case.

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

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

States a specific verb and resource ('Revoke a connect link') plus the immediate effect ('stops working at once'), which separates it from create_connect_link and from remove_account. The agent can identify what it does 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 scopes the behavior ('accounts already connected through it stay connected') and names the correct alternative ('remove them with remove_account'), so the common wrong-tool mistake is pre-empted. It also states the permission prerequisite.

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