AdaptlyPost

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

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

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

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

Front-loaded with the core action and use case, then layered with edge cases and constraints; nearly every sentence earns its place. The 'Returns { deleted: true }' line is redundant given an output schema exists, a minor efficiency loss.

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

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

For a destructive mutation tool this is complete: state-dependent behavior, error handling, access-control semantics, sibling alternative, and irreversibility are all covered, and the output schema carries return details.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning on top of the schema by stating the workspace scoping consequence ('Only posts in the workspace... others return "Post not found or access denied"'), which the schema does not express.

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

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

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

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

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

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

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

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

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

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

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

Front-loads the destructive consequence and then layers routing guidance, error behaviour, return value, and irreversibility in short declarative clauses. No sentence is filler, despite covering a lot of ground.

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

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

For a destructive two-parameter tool with an output schema present, the description supplies everything the agent needs: scope of deletion, irreversibility, sibling routing, and error semantics. Return-value explanation is redundant with the output schema but harmless.

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

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

Schema coverage is 100%, so both id and workspaceId are already documented, giving a baseline of 3. The description adds meaning beyond that by explaining the workspace-scoping consequence tied to workspaceId (ids outside the current workspace yield "Recurring post not found"), which helps the agent reason about cross-workspace misuse.

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

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

States a specific verb (Delete) and resource (recurring post), and immediately defines the scope of the deletion: the whole series stops permanently and the upcoming scheduled post is removed while already-published posts are kept. It distinguishes itself from the near neighbours delete_post and pause_recurring_post by name without the agent needing to open their schemas.

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

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

Gives explicit routing rules in both directions: prefer pause_recurring_post when the user might want the series back, and use delete_post to skip a single occurrence so the series continues. It effectively covers when-to-use and when-not-to-use with the alternatives named.

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

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

Far exceeds the annotations (which only mark it as non-read-only, non-idempotent, non-destructive). It discloses that nothing is saved or posted, the ai.generate permission and the exact 403 permission_denied code, the 2-credit cost, the member who is billed, refund-on-failure, the own-provider-key exception, and the no-retry rule when credits are exhausted.

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

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

One dense paragraph, front-loaded with the core action and return shape before permissions and billing. Nearly every sentence carries operational value, though the credit/permission detail is lengthy enough that the routing advice gets slightly buried mid-paragraph.

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

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

Given an output schema exists, the description need not explain the { caption } payload further, and it volunteers the return shape anyway. Permissions, credit economics, failure handling, and sibling routing together leave nothing an agent needs 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 prompt, platform and workspaceId are already fully documented, so a 3 baseline applies. The description reinforces the platform character-limit behavior and the general-caption fallback, but adds little syntax or semantic nuance beyond what the schema states.

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

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

States a specific verb and resource ('Write a new social media caption from a prompt') and immediately names the sibling to use for a different need ('To rework a caption you already have, use refine_caption instead'). An agent can distinguish this from refine_caption, generate_image and create_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?

Explicit routing: generated output must be passed to create_post, update_post or bulk_schedule_posts because nothing is persisted, and existing captions should go to refine_caption. Also states the pre-post check and the no-retry behavior on exhausted credits. All when/when-not/alternatives are covered.

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

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

With annotations covering mutation/safety hints, the description adds substantial operational context: asynchronous job semantics, returned { jobId, sessionId, status }, polling vs webhook, 10-40 second typical duration, permission requirement (ai.generate, with role exclusions and 403), credit cost and refund behavior, no-credit failure mode, and explicit advice not to retry. This far exceeds what the annotations disclose.

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

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

The description is front-loaded with the core action and async behavior, and every sentence carries information useful for correct invocation or integration. It is necessarily long given the async job, credit, permission, webhook, and integration details, though a bulleted structure could improve scanability.

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

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

For a complex asynchronous, credit-consuming, permission-gated tool, the description covers all agent-relevant behavior: return shape, polling/webhook options, timing, integration with create_post, permission errors, credit costs, refunds, and no-credit guidance. The presence of an output schema does not leave gaps, and the description is complete for correct use.

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 parameter descriptions already document prompt, model, quality, aspectRatio, sessionId, workspaceId, and referenceImages thoroughly. The description adds only marginal parameter meaning, such as reusing sessionId to group related images; baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Start generating an image from a prompt') and immediately distinguishes the tool from siblings by naming get_image_job for polling, create_post for using the result, and upload_media as unnecessary. An agent can identify exactly what this tool does and how it differs from adjacent tools.

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

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

