PostWire

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

Annotations provide only hints; the description adds rich behavior: dry_run defaults true and returns per-row projections (times, networks, lengths, X credits, approvals, errors), all-or-nothing scheduling when dry_run=false, plan row limits per tier, Free-tier 3-at-a-time holding, duplicate refusal, and batch_id undo. This goes well beyond what the annotations 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 dense with useful detail, but it is delivered as one long paragraph rather than structured points, which makes the return-behavior and limits slightly harder to scan. Nearly every sentence earns its place.

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

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

For a complex bulk mutation tool with no output schema, the description covers return-value behavior (per-row dry-run report, batch_id), atomicity semantics, plan limits, and duplicate handling. An agent has what it needs to invoke 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 coverage is 100% for top-level params, so baseline is 3, but the description adds substantial row/column semantics the loosely-typed rows/csv params do not encode (date formats, networks, text_<network>, media_urls prefixes, x_thread, first_comment per network). This genuinely compensates for the generic array/string parameter shapes.

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

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

States a specific verb and resource (check/schedule many posts at once) with both input modes (csv text or rows list) named up front. It is clearly distinguishable from single-post siblings like schedule_post and create_recurring_post.

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

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

Gives explicit workflow guidance ("Write the rows for the user when they describe a content plan; show them the dry run before scheduling") and describes the check-first default. It does not explicitly name when to prefer schedule_post or create_recurring_post instead, but the bulk scope and dry-run workflow set clear usage context.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds real value beyond that: it explains the withdrawal side effect (approval links stop working) and the pre-publishing timing limit, which 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?

Two compact sentences, front-loaded with the action and states, then the critical timing constraint and side effect. No filler or repetition 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 a one-parameter mutation with no output schema, the description covers what the tool does, when it is valid, and the user-visible side effect. It stops short of stating what a successful call returns or how an already-cancelled post is handled, though the idempotent annotation partly covers the latter.

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 id parameter, so the schema already carries the meaning. "Takes the id of the scheduled post" restates the schema without adding format, source, or lookup guidance, 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 (cancels/withdraws) and resource (queued, held, or approval-waiting scheduled post), and enumerates the post states it applies to. An agent can distinguish this from schedule_post, list_scheduled_posts, or get_post_status 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?

"Only works before it starts publishing" gives a clear applicability window, which is the decisive condition for choosing this tool. It does not name an alternative for the post-publish case, but the exclusion is stated clearly enough to route the agent.

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

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

Goes well beyond the annotations: it names the 768 KB read cap, states that nothing is published or changed, discloses a rate limit of 60 checks per hour per account, and explains what each verdict means (including the specific triggers for 'recompressed': HEVC/AV1, HDR or 10-bit, above 1080x1920, above 30 fps, above 16 Mbps). These are exactly the operational constraints an agent needs before calling.

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

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

The core purpose and verdict taxonomy are front-loaded, and the safety/rate-limit facts are packed into the tail. It is a single dense paragraph with a long parenthetical list, which is efficient but slightly run-on; splitting the verdict definitions would improve scannability without adding length.

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

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

There is no output schema, but the description compensates by naming the returned fields (verdict, advice, message_for_user, plus codec/size/fps/bitrate details) and explaining what each contains. Combined with one fully-documented parameter and complete annotations, an agent has everything needed to call it correctly and interpret the result.

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

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

Schema coverage is 100% and already specifies https, .mp4/.mov, and length bounds, so the schema carries most of the burden. The description still adds value by clarifying that a share page will not work and that an upload's media_url is a valid source, and by explaining the 'unknown' outcome when the header cannot be read.

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

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

