Sociro

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

Annotations already flag destructive=true, openWorld=true, and non-idempotent, but the description adds information they cannot: the effect is atomic all-or-nothing, a single bad post (wrong platform or passed time) blocks the entire batch, and the error response names the offending post. It also warns that approval publishes to real accounts, which calibrates the risk of the destructive hint.

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-stakes fact (real publishing) and free of filler. The final all-or-nothing sentence is long and chains several instructions together, which slightly hurts scanability, but nothing in it is redundant.

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

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

For a destructive, open-world mutation with no output schema, the description covers the effect, the atomicity, and the error shape, which is what an agent most needs. It leaves the success response undescribed and says nothing about required permissions or how to recover after a named failure beyond 'fix it or ask the 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?

With 0% schema description coverage, the description carries the full burden and does explain the meaning of both parameters: `task_ids` as individually chosen posts versus `plan_id` as every still-waiting post in a plan, and that either is acceptable. It omits format (UUIDs), the 30-item cap on task_ids, and what happens if both are supplied.

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 ('Approves posts waiting for review') and immediately names the consequence that distinguishes it from siblings: the posts become SCHEDULED and publish to real accounts. That separates it from look-alikes such as list_plan_posts, plan_posts, or publish_draft without the agent 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 explicit when-to-use ('Only call it when the user has said to approve these posts') and a required pre-step ('before that, list what will go out and when'), plus remediation guidance for the failure path. It stops short of naming the sibling tool (list_plan_posts) for that pre-step, so the routing is implied rather than explicit.

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, idempotentHint, and readOnlyHint=false, so the safety profile is covered; the description adds the outcome ('never publishes') and the repeat-safety note. It omits reversibility, permission requirements, and any error behavior for an invalid or already-published task_id.

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 short sentences, zero redundancy, with the operative scope stated first and the limitation second. Every clause 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 one-parameter mutation with full annotation coverage and no output schema, the description covers scope, consequence, and repeat safety adequately. The remaining hole is the identity and format of task_id, which neither schema nor description resolves.

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 0%, and the description never mentions the single required parameter, task_id. The name is ambiguous next to sibling tools that operate on post ids, so the agent is left guessing whether it must pass a scheduling task id or a post 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 (cancels) plus the exact resources it applies to (a post still SCHEDULED, or a DRAFT) and what it does not touch (already-published posts). An agent can distinguish it from publish_draft, update_post, and remove_plan_post without opening any schema.

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

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

Implies when to use it (post is scheduled or draft) and gives an explicit when-not (already published). It does not name an alternative tool for the published or plan-post cases, so the agent must infer routing from sibling names.

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, idempotentHint=true and openWorldHint=true, but the description adds substance: posts are public and hit real accounts, drafts defer platform-rule checks until publish_draft, and the idempotency key (caption + accounts + time + media) is spelled out along with the `allow_duplicate` escape hatch. That is real value beyond the hints, though it does not discuss rate limits 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?

It is a single dense paragraph, but it is front-loaded with the mode decision and every sentence carries operational weight. Minor redundancy: `allow_duplicate` and `captions_by_account` behavior is restated from the schema, and the long paragraph form makes scanning harder than a short bulleted mode list would.

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 14-parameter, nested-object mutation with no output schema, the description covers the critical decisions: mode selection, idempotency, platform-rule pre-checks, and caption distribution. It only lightly gestures at what comes back ("returns the post already made"), and does not mention media ordering or cover requirements, which the schema carries alone.

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 cross-parameter semantics the schema does not: the three-way exclusivity of scheduled_at / publish_now / save_as_draft, and the fallback rule that every account gets `caption` unless `captions_by_account` overrides it. Those relationship-level facts lift it above baseline.

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

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