Gives explicit post-call workflow (poll get_image_job every few seconds until completed/failed, or wait for image.completed/image.failed webhook) and routes the result into create_post's mediaUrls instead of upload_media. It also states when not to retry automatically after a no-credit failure, covering both how and when to use the tool versus 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 declare a safe read (readOnlyHint=true, destructiveHint=false), yet the description adds substantial behavioral context: 180-day coverage limit, multi-hour refresh cadence with lastSyncedAt, summed-over-platforms semantics, partialMetrics for partial coverage, and null for wholly unreported metrics. None of this is in the annotations.

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

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

Front-loaded with the metric list and return shape, then usage routing, then preconditions, then caveats. Dense but every sentence carries distinct information; no filler or restatement.

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 an output schema, the description supplies everything an agent needs: metric set, comparison semantics, coverage limits, refresh behavior, platform exceptions, and alternatives. Return formatting is correctly left to the output schema.

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

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

Schema coverage is 100%, so the baseline is 3, and the description goes beyond it by explaining the comparison-window math and platform caveats (X/MASTODON ignored, LinkedIn pending) that the schema only partially encodes. It doesn't add syntax details beyond the schema, but the extra cross-parameter semantics justify a bump.

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

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

States a specific verb+resource ('Workspace-wide performance for a date window') and enumerates exactly which metrics are returned, including their shape ({ value, previousValue, deltaPercent }). It clearly distinguishes itself from get_analytics_timeseries, get_platform_breakdown, and list_post_analytics by naming each.

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

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

Explicitly names the use case ('how did we do this month' questions, follower counts), names the three alternative tools with the condition that selects each, and adds a precondition ('if the user just published, call trigger_analytics_sync first'). This is textbook routing guidance.

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

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

Goes well beyond the readOnly/non-destructive annotations by disclosing the sync state enum, the meaning of historyHorizonAt ('earlier dates have no data rather than zero activity'), lastErrorMessage, and the reconnect remediation including the instruction 'tell them, do not keep querying'. This is exactly the kind of behavioral context annotations cannot carry.

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

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

Front-loaded with the core purpose in one clause, and every subsequent sentence carries real information. The field enumeration is dense and somewhat list-like, and it partly duplicates the output schema, but nothing is wasted filler.

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

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

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

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

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

Schema description coverage is 100% and the single workspaceId parameter is fully documented in the schema (id source, omission behavior, cross-workspace consistency). The description only adds 'Takes only the optional workspaceId', which is redundant, so the baseline 3 applies.

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

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

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

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

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

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

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

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

Annotations already cover the safety profile (readOnlyHint true, destructiveHint false, openWorldHint false), so the bar is lower. The description adds valuable behavioral detail beyond annotations: the return shape ({ points } with one { date, ...metrics } per bucket), the aggregation semantics (followers is the latest count at bucket end, other counters sum posts published inside it), and null handling for metrics not reported by a selected platform.

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 what the tool does, then returns semantics, then alternatives. Every sentence earns its place: the first defines the tool, the second describes the output and aggregation rules, the third routes to siblings. No filler.

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

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

With an output schema present, the description need not explain return values, but it does so succinctly where it matters for interpretation. Combined with full schema coverage and clear annotations, an agent has everything needed to invoke the tool correctly: purpose, alternatives, return shape, and aggregation rules.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters in detail, including platform restrictions, granularity default, and workspaceId usage. The description adds little parameter-specific meaning beyond what the schema provides; it reinforces platform behavior indirectly through the null-returning metric note, but that is not parameter guidance per se.

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 metrics (views, likes, comments, shares, followers, posts published, engagement rate) and the bucketing dimension (day, week, month), so the agent knows exactly what the tool produces. It also distinguishes the tool from siblings by naming get_analytics_overview for totals and list_post_analytics for post-level drill-down.

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

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

Explicitly states the use case (trend questions such as 'how are views moving' or 'when did followers jump') and names the two alternatives with their respective roles. This gives the agent a clear routing decision without needing to infer from schemas.

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

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