The description opens with a concrete verb and resource (reads a video file's header, reports what TikTok will do with it) and enumerates exactly what it returns: codec/profile, dimensions, fps, bitrate, duration, HDR, audio codec, verdict. It is unmistakably distinct from the sibling posting/scheduling tools because it explicitly operates before posting and publishes nothing.

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 'before posting it' framing plus 'an upload's media_url works' tells the agent this is a pre-flight diagnostic that pairs with an existing upload, and the verdict vocabulary (keeps_quality / recompressed / unknown) makes the use case concrete. It stops short of explicitly naming which sibling tool to call instead for posting or fetching the media_url, so it does not fully close the loop on alternatives.

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

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

Annotations already establish that this is a read-only, idempotent, non-destructive, closed-world operation. The description adds meaningful behavioral context beyond those hints, especially the plan-dependent white-label vs preview behavior and the conditional inclusion of client_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?

The description is front-loaded with the core return value and then adds the relevant conditional details. It is dense but mostly earns its length; the single long sentence is slightly harder to scan than a broken-out structure would be.

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

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

With no output schema, the description carries the burden of explaining what comes back, and it does so by naming the report categories and the client_link behavior. It is nearly complete for a simple read tool, though it does not clarify output structure or edge cases such as brand lookup failures.

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 month, brand_id, and brand_name are already well documented in the schema. The description reinforces the single-brand scope and default month, but it does not add syntax, validation, or selection rules 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 clearly states that it returns one brand's monthly report and enumerates the report contents, which is much more specific than the title alone. It does not explicitly contrast itself with nearby siblings such as get_post_performance, so it stops 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 explains that the report is for last month or a supplied month, and notes the client_link condition, but it does not say when an agent should choose this over alternatives like get_post_performance or list_brands. There are no explicit when-to-use or when-not-to-use guidelines.

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 key behavioral traits: the brand is created empty, the id is returned, and at the plan limit nothing is created and the response redirects the user to an upgrade path with plan name, price, and checkout link. This is valuable side-effect and failure-mode 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?

Two sentences, front-loaded with the core action, and every clause earns its place—defining brand, noting the return value, and explaining the plan-limit behavior. No repetition or filler.

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

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

The tool is simple (one required parameter), the schema documents the parameter fully, and the description covers the return value plus the important edge case at the plan limit. An agent has enough to call it correctly without an output schema.

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

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

The input schema already fully documents the single 'name' parameter with a clear example, so the description adds little parameter-specific meaning. Per the baseline, 3 is appropriate when schema coverage is 100%.

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 ('Creates'), a precise resource ('a new, empty brand'), defines what a brand is, and notes the return value. It clearly differentiates this tool from sibling listing or connection tools like list_brands and create_connect_link.

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 context for when this tool is appropriate: creating a new separate business entity on the PostWire account. It doesn't explicitly name alternatives or state when not to use it, but the purpose is specific enough that an agent can route to it correctly.

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

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

Annotations only say it is a non-read-only, non-destructive, non-idempotent write; the description adds the real behavioral payload: a brand may be created as a side effect (plan brand limit applies), links expire in 30 days, the newest of 3 active links is reused with reused: true, Free plan is a no-op returning upgrade info, and anyone with the URL can use it until it is turned off in the dashboard. That is exactly the context annotations cannot carry.

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

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

Purpose and audience are front-loaded, and no sentence is pure filler, but it is a single dense paragraph that packs plan gating, link limits, reuse semantics, return fields, and security caveats together. Splitting the return-value and plan-gating details out would make it faster to scan for a tool with only two parameters.

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

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

No output schema exists, and the description compensates by naming the returned fields (url, expires_at, brand, message_for_user, send_to_client) and describing the Free-plan error payload (plan name, price, checkout link). An agent has everything needed to call it and to explain 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 is 3, and the description goes further by explaining the resolution rule: an existing brand with that name is used, otherwise a new brand is created subject to the plan's limit. It does not clarify what happens if both brand_id and brand_name are supplied, or whether brand_id must belong to the caller's account.

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 concrete verb and artifact: 'Creates a private page for one brand, good for 30 days' that a client opens without a PostWire account. The 'for agencies and freelancers posting for clients' framing separates it from sibling link tools (create_connect_link, create_upload_link) that target the account owner's own networks.

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 conditions: use it when posting on behalf of a client, supply brand_id or brand_name, and on Free plan nothing is created. Also documents the 3-active-link cap and the reuse behavior instead of erroring. It never explicitly names a sibling alternative for the non-client case, so it stops short of a full when/when-not/alternative statement.

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 context beyond annotations: the link expires in one hour, nothing is connected until the user completes the flow, the page signs in on the network's own site, and Instagram requires a Business/Creator account. Annotations already cover mutation/safety hints, so the description's job is mostly the lifecycle and flow, which it handles well — though it doesn't say whether regenerating a link invalidates the previous one.

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 fact (one-hour link, browser flow) in the first sentence, then layers scope, Instagram specifics, and the client-link contrast. Dense but each clause carries information; the Instagram detail is slightly long for a general-purpose tool.

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

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

No output schema exists, and the description compensates by describing the return values (url of the page, message_for_user: one plain sentence telling the person what to do). Combined with expiry, flow behavior, and parameter effects, an agent has everything needed to call and interpret it.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: 'With platform the page offers only that network; with brand_id the accounts are connected to that brand.' That explains the consequence of each parameter, which the schema labels alone do not.

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 one-hour link the user opens to connect social accounts — and names the networks involved. Clearly distinguished from sibling link tools by describing what the link ultimately does (browser flow to connect accounts to PostWire).

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

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

Explicitly routes between alternatives: 'The link works for one hour and is for the person in the chat; a client connecting their own accounts gets a client link instead: a private page for their brand that works for 30 days.' That names both the condition and the sibling tool (create_client_link) to use instead.

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

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

The description adds substantial behavior beyond the annotations: DST handling, duplicate-guard skipping, queueing up to 7 days ahead, per-occurrence editability, approval rules, plan limits, and returned warnings. These details are directly useful for an agent deciding whether and how to call the 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 purpose and the length is justified by a complex recurring-scheduling tool with nested rule parameters. It is dense and delivered as one long paragraph, which slightly reduces readability despite every part being relevant.

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 no output schema, the description explicitly covers the return value: the recurring post with next occurrences and warnings. It also covers plan limits, approval behavior, queue timing, and duplicate-guard interactions, leaving little an agent needs to infer 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 the baseline is 3, but the description adds real meaning beyond the schema: monthly day 31 fallback behavior, -1 as last day, variants rotating in turn, guard_days skipping networks, and the duplicate-guard warning example. It does not explain every parameter, but it enriches the most semantically complex ones.

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 sets up a post that repeats on a schedule. It immediately distinguishes the tool from ordinary scheduling by explaining recurrence, variants, guard behavior, and queued occurrences.

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 usage context, including that occurrences become ordinary scheduled posts, go through approval rules and plan limits, and are available on paid plans but not Free. It does not explicitly name sibling alternatives such as schedule_post or bulk_schedule, so it falls 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?

Far beyond the annotations, it discloses single-use semantics, a 24-hour validity window, accepted formats (JPG, PNG, WebP, GIF, MP4, MOV, WebM), a 1 GB cap, automatic multi-part upload for large videos, and a detailed retention/deletion policy (deleted the day after the scheduled post publishes, 7 days after upload if unused, 2 days on Free). It also names the return payload. Annotations only say non-read-only, non-destructive, non-idempotent; the description adds the operational substance.

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 key fact — a single-use 24-hour upload link — is front-loaded, and no sentence is filler; formats, limits, retention and returns all carry weight. The single long paragraph with stacked parentheticals is dense and would read better broken into lifecycle vs. return-value groupings.

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

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

With no output schema, the description compensates by naming the returned url, upload_id and message_for_user, and it covers the full upload lifecycle including edge cases (Free-plan shorter retention, chat attachments not reaching PostWire). An agent has everything needed to call it and explain the result to a user.

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

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

There are zero input parameters, so per the baseline this scores 4. The description instead spends its detail budget on outcomes and lifecycle rules, which is the right call for a parameterless tool.

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

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

The description opens with a precise verb+resource: 'Creates a single-use link, valid for 24 hours, to a PostWire page where the user picks one photo or video.' Scope and mechanism are unambiguous. It does not, however, distinguish itself from the similarly named sibling create_connect_link or clarify the relationship to get_uploaded_file, so the agent gets no explicit disambiguation.

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 supplies real context for when this applies: a file must reach PostWire media storage, and 'A file attached to a chat does not reach PostWire; this page is how it gets there.' The 'so post or schedule it soon' line ties it to the post/schedule workflow. No explicit exclusions or named alternative tools are given, so it falls short of a full when/when-not statement.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, so the agent knows it's a non-destructive mutation. The description adds real value beyond that: it clarifies 'Nothing is published' (resolving the write-hint ambiguity), discloses that the call 'Counts toward the account's daily AI limit', and details the return shape including the missing-platform case. Strong disclosure, though it doesn't explain auth or failure modes.

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

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

The core purpose is front-loaded in the first sentence, followed by per-platform rules and return shape. It is dense and long, but with no output schema the return-format detail is not wasted. Slightly packed, but every sentence carries 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 fully carries the return-value burden: the exact { drafts: { <platform>: { text, title?, ... } } } shape, the { missing: [...] } case, and the conditional presence of thread and first_comment. Combined with the publication and daily-limit notes, an agent has everything needed to call and interpret it.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema and the baseline is 3. The description lists per-platform formatting behavior (character limits, hashtags, hooks) that relates to the 'platforms' argument but adds no per-parameter syntax or constraint detail beyond the schema. Baseline 3 is correct.

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

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

States a specific verb and resource ('Writes one draft per platform from a single idea') and immediately scopes it as a drafting tool with 'Nothing is published', which cleanly separates it from publishing siblings like post_to_social and schedule_post. The verb+resource are fully clear and the agent can distinguish it from alternatives.

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

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

Usage is implied rather than stated: 'Nothing is published' suggests using this when you want drafts, and the thread/first_comment passages describe output conditions. However, no sibling tool is named as an alternative and no explicit when-to-use-vs-when-not guidance is given. Adequate but leaves the agent to infer the routing.

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

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

Annotations only assert readOnly/idempotent/non-destructive; the description goes far beyond them with the 90-day window, the 24-hour ranking floor, minimum sample thresholds, plan-gated output (locked.patterns_preview revealing effect sizes but withholding winning values), per-network measurability limits, and the 'no estimates, no AI' computation basis. That is exactly the behavioral context an agent needs before promising results to a user.

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 opening clause is well front-loaded and the field inventory is genuinely needed since there is no output schema, but the whole thing is delivered as one ~330-word semicolon-chained sentence with no visual hierarchy. Dense and information-earning, yet structurally unscannable for an agent skimming before a call.

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

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

For a read-only analytics tool with no output schema, three optional filter params and rich annotations, the description covers what is returned, the computation basis, the gating rules and the fallback behavior ('below 8 measured posts ... two hours to post at to learn it'). Nothing an agent needs to invoke it correctly or set expectations 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 brand_id, platform and timezone (with its IANA example) are already fully documented in the schema. The description only indirectly touches timezone via 'day and time patterns' and never adds filter syntax beyond what the schema provides — baseline 3 is correct 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 return (ranked posts, best times, streaks, patterns, suggestions, competitor benchmarks) computed from the account's own reported numbers over a fixed 90-day window. An agent can distinguish it immediately from every sibling, none of which produce analytics — the nearest relatives (replicate_top_post, plan_week) consume this kind of data rather than produce it.

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

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

Usage is implied rather than stated: the description names qualifying conditions ('patterns need at least 10 measured posts and 3 per group', 'posts younger than 24 hours are not ranked') and closes with 'Read-only; nothing here uses AI.' However, it never says when to prefer this over list_scheduled_posts or get_post_status, nor that replicate_top_post is the natural follow-up.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint, so the safety profile is covered. The description adds genuinely useful behavioral detail beyond that: the independent `verification` read-back with its state vocabulary and timestamp, the automatic re-read cadence, and the live platform polling for TikTok/YouTube and Instagram 'processing' responses.

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

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

The purpose is front-loaded in the first clause, but the body is one sprawling sentence followed by a dense platform-by-platform enumeration whose detail (t.me/c/ URL shape, per-network immediate-publish list) is mostly implementation trivia. It is informative but bloated and hard to scan for the one or two facts 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 read tool with no output schema, the description fully documents what comes back: status/link, the verification block and its states, and the special-case returns for pending, rejected, scheduled, processing and failed posts. There is no meaningful gap an agent would need filled 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 description coverage is 100%, so the schema already explains `id`, `brand_id` and `platform`, including the optionality of platform and the fallback id inference. The description restates the pending/scheduled id case without adding format or syntax the schema lacks, so the baseline 3 applies.

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

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

Opens with a specific verb and resource ('Returns the status and link of ... a published post') and immediately narrows scope to status/link rather than metrics, which separates it from get_post_performance. It also expands the resource to cover pending-approval and scheduled posts, so an agent knows this is the status-lookup tool for any post lifecycle stage.

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 when-to-use contexts: call it to read the post again now rather than waiting for the 10 min/1 h/6 h/24 h/72 h re-reads, and pass PostWire's id when the post is awaiting approval or scheduled. It does not name a sibling alternative or state when NOT to use it, so it stops short of a full routing instruction.

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 significant behavioral context beyond the annotations: it explains that the link opens a Stripe payment page, that nothing is charged unless the user pays, and that for existing subscriptions it opens the dashboard plan page. These details help the agent understand the tool's real-world effects.

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 two sentences, front-loaded with what is returned and followed by behavioral context. The first sentence is dense with a parenthetical list, but no words are wasted and the structure is generally efficient.

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 the presence of annotations covering safety, the description provides a complete picture: what is returned, how the link behaves, and the subscription edge case. Nothing essential is missing for an agent to call it correctly.

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

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

Schema coverage is 100%, so parameter meanings are already fully documented in the schema. The description only briefly reiterates the 'next plan up' default for the plan parameter, adding little 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+resource: returns paid plans, current plan, and a checkout link. It clearly distinguishes the tool's scope and output, making it obvious what the tool does without needing to open 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 implied (e.g., to view plans or get an upgrade link), but the description does not explicitly say when to use this tool versus siblings like my_account or when not to use it. The note about existing subscriptions opening the dashboard plan page provides context but not explicit 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/idempotent/non-destructive/closed-world, and the description adds substantial behavior beyond them: the two-state status machine, the 6-hour media_url validity window, its renewal when the post goes out, and that the URL serves as both video_url and photo_url. This is exactly the runtime context an agent cannot get from annotations.

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

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

One front-loaded sentence with the status semantics first and the return payload second; the nested parenthetical is dense but every clause (validity window, renewal, dual URL use) carries real 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 must carry the return contract and does: status values, media_url with lifetime, kind, size, and content type. Nothing needed 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?

Schema coverage is 100% and the single parameter is already documented as 'The upload_id returned with the upload link.' The description's 'by upload_id' adds no syntax, format, or sourcing detail beyond what the schema states, 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 (returns status) and resource (a file uploaded through a PostWire upload link) keyed by upload_id, which clearly distinguishes it from sibling create_upload_link. An agent can tell it apart 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?

Implies the polling workflow by describing the waiting→done transition and tying the tool to an upload link, so an agent knows to call it after creating a link. It does not explicitly name create_upload_link as the prerequisite or state when-not to use it, so it stops short of full routing guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial non-obvious context: the credit conversion rules, the meaning of the returned mode values, the top-up price points, and the explicit reassurance that opening a Stripe page charges nothing. That is exactly the value-add expected above the annotation bar.

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

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

Front-loaded with the core purpose and the cost model, then the return contents, then the top-up details. It is long for one description but nearly every clause carries distinct information; the plan-list parenthetical is the only slightly expendable part.

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

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

With no output schema, the description carries the full burden and does so: it enumerates the return fields (mode, monthly credits, used/left, top-ups, daily usage, price table, movements, purchase links) and explains the pricing semantics. Nothing an agent needs to call or interpret it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description goes beyond it by explaining what the parameters are FOR (pricing a post before sending) and how the pricing aggregates across text, reply, images, video and thread ('with thread or reply: the whole chain'). It stops short of tying each individual parameter to a concrete example.

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 ('Shows what posting to X (Twitter) costs this account and what it has left') and immediately grounds it in the pricing model, which clearly separates it from siblings like get_upgrade_link or my_account. An agent can tell what it does without opening the schema.

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

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

Usage context is clear: it is the pre-flight cost/balance check, and the optional params exist to price a prospective post, thread, reply, image or video before sending. It does not explicitly name an alternative or a 'do not use when' condition, so it stops short of full routing guidance.

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

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

Goes far beyond the annotations (readOnlyHint=false, destructiveHint=false): it discloses that from an API key or assistant nothing is sent, that seats = members plus open invitations and are plan-limited, and exactly what the response contains (free seats, or an upgrade plan with price and checkout link, plus the dashboard link and Settings > Team steps). That is exactly the non-obvious behavior an agent needs before calling.

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

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

Front-loaded with the core action, which is good, but it is a single dense run-on paragraph with nested parentheses and semicolon-separated role definitions that is hard to scan. Most content earns its place, yet the role glossary and the fallback-response explanation would be far more usable as separate sentences or bullets.

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 spelling out the return payload in both branches (seats available vs. upgrade plan with price and checkout link) plus the manual steps. For a three-parameter mutation-intent tool with full schema coverage, nothing an agent needs in order to call or interpret the result 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 the schema lacks: it defines what each of the five enum roles can actually do and states the implicit constraint that admins cannot be brand-limited while the other four roles can. It restates brand_ids' omit-for-every-brand behavior already in the schema, keeping it just short of a 5.

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

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

Names a specific verb and resource ('Invites a person by email to work in this PostWire workspace') and enumerates the role model, so it is distinguishable from all siblings. The one wrinkle is that the headline verb overpromises: when called from an AI assistant nothing is actually sent, which the description later discloses, so the agent must reconcile the name with the real effect.

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 use: role selection, brand scoping rules ('Editors, contributors, approvers and viewers can be limited to some brands'), and the crucial constraint that only a signed-in dashboard user can actually add people. No sibling alternative exists to route against, and there is no explicit when-not guidance, but the practical usage envelope is unambiguous.

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

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

Annotations already declare the operation read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond those hints: the exact fields returned for each connected account, the 'one business each' cardinality, and the inclusion of the plan's brand limit. Minor gaps like pagination or error behavior are not material for a simple listing.

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 a single, front-loaded sentence that immediately states the main purpose before enumerating details. It is dense but not wasteful, though the long field enumeration could have been formatted more cleanly.

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

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

With no parameters and no output schema, the description carries the full burden of explaining what the agent will receive. It covers the core entities, the connected-account fields, content-type requirements, and the plan limit, making the tool callable without further inference.

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

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

The input schema has zero parameters and 100% schema coverage, so there are no parameters for the description to clarify. The baseline of 4 applies because nothing additional is needed.

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

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

The description uses a specific verb ('Lists') and a clear resource ('the account's brands') plus the connected social accounts and plan limit. It is immediately distinguishable from siblings like list_platforms or create_brand.

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 clearly establishes that this is a read-only listing operation for brand and connected-account data, which makes the intended use obvious. It does not explicitly name alternatives or exclusion conditions, so it stops short of full routing guidance.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral detail about the response contents, including client-link metadata, post-approval counts, plan-level client-link availability, and brands lacking social accounts. It does not mention pagination or size limits.

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

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

The description is two sentences and front-loads the main action and resource. The dense enumeration of returned fields is justified because there is no output schema, and no sentence is wasted.

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

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

For a read-only, zero-parameter listing tool with no output schema, the description is largely complete: it explains the main returned fields and plan-level information. It omits details such as ordering or pagination, and does not clarify its relationship to list_brands, but the core behavior is covered.

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

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

The tool takes zero parameters, so the baseline is 4. There is no parameter behavior to clarify, and the description appropriately focuses on what the returned listing contains.

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

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

The description uses a specific verb ('Lists') and clearly identifies the resource: the account's brands, one per client, along with connected social accounts, client links, and waiting posts. It is clear what the tool does, but it does not explicitly distinguish this from sibling tools such as list_brands.

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 explains what data is returned but gives no explicit guidance on when to use this tool instead of alternatives like list_brands or client_report. There are no stated exclusions, prerequisites, or selection criteria for the agent.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: no account/authentication is required, and the response is self-describing (OAuth vs credentials, field vs optional_field, article kind). It stops short of describing pagination or full response shape, but with annotations present this clears the bar.

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

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

A single sentence but front-loaded with the core purpose, and every clause carries information. It is somewhat run-on, and the parenthetical blog examples and 'title' detail are lower-value embellishment, but nothing is truly 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?

There is no output schema, so the description carries the burden of describing return values, and it does so at a conceptual level (per-platform auth type, credential field names, article kind). It is sufficient for an agent to know what it will get, though the exact field names and structure remain unspecified.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. The description instead documents the shape of the returned data (fields, optional_fields, kind) which is useful orientation, though it does not enumerate concrete field names.

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

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

States a specific verb (Lists) and resource (social platforms and destinations PostWire can publish to), and goes further by naming the per-platform attributes returned: auth mechanism, field names, and a 'kind' of article for blogs. This clearly separates it from action siblings like post_to_social or schedule_post.

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

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

Usage is implied rather than stated: an agent can infer it is a discovery/reference call to run before configuring a destination. The note 'Does not need a PostWire account' is a useful precondition that helps the agent decide to call it early, but there is no explicit when-to-use or alternative 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 declare readOnly, idempotent, non-destructive. The description adds useful behavioral context beyond them: the full status taxonomy with definitions (e.g., pending_approval = waiting for approval, processing = Instagram still processing video). This is genuinely helpful for interpreting results.

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

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

Front-loaded with the core purpose, but the long parenthetical enumerating status meanings is dense and slightly interrupts readability. Every element is relevant, but the structure could be cleaner.

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 no output schema and a simple read-only tool with two well-documented optional params, the description covers purpose, return fields (id, time, platforms, status), and status vocabulary. No output schema exists, so explaining status semantics is a reasonable inclusion that aids result 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%, so the schema already fully documents from/to. The description restates them as 'Optional from/to limit the time range' without adding syntax or boundary semantics beyond the schema. Baseline 3 for high-coverage 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?

Specific verb+resource (lists scheduled posts) and enumerates the status values it returns, which helps distinguish it from get_post_status. It doesn't explicitly delineate itself from sibling get_post_status, but the plural 'posts' plus status enumeration makes the distinction reasonably clear.

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 optional from/to parameters imply a time-range listing use case but there's no explicit guidance on when to use this over get_post_status or the filtering tools. Usage is implied by the description rather than stated.

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

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

Annotations provide readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=false, but the description adds substantial behavioral context beyond annotations: it details file format, dimensions, duration, codec, text rendering, music options, privacy (no AI, no watermark), storage lifecycle including deletion timelines per plan, return values, and rate limits. This is rich, non-obvious information that goes far beyond what annotations 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?

The description is front-loaded with the core purpose and key constraints, then flows into behavioral details. It is somewhat long but every sentence adds value; no obvious repetition. Could be slightly more structured with paragraphs or bullets for readability, but acceptable as a dense block.

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 no output schema and four parameters with full schema coverage, the description is highly complete: it covers what the tool does, output format details, return values (media_url, duration_s, text_on_video, message_for_user), lifecycle of the generated file, rate limits, and plan-specific differences. An agent has all needed information to invoke 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 baseline is 3, but the description adds meaningful context about how parameters affect output: text becomes heading and sentences, music can be royalty-free or silence, footer sits under the text, style options are light or dark. It enriches understanding beyond the schema descriptions alone.

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

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

The description states a specific verb (makes) and resource (short vertical video) and names the target networks (YouTube, TikTok) where video content is required. It clearly distinguishes itself from sibling tools like post_to_social or schedule_post by focusing on video generation from text.

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

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

The description implies when to use this tool: for networks that take only video or video/photos, and it mentions the need to post or schedule soon due to deletion. However, it does not explicitly name alternatives or state when not to use this tool compared to siblings like generate_posts or replicate_top_post.

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

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

Annotations only cover the read-only/idempotent safety profile; the description goes well beyond them by disclosing conditional behaviors: what appears at >=80% limit usage, the free-plan insights_teaser, the one-hour connect link plus message_for_user when nothing is connected, next_step guidance for unpublished accounts, and trial_offer details with exact pricing text.

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 core content are front-loaded, and each following sentence covers a distinct conditional branch of the response. It is long and the sentences are dense, but with no output schema the detail earns its place rather than repeating structured data.

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, no parameters, and only safety annotations, the description is the sole carrier of return-value semantics and it covers the base payload and every conditional extension (limit warnings, teaser, connect link, next step, trial offer) an agent needs to interpret the result.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies and no parameter-level information is missing.

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 ('Shows') and resource ('the signed-in PostWire account') and enumerates the returned content (plan, usage limits, brands, connected accounts), which is enough to distinguish it from siblings like list_brands, get_upgrade_link and get_x_credits.

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: an agent can infer this is the account-overview/status tool, and the mention of checkout link and trial_offer overlaps with get_upgrade_link, but the description never says when to call this versus those alternatives or what prerequisites apply beyond being signed in.

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

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

Annotations only say it is a non-idempotent, open-world write; the description adds the real behavior an agent needs: week counts as one AI draft against the daily limit, over-limit days are saved as held_for and auto-scheduled on upgrade, networks-per-post limit truncates to held_networks, and approval rules force a pending_approval outcome with approval_id and a human-only review link. It even enumerates refusal codes (key_network_not_allowed, key_brand_not_allowed, key_monthly_cap_reached), which is far beyond what the annotations 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?

The core action is front-loaded in the first sentence, which is good, but the remainder is a dense single paragraph mixing limits, held behavior, approval flow, and error codes with internal redundancies (held restated with held_for and never published). It is informative but hard to scan and could be split into tighter sections.

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 of return-value disclosure and does so: it describes queued and held items with id, time, and per-platform preview, cancellability before run, and the pending_approval payload including status, id, approval_id, notified parties, and review link. Nothing an agent needs to call or interpret the result 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 every parameter (days, hour, topic, brand_id, timezone, platforms, brand_voice) is already documented in the schema, and the description mostly restates the day range and hour semantics rather than adding format or syntax detail. The one added nuance is that platform eligibility is constrained to text-capable networks, but that is already implied by the enum and platform 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?

States a precise verb+resource and scope: writes one post per day for 1-7 days from a single topic, each day a different angle, each platform in native format, queued for public publication. That combination of per-day generation with multi-platform native formatting is specific enough to separate it from schedule_post, bulk_schedule, and generate_posts without opening their schemas.

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

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

Gives clear preconditions and exclusions: text-only, platforms requiring video/photo (TikTok, YouTube, Instagram) are refused, and every platform must already be connected. It never names a sibling tool as the alternative for the non-text or single-post case, so it stops short of full when/when-not routing.

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

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

Annotations already declare destructive=true and idempotent=false, but the description adds extensive behavioral detail beyond them: posts cannot be withdrawn, duplicates within 2 minutes are refused, brand ambiguity blocks publishing, approvals must be manual, plan limits and X credits apply, and thread reservations happen before sending. These are exactly the operational traits an agent needs to avoid incorrect invocation.

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 opening is front-loaded and the content is relevant, but the description is a very dense block covering many edge cases, plan limits, trial offers, and platform quirks. It is informative but not concise; an agent must parse a wall of text to reach later operational details.

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

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

Given 11 parameters, nested per_platform objects, many platforms, and no output schema, the description is remarkably complete. It explains the return shape, platform-specific media rules, approval behavior, credit and limit handling, and thread status semantics — enough for an agent to call and interpret the tool correctly.

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

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

Schema description coverage is 100%, so the schema already carries most parameter meaning. The description still adds valuable cross-parameter constraints not fully captured in the schema, such as YouTube requiring video_url, TikTok requiring video_url or photos, multi-item carousel behavior, and X thread/reply credit rules.

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 — 'Publishes a post immediately and publicly' — and the word 'immediately' distinguishes it from the scheduling siblings such as schedule_post and bulk_schedule. It is clear what the tool does without needing to inspect 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 strong usage context: immediate publishing, public visibility, per-platform media requirements, duplicate refusal, brand ambiguity, approval holds, and API-key limits. It stops short of explicitly naming the alternative tool for scheduling, but the immediate-publish framing makes the when-to-use boundary clear.

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

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

Annotations only establish the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false, idempotentHint=false). The description goes well beyond them by disclosing that nothing is published or scheduled, that the call consumes the account's daily AI quota, and that availability is plan-gated – exactly the quota and side-effect context an agent needs before invoking.

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

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

A single dense paragraph that is well front-loaded: what it writes and what it reuses comes first, constraints and return shape last. There is minor redundancy – the post_id provenance is stated in both the description and the schema, and the sentence chain is long – but no sentence is wasted.

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

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

With no output schema, the description compensates by inlining the return shape ({ drafts: { <platform>: { text, title?, tags? } }, reference }). Combined with the quota, plan-gating and no-publish disclosures, an agent has everything needed to call this 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 post_id, topic, platforms and brand_voice are already documented, including the platform default. The description largely restates the schema (published-post ids from performance results, new topic vs new angle) without adding format or interaction detail, so the schema-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 names a specific verb and resource ('Writes new drafts, one per platform') and pins down the mechanism precisely: reuse of structure, opening type, length, format and tone from a reference post, with an explicit negative ('the reference post's sentences are not reused'). It is distinguishable from generate_posts in substance, but it never names that sibling, so the differentiation is left for the agent to infer.

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 clear operating context: the required id must come from the account's post performance results, nothing is published or scheduled, it counts toward the daily AI limit, and availability depends on the plan. What is missing is explicit routing against alternatives such as generate_posts or plan_week, so the when-to-use-this-instead signal is absent.

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

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

Goes far beyond the annotations: queue limits and the held fallback with code queue_limit, held_networks truncation, the approval flow with pending_approval/approval_id and the note that AI assistants or API keys cannot approve, plus specific error codes (key_network_not_allowed, key_monthly_cap_reached). The X credit accounting rules and the 'reserved before anything is sent' atomicity note are exactly the kind of behavior an agent needs. Only minor gap: it doesn't warn that retrying creates duplicate posts (idempotentHint=false).

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

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

The purpose is front-loaded and sentences are dense with substance, but the description is a single sprawling block that mixes queue mechanics, X credits, thread semantics, approval flow and error codes. The X-credit and thread paragraphs in particular read like documentation that belongs in a reference page rather than a tool routing description.

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 describing return payloads in detail: queued item id, per-platform handle and brand, held status plus plan/price/checkout link, held_networks, thread.tweets/thread_url/thread.status, and approval fields. For a 13-parameter nested mutation tool this is appropriately complete.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: run_at accepts the literal "next_slot" with a 365-day horizon and ISO-with-offset format, timezone only applies in next_slot mode, and the brand_id ambiguity behavior is spelled out. per_platform.x gets extra rules (max 25 posts, 280 chars as X counts them, link counts 23, reply alias). Some params (media, privacy, label, upload_method) 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?

Opens with a precise verb+resource ('Queues a post to be published at a future time') and immediately contrasts it with 'publishing now', which cleanly separates it from post_to_social. The two run_at modes (fixed timestamp vs next_slot) are defined in the first sentence.

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

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

Gives explicit conditions for the next_slot mode, explicit gating advice ('Write a thread only when the user asks for one'), and prerequisites (every platform must already be connected, media must suit each platform). It implies but never names the alternatives (post_to_social for immediate publishing, bulk_schedule, create_recurring_post).

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