Post Bridge

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

Goes far beyond the annotations by disclosing several non-obvious failure-causing behaviors: X/Twitter strips full URLs AND bare domains from captions (with the pricing rationale), is_draft only saves in Post Bridge and publishes immediately when later sent, and platform_configurations.tiktok.draft is a distinct native-draft option. No contradiction with readOnlyHint=false or destructiveHint=true; the description strengthens the agent's mental model of a destructive, open-world operation.

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

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

Roughly 200 words with zero filler. Core purpose is front-loaded, followed by prerequisites, then two critical warnings clearly flagged with 'IMPORTANT' and 'Note.' Every sentence carries actionable information appropriate to a 10-platform tool, and no sentence merely restates the name or 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 tool with 9 parameters, deeply nested per-platform overrides, 10 platforms, and no output schema, the description covers the non-obvious operational behaviors an agent cannot infer: immediate vs scheduled posting, public media URL download, X link removal, and the two distinct draft concepts. The exhaustive per-platform schema fills the remaining detail, so nothing needed for correct invocation is missing.

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

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

Schema coverage is 100%, so the schema already documents every parameter in depth (baseline 3). The description still adds interpretive meaning: cross-posting explains the multi-account semantics of social_accounts, the X/Twitter link-stripping warning attaches behavior to the caption parameter, and the is_draft versus tiktok.draft clarification resolves a confusion the schema alone could not.

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

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

States a specific verb ('publish or schedule'), resource ('social media post'), and exhaustively enumerates the 10 supported platforms, making the scope unmistakable. It also discloses the cross-posting capability up front, which clearly differentiates it from siblings like update_post (modify existing), upload_media (upload files), and list_posts (read).

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?

Provides concrete preconditions: 'Use list_social_accounts first to get account IDs' and 'Omit scheduled_at to post immediately,' plus platform-specific guidance on X/Twitter links and the is_draft/tiktok.draft distinction. However, it never explicitly names alternatives or exclusions (e.g., 'to modify an existing post, use update_post'), so some routing decisions are left to inference.

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

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

The annotations already mark the operation as destructive, so the description does not need to restate that. The added constraint that media in use by a post will not be deleted provides useful behavioral context beyond the annotations, though it does not specify whether an error is raised or the action is silently ignored.

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 only two short sentences, with the core action stated first and the important limitation stated second. Every word earns its place and there is no redundancy or fluff.

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 simple one-parameter, no-output-schema tool with a destructive annotation, the description covers the essential purpose and key constraint. A minor gap is that it does not clarify what happens when deletion is attempted on media still in use by a post.

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

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

The schema fully documents the single required 'id' parameter with a clear description, so the parameter semantics are already well covered. The description adds only the 'media file' context and does not provide additional meaning beyond the schema.

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

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

The description states a specific action ('Delete') and target resource ('uploaded media file'), clearly distinguishing it from deleting a post or managing other resources. The added condition about media not used by posts further clarifies scope.

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

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

The description gives clear context on when deletion is appropriate by specifying that only media not currently used by any post can be deleted. It does not explicitly name alternative sibling tools like delete_post or list_media, but the conditional guidance is enough to inform basic routing.

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

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

Annotations already flag destructive behavior, but the description adds a non-obvious API restriction: published posts cannot be deleted. It also narrows the behavioral scope to scheduled/draft posts. This exceeds the annotations, though it does not mention permanence or response 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?

Two short sentences with no filler. The action and target are front-loaded, and the key constraint about published posts is stated immediately after.

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 single-parameter destructive action, the description is complete: it clearly defines what can be deleted and the one major limitation. With annotations already covering the destructive nature and no output schema requiring explanation, nothing critical 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?

The schema covers the only parameter, id, with a clear description: 'The post ID to delete'. The tool description adds context that only scheduled/draft post IDs are valid, which slightly supplements the schema, but the parameter itself is already well-documented.

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

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

The description clearly states the action (delete) and resource (post), and specifies the scope by saying 'scheduled or draft post' while explicitly excluding published posts. This makes it distinct from sibling tools like create_post, update_post, get_post, and list_posts.

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

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

The description tells the agent when to use this tool: for deleting scheduled or draft posts. It also tells the agent when not to use it: published posts cannot be deleted via the API. It does not explicitly name an alternative for published posts, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the base safety profile is known. The description adds meaningful behavioral detail: it returns cumulative snapshots and per-day gains for views/likes/comments/shares, and scopes to a single post. This goes beyond what annotations provide, though it stops short of discussing pagination or date-range 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?