Annotations already declare readOnlyHint/destructiveHint=false, but the description adds substantial behavioral context: the status state machine, terminal failure semantics, member-scoped visibility, the ai.generate permission with 403 permission_denied and which roles hold it, and that reading spends no credits.

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

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

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

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

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

For a polling tool, the definition covers lifecycle states, terminal conditions, polling cadence, permissions, visibility scoping, and cost. With an output schema present, the return description is a bonus rather than a necessity, so nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents jobId and workspaceId in detail; schema description even repeats 'jobId returned by generate_image.' The description adds only marginal meaning (same-member visibility constraints) beyond the structured fields, so the baseline 3 applies.

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

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

States a specific verb and resource: 'Read the state of an image started with generate_image.' It explicitly ties the tool to its sibling generate_image as the producer of the job, so an agent can distinguish polling from generation without opening either schema.

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

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

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

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

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

Annotations already establish readOnly/safe/no-destructive behavior, so the bar is lower. The description adds genuine behavioral context beyond annotations: the shape of the response ({platforms} rows), which metrics each row carries, per-metric {value, previousValue, deltaPercent} semantics, and the supportedMetrics caveat about comparing only commonly-reported metrics.

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 comparison use case are front-loaded, and the alternative-tool routing closes the paragraph. It is dense but every clause carries meaning; the field-level enumeration is somewhat verbose relative to the output schema.

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

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

A read-only analytics query with full schema coverage, annotations, and an output schema — nothing needed to invoke it correctly is missing. It arguably over-explains return fields that the output schema already supplies.

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 from/to/workspaceId are already fully documented, and the baseline is 3. The description only adds that no platform filter exists, which is marginal beyond the schema.

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

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

States a specific verb+resource plus scope: 'overview metrics split per platform for a date window.' It even names the use case ('which platform performs best') and explicitly contrasts with the sibling get_analytics_overview, so an agent can select it without opening a schema.

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

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

Explicit routing: use get_analytics_overview for the combined total, and this one for per-platform comparison. It also rules out a platform filter ('Takes no platform filter') and gives a comparison caveat about only comparing metrics both platforms report.

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 safe read profile (readOnlyHint, destructiveHint=false, openWorldHint=false), so the bar is lower. The description nonetheless adds real behavioral context: workspace scoping rules and the exact failure mode ('any other id returns Post not found or access denied'), which preempts confusion about cross-workspace ids.

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

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

Dense but front-loaded: the resource and return shape lead, then scoping, then sibling routing. Every sentence carries information, though the field enumeration and id-provenance sentence edge toward redundancy with the schema.

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

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

For a two-parameter read tool with an output schema already present, the description covers scope, access failure, provenance, and sibling routing. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so both id and workspaceId are already fully documented in the schema. The description largely restates the id provenance ('Post ids come from create_post, bulk_schedule_posts, or list_posts') rather than adding new format or constraint meaning, so baseline 3 applies.

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

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

