ShortSync

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

Annotations already flag this as a destructive, non-read-only, open-world operation, and the description adds important behavior beyond that: each post is validated for subscription, quota, connection health, and caption limits. It also discloses partial-failure semantics, notable for a batch mutation: one failure does not stop the rest. That is exactly the kind of operational context an agent needs before invoking a destructive batch 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?

The description is front-loaded with the core action and its batch nature, then moves through input modes, validation behavior, failure isolation, and return shape. Every sentence contributes operational information; there is no filler.

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

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

For a destructive batch mutation with no output schema, the description covers the essential gaps: input mode selection, per-post validation, partial failure behavior, and the shape of results (per-post). Combined with annotations and schema descriptions, an agent has enough to call this correctly and interpret outcomes.

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 each parameter well. The description adds relational meaning by clarifying the either/or usage between video_post_ids and video_upload_id, and by noting that platforms applies only with video_upload_id. That goes beyond individual field descriptions.

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

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

The description states a specific verb and resource: publishing multiple draft or scheduled posts immediately in one batch call. It explicitly distinguishes itself from the singular sibling publish_now by calling itself the batched equivalent. An agent can tell exactly what this 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?

It clearly says to use this when publishing more than one post and names publish_now as the per-post equivalent, which gives the agent a usable alternative. It does not explicitly state the inverse rule, such as 'use publish_now for a single post', so it stops just short of fully explicit when/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 a non-read-only, non-destructive, open-world write. The description adds genuine behavioral context beyond them: partial success is possible ('per-post results so you can see which succeeded and which failed'), uploads consume next slots in the given order, and all of an upload's platforms share one time. It omits retry/idempotency behavior and any auth or rate-limit notes, which keeps 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?