States a specific verb and resource ("Creates ONE post on the given accounts of ONE social group") and immediately enumerates the three mutually exclusive modes, which distinguishes it from update_post, plan_posts and publish_draft. The emphasis on ONE post / ONE group also pins down scope that a sibling like plan_posts would not have.

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 decision rules: "Exactly one of the three" modes, only schedule/publish when the user supplied content, accounts and time, "when unsure, save a draft and tell the user," and "Call get_platform_rules first when you are not sure a caption or the media fits a platform." It also routes the re-post case to `allow_duplicate` rather than a separate tool, so alternatives are named and conditioned.

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, idempotentHint=true, readOnlyHint=false, so the safety profile is largely covered. The description still adds real value beyond them: irreversibility ('cannot be undone'), the preservation guarantee for approved posts, and a required confirmation step. It does not say what happens if both parameters are supplied or omitted, or what the call returns.

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: the destructive scope first, the safety caveat second. No filler, and the irreversible warning is placed where an agent will read it before acting.

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, no-output-schema tool, the description covers scope, preservation of approved posts, irreversibility, and the confirmation duty – enough to act safely. Remaining gaps are argument-selection rules (both/neither) and any return value such as the affected post count.

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 0%, so the description must carry the meaning – and it does, explaining that `plan_id` targets a plan's waiting posts and `social_group_id` targets a group's waiting posts, with 'or' signalling alternatives. It never states that both are optional and mutually exclusive, nor the behavior when neither or both are passed.

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 (removes) and a precisely scoped resource: only posts 'still waiting for review' under a plan, or waiting posts of a social group. The scoping clause 'Approved posts are never touched' implicitly separates it from single-post sibling remove_plan_post, but no sibling is named explicitly.

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

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

Gives clear when-to-use conditions for both modes (`plan_id` vs `social_group_id`) and an explicit operational rule: ask the user before discarding and state how many posts will be removed. It does not point to `remove_plan_post`/`list_plan_posts` as alternatives when the intent is a single post or a review first.

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

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

Annotations already cover read-only/idempotent, but the description adds real operational context beyond them: data can be up to an hour stale (fetched_at), missing platform numbers are null rather than zero and must be reported as 'not available', and one report belongs to exactly one social group. These are disclosure points an agent could not infer from the schema or annotations.

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

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

Front-loaded with the purpose and packed with useful constraints; every clause carries information. The opening sentence runs long with stacked clauses, which slightly hurts scanability, but nothing is redundant 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?

No output schema exists, so the description must convey the return shape — and it does: follower counts, 7-day metrics with prior-period deltas, and latest posts with engagement metrics. Combined with the null/staleness rules and platform scope, an agent has everything needed to call and interpret it.

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

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

Schema coverage is 100% and the schema already says social_group_id comes from list_accounts and is needed when the connection covers multiple groups — the description largely restates this rather than adding format or edge-case meaning. The platform restriction is the only marginal addition, already implied by the enum.

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

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