States a specific verb and resource ('Get one post's full record by id') and enumerates the returned shape (text, contentType, status, scheduledAt, timezone, platforms array). It is immediately distinguishable from list_posts and list_post_results, which it names 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 explicit when-to-use ('inspect content before update_post or publish_draft') and when-not-to with named alternatives ('list_post_results instead when you only need per-platform publishing outcomes... list_posts to find ids by status, platform, or date'). Routing 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 readOnly/non-destructive, so the safety bar is low; the description goes further by disclosing the exact fields returned, the semantic of nextOccurrenceAt (next slot not yet created; absent once ENDED), and the cross-workspace error message. It stops short of describing pagination or auth requirements, but for a read tool that is minor.

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

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

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

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

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

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

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

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

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

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

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

States a specific verb (Get) and resource (one recurring post/series) by id, and immediately differentiates from list_recurring_posts by scoping to a single record. An agent can tell it apart from the sibling list tool without opening either schema.

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

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

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

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and openWorldHint=true, so the mutation/world profile is covered structurally. The description adds genuinely new behavioral context: the ticket's 5-minute validity window and the fact that it is issued by an internal widget rather than the agent. It does not, however, explain what a ticket grants or what happens on expiry.

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

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

Two sentences, zero filler, with the operational constraint (who calls it) and the key return trait (5-minute validity) both front-loaded.

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

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

An output schema exists, so return shape need not be described; the description supplies the one non-schema fact an agent needs (don't invoke directly, validity window). Complete for a single-parameter, non-agent-facing 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 sole workspaceId parameter is fully documented in the schema, including scoping rules and the current-workspace default. The description adds no parameter-level meaning, so the 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?

Names a specific verb and resource (authorize storing one file in media storage, return a ticket) and identifies the exact caller (the upload box shown by open_upload_widget). This cleanly distinguishes it from siblings like upload_media and open_upload_widget.

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

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

Explicitly states when not to use it and where to go instead: 'Do not call this yourself; call open_upload_widget instead.' It also gives the invocation cadence (once per file) via the described caller. Nothing is left to inference.

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

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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=false) by disclosing the two-step upload flow, the exact downstream failure mode ('Media file(s) not found in storage'), and the retention/lifecycle rule that a publicUrl survives until the last referencing post publishes. It also flags that the tool 'only mints a URL', preventing the common mistake of assuming upload already happened. No contradiction with 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 the critical action, then ordered by relevance (requirement, alternative, per-file params, MIME list, lifecycle). The justification is dense but the long MIME enumeration duplicates the schema enum verbatim, which is the one block that 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?

Despite an output schema existing, the description still explains what the returned fields are for and how to consume them, plus the constraint set (max 20 files implied, allowed types, extension rule, reuse semantics). Nothing an agent needs to call this correctly and follow through on the second step 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 baseline is 3, and the description adds real meaning on top: it tells the agent that fileName and mimeType must be supplied per file, and that the extension in fileName is load-bearing because the post reads file type from it. It also restates the supported MIME set (already in the schema enum) rather than extending it, which caps the score below 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 ('Get presigned upload URLs for direct file uploads') and immediately distinguishes the output contract by naming the two returned fields (uploadUrl, publicUrl) and their downstream use. An agent can tell this apart from upload_media without opening either schema.

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

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

Explicitly names the alternative and the selection condition: 'Prefer upload_media for public URLs and for inline files under 30 MB; use this for larger files you hold yourself.' It also states the hard requirement (PUT to uploadUrl and confirm 2xx) before the URL is usable.

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

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

Annotations only declare the safe read profile; the description adds real behavioral context beyond them: the meaning of status active vs unauthorized, that an unauthorized account is refused with 400 by create_post until reconnection, that unauthorizedReason carries the platform message, and that downstream tools require ids rather than usernames. This is exactly the extra context annotations cannot provide.

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

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

Dense but front-loaded: purpose and return shape first, then status semantics, then usage routing and exclusions. Slightly redundant in enumerating the returned fields (id, platform, displayName, etc.) when an output schema already exists, which is the only wasted sentence.

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

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

Given a single fully documented optional parameter, a rich output schema, and clear read-only annotations, the description supplies everything else an agent needs: missing or unauthorized accounts, id-vs-username requirements, platform-specific id arrays, and the correct sibling for adjacent tasks.

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 workspaceId is already fully documented (including the cross-workspace id scoping rule). The description only adds 'Takes only the optional workspaceId', a small boundary clarification; baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource ('List the social accounts connected to the workspace') with scope across all ten platforms, and names the sibling tools it feeds (create_post, update_post, bulk_schedule_posts) as well as the ones it is not for (list_posts, list_post_results). An agent can distinguish it from every sibling without opening a schema.

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

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

Explicit sequencing guidance ('Call this before create_post, update_post, or bulk_schedule_posts: they take these ids, never usernames'), explicit exclusions ('Not for post history or publishing status: use list_posts or list_post_results'), and operational guidance to omit unauthorized accounts and inform the user.

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

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

Annotations declare this a safe read (readOnlyHint=true, destructiveHint=false), and the description adds behavior annotations could not: discovered posts have postId/postPlatformId null, metrics are null where the platform does not report them, and TWITTER/MASTODON are ignored while LinkedIn analytics are pending approval. These are the exact gotchas that would otherwise cause misinterpretation of 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?

Purpose, sort guidance and the sibling exclusion are front-loaded, and every clause is informative. It is dense and runs long, and the enumerated return-field list partly duplicates the output schema, keeping it short of a 5.

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

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

With an output schema present, the description need not restate return values, yet it supplies the null-semantics and platform-coverage caveats an agent needs to interpret them. Combined with window, sorting, pagination and workspace scoping, nothing required to call or read the tool is missing.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters, and the description stays above baseline by adding operational meaning: sort semantics (descending, PUBLISHED_AT newest first, VIEWS+small limit for a top list) and the platform restriction caveats. It does not materially extend from/to, page or limit beyond the schema, which is why it does not reach 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+resource ('Per-post metrics for posts published inside the window') plus the sorting and pagination model in the first sentence. It distinguishes itself from get_post (per-post detail), list_post_results (publishing status) and get_analytics_overview by naming them or scoping itself 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 concrete natural-language use cases ('top posts', 'which post got the most comments', 'how did post X do') and an explicit exclusion: 'Not for publishing status: use list_post_results for that.' It also routes on sort choice (VIEWS with a small limit vs PUBLISHED_AT for chronological review).

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

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

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

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

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

Front-loaded with the return shape and dense with actionable content; every sentence carries a directive. It is somewhat long and the tiktokDraftFallback sentence is heavily packed, but nothing is wasted.

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

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

For an asynchronous, per-platform results tool, the description covers the polling loop, row-level reading, failure handoff to retry_failed_platforms, and the special TikTok fallback. Even though an output schema exists, the behavioral guidance is complete for correct invocation.

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

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

Schema coverage is 100%, so the schema already documents both 'id' and 'workspaceId'. The description adds no syntax or format detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get one post's per-platform publishing outcomes') and immediately names the sibling it is not ('Use get_post when you also need the content and schedule'). An agent can distinguish it from get_post and list_posts without opening any schema.

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

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

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

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

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