Purpose and the single-vs-batch routing are front-loaded, followed by the two scheduling modes and the return shape. It is dense and mostly earns its sentences, though the parenthetical asides ('same shape as the public API', 'like the app's bulk scheduling') could be trimmed.

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

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

No output schema exists, so the description carries the return-value burden, which it handles by stating per-post results are returned. For a batched write tool with a fully documented schema and safety annotations, the remaining gaps (auth prerequisites, failure/retry semantics) are minor.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds meaning the schema does not: next-slot assignment is ordered by input order, platforms within an upload share the slot, and recurrence mirrors the app's 'Repeat this post' semantics. That is useful clarification on top of a fully documented schema.

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

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

The description states a specific verb and resource ('Schedules multiple draft video posts in a single call') and explicitly frames it as the batched equivalent of schedule_post. An agent can distinguish it from schedule_post and from the broader sibling list 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 names the alternative (schedule_post) and the exact condition that selects this tool ('use this when scheduling more than one post'). It also routes the agent between the two scheduling modes (scheduled_for vs use_next_slot) with the conditions for each.

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 openWorldHint=true, and the description goes well beyond them: it discloses that posts on the same upload share one video_settings row, that an over-limit caption rejects the whole upload group, and that failed posts are re-queued with a new `status` once fixed. These are non-obvious side effects and failure modes that materially change how an agent should batch edits. It stops short of describing permission requirements or partial-failure semantics for non-caption errors.

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 purpose, then usage, then constraints, then failure behavior — a sensible order with no filler sentences. It is on the long side and repeats the precedence rule that the schema also states per field, which keeps it from a 5.

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

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

For a 9-parameter batch mutation with no output schema, the description covers the grouping model, the override precedence, the caption-limit failure path, and the re-queue outcome, which is most of what an agent needs. It does not describe the shape of the returned per-post results beyond the `status` field, leaving some ambiguity about how partial failures are reported.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning on precedence ('an entry's own value wins over the top-level one') and on the division of labor between video_post_ids and updates. That precedence rule is the single most error-prone aspect of this tool and is stated in prose rather than left to per-field schema text.

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

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

The description opens with a specific verb and resource ('Updates caption, title, description, first comment, and platform-specific settings on multiple posts') and immediately distinguishes itself from the single-post sibling by calling itself the batched equivalent of update_post. It also carves out an explicit non-capability (thumbnails), so an agent can route correctly without opening the schema.

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

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

It states the selection condition directly ('use this when editing more than one post') and names the alternative for the excluded case ('Does NOT support thumbnail operations — use update_post for those'). It also explains the two input modes (top-level shared values vs. per-entry overrides in updates), which is the main usage decision an agent faces here.

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 the description adds exactly the consequences an agent needs beyond that: scheduled posts are removed from the library and the workflow will not pick that source post again. It also discloses the failure mode for already-published reposts, which no annotation conveys.

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

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

Three sentences, each with a distinct job: what happens, parameter provenance, and failure condition. Effects are front-loaded before the parameter note, with no filler.

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

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

For a 2-parameter destructive tool with no output schema, the description covers effect, side effects, parameter sourcing, and failure conditions. 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 earns extra by disambiguating post_id as the workflow entry id rather than a platform post id, and by naming the source tool for each parameter. It adds meaning beyond the field descriptions, though not format details.

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

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

Specific verb (cancels) + resource (an upcoming repost from a Repurposing workflow) with the scope qualifier 'from a Repurposing workflow' that separates it from the sibling cancel_scheduled_post. An agent can identify the action and its domain 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?

Explains the preconditions ('fails if the repost has already gone out') and points to both prerequisite lookup tools (list_repurposing_workflow_posts for post_id, list_repurposing_workflows for workflow_id). It does not explicitly contrast with cancel_scheduled_post or delete_repurposing_workflow, so it falls short of naming alternatives.

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

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

The description adds substantial behavioral detail beyond the destructiveHint annotation: it removes the QStash job, cancels a pending auto-retry, returns the post to Draft, clears a failed post's error, and refuses posts that have already published. These are precise effects and preconditions for a destructive mutation.

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

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

The description is four tight sentences, front-loaded with the effect followed by usage guidance, alternative routing, and a refusal condition. Every sentence contributes useful information.

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

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

For a destructive mutation with no output schema, the description covers outcomes, side effects, preconditions, and alternatives. The schema already documents both parameters, so no critical invocation detail 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 video_post_id and idempotency_key are already fully documented in the schema. The description does not add syntax or format details about the parameters, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: cancels scheduled or failed posts. It also distinguishes the action from retry_post and from posts that have already published, so an agent can identify its role even with many sibling tools present.

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 when to use it: stop a scheduled publish before it fires or park a failed post for editing. It also names the alternative for republishing (retry_post) and states the refusal condition for already-published 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 readOnlyHint/openWorldHint/non-destructive, and the description adds real value on top: live external reads from Instagram, per-account ok:false + reason on unreadable accounts, and the auth dependency with a recovery path. The one gap is that it doesn't say anything about latency, rate limits, or whether partial failures still return the remaining accounts' data.

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

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

Front-loaded with the verb and scope, then returns, then caveats, then prerequisites, then example intents. The long metrics clause is dense but each item is information the agent needs to describe results to a user; 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?

There is no output schema, so the description carries the return contract itself and does so fully: per-account followers, posts, 12-post averages, engagement-rate formula, posts-per-week, and the `own` label. Combined with the auth prerequisite and error shape, an agent has everything needed to call it and interpret the response.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning the schema doesn't: the workspace account is always included and labeled `own`, which tells the agent how to interpret the result relative to `usernames`. It doesn't add anything beyond the schema for `workspace_id`, and the @/profile-link/empty-array nuances are already in the schema text.

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

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

States a specific verb and resource ('Compares the workspace's Instagram account with up to 5 other public Instagram Business or Creator accounts, read live from Instagram') and enumerates exactly which metrics come back. The scope (max 5 others, own account always included as `own`, public Business/Creator only) makes it unmistakable against siblings like get_workspace_analytics or get_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 trigger questions ('how do I compare to @competitor', 'which of these creators gets more engagement') plus the prerequisite (Facebook Login for Instagram) and an explicit alternative when the prerequisite is missing (get_connect_link). It also states the failure condition for personal/age-gated accounts, so the agent knows when this tool simply won't work.

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 (which declare a non-destructive, open-world write), the description adds substantial behavioral detail: a workspace has one Discord connection holding several channels, each webhook adds a channel, re-sending an existing webhook refreshes it, the first channel is a default channel, and the webhook URL is stored encrypted and never returned. It also describes the return value (connection and added channel with id for platform_settings.channelIds).

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

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

The description is front-loaded with the core action, then provides necessary user-facing instructions and behavioral context. Every sentence contributes, though the step-by-step Discord navigation is slightly detailed for a tool description and could be trimmed without losing critical 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 lack of an output schema and minimal annotations, the description is complete: it covers the return shape, idempotency/side effects, secret handling, and the distinction between adding and refreshing a channel. An agent has everything needed to call the tool 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 description coverage is 100%, so all four parameters are already documented in the schema. The description reinforces a few points (label defaults to webhook name, workspace_id source, idempotency behavior) but adds little meaning beyond what the structured fields already provide, so the baseline 3 applies.

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

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

The description opens with a specific verb and resource: 'Adds a Discord channel to a workspace from a channel webhook URL.' This clearly distinguishes it from sibling tools like list_discord_channels (which lists) and other connection-related 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 explains how the user obtains the webhook URL in Discord, notes it works for every channel type including forum channels, and describes what happens when sending an already-connected webhook (refreshes it). It does not explicitly name alternative tools or state when not to use this, but the context is clear enough for an agent to act.

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 indicate this is a non-read-only, non-destructive write operation. The description adds meaningful context beyond annotations: per-platform limits, enforcement at publish time, unsupported platforms, and how the returned upload_id is consumed. It does not cover failure behavior or idempotency semantics, but the schema handles idempotency.

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 workflow are front-loaded, and each sentence is information-dense. The platform-limit list is long but specific and relevant; it is arguably more detailed than strictly necessary for invoking this tool, since limits are enforced at publish time.

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

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

For a four-parameter creation tool with full schema coverage, annotations, and no output schema, the description is complete enough: it explains purpose, prerequisites, ordering, platform constraints, unsupported platforms, and how the returned upload_id is used downstream.

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

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

Schema description coverage is 100%, and the schema documents workspace_id, child_upload_ids ordering/min/max, cover_index, and idempotency_key. The description reinforces that upload IDs are passed in display order, but adds little parameter detail beyond what the schema already provides.

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

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

The description opens with a specific verb and resource: 'Groups multiple already-uploaded media items into a single carousel post.' It clearly distinguishes this tool from siblings by describing an intermediate assembly step before create_post_draft publishes the carousel.

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 the required workflow: upload media first via create_video_upload or create_video_upload_from_url, pass upload IDs here in display order, then use the returned upload_id with create_post_draft. It also names platforms that do not support carousels, giving clear exclusions.

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 openWorldHint=true, and the description earns credit beyond them by explaining why: it starts messaging real people immediately, is limited to once per person per rule, and messages land in Message requests where they may go unseen. The safety confirmation requirement and plan gating are exactly the kind of context annotations cannot carry.

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

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

Three sentences, front-loaded with the action and mechanism, then the risk warning and mitigation, then the plan requirement. Nothing is repeated from the schema and every sentence changes how the agent would behave.

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, risk, preconditions, plan gating, and delivery channel for a mutation tool with no output schema. The only minor gap is that it never says what is returned on success (a rule record, including the disclosure_missing field referenced in the schema), which matters slightly given there is no output schema.

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

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

Schema coverage is 100% and the parameter descriptions are already thorough (keyword whole-word matching, 1,000-byte DM limit, idempotency window, post_id null meaning all posts). The description only indirectly touches parameters via 'confirm the keywords and text' and 'enabled=false', so it does not add meaningful semantics beyond the schema. Baseline 3 applies.

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

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

States a specific verb (Creates) and resource (an Instagram comment DM rule) and then explains the mechanism: anyone commenting a keyword receives the message as one private DM, once per person per rule. That mechanism-level detail makes it unmistakable against siblings like update_comment_dm_rule or reply_to_comment without touching 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 clear preconditions: confirm keywords and text with the user first, or set enabled=false, and the plan requirement (Team plan or Creator add-on). It stops short of naming the sibling that modifies an existing rule (update_comment_dm_rule) or the listing tool, but the when-to-use context is strong.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the write/safety profile is structured. The description adds real value beyond that – a feature-flag precondition that will fail the call if Concepts is off, the default landing column ('idea'), and the calendar side effect of due_date. It stops short of describing the return payload or what errors look like, so it is good but not rich.

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

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

Front-loads the core action and resource, then adds the prerequisite and the two usage patterns. Slightly redundant with the schema on due_date and workspace_id, 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?

For a 10-parameter mutation with no output schema, the definition covers the prerequisite, the default state, and the calendar behavior. A hint about what is returned (e.g. a concept id for later update_concept calls) would close the remaining gap.

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

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

Schema coverage is 100% and every parameter carries its own description, so the baseline is 3. The description largely restates schema content (due_date planning, workspace_id lookup) rather than adding new meaning, though it does reinforce the default 'idea' status.

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

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

Specific verb ('Creates') plus concrete resource ('content concept / idea / brief') and its location (ideation bank → Library → Concepts). Clearly distinct from list_concepts (read), update_concept (modify), and create_post_drafts_from_concept (conversion), so an agent can route correctly.

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 prerequisite (Concepts must be enabled in Settings → Advanced) and a routing hint (use list_workspaces to resolve workspace_id), plus the planning pattern via due_date. It does not, however, say when to prefer create_post_draft or create_post_drafts_from_concept over this tool, so the sibling discrimination is only partial.

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

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

The description discloses crucial operational behaviors beyond the annotations, specifically: folder name uniqueness (case-sensitive among siblings) and the maximum nesting depth of 5. This is critical execution context.

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

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

The description is highly dense and efficient. Every clause adds essential constraints or workflow logic, making it appropriately sized and highly effective.

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 thorough input schema and the detailed explanation of constraints (nestability, uniqueness, limits), the definition provides all necessary context for the agent to execute the tool correctly.

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

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

While schema coverage is 100%, the description adds high-value semantic context by detailing the strict naming constraints (case-sensitive, max 80 chars) and the required prerequisite for nested folders.

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 purpose is perfectly clear: 'Creates a new folder inside a workspace.' It explicitly handles the nuance of optional nesting.

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 provides explicit instructions on workflow, stating 'Use list_folders first to look up the parent_id when creating a subfolder.' It also defines hard operational constraints (80 char limit, 5 level cap).

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 traits beyond the annotations: an existing draft/failed/ready post is reset to draft rather than duplicated, unsupported content types are refused, per-platform posting limits (Tumblr 250 posts/20 videos per day, Reddit 10 per workspace per day) and per-platform constraints (no carousels, no custom thumbnail) are spelled out. Annotations only say it is a non-read-only, non-destructive write; the reset behavior is exactly the kind of mutation context the description must 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?

Front-loads the core action and upsert semantics in the first two sentences, then gives constraints. The 16-platform content-type chain is a single dense sentence that would be easier to scan as a table, but it is information-dense rather than 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 no output schema, the description covers inputs, refusal conditions, per-platform quirks, and defaults thoroughly. It does not say what the tool returns (presumably a draft post id needed for subsequent update_post calls), which is the main remaining gap for a create-and-configure workflow.

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 the accepted-content-type matrix per platform and the Snapchat Spotlight caveat, which is not fully captured in the platform parameter description. The idempotency_key and video_upload_id semantics live entirely in the schema and are not echoed, which is acceptable.

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 plus scope: 'Creates a draft video post for a single platform on top of an existing video upload.' The 'single platform' and 'on an existing video upload' qualifiers distinguish it from the plural create_post_drafts and from the upload-creation tools.

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

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

Gives concrete call guidance: 'Call once per platform' and 'use list_video_uploads first to get a video_upload_id', plus platform refusal rules. It stops short of explicitly routing between itself, create_post_drafts, and schedule_post/publish_now, so the agent must infer when a single draft is preferable to a batch or a direct publish.

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

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

Annotations only declare it is a non-read, non-destructive, closed-world write. The description goes well beyond that by disclosing partial-failure semantics ('platforms that can't take the upload's content type come back with ok: false') and a full per-platform content-type matrix, which is the main failure mode for a batched write. It stops short of stating permissions/account requirements or whether successful drafts are later publishable, keeping it at 4 rather than 5.

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

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

Front-loaded with purpose and the sibling comparison in the first two sentences; the content-type matrix follows as reference material. The enumerated platform list is dense prose that would read better as a table, but every clause carries actionable constraint 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?

No output schema exists, and the description compensates by explaining the return shape (per-platform results with each post's id and ok flags). For a 3-parameter batch write with full schema coverage, 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, but the description adds real meaning for the 'platforms' parameter: the accepted content types per platform and the Snapchat Spotlight video-only caveat constrain which values will succeed. Idempotency and video_upload_id semantics are left entirely to the schema.

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

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

States a specific verb and resource ('Creates draft video posts') plus the distinguishing scope ('for multiple platforms in a single call'). It explicitly separates itself from the singular sibling create_post_draft, so an agent can route 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 an explicit selection rule: 'Equivalent to calling create_post_draft once per platform but batched — use this instead when drafting to more than one platform.' The alternative and the condition that selects it are both named, leaving nothing to inference.

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

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

Annotations already declare a non-destructive write, but the description adds substantial beyond-schema behavior: which fields are copied (caption, per-platform captions, first comments, YouTube title/description override), that notes are NOT copied, the media resolution precedence, and the resulting board state transitions (Draft → Scheduled → Published). That is exactly the kind of side-effect disclosure an agent needs before a 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-loaded with the core action and no filler sentences; every clause carries operational detail. It is a dense single paragraph, though, and the media-selection chain plus the lifecycle sentence could be split for faster 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?

Covers source resolution, copy semantics, media fallback, linking, and lifecycle consequences, with no output schema needed to infer results. For a 5-parameter write tool with no output schema, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3; the description still adds value by explaining precedence ("Overrides the concept's attachment and linked upload") and the conditional reason to pass attachment_id ("if it has several"). idempotency_key semantics are left entirely to the schema, keeping it just shy 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?

Opens with a specific verb+resource ("Turns a concept into draft posts") anchored to a concrete UI affordance ("like 'Create draft' on the Concepts board"). This clearly separates it from plain create_post_draft / create_post_drafts, which presumably don't take a concept as the source.

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 downstream routing ("Then use batch_update_posts for platform settings and batch_schedule_posts to schedule") and a media-selection decision tree (video_upload_id > linked upload > attachment). It never explicitly contrasts with the sibling single-draft tools, 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 only declare the generic write/non-destructive profile; the description goes far beyond by disclosing the return shape ({ upload_token, presigned_url, method, expires_at }), that the URL expires, allowed Content-Types, the mandatory finalize_post_thumbnail follow-up, and the absence of cleanup side effects. It also reveals the cross-post sharing behavior that a caller would otherwise not anticipate.

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 return contract, then alternatives last — a sensible ordering with little filler. The platform list ('YouTube, Instagram Reels, Facebook Reels and Pinterest') is the one sentence that borders on trivia for a caller deciding how to invoke the tool.

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

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

For a write tool with no output schema, the description supplies the return shape, the required follow-up call, the upload protocol, and the side-effect profile. Nothing an agent needs in order 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% and the video_post_id description already explains the shared-cover semantics, so the schema does the heavy lifting. The description reinforces that the same video_post_id must be passed to finalize_post_thumbnail but adds no new syntax or constraints for idempotency_key. 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 precise verb and resource ('Reserves a presigned S3 PUT URL scoped to a specific video post's custom-thumbnail slot') and explicitly separates itself from create_video_upload ('Does NOT create a video_uploads library entry'). An agent can distinguish it from every sibling without opening a schema.

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

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

Gives the exact triggering condition ('when the user has a LOCAL image file ... for an existing video post') and names two alternative paths with the condition selecting each: public image URL -> update_post with custom_thumbnail_url; already-in-library image -> update_post with custom_thumbnail_upload_id. Both when-to-use and when-not-to-use 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?

It reveals critical operational constraints not found in the schema or annotations, such as the limit of 'one upload per plan' and the policy that ShortSync's own posts to the source are never reposted.

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 very long, which is necessitated by the tool's complexity, but the information is highly dense and well-ordered, grouping logic by source and workflow type efficiently.

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 complexity of a multi-platform, multi-mode, scheduled, and constrained workflow creator, the description is exceptionally complete and addresses almost all edge cases and limitations an agent might encounter.

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?

Although the schema is 100% covered, the description provides crucial context for the function of specific parameters like caption generation rules (X vs Instagram) and the constraints of 'target_options' (e.g., 'list_platform_connections').

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 purpose is clearly stated: to create a Repurposing workflow that repost source content to connected accounts. It immediately defines the core function and operational 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?

The description acts as a decision tree, clearly outlining the constraints and necessary inputs based on source type (IG/FB, Twitch, RSS) and workflow kind (new_posts, existing). This prevents common configuration errors.

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 cover the safety profile (non-destructive write), while the description adds the meaningful behavioral details: the call returns an upload_id, caption acts as the post body, length limits are validated at draft-save time, and scheduling fails without a 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?

Front-loads what the tool does and then the follow-up chain in three dense sentences with no filler. The long parenthetical enumeration of eleven platforms is slightly verbose but earns its place by telling the agent which platforms accept text posts.

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?

Everything an agent needs is present: what it creates, the return value (upload_id, standing in for the absent output schema), the required follow-up calls, and the caption constraint. Nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes further by clarifying that the caption is shared across every platform and can be supplied later via batch_update_posts, which is semantics the schema only hints at.

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

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

States a specific verb and resource ('Creates a text-only post (no media)') plus the return value, and distinguishes itself from media-creating siblings like create_carousel and create_video_upload by the explicit 'no media' qualifier.

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 downstream workflow: call create_post_drafts with the upload_id, batch_update_posts for per-platform captions, then batch_schedule_posts or batch_publish_now. It also names the precondition (a text post can't be scheduled/published without a caption) and lists which platforms accept text 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?

The description adds substantial behavioral context beyond the annotations: it describes the response object, the required PUT method, Content-Type constraints, the 403 risk when required_headers are not echoed, size limits, and the need to call finalize_video_upload afterward. These details go well beyond the safety hints in the annotations and do not contradict 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?

The description is appropriately long for a multi-step upload workflow and is front-loaded with the core action, the alternative sibling, the response shape, PUT instructions, limits, and the finalize step. Each section serves a clear operational purpose.

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

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

Although there is no output schema, the description explicitly documents the response fields including upload_id, presigned_url, method, expires_at, and required_headers. It also gives enough workflow guidance to complete the upload and finalize it correctly, including constraints and the follow-up tool.

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

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

Schema description coverage is 100%, so workspace_id, filename, and idempotency_key are already well documented in the schema. The description reinforces the filename/header workflow and upload constraints, but it does not add significant parameter-level meaning beyond what the schema provides.

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

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

The description states a specific verb and resource: it reserves a NEW video/image library slot and returns a presigned S3 PUT URL. It clearly distinguishes itself from the sibling create_video_upload_from_url and from thumbnail-setting behavior on existing posts.

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: use this when the file is local and you do not want to host it publicly first, with create_video_upload_from_url named as the URL-based alternative. It also gives an explicit DO NOT case for cover/thumbnail creation and routes that use case to update_post with the appropriate parameters.

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 explains that a new video_uploads row is created, the tool returns the new video_upload_id, and server-side SSRF guards apply: https only, no private IPs, Content-Length required, and size limits of 950 MB for video and 20 MB for images. It also highlights the important behavioral distinction that this creates a separate library entry, not a cover image.

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

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

The description is front-loaded with the primary purpose and return value, then moves through practical usage, filename guidance, safety limits, and the critical misuse warning. Despite its length, every section provides actionable information for correctly invoking the tool.

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

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

Given the tool's complexity and the absence of an output schema, the description covers creation behavior, return value, URL requirements, filename inference needs, size limits, SSRF restrictions, and the key non-use case. An agent has enough information to call it correctly and avoid confusing it with cover-image or draft-creation tools.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters thoroughly. The description reinforces the filename guidance for generic Content-Type responses and mentions public https URL behavior, but most of that detail is already present in the schema, so it adds limited additional parameter semantics beyond structured data.

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 precise verb and resource: downloading a video or image from a public URL into ShortSync and registering a NEW video_uploads row. It also distinguishes this tool from create_post_draft and from update_post by explaining that this creates a separate library entry rather than a cover image.

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

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

It gives a concrete when-to-use scenario ('here's my Dropbox/Drive/S3 link, post it') and an explicit when-not-to-use case: it must not be used to set a cover/thumbnail on an existing video post. It also names the correct alternative, update_post with custom_thumbnail_url or custom_thumbnail_upload_id.

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, so the description doesn't need to re-establish that this is a write. It does add genuinely new behavioral context by disclosing that send history is deleted too and why that matters (a new rule could DM the same people again). It stops short of stating irreversibility or permission requirements outright.

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

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

Two sentences, zero waste, with the destructive scope front-loaded and the safer alternative placed second where it reads as a guardrail.

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 two fully documented required parameters, no output schema, and annotations covering the safety profile, the definition is nearly complete. The only remaining gap is an explicit statement that the deletion is permanent and cannot be undone.

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 documented in-schema with sourcing hints (list_comment_dm_rules, list_workspaces). The description adds no parameter meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Deletes an Instagram comment DM rule') and adds the consequential scope ('and its send history'), which lets an agent distinguish it from update_comment_dm_rule 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 routes the agent away from this tool when the intent is only to pause: 'To stop one for now, use update_comment_dm_rule with enabled=false instead.' Both the alternative and the selecting condition are 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?

Annotations already flag destructiveHint=true, so the description earns credit for disclosing what annotations cannot: subfolders are cascade-deleted, videos are preserved but unfoldered (folder_id null), and the response shape is { success: true }. It stops short of stating whether the deletion is recoverable or what permissions/role are required, which are the remaining behavioral unknowns for a 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?

Three tight sentences with zero filler: the operation first, the dangerous side effect second, the non-obvious preservation behavior third, and the return value last. Front-loaded and every sentence carries distinct 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?

No output schema exists, yet the description supplies the return value, the cascade side effect, and the nulling behavior for videos — covering the questions an agent must answer before firing a destructive call. Combined with the destructive annotation and fully documented two-parameter schema, nothing essential 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% — folder_id documents its source (list_folders) and idempotency_key documents its 10-minute retry semantics in full. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ("Deletes a folder") and immediately scopes the blast radius with cascade semantics, which is exactly what separates it from update_folder or move_video_to_folder in the sibling list. An agent can identify the operation and its scope 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?

Usage is only implied by the verb — delete a folder when you want it gone. There is no guidance on when not to use it (e.g., to remove a video from a folder, use move_video_to_folder), no confirmation/permission prerequisite, and no mention that deletion may be irreversible. The schema's pointer to list_folders for the ID is the only navigational aid.

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 openWorldHint=true, so the description is not carrying the safety burden alone — yet it still adds substantial context: exactly what is destroyed (live post, views, likes, comments), what survives (ShortSync post kept as an audit record with status "removed", upload retained), and per-platform capability limits (TikTok/Snapchat/Reddit unsupported; Instagram/Threads conditional) with the resulting error behavior.

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

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

Front-loaded with the highest-severity signal ("DESTRUCTIVE AND IRREVERSIBLE") before any procedural guidance, and each subsequent sentence carries distinct information. It runs long for a two-parameter tool and a couple of clauses (the dashboard analogy, the parenthetical about views/likes/comments) are reinforcement rather than new facts, keeping it just below top marks.

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

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

No output schema exists, yet the description supplies the post-condition (post marked "removed", upload kept) and the failure mode (platform-specific errors instructing the user to delete in-app). Combined with the confirmation requirement and the sibling routing rule, an agent has everything needed to decide and to act safely.

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% — both video_post_id and idempotency_key are fully documented in the schema, including the warning that it is not the platform's own post ID. The description adds no parameter-level detail of its own; its mention of status "published" only indirectly scopes which ID is valid. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ("deletes an already published post from the social platform it went out on") and immediately bounds it with "Only works on posts with status 'published'". It also names the sibling it is not (cancel_scheduled_post) and the class of posts that sibling handles, so an agent can distinguish it without opening any schema.

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

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

Explicit when-to-use (published post, matches the dashboard's "Delete from platform"), explicit process constraint ("Always confirm with the user first, naming the platform and the post"), explicit prohibition ("never call it on your own initiative or to clean up"), and an explicit alternative for drafts/scheduled/failed posts. 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, so the bar is lower, but the description still adds real value: published reposts persist, unshipped posts default to drafts, and only 'remove' deletes them. The one gap is that it never states the workflow deletion itself is permanent/irreversible or whether confirmation or special permissions are needed.

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

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

Four tight sentences, front-loaded with the action, then consequences, then the parameter caveat, then the alternative. Every sentence carries distinct information and nothing is 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 two-parameter destructive tool with no output schema, this covers survival semantics, default branch behavior, and the non-destructive alternative. It stops short of stating permanence of the workflow deletion itself, the main remaining unknown an agent would want before calling it.

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

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

Schema coverage is 100% and the stop_action parameter already documents both enum values and the 'drafts' default, so the description's rephrasing of stop_action is largely redundant. It contextualizes it slightly ("for a scheduled ('existing') workflow") but adds no syntax or scope 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?

Specific verb-plus-resource ("Deletes a Repurposing workflow") in the first sentence, immediately followed by what survives the deletion. It also distinguishes itself from update_repurposing_workflow, so an agent can tell the two apart 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 names the alternative path and its condition: "To stop it for now instead, use update_repurposing_workflow with enabled: false." That is a rare, unambiguous when-not-to-use statement with the substitute call 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?

Goes well beyond destructiveHint=true by disclosing the exact cascade: media and thumbnails removed, all scheduled/queued/draft posts from the upload cancelled, already-published posts left live. It also states irreversibility and a permission restriction (workspace clients), which the annotations cannot express.

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

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

Five short sentences, front-loaded with what is deleted, then consequences, then the safety instruction. Every sentence carries distinct information — cascade, published-post exception, irreversibility, permission — with no filler.

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

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

For a destructive mutation with no output schema, this covers the full decision surface: scope, side effects, exception for published content, irreversibility, and authorization limits. Nothing an agent needs before invoking it is missing.

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

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

Schema description coverage is 100% and both parameters are documented in-schema, including the idempotency key's retry window. The description adds no additional parameter meaning, so the baseline of 3 applies.

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

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

States a specific verb (deletes) and resource (an upload) and enumerates the covered media types (video, image, carousel, text post), so the agent knows exactly what object class is affected. The analogy to the ShortSync dashboard anchors the semantics without ambiguity.

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

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

Gives clear operating conditions: confirm with the user first, and workspace clients can't delete — that rules out a whole caller class. It does not, however, route to the sibling alternative delete_published_post, which is the obvious choice when the target is an already-published post rather than a library upload.

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 alone (readOnlyHint=false, openWorldHint=true) would leave the agent confused about why a read-looking diagnostic isn't read-only; the description resolves this by disclosing that the call may kick off a background sync when data is stale, and reports that in a `sync` field. It also surfaces failure modes ('sync_never_ran', 'sync_failed' with fetch_error, token expiry) and plan limits beyond what annotations cover.

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 one-line purpose, then a scannable state list — the length is largely justified because there is no output schema and these enum values must be documented somewhere. A few sentences (e.g., restating actionable/next_step after already explaining each state) are mildly 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?

With no output schema, the description carries the full burden and does so: it enumerates all eight `state` values, names the accompanying fields (explanation, fetch_error, actionable, next_step, sync, last_synced_at), and explains the side effect and staleness caveat. Nothing an agent needs to interpret the response 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 parameter and the schema already documents it at 100% coverage, including where to obtain video_post_id. The description adds no additional meaning about the parameter's format or constraints, so the baseline 3 for high schema coverage 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 ('Diagnostic — returns one of eight concrete states explaining why a post's analytics look the way they do') and immediately distinguishes itself from the sibling that produces the raw numbers, get_post_analytics. An agent can tell exactly what this returns 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?

Explicit routing rule: 'Use this instead of inferring from raw zeros / nulls in get_post_analytics.' It also gives follow-up guidance ('call again in a few minutes for fresh ones') and explains what a sync.status of free_plan_limit or daily_limit implies about the data's currency.

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 by disclosing what is mutated (the post's video_settings row), a cross-post side effect (sibling posts on the same upload use the cover at publish time, across four named platforms), and concrete error strings with remediation. This is exactly the kind of write-scope and failure-mode detail 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-loads the action and the prerequisite, then layers in side effects and errors. Every sentence carries information an agent needs; there is no filler or restatement of the 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?

For an annotated mutation with no output schema, the description covers prerequisite state, mutation target, cross-post consequences, and error handling. An agent has everything needed to call it correctly and to recover from the common failure mode.

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 value by tying upload_token to the 'reserved' error condition and explaining that its absence of a landed PUT is what triggers the retry. The idempotency_key is left to the schema, which documents it well.

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 ('finalizes a thumbnail upload') and explicitly ties it to the sibling create_post_thumbnail_upload, so an agent can place it in the upload flow without opening either schema. It also names the exact fields written (custom_thumbnail_url, custom_thumbnail_s3_key).

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 ordering precondition: call only after PUTting image bytes to the presigned URL obtained from create_post_thumbnail_upload. The retry guidance for the 'reserved' error also tells the agent what to do when the prerequisite isn't yet satisfied.

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

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

Goes well beyond annotations by documenting both return states, the retry guidance for the 'reserved' case, allowed MIME types, size caps, and the background-timer auto-finalization. Annotations only cover readOnly=false and destructive=false; the description supplies the substantive behavior (mutation semantics, delay window, optionality).

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

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

Front-loads the purpose and sequencing, then stacks return values, error conditions, and the optionality note in compact sentences. Every sentence carries distinct information with no repetition of the title or annotations.

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

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

No output schema exists, yet the description inlines both response shapes ({status:'ready',...} and {status:'reserved'}) plus error cases and retry timing, leaving nothing an agent needs in order to invoke and interpret this tool correctly.

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

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

Schema description coverage is 100%, so upload_id, workspace_id, and idempotency_key are already fully documented. The description adds no parameter-level detail (e.g., it never mentions idempotency or workspace matching), so it sits at the baseline where schema does the work.

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

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

States a specific verb+resource and ties it directly to its predecessor ('Finalizes an upload started with create_video_upload'), which disambiguates it from siblings like create_video_upload and cancel_scheduled_post. An agent can identify this as the terminal step of the upload lifecycle 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 says when to call ('after PUTting bytes to the presigned URL') and offers the alternative path ('the upload also finalizes on its own via a background timer... calling this is optional but faster'). This is a clear when/when-not with a named alternative mechanism.

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), yet the description still adds substantial behavior: `growth` is null without a baseline, `needs_reconnect` flags broken connections, Instagram clamps windows to 30 days and surfaces this via `growth_window_days`, and YouTube/Facebook/Instagram deltas are fetched live while others come from daily snapshots. That is exactly the kind of data-quality caveat an agent cannot get from the schema.

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

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

Front-loaded with the resource and the question it answers, then layered with caveats in decreasing priority. It is dense rather than padded, though the snapshot-vs-live sentence is compacted enough to require a second read.

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

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

There is no output schema, so the description carries the burden of return values and does so fully: it names each entry field, its nullability, and the one platform-specific shape deviation. An agent can consume and interpret the response without further documentation.

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 genuinely adds meaning: `previous` is defined as the last snapshot at or before `from`, and the platform-window interaction (Instagram 30-day clamp) affects how `from`/`to` behave. That goes beyond the schema's terse ISO-8601 notes.

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 and enumerates exactly what is returned: follower/subscriber/following/post counts per connected account plus in-window growth. It even notes the Google Business Profile variant, so the agent knows the shape changes by platform. It stops short of naming siblings like get_workspace_analytics or compare_instagram_accounts, so there is no explicit 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?

The framing question "how are my followers trending" gives an unambiguous use case, and the Google Business carve-out clarifies a case where the tool still applies. There is no when-not guidance and no named alternative for overlapping analytics tools, which keeps it out of the 5 range.

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 adds substantial context beyond them: the link carries no credentials, only works in a browser signed in to ShortSync, and never expires. It also discloses the post-condition (the account appears in list_platform_connections once approved) and that some platforms demand a handle/server/Page/channel first.

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

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

The critical facts (what it returns, that the user must act, that the link is safe and non-expiring) are front-loaded in the first three sentences. The final clause about `action` and `steps` is slightly rambling but still earns its place since no output schema exists.

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

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

With no output schema, the description carries the return-value burden and does so: `url`, `action` (first connect vs reconnect) and `steps` (per-platform prompts) are all explained. For a read-only, two-parameter tool, an agent has everything needed to call it and to tell the user what happens next.

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 carry their own descriptions including a full 17-value platform enum, so the schema does the heavy lifting and baseline 3 applies. The description does add value by tying the platform/workspace choice to the 'needs_reconnect' health state and by explaining the returned `action` and `steps` fields, but it gives no syntax or selection guidance for 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 ('Returns a link the user opens to connect a social platform to a workspace') and scopes it to two cases: first connect and reconnect. It is clearly distinguished from the sibling list_platform_connections, which is named as the discovery/status tool rather than the action tool.

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

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

Gives an explicit trigger ('connect a social platform... or reconnect one whose health is needs_reconnect in list_platform_connections') and names the sibling that surfaces that condition. It also sets the expectation that the agent cannot complete the flow alone ('Connecting always needs the user') and states the verification step afterwards.

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 non-obvious behavior beyond the readOnlyHint annotations: data comes from ShortSync's cached inbox sync and no platform API call occurs on read, which lets an agent reason about staleness and latency. It doesn't state how stale the cache may be or whether a sync_inbox call is needed to refresh, so not a 5.

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

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

Three short sentences: purpose and ordering first, then the usage pointer, then the caching caveat. Every sentence carries distinct information with zero repetition.

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

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

With no output schema, the description should hint at what a message looks like and whether there's pagination; it does say results are ordered oldest-first so the tail is newest, but doesn't say if there's a has_more cursor beyond limit. Adequate for a small read tool but slightly incomplete.

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/default/max and workspace_id auto-resolution are already documented. The description only repeats the oldest-first ordering and adds no new parameter guidance, which is the baseline 3.

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

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

States a specific verb ('Returns') and resource ('messages in an inbox conversation') with a scope qualifier (oldest-first). This clearly separates it from list_inbox_conversations, which returns conversations rather than their messages, and the schema's conversation_id description reinforces the chain.

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

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

Explicitly says to call it 'before reply_to_comment when you need thread context', naming both the sibling and the condition. It lacks an explicit when-not (e.g., don't use for a single message, or when live data is required), so it falls just short of 5.

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

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

The description goes well beyond the annotations by disclosing that data comes from locally cached analytics rather than a live platform fetch, explaining dashboard parity caveats, unsupported platforms, X API key requirements, and background sync behavior. This is exactly the kind of behavioral context an agent needs before calling a tool whose annotations alone would not reveal these operational traits.

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

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

The description is front-loaded with the core purpose and main subfolder behavior, and it uses clear paragraphs for caveats, platform coverage, and freshness. It is fairly long and some platform coverage details are verbose, but most sentences carry useful behavioral context 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?

Given the tool's complexity, the 100% schema coverage, and the absence of an output schema, the description is highly complete. It explains the response shape, per-platform and per-video breakdowns, platform-specific limitations, and sync freshness behavior, leaving little ambiguity for an agent invoking it.

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

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

Schema coverage is 100%, so the schema already documents all three parameters in detail, establishing a baseline of 3. The description adds useful contextual meaning for include_subfolders and the folder_id lookup path, though it does not add much about the days parameter 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?

The description states a specific verb and resource: it returns aggregated analytics for a folder across every video inside it. It also distinguishes the folder-level rollup from workspace-level and post-level analytics through explicit scope and examples, so an agent can identify the 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?

The description gives clear usage context, including the default subfolder rollup behavior, the include_subfolders=false alternative, and the prerequisite to use list_folders for a folder_id. It does not explicitly route the agent to sibling tools such as get_video_analytics or get_post_analytics when finer-grained analytics are needed, so it stops short of full when-to-use/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?

With readOnlyHint=false, the description supplies the missing reason: the call can kick off a background sync and returns sync.status of 'started'/'in_progress', with 'free_plan_limit'/'daily_limit' meaning no sync ran and numbers may be stale. It further discloses what zeros actually mean per provenance value and per fetch_status 'unavailable', which an agent cannot infer from any structured field.

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, then organized into clearly separated topics (metrics, provenance, fetch_status, freshness). It is long for a single-parameter tool and the provenance block partly overlaps the sibling explain_post_analytics_state, but nearly every sentence carries decision-relevant detail.

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

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

There is no output schema, so the description must carry the return semantics, and it does: which metrics appear, platform-specific fields, nullability causes (unsupported metric vs. no sync yet), and stale-data behavior. An agent has enough to call this correctly and to interpret a zeros 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% and the single parameter video_post_id is fully documented in the schema ('Only meaningful once the post is published'). The description adds no further syntax or format detail about the parameter, so this sits at the high-coverage 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?

Opens with a specific verb and resource: 'Returns the latest analytics snapshot for a single platform post', and immediately scopes it as 'layer 1 of 3 — one post = one platform'. That framing lets an agent distinguish it from get_video_analytics and get_folder_analytics without opening any schema.

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

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

Explicitly routes adjacent cases: 'For the same video summed across platforms use get_video_analytics; for a whole folder rolled up use get_folder_analytics.' It also implies the pre-publish restriction via the schema note. It does not tell the agent when to use the sibling explain_post_analytics_state instead of reading the provenance prose here.

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 value beyond that by disclosing resolution semantics: the text is derived from the parent video_settings with per-platform overrides applied, which an agent could not infer from annotations or schema.

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

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

Two sentences, front-loaded with the return payload and followed by the usage condition. No filler or redundant restatement of the 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?

There is no output schema, but the description compensates by enumerating what is returned, and the sole parameter is fully documented. The only gap is behavior on an invalid or deleted video_post_id (error vs. empty result), which is minor for a single-item read.

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

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

With 100% schema description coverage, the single parameter is fully documented in the schema, including where to obtain the value (list_video_uploads, list_scheduled_posts, create_post_draft). The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ("Returns full detail on a single video post") and enumerates the returned fields — status, platform, timestamps, resolved caption/title/description. This clearly distinguishes it from sibling list tools like list_video_uploads and list_scheduled_posts.

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 before update_post when you need to know the current text" gives an explicit trigger and names a sibling tool as the downstream consumer. It does not cover when-not-to-use (e.g., batch scenarios where batch_update_posts or list tools suffice), but the routing guidance 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?

Annotations already declare readOnly/non-destructive, and the description adds substantial context beyond them: how a slot is deemed free, timezone fallback behavior (`effective_timezone` is UTC when none is saved), the `move_posts_past_limits` default-on setting, and the equivalent REST endpoint.

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 return value and the primary usage directive, with no filler sentences; the parenthetical asides about timezone and the settings flag are dense but each carries real information, though the long compound sentences could be split for readability.

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

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

With no output schema, the description carries the burden of explaining return values and does so (saved daily times plus `next_slots` as UTC timestamps), and it covers timezone semantics and the limit-handling setting, leaving nothing an agent needs before calling it.

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

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

Schema coverage is 100%, so both `count` and `workspace_id` are already documented in the schema; the description adds contextual meaning about what the workspace's queue represents but no extra syntax or format detail for the parameters themselves. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Returns the user's saved daily posting times for a workspace') plus the derived `next_slots` output, and implicitly distinguishes itself from the write-side sibling update_posting_slots by describing a read of the queue.

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

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

Explicitly says when to use it ('Use this before scheduling instead of guessing a time') and names the concrete alternative path ('pass use_next_slot: true to schedule_post / batch_schedule_posts'), so the agent knows both the trigger and the downstream consumer.

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 and openWorldHint=false, so the safety profile is covered. The description adds that the response is scoped to the authenticated caller, but says nothing about auth failure behavior or whether fields can be null.

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

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

Two sentences, front-loaded with the return contract, then the usage guidance. No filler, and each clause carries distinct information an agent needs.

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

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

With no output schema, the description's explicit field enumeration does the heavy lifting for an agent that needs to know what comes back. Only gap is edge cases (unauthenticated call, missing organization), which is minor for a trivial no-arg read.

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. The description's field list is about return values rather than inputs, but it usefully signals that the call implicitly targets the current user, complementing the empty 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 ('Returns the authenticated user's ShortSync profile') and enumerates the returned fields (user_id, email, current_organization_id, creation date), which distinguishes it clearly from siblings like list_organizations or list_workspace_people.

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

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

Gives three concrete use cases: introducing yourself, confirming which account is connected, and resolving the default organization before calling other tools. This is actionable routing guidance, though it names no explicit alternative or exclusion condition.

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?

Discloses significant behavior beyond the annotations: numbers come from a local cache, not a live fetch; a stale workspace triggers a background sync reported in the `sync` field with the returned numbers still being from the previous sync; and sync.status values free_plan_limit/daily_limit mean no sync ran. The readOnlyHint=false is consistent with this write side effect, and per-platform data availability limits (X API key requirement, Google Business Profile, Telegram/Discord) are 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?

Purpose and return shape are front-loaded in the first sentence, and the labeled sections (Dashboard parity note, Analytics coverage, Freshness) make it scannable. It is nonetheless long, with a 13-platform enumeration that could be trimmed, costing it the top score.

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

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

No output schema exists, so the description carries the burden of return-value disclosure and does so by naming every returned metric plus the per-platform sibling rows and the `sync` field. For a tool with real data-reliability caveats, it covers source of truth, coverage gaps, and freshness handling.

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 parameter, and the schema already documents both the list_video_uploads lookup and the 'published sibling' precondition. The description repeats that guidance without adding syntax, format, or edge-case detail beyond what the schema provides, 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 ('Returns aggregated analytics for a single video upload') plus the exact scope: per-platform sibling rows plus summed totals, with the metric list enumerated. An agent can distinguish this from get_post_analytics or get_workspace_analytics purely from the phrasing without opening a schema.

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

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

Explicitly routes the agent to list_video_uploads for the required id and names the precondition that a platform sibling must already be published. It does not explicitly contrast against siblings like get_post_analytics or explain_post_analytics_state, so the when-not guidance is implied rather than stated.

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

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

Despite annotations covering safety, the description adds substantial behavioral context: data comes from cached post_analytics rather than live APIs, stale data may trigger a background sync, and freshness statuses like free_plan_limit and daily_limit affect whether numbers are current. It also documents platform-specific coverage gaps, X API key requirements, and Google Business Profile limitations.

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

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

The description is front-loaded with the core purpose and well structured into freshness, coverage, Google Business Profile, and dashboard parity sections. It is lengthy and has minor repetition, such as restating that Google Business Profile posts show 0, but the detail is largely justified by 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?

There is no output schema and annotations are minimal, so the description carries the full burden. It adequately explains the returned metrics, sync field behavior, platform-specific availability, Google Business Profile profile stats, and dashboard parity caveats.

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 days, platform, and workspace_id are already well documented in the schema. The description reinforces the platform filter and rolling-window concept but adds little parameter-specific meaning beyond the schema.

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

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

States a clear verb and resource: summarizes published-post analytics for a workspace over a rolling window. It names the exact metrics and per-platform breakdown, and explicitly distinguishes itself from get_post_analytics for single-post numbers.

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

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

Gives clear context for filtering to one platform and points to get_post_analytics as the single-post alternative. It does not address other analytics siblings such as get_video_analytics or get_folder_analytics, so the when-to-use mapping is incomplete but still strong.

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

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

Annotations already establish read-only and non-destructive, but the description adds the substantive behavioral detail they cannot: the 14-day failure lookback, the 7-day scheduling horizon, grouping of upcoming posts by upload, quota inclusion, and that reconnect entries carry a shareable reconnect_url. That is exactly the extra context an agent needs to interpret the response without an output schema.

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

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

The highest-value content — what the call returns — leads, followed by usage triggers, then the scope caveat. Every clause maps to a distinct return element; nothing is filler or repeated from 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?

With no output schema, the description carries the burden of describing return values, and it does so item by item, including the failure reason and reconnect_url. An agent knows what it will get, when to call it, and how scope widens when workspace_id is omitted.

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

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

Schema description coverage is 100% and the single parameter is fully documented, so the baseline is 3. The description's closing line about omitting workspace_id restates the schema's own note rather than adding new semantics such as ordering or pagination across multiple workspaces.

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

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

States a specific verb and resource (returns workspace status) and then enumerates exactly what comes back: broken/rate-limited connections, failures from the last 14 days, the next 7 days of scheduled posts, and the monthly upload quota. This clearly differentiates it from narrow siblings like list_scheduled_posts or list_platform_connections by framing it as a single aggregated health view.

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

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

Gives explicit trigger conditions — 'how things are going', 'why something didn't post', 'what's coming up' — and calls itself a 'good first call', which is a real routing signal. It does not name which sibling to use instead when the user wants, say, full post lists or analytics, 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?

Goes well beyond the annotations (readOnly=false, destructive=false, openWorld=true) by disclosing the per-call cap (20, or 10 for Canva/Descript), that render-first sources can take up to 2.5 minutes, and that failures are partial ('Items that fail don't stop the others'). It also describes the per-item return shape (video_upload_id, caption, title, or ok:false with an error), which is exactly the behavior an agent needs before a slow mutation.

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

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

Front-loaded with the core action, then caps, then options, then returns — a sensible order with no filler sentences. The nested parenthetical '(the per-call cap is max_per_import from the source list, usually 20; Canva and Descript cap at 10)' is information-dense but awkwardly embedded mid-sentence.

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

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

For a 6-parameter, nested-object, open-world mutation with no output schema, the definition covers caps, latency, partial-failure semantics, and return fields, which is close to sufficient. It omits any permission or connection prerequisite (e.g. whether the source account must be linked to the workspace) and whether the call blocks for the full 2.5 minutes.

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

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

With 83% schema coverage the schema already documents most fields, but the description adds real meaning the schema lacks: container_id's purpose for project-based sources and concrete `options` payloads per source ({ format: "landscape" } for twitch, { version: "captioned" } for heygen, { format: "mp4" } for canva) for an otherwise free-form additionalProperties object. It says nothing extra about workspace_id or idempotency_key, so 4 rather than 5.

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

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

States a specific verb and resource ('Imports items ... into a workspace library') and ties the input to a named producer ('items found with list_import_items'), which immediately separates it from upload tools like create_video_upload. An agent knows what entity it moves and where it lands without opening the schema.

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

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

Gives explicit routing context: call list_import_items first, pass container_id for sources with projects, and send create_post_drafts/create_carousel the returned video_upload_id, so downstream usage is clear. It never states a when-not condition and does not disambiguate against the overlapping sibling import_opusclip_clips, which keeps it from a 5.

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

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

Annotations only cover the safety profile (readOnly=false, destructive=false, openWorld=true); the description adds the traits that actually matter here: a 15-90 second latency window because OpusClip renders first, a 20-clip cap, and partial-failure semantics (failed clips don't abort the others). It doesn't discuss auth/permission requirements or whether partially imported batches can be retried safely without the idempotency key.

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 deprecation notice and the replacement tool are front-loaded in the first clause, followed by limits, latency, and return shape in descending order of decision value. Dense but no sentence is filler.

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

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

With no output schema, the description carries the return-shape burden and does so: per-clip video_upload_id, caption, title, or ok:false with an error, plus what to do with each downstream. It's nearly complete for a write tool; only permission/auth expectations are unstated.

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 is already documented in structured form, including idempotency_key's retry semantics. The description's added meaning is mostly about the return fields (video_upload_id, caption, title) rather than the inputs, 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 with scope: imports clips of one OpusClip project into a workspace library, capped at 20 per call. It names the sibling superseding it (import_items with source opusclip), so an agent can distinguish the two 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 flags deprecation and names the replacement (import_items with source opusclip), which is the strongest possible routing guidance. It also gives the precondition (clip ids come from list_opusclip_clips, all from the same project) and the batch-size limit.

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

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

Annotations only declare it is a non-read-only, open-world, non-destructive write. The description adds substantial context beyond that: a real email is sent, the link is valid 7 days, invite_url is returned, plan gating applies, and re-inviting a pending address issues a fresh link.

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 side-effect warning, then permissions and edge cases. Dense but nearly every sentence carries distinct information; the dashboard analogy is slightly redundant with the title but aids recognition.

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

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

For a write tool with no output schema, the description covers side effects, return value (invite_url), permission model, plan requirement, and idempotent retry behavior. An agent has everything needed to call it correctly and safely.

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 role enum, defaults, email, workspace_id sourcing, and idempotency_key semantics are already documented in the schema. The description only reinforces that role should be confirmed with the user, adding little beyond the structured fields.

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

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

States a specific verb and resource ("Invites someone by email to join a workspace as a team member") and anchors it to a known UI action ("like the dashboard's 'Invite member'"). It also explicitly distinguishes itself from the similarly named sibling list_workspace_people by clarifying these are login members, not tagged people.

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 and exclusions: confirm address and role with the user first, requires a Team plan, owners/admins can invite but only owners can invite admins or owners. It also names the alternative concept (list_workspace_people) and the re-invite case, leaving little to inference.

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

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

Annotations only declare non-read-only, non-destructive, open-world; the description adds real behavior — liked=true hits the platform like endpoint and persists, liked=false unlikes, errors on DM threads, no YouTube support, and an auth-scope requirement surfaced via has_like_scope on list_inbox_connections. The retry warning after a missing-scope error is exactly the kind of operational context 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?

Four dense sentences, front-loaded with what the tool does, then platform/thread constraints, then the auth prerequisite. No filler and no repetition of the schema's optional-parameter text.

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

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

For a two-required-parameter mutation with no output schema, the definition covers what is mutated, which resource kinds are valid, which platforms are excluded, the auth prerequisite, and the retry policy. An agent can call it correctly and handle the main failure mode without extra lookups.

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

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

Schema coverage is 100%, so every parameter including the idempotency key and workspace auto-resolution is already documented in structured form. The description restates liked=true/false semantics rather than adding syntax or format detail beyond the schema, so the baseline 3 applies; the thread_kind constraint is useful but is not a 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?

The first sentence names a specific verb and resource: setting the 'liked by us' state on a top-level comment thread, with the platforms scoped (Instagram or Facebook). It also carves out DMs and YouTube, which effectively separates it from the sibling like_message without ambiguity.

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

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

Explicit when/when-not guidance: only thread_kind post_comments or video_comments can be liked, DMs return an error, and YouTube is unsupported because Data API v3 lacks a like endpoint. It also states a prerequisite (like scope) and a behavioral rule (don't retry until the user opens the error link).

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, but the description adds real value beyond them: the write happens on the platform and persists, unlike is the inverse of like, and unsupported row types fail with an error rather than silently no-op. It does not cover permission requirements or rate limiting, so not a full 5.

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

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

Three sentences, zero waste: the resource and scope come first, the equivalence to like_conversation and boolean semantics second, the failure cases last. Every sentence carries information an agent needs.

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

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

For a mutation tool with no output schema, the description covers the write side effect, inverse behavior, scoping, and error conditions, while the schema fully documents all four params including idempotency. Remaining gaps are the response shape and auth/connection prerequisites, which are minor given the annotation coverage.

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 to the `liked` boolean by specifying that true likes on the platform and persists rather than toggling a local flag, and it clarifies the message_id must be a reply row rather than any dm_messages id.

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 ('sets the liked state on a nested comment reply') and pins the exact data shape (a dm_messages row inside a comment thread on Instagram or Facebook). It also explicitly differentiates itself from the like_conversation sibling rather than leaving that to inference.

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

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

Names the alternative ('Same semantics as like_conversation but scoped to a reply row') and gives the selecting condition, plus a clear when-not: DM and YouTube reply rows can't be liked and return an error. An agent can route between like_conversation and like_message without opening either schema.

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, openWorldHint=true and destructiveHint=false, so safety is covered. The description adds real context beyond them: the result set is capped at the 30 most recent posts, it is scoped to the connected Instagram account, and it is fetched live from Instagram rather than cached — all of which affect expectations about freshness and completeness.

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 sentence, front-loaded with the verb and the resource, with the rule-related purpose and the live-read caveat following. The phrasing 'for post_id on a comment DM rule' is slightly compressed 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 a one-parameter read with no output schema, the description covers what is returned (30 most recent posts), whose account it comes from, and how fresh it is. The only mild gap is the absence of any note about what happens when the account has fewer than 30 posts or no Instagram connection.

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

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

With a single parameter at 100% schema coverage, the schema already explains workspace_id and even points to list_workspaces. The description adds nothing about the parameter itself (the mention of post_id refers to the returned values, not the input), 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 (lists the connected Instagram account's 30 most recent posts) and ties the result to the post_id needed by a comment DM rule. It is clear on its own, though it never explicitly contrasts itself with nearby siblings such as list_comment_dm_rules or get_post_details.

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 rather than stated: the phrase 'for post_id on a comment DM rule' suggests you call this when configuring a comment DM rule and need a post to target. There is no explicit when-not guidance and no named alternative for fetching post IDs or post details.

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 genuinely new behavioral context: the response carries sent/failed/queued counts, whether the plan includes comment DMs (Team included, paid add-on on Creator), and a reconnect_reason field for a broken Instagram connection. That is real payoff information an agent cannot get from the structured fields, especially since no output schema exists.

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

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

Two tight sentences, front-loaded with what is listed before the supporting detail about access and reconnection. The trailing 'Instagram only.' fragment is slightly abrupt but earns its place as a hard scoping constraint; there is no filler.

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

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

For a read-only, single-parameter listing tool with no output schema, the description covers what is returned, the account-type gating, and the failure mode (Instagram needing reconnection), which is close to everything an agent needs to call and interpret it. Only minor gaps remain, such as ordering or whether an empty list is distinguishable from an unconnected account.

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

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

With a single parameter at 100% schema coverage, the schema already documents workspace_id as required and tells the caller to obtain one from list_workspaces. The description adds no additional meaning about the parameter (no format, no default, no alternate lookup), so the baseline of 3 applies.

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

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

States a specific verb and resource ('Lists the workspace's Instagram comment DM rules') and then defines the domain concept inline ('a keyword comment sends one private DM'), which lets an agent distinguish this from create/update/delete_comment_dm_rule and from list_comment_dm_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?

The 'Instagram only' constraint gives a clear applicability boundary, and the scope explanation implies this is the read/inspection entry point before creating or deleting rules. However, it never explicitly routes the agent away from the very similar sibling 'list_comment_dm_posts' or states when to use this versus those alternatives, leaving selection to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral context on top: result ordering, the feature-flag prerequisite that causes empty results, and the conditional nature of the linked upload field ("once it has been turned into posts").

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 purpose and location, then returns, then next steps and prerequisite — logical order with no filler. The field enumeration in the second sentence is long but earns its place because there is no 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?

With no output schema, the description enumerates the returned fields, discloses the feature-gating prerequisite, and points at the tools that consume the returned ids. An agent has everything needed to decide to call it and to use 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 description coverage is 100% — limit (default 50, max 200), status enum values, and workspace_id sourcing from list_workspaces are all documented in the schema. The description adds no syntax or filtering nuance beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ("Lists content concepts (ideas/briefs)"), pins the location in the product UI (Library → Concepts), and specifies ordering (newest first). This clearly separates it from create_concept and update_concept in the sibling set.

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 follow-up paths ("Use the id with update_concept or create_post_drafts_from_concept") and states the prerequisite ("Requires Concepts to be turned on (Settings → Advanced)"). It stops short of an explicit when-not-use/exclusion statement, so it lands just below the top band.

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 readOnlyHint, openWorldHint, and destructiveHint, the description discloses returned fields, status values (`active` or `needs_reconnect`), that webhook URLs are never returned, and forum-channel constraints including threadName defaults and comment-as-first-reply behavior. This is rich context that materially helps an agent interpret results and avoid misuse.

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

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

The description is front-loaded with purpose and usage, then moves into forum behavior, channel-addition context, and return fields. Most sentences earn their place, but the channel-addition method sentence is slightly ancillary for invoking the tool.

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

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

With no output schema, the description fully carries the return-value burden by listing every returned field and status value. It also covers forum vs text comment behavior and the security-relevant note that webhook URLs are never returned, making it complete enough for correct invocation and interpretation.

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 `workspace_id` schema description already says to get one from list_workspaces. The description adds workspace-level context but no additional parameter syntax or meaning beyond the schema, 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 states a specific verb and resource: 'Lists the Discord channels connected to a workspace,' and clarifies the one-to-many workspace/Discord connection scope. It does not explicitly contrast with sibling tools such as list_platform_connections, so it falls short of full 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?

It gives clear context for use: the returned ids feed `channelIds` in update_post / batch_update_posts, and omitting `channelIds` targets every `is_default: true` channel. It also explains forum vs text comment handling, but does not name when to choose this tool over alternatives like list_platform_connections.

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

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

Annotations already establish readOnly=true, openWorld=true, and destructive=false, so the safety profile is clear. The description adds useful behavioral context about cross-workspace login reuse, current Page reporting, and conditional connect_url output, though it does not describe the page item shape in detail.

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

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

The description is three compact sentences, front-loaded with the core list operation. Each sentence adds distinct value: scope, usage/alternative, and the no-login fallback.

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

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

For a one-parameter read-only list tool with no output schema, the description covers the key operational context: whose Pages are listed, which Page is current, how to switch, and what happens without a Facebook login. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, and the single workspace_id parameter is fully documented in the schema, including how to obtain it from list_workspaces. The description does not add parameter-specific meaning 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?

The description states a specific verb and resource: it lists Facebook Pages the user can post to, plus the Page the current workspace posts as. It also distinguishes the tool from select_facebook_page, which is named as the follow-up action.

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

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

It gives explicit when-to-use guidance: connecting Facebook to another workspace or switching Pages without a new sign-in. It routes the user to select_facebook_page for page selection and explains the no-login fallback via connect_url.

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, so the safety profile is covered; the description adds real context beyond that: return shape (id, name, parent_id, position, created_at), null semantics for top-level folders, and a hard nesting limit of 5 levels. The one meaningful gap is that it never says whether the result set is paginated or capped for large workspaces.

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 tightly packed sentences: purpose and ordering first, then return fields and the nesting constraint, then the usage routing. No filler, and the most decision-relevant content is 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?

With no output schema, the description usefully enumerates the returned fields and their null semantics, and gives an agent enough to call it correctly with the single required param. Missing only scale/pagination behavior, which matters for a listing tool in a workspace that could hold many folders.

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 workspace_id parameter is fully documented in the schema (including 'Get it from list_workspaces'). The description adds no parameter-level detail, so baseline 3 is appropriate — the schema does all the work here.

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

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

States a specific verb and resource ('Lists folders in a workspace') plus the ordering ('alphabetically by name'), which cleanly separates it from siblings like list_workspaces and list_concepts. An agent knows exactly what this returns 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 tells the agent when to reach for this tool: to resolve a folder_id before create_folder (as parent), update_folder (reparent), delete_folder, or move_video_to_folder. All four named siblings actually exist in the sibling list, so the routing advice is actionable rather than decorative.

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 declare readOnlyHint, openWorldHint, and destructiveHint=false, but the description adds substantial behavior: connection prerequisites, pagination via next_cursor, container traversal for has_containers sources, and per-source item characteristics. It also covers source-specific defaults and constraints without contradicting the annotations.

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

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

The description is front-loaded with general behavior before the source-specific bullets, and each source note carries practical detail. It is still lengthy and somewhat repetitive, such as repeated 'Projects first' phrasing, so it is comprehensive but not maximally concise.

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

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

For a complex nine-source listing tool with no output schema, the description covers connection state, pagination, container traversal, per-source item types, and option defaults. That is sufficient for an agent to call the tool correctly without needing additional structured return-value documentation.

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 meaningful semantics beyond the schema. It explains the source enum values, per-source options such as format, range, and version, container_id behavior for projects and folders, and how cursor maps to next_cursor.

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 ('Browses') and resource ('content the user can import') and explains both modes: omitting source lists connected sources, while supplying source lists that source's items. It clearly distinguishes listing from importing, so it is distinguishable from sibling tools such as import_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?

It gives clear mode-selection guidance: omit source to discover sources, provide source to list items, and pass container_id for projects or folders. It also instructs the agent to tell users to connect unavailable sources in Settings > Integrations. It does not explicitly name import_items as the follow-up tool for importing selected items, so it falls short of a perfect 5.

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

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

Annotations only declare readOnly/non-destructive/openWorld=false; the description adds the substantive behavior an agent actually needs: per-platform capability matrix (Threads/LinkedIn comment scopes, IG/FB-only DMs, like-scope always false for three platforms) and the meaning of needs_reconnect (missing scopes or token flagged). This is exactly the context 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?

Purpose and usage are front-loaded in the first two sentences, then the row fields. The second sentence is a dense chain of nested parentheses that would scan better as a short list, but every clause carries platform-specific 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?

There is no output schema, so the description does the work of documenting the returned row shape (has_comment_scope, has_messaging_scope, has_like_scope, needs_reconnect) in detail. Combined with the explicit downstream-tool gating, an agent has everything needed to call it and interpret results.

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

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

Single parameter with 100% schema description coverage, including the 'get one from list_workspaces' hint already in the schema. The description adds no further meaning about workspace_id, 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 ('Lists the workspace's platform connections') and narrows scope to those 'wired into the DM inbox', listing the platforms covered. This scope language distinguishes it in substance from the sibling list_platform_connections, but that sibling is never named, so the differentiation is implicit rather than explicit.

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

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

Gives two concrete use cases ('which accounts can I reply to?' and pre-flight check before sync_inbox or reply_to_comment), naming the downstream tools it gates. It lacks an explicit 'do not use this for X, use list_platform_connections instead' exclusion, which is the one gap for this tool family.

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), so the description doesn't need to restate it. Instead it adds genuinely non-obvious behavior: include_own is hidden by default 'because they need no action', spam rows are hidden by default, and unseen_only uses a last_seen_at >= last_message_at comparison. It also spells out the pagination protocol (offset += returned count), which is exactly the kind of operational detail annotations cannot convey.

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

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

Front-loaded with purpose and return shape, then filters, then pagination mechanics, then the sibling hand-off — a logical order an agent can scan. It is dense but somewhat long, with a few clauses that duplicate what the schema already documents verbatim (limit/offset, q, sort).

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 13-parameter tool with no output schema, the description compensates by enumerating the returned fields (id, platform, thread kind, participant, unread/like counts, spam/seen state, preview) so an agent knows what it will get back. Combined with default-hiding behavior and pagination guidance, nothing essential for a correct first call is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns extra by explaining intent behind defaults rather than just restating them — e.g. why own top-level threads are suppressed and what 'unanswered' means in workflow terms. It remains largely a prose mirror of the schema for filters like platform and sort, which keeps it from a 5.

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

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

Opens with a specific verb and resource ('Lists inbox conversation threads') and immediately scopes what a thread is (post/video comments and DMs) plus the ordering ('most recently active first'). It distinguishes itself from get_conversation_messages by describing a filtered, paginated listing rather than a thread read, and enumerates the returned fields so an agent knows what the row contains.

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

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

Explicitly states the downstream use case: 'Use this to find a conversation_id before calling reply_to_comment, like_conversation, mark_conversations_seen, or mark_conversations_spam.' That is a strong when-to-use signal tied to real siblings. It stops short of naming when NOT to use it (e.g., use get_conversation_messages to read a thread's contents), so a 4 rather than a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered; the description adds non-obvious behavior — caching of Company Pages and concrete rate limits (at most once a minute, 10 times a day) — which directly affects how an agent should call it. It doesn't say what happens if the limit is exceeded or what permissions/connection state is required, so it isn't exhaustive.

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

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

Three tight sentences: what it returns first, then the follow-up action, then the caching caveat with limits. No filler and nothing buried.

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

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

With no output schema, the description carries the return-value burden and does so — names the author types plus the current choice — and explains the cache/refresh behavior and the handoff to select_linkedin_author. Enough for an agent to call it and act on 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 baseline would be 3, but the description adds real meaning beyond the schema: refresh triggers a live LinkedIn fetch with hard throttling, and organization ids are the handoff value for select_linkedin_author. This makes the refresh trade-off legible rather than just a boolean toggle.

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

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

States a specific verb and resource ('Lists who the workspace's LinkedIn posts can go out as') and enumerates the two things returned: the connecting person and the Company Pages they manage, plus the current selection. An agent can distinguish this from list_organizations or list_platform_connections 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 the next step: 'Pass an organization id to select_linkedin_author to post as that Page,' and explains when to use refresh: true versus the cache. It doesn't cover when to prefer this over other listing tools (e.g. list_organizations), so it stops short of full when/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 cover readOnly/openWorld/non-destructive, so the safety profile is free. The description adds value the annotations do not: it spells out the returned fields and clarifies that the caption is OpusClip's description plus hashtags, which affects how an import will look. It does not mention pagination or result limits, which keeps 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?

Two sentences, deprecation notice front-loaded so it is the first thing read. Every clause carries information: replacement target, return fields, caption composition, and ID provenance.

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

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

There is no output schema, and the description compensates by listing the returned fields and explaining the caption's composition. For a deprecated read tool with full schema coverage, that is close to complete; only result volume/pagination behavior is unaddressed.

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

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

Schema coverage is 100% and both parameter descriptions already say 'from list_opusclip_projects'. The description restates this sourcing hint, adding only slight reinforcement rather than new meaning, 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 with scope: 'Lists the clips OpusClip made in one project', and enumerates the returned fields. It also names the replacement tool and the downstream tool (import_opusclip_clips), so an agent can place it precisely among the sibling list_* and import_* tools.

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

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

Explicitly tells the agent not to use it ('Deprecated: use list_import_items with source opusclip') and names the exact alternative plus the argument variant. It also explains prerequisites: get project_id and org_id from list_opusclip_projects.

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 ordering, page size, key returned fields, the meaning of stage=COMPLETE, and the API-key prerequisite. That is strong behavioral context, though it does not cover rate limits or error behavior.

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

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

The deprecation warning is front-loaded, followed by purpose, return shape, and prerequisite. The prose is dense but well organized, and every sentence contributes useful selection or setup information.

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

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

With no output schema, the description compensates by listing the important returned fields and their relevance. It also covers pagination, ordering, deprecation, and the API-key prerequisite, so an agent has enough information to invoke it correctly or redirect.

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

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

The schema already documents the single page parameter at 100% coverage. The description adds useful meaning by stating that results are returned 24 per page, which clarifies the unit of the page parameter 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 gives a specific verb and resource ('Lists the user's OpusClip projects'), clarifies what those projects are, and immediately routes agents away from this deprecated tool to list_import_items with source opusclip. It also names the related clip tools, so it is clearly distinguishable from siblings.

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

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

It explicitly marks the tool as deprecated and names the replacement tool plus the required source value. It also states the prerequisite that the user's OpusClip API key must be saved under Settings > Integrations and says what to tell the user if it is missing.

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 fully covered upstream. The description adds useful disclosure of what comes back (membership plus role: owner, admin, member), but says nothing about ordering, result size, or behavior when the user belongs to a single organization.

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

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

Two sentences, front-loaded with the operation and scope, then the usage guidance. No filler or restatement of the 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 zero parameters and no output schema, the description still conveys the shape of the result (organizations plus the caller's role), which is the main thing an agent needs. It leaves minor gaps around ordering and pagination, but nothing that would block 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?

The tool takes no parameters and schema coverage is 100%, so there is nothing for the description to disambiguate. Baseline applies; the mention of the 'role' field is a small extra since no output schema exists.

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

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

States a specific verb and resource ('Lists organizations') plus the scope constraint ('the authenticated user is a member of') and the returned field (role). It does not explicitly contrast with the adjacent list_workspaces / list_workspace_people siblings, which an agent might confuse for the same hierarchy 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 two concrete situations to invoke it: choosing which organization to operate on, and answering questions about team membership. It stops short of exclusions or pointing at alternatives such as list_workspaces when the caller actually needs workspaces.

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