Three sentences with no filler: the primary action, the return shape, and the parameter source. The description is front-loaded and every sentence earns its place, with only minor, acceptable redundancy between 'snapshots and deltas' and 'cumulative snapshots and per-day gains'.

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 single-parameter read-only tool with no output schema, the description tells the agent what ID to pass, where to get it, and what kind of data to expect. It would be slightly more complete if it specified the response structure or ordering, but this is a minor gap for such a simple 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?

The schema already fully documents the only parameter as 'Analytics record ID (from list_analytics)' with 100% coverage. The description repeats this source but adds no new meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Get', the resource 'per-day analytics snapshots and deltas for a single post', and the return contents. It is unambiguous and naturally distinguishes itself from siblings like list_analytics and sync_analytics.

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

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

The description gives clear context: this tool is for per-day analytics of one post, and it tells the agent to source the ID from list_analytics. It does not explicitly name alternative tools or when-not-to-use conditions, but the workflow is well implied.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description only needs to add context. It adds the returned fields, but it does not disclose edge-case behaviors such as not-found handling, permission requirements, or whether 'platform results' are always present. This is adequate but not rich.

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

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

The description is a single concise sentence that front-loads the operation and resource, then lists the key returned details. Every part earns its place and there is no redundant wording.

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 simple read-by-ID tool with one required parameter and no output schema, the description is largely complete: it states what is returned and the annotations cover safety. 'Platform results' could be slightly more specific given the list_post_results sibling, but the overall context is sufficient.

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

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

The only parameter, id, is already fully described in the schema as 'The post ID', with 100% schema description coverage. The description reinforces that the tool fetches by ID but adds no extra meaning beyond the schema.

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

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

The description clearly identifies a specific verb ('Get'), a specific resource ('details of a single post by ID'), and enumerates the included fields (status, caption, media, platform results). This distinguishes it from list-oriented siblings like list_posts and list_post_results.

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

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

The phrase 'single post by ID' implies that this tool is for retrieving a specific post rather than listing posts, but it does not explicitly name alternatives or state when not to use it. Usage guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safe read nature is covered. The description adds useful context about returned metrics and platform scope, but it also claims date-range filtering even though the schema only exposes platform, limit, and offset. This creates a misleading behavioral expectation beyond the structured schema.

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

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

The description is a single sentence, front-loaded with the core action and metrics, and avoids unnecessary verbosity. However, the unsupported date-range claim is clutter and slightly undermines the otherwise crisp 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?

The core purpose and metric set are present, and annotations cover the safety profile. But with no output schema, the description does not describe the response shape or pagination behavior, and it lacks guidance on how it differs from get_analytics_daily. The false date-range capability also leaves the tool less complete than it appears.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description does not add meaningful parameter semantics beyond the schema. It adds a 'date range' filter option that is not represented as a parameter, which could cause an agent to supply an invalid argument. Limit and offset are not mentioned in the description, so no extra value is provided there.

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

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

States a clear action and resource: getting social media post performance analytics with specific metrics (views, likes, comments, shares) and platform scope through Post Bridge. It is reasonably distinct from siblings like list_posts or get_analytics_daily, though it does not explicitly contrast with get_analytics_daily. The mention of a date-range filter is misleading because no such parameter exists in 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?

No explicit guidance on when to use this tool versus alternatives such as get_analytics_daily or sync_analytics. The description implies it is for post-level performance analytics, but does not state when not to use it or which sibling covers daily aggregates. An agent must infer the usage boundary.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful scope information ('your uploaded media files') and return content details, but it doesn't disclose behaviors like pagination defaults or ordering. With strong annotation coverage, this is adequate but not exceptional.

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

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

Three short sentences each earn their place: the first states the action, the second lists what is returned, and the third explains a practical downstream use. There is no redundancy or filler.

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

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

For a simple, read-only list tool, the description is complete: it states scope, return fields, and a relevant use case. The schema covers parameters, annotations cover safety, and the description covers what the agent will receive. No essential information is missing.

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

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

Schema description coverage is 100%, with both limit and offset already described as 'Number of media items to return' and 'Offset for pagination'. The description adds no parameter-specific detail beyond this, so the schema carries the burden and the baseline of 3 is appropriate.

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

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

The description clearly states the verb ('List') and resource ('your uploaded media files'), and the mention of returned media IDs, URLs, and types distinguishes it from sibling tools like upload_media or delete_media. An agent can immediately identify what action this tool performs.

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

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