Annotations already declare a safe read (readOnlyHint=true, destructiveHint=false), so the bar is lower. The description still adds real operational context: default sort order, pagination workflow tied to hasMore, and the non-obvious rule that startDate/endDate bound scheduledAt but fall back to createdAt for never-scheduled posts. It does not cover rate limits or workspace-access caveats beyond the workspaceId note.

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

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

Front-loads purpose and scope, then return shape, then filters, then routing to siblings. Every clause carries distinct information (pagination, filter-bound semantics, alternatives) with no filler or restated marketing prose.

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

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

With an output schema present the description need not explain the payload in depth, yet it still summarizes { posts, total, hasMore } and per-platform status shape. Combined with filter semantics, pagination rules, and sibling routing, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds matching semantics not stated per-parameter: platforms is an OR match ('posts targeting any of them') and the date filters bound scheduledAt with a createdAt fallback. It also ties offset to the returned hasMore flag, which is a behavioral tie the schema alone does not express.

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

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

States a specific verb and resource with scope ('posts in the workspace, the current one unless workspaceId names another'), default ordering, and default status breadth. It explicitly contrasts itself with get_post and list_post_results, so an agent can distinguish it from siblings without opening any schema.

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

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

Gives explicit when-to-use ('find post ids or check what is already queued') and names both alternatives with the condition that selects each (get_post for one full record, list_post_results for per-platform outcomes and retry ids). Nothing is left to inference.

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

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

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

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

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

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

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

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

For a read-only list tool with a full output schema, the description covers purpose, filtering, pagination, workspace scoping, and the lifecycle semantics an agent needs to interpret statuses and pause reasons. Nothing material for correct invocation is missing.

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

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

Schema description coverage is 100%, so limit, offset, statuses, and workspaceId are already documented in structured form. The description largely restates these (limit 1-100 default 20, paging with offset), adding little beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('List the recurring posts (series) in the workspace') and immediately defines what a recurring post is (created by passing recurrence to create_post). This lets an agent distinguish it from get_recurring_post, list_posts, and delete_recurring_post without opening any schema.

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

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

Gives clear usage context: pagination via offset/limit while hasMore is true, workspaceId should be reused for related calls, and it points out that list_posts surfaces the scheduled next occurrence. It does not explicitly state when to prefer this over get_recurring_post (single series) or how it relates to the pause/resume siblings, so routing guidance is slightly incomplete.

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

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

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

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

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

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

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

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

An output schema exists so return-field documentation is not strictly required, yet the description still summarizes the payload. Combined with the workspaceId routing rule and API-key exception, an agent has everything needed to call this tool correctly and to use its results in subsequent calls.

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

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

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

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

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