States a specific verb and resource — 'how one social account is doing' — and enumerates exactly what is returned (followers, 7-day numbers with prior-period change, latest posts with likes/comments/shares/views). This clearly separates it from list_accounts (which enumerates accounts) and get_post (single 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?

Explicitly scopes applicability to Facebook, Instagram and Threads, and states the social_group_id prerequisite with a pointer to list_accounts when the connection spans several groups. No explicit 'when not to use this / use X instead' routing, so not 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 readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds a genuinely useful degenerate case: profile null means the brand is not set up yet and plans still work from the brief alone. The trailing 'Read only' restates the annotation and adds no value, keeping it just shy 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?

Four sentences, front-loaded with what is returned, then when to call it, then the null edge case, then parameter sourcing. Almost every clause earns its place; the final 'Read only' is redundant against the annotations.

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

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

There is no output schema, so the description must describe the return shape — and it does, enumerating the profile facets and the planning ideas, plus what null profile means for downstream planning. An agent has everything needed to call this and interpret the result, including how to obtain the optional ID.

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

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

Schema coverage is 100% and the single optional parameter is fully documented in the schema, including its source (list_accounts) and the multi-brand condition. The description restates nearly the same guidance rather than adding syntax, format, or fallback behavior beyond it, 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?

Names the specific resource (the brand profile of one social group) and enumerates what it contains — business, place, voice, call to action, plus the brand's own planning ideas. It is clearly distinguishable from list_accounts, which supplies IDs rather than profile content, and from plan_posts, which consumes this data.

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 rule ('Read it before plan_posts'), a conditional trigger for using the returned ideas ('when the user has no brief'), and a sourcing rule for the optional parameter ('Pass social_group_id from list_accounts when the connection covers more than one brand'). All three are actionable without 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/idempotentHint, so safety is covered; the description earns credit by disclosing the return shape (which rules are included) and the non-obvious `null` semantics, including the special case where `null` for `first_comment` means the platform takes none. It repeats 'Read only' from annotations, which adds nothing, but the null-handling note is genuine value.

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

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

Three tight sentences, front-loaded with the returned fields, then the usage rationale, then the null semantics that would otherwise confuse an agent. Nothing is padding except the redundant 'Read only' tail.

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 enumerating the returned rule fields and explaining the `null` convention. Combined with a fully documented single optional parameter, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100% and the single `platform` parameter is fully documented there, including case-insensitivity and the list_accounts cross-reference. The description adds no meaning about the parameter, 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 first sentence names the resource and enumerates the exact facts returned (caption length, media counts, media requirement, first comment). No sibling among the post/plan/publish tools does anything similar, and the description makes that distinction obvious 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 gives a clear trigger: read these rules before writing for a platform you are not sure of, rather than learning from a refused post. There are no competing alternatives to name, but it also never states when the lookup is unnecessary (e.g. for a platform you already know), so it stops short of full when/when-not coverage.

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

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

The annotations already declare read-only, idempotent, non-destructive, and closed-world behavior, so the description's 'Read only' adds little. It does disclose that per-account errors and publication links appear in the result, which is useful failure-state context, but it does not add deeper behavioral details like auth requirements or error cases such as missing task_id.

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 and every listed return field earns its place, especially since there is no output schema. The first sentence is long and dense, but it is not padded with 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 burden of explaining the return shape, and it does so thoroughly: status, media ids, per-account caption, public link, error message, and first-comment state. Combined with full schema coverage for the only parameter, an agent has enough 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?

The single required task_id parameter is fully documented in the schema, including where to obtain it from create_post or list_posts. The description does not mention the parameter at all, so it meets the baseline for high schema coverage but adds no extra semantic value.

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 exactly what the tool returns for a single post, enumerating status, media ids, per-account caption/public link/error/first-comment details. It also distinguishes itself from update_post by framing the read as a prerequisite. An agent can identify both the resource and the payload 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 explicitly says 'Read it before update_post', giving a concrete workflow condition for when to use this tool. It does not name every alternative such as list_posts, but the context is clear enough: this is the single-post read that precedes mutation.

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

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

Beyond the read-only/idempotent annotations, it discloses workspace-dependent retention ('asking for too many days is refused with the most allowed'), the refusal behavior, and that days are UTC days. 'Read only' merely repeats the annotation, and the shape of the returned counts is only sketched, so it is strong but not 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?

Front-loaded with the core purpose, then filtering and retention constraints in a compact flow. Minor waste in the fragment 'Every platform.' and the redundant 'Read only.' which the annotations already declare.

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

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

For a two-parameter read tool with no output schema, it covers purpose, aggregation granularity, filtering, timezone, and retention limits. The exact returned fields and whether drafts/planned items are counted are left implicit, which keeps it from a 5.

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 genuine context beyond the schema by explaining that the lookback limit is workspace-dependent even though the schema advertises a fixed maximum, and that days are UTC days. It largely restates the social_group_id semantics already present in the schema.

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

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

States a specific verb and resource ('what Sociro sent out... posts published and failed, per platform, per account and per day') and makes clear it is an aggregated activity report pulled from its own records. That aggregation frame distinguishes it from sibling post-level tools like list_posts, get_post and list_accounts without naming them.

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

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

Gives clear scoping rules: omit social_group_id to count every social group together, pass one to isolate a single brand. It does not explicitly route the agent away from alternatives (e.g. list_posts for individual posts) or say when not to use it, so it stops short of 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?

Goes well beyond the annotations by disclosing what actually happens to the data: a copy is stored at most 1080 px wide with metadata stripped, so the source link doesn't need to persist. It reinforces `idempotentHint: false` in plain language ('Not safe to repeat: every call stores a new copy') and states the constraint that private, local or sign-in-only URLs are refused — none of which appears in the schema or 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 return value, accepted formats, storage behavior and the repeat-safety warning each carry weight, and the core purpose is front-loaded in the first clause. The first sentence is long and carries a parenthetical, but no sentence is filler.

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

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

For a two-parameter mutation tool with no output schema, the description covers the return value, the format and accessibility constraints on the input, the post-import storage behavior, and the non-idempotency warning. An agent has everything needed to call it correctly and to avoid accidental duplicates.

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 real value by naming the accepted formats (JPG, PNG, WebP, GIF) and the public-https requirement, which are validation rules absent from the schema. It does not mention the optional `filename` parameter at all.

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 ('Adds one image to the Sociro media library from an https link') and immediately names what it returns (`media_file_id`). This distinguishes it from `list_media` (read) and `make_plan_post_image` (generation), so an agent can pick the right tool 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 clear positive selection criteria: use it for an image that is already online or that an image model produced with a link, and explains the downstream use by naming create_post's `media_file_ids` and cover usage. It does not explicitly contrast with `make_plan_post_image`, leaving that sibling routing implicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context — that a group marked `locked` cannot be posted to, and that `id` values from this result are the inputs to create_post — but it does not describe the overall response shape or ordering. The trailing 'Read only' merely restates the annotation.

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 the 'call this first' directive are front-loaded, and each sentence except one adds routing or constraint information. The final 'Read only.' is pure duplication of readOnlyHint and does not earn 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?

There is no output schema, so the description must convey the return content; it does so adequately by stating that groups are returned with their accounts and by surfacing the `locked` flag and the usable account `id`. Pagination or response envelope details are absent, but for a small closed-world lookup this is close to 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 description coverage is 100%, and the schema already documents that `social_group` accepts a name (any case) or an id and should be omitted to list everything. The description's 'Give `social_group` to see just one group' is essentially redundant. Baseline 3 applies when the schema carries the semantics.

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

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

States a specific verb and resource ('Lists the social groups ... and the accounts in each') and even defines the domain term ('a social group is one brand: its own set of social accounts'). An agent can distinguish it from get_brand, list_media, and list_posts 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 ordering ('Call this first, before posting') plus a concrete routing rule: find the brand's social group here, then pass the account `id` to create_post. It also names the filtering condition for the optional parameter, 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 readOnlyHint, idempotentHint and destructiveHint=false, so the description only needs to add context. It does so with two non-obvious facts: results are newest-first, and the library includes files added outside this tool. It omits any mention of pagination behavior, which is relevant given page/per_page exist.

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

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

Three short sentences, front-loaded with what the tool returns and how it is ordered, then the reuse guidance. The trailing 'Read only.' is mild redundancy against readOnlyHint=true but costs almost nothing.

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 saying what comes back, and it does name the key field (`media_file_id`) plus the ordering. A note on paging defaults (20 per page) would close the remaining gap, but the definition is otherwise sufficient for correct invocation.

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

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

Schema coverage is 50% – `search` and `per_page` are documented in the schema, and `type` is self-describing via its enum, leaving only `page` undocumented. The description confirms filtering and search intent but adds no format or paging detail 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 names the specific resource (the Sociro media library), its contents (images and videos), and its ordering (newest first), and it clarifies that files added via the Sociro app are included. The verb is carried by the title rather than the sentence, but an agent can still tell this apart from import_image or list_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 concrete downstream guidance: reuse a file's `media_file_id` in create_post or update_post rather than re-uploading, which steers the agent away from import_image. It also states the two filtering modes (type, file name search) but never explicitly says when not to call it, e.g. versus import_image or list_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 cover the safety profile (readOnly, idempotent, non-destructive), so the description's added value is real: default ordering (oldest first), the per-post `timezone` convention for rendering times, and the hint that re-reading is how you observe an image landing (async image generation). That is meaningful behavior not present in the structured fields.

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

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

Three compact sentences, front-loaded with what is returned and in what order, then filters. The parenthetical 'read it again to see an image land' is informal but carries real information, so it 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?

No output schema exists, and the description compensates by enumerating returned fields, ordering, and timezone rendering. A mutation-free read tool with full schema coverage needs little more; only error/empty-state 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 description coverage is 100%, so the three filters are already documented with format and intent. The description paraphrases them (task_id = one post in full; plan_id/social_group_id = filters) without adding syntax, precedence, or combination rules, so it sits at the baseline.

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

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

States a specific resource and scope: AI Planner posts still awaiting review, with the fields returned (captions, image scenes, images, times). This implicitly separates it from list_posts and get_post, though it never names a sibling outright.

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?

'Give task_id for one post in full' and 'Filter by plan_id or social_group_id' explain how to narrow results, but the agent is left to infer when this tool beats list_posts or get_post. No explicit exclusions or alternatives are given.

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, but the description adds real value beyond them: results are limited to groups the key can access, drafts are hidden by default, and each returned post carries its social_group_id. No pagination or auth detail is added, which keeps it from 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?

Four short sentences with no filler, and the scope constraint is front-loaded. The phrasing is slightly telegraphic ('made here or in the Sociro app', 'Read only') 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 7-parameter, zero-required listing tool with annotations and no output schema, the description covers scope, default draft behavior and the shape of returned items. It could still note pagination behavior (page/per_page defaults) but is otherwise complete enough to call correctly.

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

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

Schema coverage is 86%, so the schema already documents from/to, status, order, per_page and social_group_id thoroughly. The description's 'Filter by group, status and date' and the DRAFT caveat largely restate schema content, adding no new syntax or interaction details, 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 (list) and resource (posts) and scopes it to 'the social groups this key can use', which tells an agent this is the collection endpoint. It doesn't explicitly distinguish itself from siblings like list_plan_posts or get_post, but the resource and scope are unambiguous.

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

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

The description gives filtering context ('Filter by group, status and date') and the important default that drafts are excluded unless status DRAFT is requested, which is genuine usage guidance. However, it never says when to pick this over list_plan_posts or get_post, so the alternative-selection guidance is only implied.

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

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

Goes well beyond the annotations: discloses that it consumes the user's image credits, can take up to a minute, attaches the result to the post, and returns the image. It also explains timeout and in-progress-limit behavior, which annotations do not 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 core action and no filler, but the single dense paragraph chains many clauses together, making it slightly harder to scan than it could 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?

Complete for a three-parameter mutation tool with no output schema: it covers the return value, side effects, cost, latency, concurrency, and failure handling, so an agent has everything needed to call it correctly.

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

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

Adds real meaning beyond the schema: prompt should normally be omitted to use the post's own scene and should only be supplied for a different picture; the idea-to-parameter mapping for image_prompt/image_avoid is valuable. task_id's meaning as the target post id is only implied via the list_plan_posts reference, not stated outright.

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: makes one post's image and attaches it. It scopes the target precisely ('one post waiting for review') and clearly separates itself from neighbors like import_image or set_video_thumbnail.

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 (post waiting for review), how to use idea scenes (pass image_prompt as prompt and image_avoid as avoid), concurrency limits (up to 3), and explicit when-not-to-retry guidance with the list_plan_posts fallback.

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 the annotations: nothing is published until approve_plan_posts, it consumes the user's AI credits, it blocks for tens of seconds to minutes, and a timeout does not mean failure. The annotations only say non-read-only, non-destructive, non-idempotent; the description explains the practical consequences that matter. It stops short of saying whether a failed call still burns credits.

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

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

Front-loaded with purpose and then the safety-critical constraint (nothing published, credits consumed) before latency and recovery advice. Dense but every sentence carries operational value; the heavy capitalization and long final run-on of follow-up tools cost it a point on polish, not on 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?

For a 12-parameter, blocking, credit-consuming generation tool with no output schema, the description covers what is produced (captions, themes, image scenes), the review-gated state, cost, latency and failure recovery. Only the credit-cost-per-post and what happens to a partially written plan are left implicit.

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

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

Schema coverage is 75% with enums and defaults documented for days, tone, frequency, timezone, start_date, account_ids and social_group_id. The description reinforces the social-group scoping ('ONE social group') and that post count should be surfaced to the user, but adds almost no new per-parameter meaning. Baseline 3 fits given 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?

Specific verb and resource (write a run of posts), plus scope qualifiers that matter: ONE social group, AI Planner, caption per platform, theme, image scene. That clearly separates it from single-post siblings like create_post and from the plan-editing siblings it names.

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 (tell the user how many posts and ask first, because credits are consumed), an explicit non-action (do not re-call after a timeout), the alternative to use instead (list_plan_posts), and the follow-up tools to offer afterwards. Essentially a complete when/how-to decision tree.

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

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

Beyond the annotations (destructive/openWorld/non-idempotent), the description discloses the real-world effect ("puts a post on real accounts"), that per-platform validation happens inside this call, and the failure contract: on mismatch the draft stays a draft and the reasons are returned. That failure semantics is exactly the information 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 compact sentences, front-loaded with the action and mode split, then the safety condition, then failure behavior, then discovery. Slightly dense and parenthetical-heavy, but no sentence is expendable.

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 still specifies what comes back on the failure path (reasons per platform) and how to locate the required `task_id`. For a destructive 4-parameter tool, 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, but the description adds a genuine constraint the schema does not enforce: "Exactly one of the two" for `publish_now` vs. `scheduled_at`. Minor deduction because timezone's role is left entirely to the schema.

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

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

States a specific verb and resource ("Sends a DRAFT") plus the two mutually exclusive modes (scheduled vs. immediate). It distinguishes itself from create_post (which only saves the draft) and from update_post, so an agent can tell it apart from siblings without opening schemas.

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

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

Explicit precondition: only call when the user has said to send that draft and when. It also routes to alternatives — create_post `save_as_draft` to produce the draft and list_posts status DRAFT to find it — covering both the before and after of this tool's place in the workflow.

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 irreversibility is partly known; the description still adds real value by stating side effects ('Its images stay in the media library'), irreversibility ('cannot be undone'), and the user-confirmation gate. It stops short of covering permissions or what happens if the post is no longer pending, which is why it lands 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?

Four short sentences, each doing distinct work: action, side effect, irreversibility, alternative. The critical destructive warning is front-loaded before the routing hint.

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 destructive tool with annotations covering the safety profile and no output schema, this covers nearly everything an agent needs. The only gap is that the lone required parameter's meaning is never explained anywhere.

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

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

The single parameter task_id has 0% schema description coverage, so the description carries the full burden of explaining it — and it says nothing about it. An agent cannot tell from either source whether task_id is the post identifier or a plan-task identifier, which matters for a destructive call.

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 tight scope ('Removes ONE post that is still waiting for review from its plan'), and immediately differentiates from the sibling cancel_post by state ('Approved posts are canceled with cancel_post instead'). An agent can pick this over cancel_post 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 precondition (post must still be waiting for review), a user-intent gate ('only when the user asks'), and names the alternative tool plus the condition that selects it. No inference required.

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

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

Goes well beyond the destructiveHint/readOnlyHint annotations: it discloses that the call consumes one of the user's AI credits, that existing images and unattached parts are preserved, and that the `scenes` mode returns three candidate image ideas that still need make_plan_post_image. That is exactly the cost and side-effect information 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?

Front-loads the action and cost, then walks the enum; almost every clause carries information. The `scenes` parenthetical is long and stacks several facts (three ideas, carousel option, image-tool follow-up), making that sentence heavier than needed.

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 for a rewrite-with-AI mutation the definition covers cost, preservation, mode semantics, and the alternative tool. The one remaining gap is what the agent gets back after the rewrite (a new draft version? pending approval?), which an agent might want before chaining further calls.

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

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

Schema coverage is only 33% and the `part` enum is undocumented in the schema, but the description compensates fully by defining all four values with their preservation semantics. It also frames `instruction` as the user's own words and notes that offers/facts supplied there are treated as true; only `task_id` is left to inference, which is the reason this isn't a 5.

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

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

States a specific verb and resource (rewrite one post awaiting review) with the engine named (Sociro's AI Planner), and immediately distinguishes itself from update_plan_post, which handles small self-serve edits. An agent can tell what it does and what it does not do 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 routing to the alternative is given ('For a small change you can make yourself, use update_plan_post instead'), and each `part` value is described with what changes and what stays, so the agent knows exactly which mode to pick. It also names the downstream tool (make_plan_post_image) for the `scenes` branch.

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 idempotentHint=true, destructiveHint=true and openWorldHint=false; the description's 'sets or replaces' is consistent with that replace semantics, so no contradiction. It adds genuinely new context beyond the annotations by disclosing a cross-tool side effect: create_post consumes this image as the cover when `cover.use_video_thumbnail` is true. It stops short of noting permission requirements or what the old thumbnail's fate is beyond 'replaces'.

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: purpose and input first, accepted formats second, downstream consequence last. 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?

For a two-parameter write tool with fully documented schema, the description covers purpose, input constraints and a downstream effect, which is close to sufficient. There is no output schema, so a brief note on what is returned or confirming the video must already exist would have closed 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?

With 100% schema description coverage, the schema already documents both parameters including the accepted formats. The description repeats the image formats and https requirement but adds no syntax, size, or aspect-ratio guidance beyond the schema.

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

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

States a specific verb (sets/replaces), a specific resource (a video's library thumbnail in the Sociro media library) and the input source (an https image link). This is clearly distinguishable from siblings like import_image and make_plan_post_image 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 description gives one useful usage context — that this same image becomes the post cover when `cover.use_video_thumbnail` is true, which implies when the choice matters. It never states when to use this versus import_image or make_plan_post_image, nor any prerequisites such as the video already existing in the library.

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

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

Adds real context beyond the annotations: list params REPLACE rather than append (matching destructiveHint=true), the call uses no credits, and date/time are interpreted in the post's own timezone. The remaining gap is that it never states whether omitted fields are left untouched — a meaningful ambiguity for a partial-update mutation with 10 optional params.

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

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

Front-loads the resource and precondition, then the risky semantics, then the alternative tool — a sensible order with no filler sentences. The field list at the start partially duplicates the schema property set, which is minor waste but also serves as a quick scan.

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

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

For a destructive 10-param mutation with no output schema, it covers preconditions, unit/timezone semantics, side effects and the correct alternative tool. What's missing is partial-update behavior for omitted params and any note on what the response contains.

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 80%, so baseline is 3; the description lifts it by clarifying that `date` and `time` are in the post's own timezone, which the schema does not say. The REPLACE semantics it repeats are already in the account_ids and media_file_ids schema descriptions, so that part adds no new information.

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 ('Changes') on a specific resource ('an AI Planner post that is still waiting for review') and enumerates the editable fields, so the scope is unambiguous. It also explicitly distinguishes itself from the sibling update_post by state (approved vs. pending review).

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 exclusion and the alternative: 'An approved post cannot be changed here (use update_post).' It also sets a precondition ('read the post first') for the replace-style parameters, so the agent knows the required read-before-write workflow.

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 destructive/idempotent annotations: discloses that media_file_ids and account_ids replace the entire list, that the change is atomic ('nothing is changed' if any platform fails validation), and enumerates what cannot be modified. This is exactly the mutation-risk context an agent needs before a destructive call.

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

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

Front-loaded with the scope and the editable fields, then consequences, then exclusions — no filler sentences. Slightly dense run-on phrasing, but every clause carries operational meaning.

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

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

For a 7-parameter destructive mutation with no output schema, the description supplies preconditions (read first), atomicity, list-replacement hazards, and the unsupported-field workaround. Nothing an agent needs to call it safely is missing.

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

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

Schema coverage is 86% and the schema already documents the replace semantics and timezone handling, so much of the description restates structured data. It still adds real value by tying replace behavior to a required read step and by grouping the editable fields, which helps an agent avoid data loss.

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 (changes a post) and scopes it precisely to SCHEDULED posts and DRAFTs, plus the editable fields. This immediately separates it from siblings like update_plan_post, publish_draft and cancel_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?

Explicitly instructs to read the post with get_post first, tells the agent that a draft takes no time and that publish_draft supplies one, and names the escape hatch (cancel and create again) when platform options or a TikTok account must change.

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