The description provides clear context: it lists uploaded media and notes that media IDs are useful when creating posts with previously uploaded content. However, it doesn't explicitly state when not to use it or name alternative tools, though the usage context is sufficient for most cases.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds useful context about per-platform success/failure and error details, but it does not disclose pagination behavior, ordering, or data freshness. This meets the lowered bar set by annotations but does not go beyond into richer behavioral context.

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

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

Two short sentences with no redundant wording. The core purpose is front-loaded, and every clause adds value: the action, the scope, and the outcome details. This is appropriately concise for the tool's simplicity.

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 operation with no output schema, the description explains the main return content (success/failure per platform and error details), while the input schema covers pagination and filtering. It could be more explicit about the response shape or default ordering, but nothing critical is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so limit, offset, and post_id are already fully documented in the input schema. The description adds no additional parameter meaning, so the baseline score of 3 applies.

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

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

The description uses specific action verbs ('Check', 'Shows') with a clear object ('posting results per platform') and explicitly states what it reports: success/failure with error details. This clearly distinguishes it from sibling tools like list_posts or get_post, which focus on the posts themselves rather than platform-level delivery outcomes.

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

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

The description conveys the tool's purpose clearly, which implies when it should be used, but it does not explicitly mention alternatives or state conditions for choosing this tool over list_posts or get_analytics. There is no 'use when' or 'use instead' guidance, only an implied use case.

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 mark the operation as read-only and non-destructive. The description adds meaningful behavioral context beyond that: drafts use status 'scheduled' with is_draft: true and scheduled_at: null, which is essential for correctly interpreting filtered results. This prevents a likely misinterpretation when filtering by status.

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 deliver the purpose, return fields, and a subtle behavioral caveat with no wasted words. The core action is front-loaded and the additional draft clarification is directly relevant to interpreting results.

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 simple read-only list tool with no required parameters and full schema coverage, the description is complete. It specifies the return fields, covers the tricky draft/status edge case, and benefits from annotations that already establish safety. No critical information needed to call the tool 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 parameters (limit, offset, status, platform) are already well documented. The description does not add parameter-specific details beyond what the schema provides, matching the baseline of 3.

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

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

The description clearly states the tool's function: 'List your posts with optional filters' and enumerates the returned fields (post ID, caption, status, is_draft, scheduled time, accounts). This distinguishes it from the more specific get_post sibling, though it does not explicitly name any alternative tool.

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

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

The description gives no guidance about when to use this tool versus siblings like get_post or list_post_results. The phrase 'List your posts' implies the basic use case, but there are no explicit conditions, exclusions, or references to alternatives, leaving the agent to infer selection criteria.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral context: the meaning of needs_reconnect, how repeated dead-token failures pause posting, that posts to such accounts are skipped, and that reconnecting clears the state automatically. This goes well beyond the annotations and prevents the agent from taking inappropriate actions.

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 focused and front-loaded: it states the core listing action first, then the returned fields, then the important needs_reconnect behavior and resulting instruction. Every sentence adds necessary value, and there is 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?

For a parameterless list tool with no output schema, the description is remarkably complete. It specifies the platforms, the return fields, the meaning of the critical needs_reconnect flag, the consequences for posting, and the correct user-facing action. No output schema is needed because the return shape is stated directly.

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

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

The tool has zero parameters and the schema coverage is 100%, so there is no parameter ambiguity. The description appropriately focuses on behavior and return fields instead of parameter details, matching the baseline expectation for a parameterless tool.

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

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