States a specific verb and resource with scope: 'List the workspaces this sign-in can act in, across every organization the user belongs to.' It is immediately distinguishable from sibling list tools like list_accounts, and it even enumerates the returned fields so the agent knows the tool's identity without opening a schema.

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

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

Explicit trigger conditions are given ('when the user names a workspace, brand, client or organization, or when accounts or posts they expect are missing') along with the follow-up action ('pass the matching id as workspaceId to every other tool'). It also states the fallback semantics when no workspaceId is supplied, so the agent knows when this tool is required versus optional.

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

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

Adds substantial context beyond the annotations: nothing is uploaded until the user picks files, the widget only renders in MCP Apps hosts like ChatGPT and Claude, files land at public URLs, and the box posts back a message of media URLs. It also discloses accepted formats and per-file 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?

Front-loaded with the purpose, then prerequisites and downstream usage. Slightly long due to the format/size inventory, but nearly every sentence carries operational value.

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

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

An output schema exists so return values need no explanation, yet the description still explains the URL handoff to post-creation tools. For a widget-launch tool with one optional param, nothing an agent needs is missing.

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

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

Schema description coverage is 100% and there is a single optional workspaceId whose semantics are fully documented in the schema; the description adds no parameter detail, 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 action and resource ('Show an upload box in the chat so the user can add photos, videos or documents') and clearly separates itself from upload_media and get_upload_urls, which 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 when-to-use ('when the user wants to post a file that has no public URL'), a fallback for unsupported environments ('elsewhere ask the user for a public URL and use upload_media'), and ties the result to the downstream create_post/update_post/bulk_schedule_posts calls.

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

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

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

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

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

Front-loaded with the core action and its immediate side effect, then the usage routing, then edge cases. Dense but every sentence carries distinct information; slightly long, though nothing is filler.

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

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

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

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds value by explaining workspace scoping (ids outside the current/other workspace yield 'Recurring post not found') and reinforcing that id comes from list_recurring_posts. This goes modestly beyond the schema's own parameter text.

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

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

States a specific verb+resource (pause a recurring post) and immediately clarifies the scope: it stops occurrence creation and deletes the upcoming SCHEDULED post. It explicitly contrasts with delete_recurring_post, resume_recurring_post, and delete_post, so an agent can distinguish it from every relevant sibling.

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

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

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

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

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

Annotations declare destructiveHint=true and openWorldHint=true, and the description goes well beyond them: it states that publishing cannot be recalled, that a job is queued per platform, that PENDING/SCHEDULED states differ by scheduledAt, and enumerates failure causes (disconnected account, missing TikTok privacyLevel). This is exactly the irreversibility and side-effect disclosure a mutation tool needs.

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

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

Front-loaded with purpose, then failure modes, alternatives, and follow-ups; nearly every clause earns its place. It is dense and long, but the density is informational rather than redundant, so only slightly below optimal.

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

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

An output schema exists, so return values needn't be explained, and the description still routes the agent to list_post_results for per-platform outcomes. Combined with failure conditions and state transitions, an agent has everything needed to invoke this mutation correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real semantics: scheduledAt omission or a past value means publish-now while a future value queues nothing yet, and timezone is display-only and does not shift scheduledAt. These behavioral consequences exceed the schema text.

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

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

Opens with a specific verb+resource ('Publish a DRAFT post now or schedule it') and extends to SCHEDULED posts. Explicitly distinguishes itself from create_post for new content, so the agent can differentiate it from siblings without opening a schema.

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

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

Gives explicit when-to-use (DRAFT or SCHEDULED), when it fails ('Other statuses fail with "Post is not a draft"'), prerequisites to fix via update_post, alternatives (create_post for new content), and a follow-up tool (list_post_results). Nothing is left to inference.

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

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

Goes well past the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false): it states nothing is saved or posted, names the required permission and which roles hold it, documents the 403 permission_denied code, quantifies the cost as 2 AI credits with refund-on-failure semantics, and prescribes behavior when credits run out (explain unavailability, do not auto-retry). This is unusually rich behavioral disclosure for a generation tool.

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

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

Front-loads the core purpose in the first clause, then layers operational details in a single dense paragraph with no filler. Some sentences pack permission, credit, and failure semantics together, which is heavy but each 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?