The description states a specific verb ('List'), a clear resource ('the user's connected social media accounts'), and enumerates the platforms covered. It also names the exact returned fields (account IDs, platforms, usernames, needs_reconnect), making the tool's role unmistakable and distinct from sibling tools like list_posts or list_media.

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

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

The description makes clear when to use this tool: whenever connected social accounts need to be listed or inspected, including checking the needs_reconnect state. It also provides actionable guidance by instructing the agent not to post or retry against accounts in the needs_reconnect state and to tell the user to reconnect instead. It does not explicitly name alternative tools, but no sibling tool serves the same purpose.

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

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

The description discloses key behaviors: the link is valid for 24 hours, supports one or many files including a full carousel, and each file lands in the Post Bridge media library. Since annotations carry no read-only/destructive hints and the tool has no params, these details are valuable and accurate. 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?

Four sentences, each serving a distinct purpose: scope, behavior, follow-up workflow, and when-to-use. It is front-loaded with the core purpose and doesn't repeat the schema (which is empty).

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

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

Given the empty input schema and absence of an output schema, the description fully covers what the agent needs: what the tool returns (24h link), how the user interacts with it, and the exact next steps (list_media then create_post) to complete a post. No missing information 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?

The tool has zero parameters, so the schema already documents everything; with 0 params the baseline is 4. The description adds no parameter details, but the workflow guidance clarifies what the returned link is for.

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 an upload page') and the exact resource type (a temporary upload page/link for device-local files without a public URL). It distinguishes itself from upload_media by explicitly naming the condition ('no URL, or larger than 3MB'). No ambiguity about what the tool accomplishes.

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 use: 'Use this whenever the user wants to post a file that upload_media cannot reach'. It also provides a step-by-step workflow (give link, wait for upload, call list_media, then create_post), leaving no doubt about how it fits with 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 indicate this is not read-only and has open-world effects, and the description adds that the refresh applies to all connected platforms unless a specific one is chosen. It does not describe potential asynchronous behavior or side effects, but the annotations lower the burden and this is sufficient for a simple trigger action.

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 consists of two short, front-loaded sentences. The first states the main purpose and the second gives a usage trigger, with no unnecessary words.

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 low-complexity tool with one optional parameter, no output schema, and annotations covering safety, the description is complete. The agent knows what the tool does, when to use it, and how the optional parameter behaves.

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

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

The single parameter is fully documented in the schema, including its enum and the behavior when omitted ('Omit to sync all platforms'). The description adds 'all connected platforms' context but does not need to go beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Trigger a refresh of analytics data') and the scope ('from all connected platforms'). It distinguishes this tool from siblings like list_analytics and get_analytics_daily, which read data, by emphasizing the refresh/update nature.

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

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

The description explicitly says when to use the tool: 'Use this if analytics seem stale.' This gives a clear condition for invocation. However, it does not mention when not to use it or name any alternative tools.

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 mutation/destructive nature (readOnlyHint=false, destructiveHint=true), so the description's burden is lower. It adds the scheduled/draft scope and implies partial updates ('You can change...'), but does not disclose outcomes such as behavior on published posts, effects of platform-specific overrides, or whether omitted fields are preserved.

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

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

Two short sentences with no filler. The action and resource are front-loaded, and the list of changeable fields is compact and readable. Every word 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?

The tool is highly complex (9 top-level params, deeply nested platform_configurations for 11 platforms, no output schema), yet the description only covers a few top-level fields. It never mentions per-platform overrides, account_configurations, or partial-update semantics, leaving a significant orienting gap despite a rich 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 description coverage is 78%, so most parameters are already documented. The description simply restates a subset (caption, schedule time, accounts, media) without adding meaning, and it omits platform_configurations, account_configurations, is_draft, and media_urls entirely. It adds no semantic value beyond the schema.

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

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

The description states a specific verb ('Update'), a specific resource ('a scheduled or draft post'), and enumerates the changeable fields (caption, schedule time, accounts, media). This clearly distinguishes it from sibling tools like create_post, delete_post, and get_post by its action and object, even without naming them.

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

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

There is no guidance on when to use this tool versus create_post or delete_post, no mention of alternatives, and no exclusions (e.g., cannot update published posts). The 'scheduled or draft' qualifier provides some scope, but it stops short of explaining when-not-to-use or what to use instead.

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

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

Annotations only signal readOnlyHint=false, openWorldHint=true, and destructiveHint=false, so the description carries much of the behavioral burden. It discloses the reusable media_id output, the special PDF document-kind behavior, the base64 vs URL mode trade-offs, format restrictions, and the serverless request-body limit.

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

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

The description is dense but well structured: the main outcome and two modes are front-loaded, followed by supported formats, a special PDF case, a usage pointer to create_post/update_post, and explicit limitations. Each sentence adds actionable information without fluff.

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

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

For a four-parameter tool with no output schema, the description is notably complete. It explains both input modes, supported types, the returned media_id, PDF-specific behavior, the 3MB cap, and the conversion requirement for HEIC/HEIF, so an agent has nearly everything needed to invoke it correctly.

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

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

Although schema coverage is 100%, the description adds decision-level meaning beyond the parameter docs: which of `url` and `data` to prefer, that `mime_type` is required for `data`, that `data` is capped at 3MB, and what happens for PDF uploads. This materially helps an agent pick and fill parameters correctly.

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

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

The description opens with a specific verb and resource: 'Upload media and get back a reusable media_id.' It clearly distinguishes the tool's job from siblings like delete_media and request_upload_link by emphasizing both the upload action and the reusable ID it produces.

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

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

The description explicitly tells the agent when to use each mode: use `url` for anything over a few MB, and use `data` for direct bytes. It also gives when-not guidance, such as HEIC/HEIF being unsupported and the 3MB cap, and points to alternatives like hosting at a public URL or uploading via the dashboard.

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