With an output schema present, return values need not be explained, yet the description still states it returns { caption }. Between the description and annotations, an agent has purpose, permission model, cost, failure handling, and non-persistence — everything needed 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 the schema already documents all five parameters, including platform's enum and the partialText/originalText distinction. The description reinforces the purpose of platform and partialText but adds little syntax or interaction detail beyond the schema (e.g., it does not say how partialText and the required originalText combine). Baseline 3 is appropriate.

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

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

States a specific verb and resource ("Rewrite an existing caption following an instruction") and immediately distinguishes itself from the sibling generate_caption by operating on an existing caption rather than producing a new one. The example instructions ("shorter", "more playful") make the operation concrete.

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 contextual triggers: send partialText to continue a partly written caption, pass platform to target a character limit, check the returned text before posting, and compares cost to generate_caption. It never states the inverse routing rule (use generate_caption when there is no existing caption to rewrite), so the alternative 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 (destructiveHint=true, openWorldHint=true, readOnlyHint=false) mark this as a state-changing, outward-facing call, and the description adds substantial extra context: missed slots are not published, the next occurrence becomes a SCHEDULED post ~24h ahead, ENDED is returned when the series is exhausted, and workspace-scoped ids yield 'Recurring post not found'. This is exactly the behavioral disclosure the annotations cannot carry.

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

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

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

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

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

With an output schema present, the description does not need to enumerate return fields, yet it still names the returned statuses and nextOccurrenceAt. For a destructive, world-affecting mutation tool with two fully documented parameters, nothing an agent needs to invoke it safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the field definitions by explaining that ids outside the named or current workspace return 'Recurring post not found' and by tying id provenance to list_recurring_posts. The workspace scoping rule is largely duplicated from the schema, keeping it short of a 5.

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

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

States a specific verb and resource ('Resume a PAUSED recurring post') and the scope is tightened by 'PAUSED', which clearly separates it from pause_recurring_post and the generic get/delete recurring post siblings. An agent can identify the operation without opening the schema.

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

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

Gives clear when-to-use context ('confirm with the user first', fix the cause when pauseReason is CONNECTION_REMOVED/ACCESS_LOST/etc.) and describes the outcome when no slot remains. It does not explicitly name pause_recurring_post as the inverse alternative, but the preconditions are well specified.

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

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

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

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

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

Front-loaded with the core action, then constraints, failure modes, and post-call guidance in a logical order. Dense and slightly long, but virtually every clause carries distinct operational information rather than filler.

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

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

An output schema exists, so return values need not be described. With error cases, state transition, async caveat, and the follow-up tool all covered, an agent has everything needed to invoke this correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description still adds value: it clarifies that platformIds accepts row ids, platform names, or omission, and specifies the failure behavior for values matching neither a row id nor a platform of the post.

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

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

States a specific verb+resource: re-queue publishing for a post's FAILED platforms. It scopes exactly which rows are affected ('Only rows with status FAILED are reset to PENDING'), which distinguishes it from siblings like publish_draft or update_post without needing to open their schemas.

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

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

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

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

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

The description adds substantial behavior beyond annotations: a once-per-workspace 10-minute cooldown, cooldown return shape with queued:false and cooldownSecondsRemaining, background execution, and the need to poll get_analytics_sync_status. It is consistent with readOnlyHint=false, idempotentHint=true, and destructiveHint=false without repeating them.

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

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

The description is front-loaded with the core action and then layers in usage, cooldown, and polling guidance. Every sentence carries operational value, with no redundant or filler content.

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

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

An output schema exists, so the description need not explain return values. It still covers everything an agent needs to invoke the tool correctly: purpose, timing, cooldown behavior, background execution, and follow-up polling.

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 single workspaceId parameter is already well documented in the schema. The description only notes that it takes an optional workspaceId, adding no syntax or selection detail beyond the schema baseline.

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

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

The description states a specific verb and resource: refresh analytics now instead of waiting for the scheduled sync. It distinguishes itself from get_analytics_overview and get_analytics_sync_status by describing its trigger role and the downstream polling workflow.

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

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

It explicitly says when to use it: when the user just published and wants numbers, or when get_analytics_overview shows an old lastSyncedAt. It also provides a clear when-not-to-retry rule inside the cooldown.

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 cover the safety profile (not read-only, idempotent, non-destructive), and the description adds real context beyond them: the exact post-state transition, error codes for disallowed statuses (400), cross-workspace 404 behavior, and idempotency on an already-undated draft. No contradiction with idempotentHint=true.

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 transition, then usage and error semantics, all earning their place. It is a single dense compound string rather than clearly separated clauses, so slightly harder to scan than ideal.

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

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

An output schema exists, yet the description still names the return ("Returns the post record") and covers state transitions, error conditions, workspace scoping, and idempotency. Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented, which sets a baseline of 3. The description reinforces workspaceId scoping via the 404 note but adds no new format or syntax meaning for the id itself.

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+resource (take a post off the calendar) plus the exact resulting state (undated DRAFT, scheduledAt null, nothing publishes). It also distinguishes itself from siblings by name (update_post, publish_draft, delete_post), so an agent can separate it from adjacent tools 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 when-to-use ("hold a scheduled post back") and explicit alternatives for other intents (reschedule with update_post/publish_draft, drop entirely with delete_post). It also states the when-not case: other statuses fail with 400.

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 mark it destructive and open-world, but the description goes far beyond that: it explains partial-update semantics for the omitted fields, the exception that sending platforms rebuilds the entire target set, the mediaUrls-only-with-platforms dependency, storage verification for new media on scheduled posts, and the exact 400 failure wording. This is unusually rich disclosure of mutation behavior.

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

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

The most consequential constraint (which statuses can be edited) is front-loaded in the first clause. Despite its length, nearly every sentence carries non-redundant operational information, and it closes with sibling routing rather than trailing tangents.

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 28-parameter destructive mutation with an output schema and full annotation coverage, the description supplies the state preconditions, partial-update contract, platform-replacement hazard, and dependency rules an agent needs to call it correctly. Return values are covered by the output schema, so omitting them is correct.

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 cross-parameter interaction semantics the schema does not: that platforms replaces every target requiring the connection-id arrays and configs be resent, that mediaUrls only applies alongside platforms, and the publicUrl sourcing. It does not re-derive most per-field details, which is appropriate.

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

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

States a specific verb and resource ('Update a DRAFT or SCHEDULED post in place') and immediately bounds the scope by status, naming the exact failure for other states. It also routes to four sibling tools by name, so the agent can distinguish it without opening any schema.

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

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

Explicitly says when-not to use it ('published posts cannot be changed') and names the alternatives with their conditions: publish_draft for status changes, unschedule_post to remove from the calendar, delete_post to cancel, create_post for new posts. Nothing is left to inference.

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

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

Annotations only declare write/openWorld/destructive; the description adds the genuinely useful behavioral facts: files become public immediately even with no post, retention lasts until the last referencing post publishes, source URLs must be https and send a Content-Length, private/internal addresses are refused, and validation is by file content plus extension for Office files. These are exactly the side effects and constraints an agent needs before calling a write tool.

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

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

Front-loaded with purpose and usage, and nearly every clause carries operational information (limits, validation, rejection rules, reuse). It is a long single block, and a few asides (e.g. the repeated Office-extension note) could be tightened, but density is high rather than padded.

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

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

For a write tool with an output schema, everything an agent needs is covered: sources, limits, validation, refusal conditions, public-visibility warning, retention semantics, and the escape hatch for oversized files. Return values are given anyway, and the output schema covers the rest.

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 goes beyond it: it explains the https/Content-Length/private-address constraints on urls, the 30 MB decoded ceiling on files, and the 50/100/250 MB per-type limits. workspaceId is left to the schema, so the add is substantial but not exhaustive.

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

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

Opens with a specific verb+resource ('Upload images, videos or documents to AdaptlyPost storage') and states the output (public URLs for mediaUrls). It explicitly routes into sibling tools (create_post, update_post, bulk_schedule_posts) and names get_upload_urls as the alternative path, so an agent can distinguish it from siblings without reading schemas.

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

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

Explicit when-to-use for both sources ('urls' for public https links the server streams, 'files' for media attached in the conversation), states they are combinable, states that omitting both errors, tells when to use the alternative (inline files over 30 MB → get_upload_urls), and advises upload-once/reuse-across-posts. This is about as complete as usage guidance gets.

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