Post Bridge

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

Annotations only flag it as a destructive, open-world write. The description goes well beyond that with genuinely non-obvious behavior: X silently strips URLs (including bare domains) and surcharges for links, oversized captions get cut, media IDs are invalidated after the last post publishes, is_draft is Post-Bridge-only rather than a native draft, and TikTok's platform_configurations.tiktok.draft is the real native draft. These are exactly the surprises an agent must know before invoking.

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

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

Long (~350 words), but for a 9-parameter cross-platform tool essentially every sentence carries a platform-specific constraint, and the most consequential warning (X link stripping) is called out with an 'IMPORTANT' marker. The only waste is minor duplication of caption limits that also appear in nearly every platform schema field.

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 nested, destructive, multi-platform write with no output schema, the description covers the hard parts: platform-specific media requirements, caption ceilings, X premium branching, draft semantics, and threads. It does not describe what a successful response contains (post IDs, per-platform results) nor how to inspect partial failures, which an agent would need after creating.

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 the schema alone does not surface: media_urls are downloaded by the API, has_x_premium on the account determines whether the 280 or 25,000 X limit applies, and platform_configurations should be populated proactively with a shorter caption when the shared one overflows. It explains the intent behind the override structure rather than restating fields.

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

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

States a specific verb (publish/schedule) and resource (social media post) across an enumerated platform list, and immediately establishes the key capability differentiator: one call can cross-post to multiple accounts. An agent can distinguish this from update_post or preview_media without opening a schema.

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

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

Gives clear conditional routing inside the tool: 'Use list_social_accounts first to get account IDs', 'Omit scheduled_at to post immediately', and use platform_configurations.<platform>.caption when the shared caption exceeds a limit. It does not contrast against sibling alternatives for an already-created post (update_post, delete_post, preview_media), so it stops short of full when-not guidance.

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

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

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, destructiveHint=false, and openWorldHint=false, so safety is covered. The description usefully adds that results are scoped to posts published through Post Bridge and that media_type has platform-specific exclusion behavior, but it does not cover pagination, default limits, or return shape. Modest added value over 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?

Two front-loaded sentences with no filler: the first names the resource and metrics, the second lists the filters. Every clause earns its place.

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

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

Annotations cover the safety profile and the schema fully documents parameters, so the essential invocation info is present. However, for a list/analytics tool with no output schema, the description says nothing about return format, pagination behavior, or how results relate to get_analytics_daily or sync_analytics, leaving sibling disambiguation incomplete.

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

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

Schema description coverage is 100%, so every parameter already has a description. The description echoes the filterable dimensions (platform, timeframe, media type) but adds no syntax, defaults, or edge cases beyond what the schema provides. 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 ('Get') and resource ('social media post performance analytics'), and enumerates the metrics returned (views, likes, comments, shares) plus the platforms involved. An agent can distinguish this from get_analytics_daily and sync_analytics without opening any schema.

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

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

The description implies usage by naming supported platforms and filter dimensions, but never states when to use this over the sibling get_analytics_daily or exactly what its scope is relative to sync_analytics. No alternative is named and no when-not condition is given.

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

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

Annotations already declare readOnlyHint=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 establish the safe read-only, non-destructive, closed-world profile, but the description goes well beyond them: it details the returned fields, decodes has_x_premium (25,000 vs 280 character limit for X), and explains the operational consequence of needs_reconnect (posting paused, posts skipped, cleared automatically upon reconnect). That is the root-cause-plus-remediation context an agent needs and cannot get from annotations.

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

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

Front-loaded with the core purpose, then progressively adds return fields and the needs_reconnect rule; every sentence carries information. The ten-platform enumeration in the first sentence is slightly bloated but defensible as scope-setting, so it falls just 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?

There is no output schema, so the description carries the full burden of explaining the return value, and it does so by enumerating the fields and interpreting the two non-obvious ones. Combined with complete safety annotations and zero parameters, nothing an agent needs to call 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?

The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly adds no parameter guidance since there is none to give, and instead spends its words on the return shape.

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

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

States a specific verb (list) and resource (the user's connected social media accounts) and enumerates the exact platforms covered, which no sibling tool addresses. An agent can immediately distinguish this from list_posts, list_media, or list_analytics without opening any schema.

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

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

Clear context for when to reach for it (checking connected accounts and their health) and an explicit negative rule: do not post or retry against accounts flagged needs_reconnect, and tell the user to reconnect instead. It stops short of naming alternative sibling tools or explicitly framing this as a prerequisite step before create_post, so it is strong but not fully prescriptive.

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. The description adds meaningful behavioral context by explaining that images return a visual preview while videos and PDFs return only a text note. This goes beyond the annotations and helps set expectations.

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

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

The description is two compact sentences with no filler. The core purpose is front-loaded, and the illustrative 'pink hat' example adds clarity without bloating the text.

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

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

For a simple single-parameter read-only tool, the description covers the main behavior, the unsupported media types, and the prerequisite. It does not specify the exact preview format (e.g., image URL vs. inline data), but the lack of an output schema makes that a minor gap.

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

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

The schema already fully documents the single 'id' parameter with a description and provenance ('from list_media or upload_media'). The description reinforces using list_media first, which is helpful, but adds little beyond the schema's own documentation.

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: 'See an uploaded image' and 'returns a small preview of the picture itself.' It also clarifies scope by saying images only, and distinguishes the tool from other media operations clearly.

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 explicit guidance: 'Images only; videos and PDFs return a text note' and 'Use list_media first to get ids.' This tells the agent when the tool is useful and what prerequisite step is needed, though it does not name an alternative tool for non-image media.

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

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

Goes well beyond the annotations: it discloses the plan account-cap behavior and the error that points at the billing page, that connected accounts are reported back in-chat in Claude/ChatGPT, and the per-platform connection semantics (Instagram login vs Facebook Pages, LinkedIn profile + company pages, Bluesky handle + app password). Annotations only say non-read-only/non-destructive, so this adds substantial operational 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?

Front-loaded with the core action and recipient in the first sentence, then layered with behavior, external_ref, and platform specifics. Dense and mostly waste-free, though the trailing platform-by-platform detail is long enough that it edges toward reference material rather than invocation guidance.

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

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

With no output schema and no annotations covering behavior, the description carries the full burden and does: it explains what the caller gets back (in-chat connect button, account reported on connection), the failure mode at the account cap, and platform-specific connection scope. An agent has everything needed to call and interpret it.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds cross-tool meaning the schema lacks: external_ref tags connected accounts so list_social_accounts can later be filtered by it, and platform values carry distinct connection behavior (bluesky's app password, linkedin's company pages). expires_in and return_url are left to the schema.

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

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

States a specific verb (get a link), the resource (connect link), and the exact outcome: connecting a new social account to the user's Post Bridge account without dashboard access. It names the nine supported platforms, so an agent can distinguish it from request_upload_link and other 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?

Clear about the operating context: hand the link to the account owner (the user or their client), who approves on the platform's consent screen. It implies the alternative (opening the dashboard) is being avoided, but never explicitly states when not to use this tool or names a competing sibling to route to.

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

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

Annotations only declare the generic non-readonly/non-destructive profile, but the description adds real behavioral detail: the link expires in 24 hours, one or many files can be dropped at once, and media_ids are auto-reported in Claude/ChatGPT while other clients require a list_media fallback. That is exactly the context annotations cannot carry.

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

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

Front-loads the core purpose and the 24-hour validity, then layers the workflow. It is on the long side with a dense final sentence, but nearly every clause carries operational information an agent needs 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?

No output schema and no parameters, so the description must explain what comes back and what to do next, and it does both: the link's lifetime, how ids are surfaced per client, and the list_media/create_post handoff. 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. It does usefully describe the downstream artifacts (the link, the media_ids) the caller will consume.

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 (get an upload page for device-local files) and immediately scopes it against siblings: it is for files with no public URL, which upload_media cannot reach. An agent can distinguish it from upload_media and request_connect_link 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 conditions (no URL, larger than 3MB, no shell access on the user's machine) and names the alternative plus its selector: 'if you can run shell commands, use upload_media with size_bytes instead.' It also prescribes the post-upload workflow (list_media newest-first, then 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 declare readOnlyHint=true and openWorldHint=true, and the description still adds real behavioral context: the account-type prerequisite (supports_instagram_music: true), the precise failure mode for Instagram-login accounts, and the caveat that the catalogue differs from Meta's in-app library. That is beyond what structured fields supply.

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

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

Front-loaded with purpose then downstream usage, and each sentence carries distinct information (usage, prerequisite, error handling, catalogue caveat). The error-remediation sentence is long and parenthetical-heavy, but no sentence is pure filler.

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

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

For a read-only discovery tool with no output schema, the description covers selection criteria, the consumer of the result, the preconditions, and the failure path. Nothing an agent needs to call it correctly or interpret failure 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 enum values and the query omission rule are already documented. The description still adds cross-tool meaning by explaining what to DO with the returned audio_id and the companion 0-100 audio_volume/video_volume parameters, which the schema does not mention.

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 ('Search the music ... Meta lets apps attach to an Instagram reel') and immediately frames the scope as the third-party-app catalogue rather than the in-app library. An agent can distinguish it from list_media or list_posts without opening the schema.

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

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

Explicitly covers when to use it (attach returned audio_id in create_post/update_post), how to get trending audio (omit query), and when it will not work (Instagram-login accounts). It also names the fallback workflow (add audio before uploading) and the exact dashboard path for remediation.

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 declare destructiveHint=true and readOnlyHint=false, so the safety burden on the description is lower, but it still adds almost nothing behavioral. It never says whether omitted fields are preserved or wiped (critical for a partial-update tool with 9 params), whether replacing media destroys prior uploads, or what happens if the post is already published. For a destructive mutation this is a significant gap.

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, and the scope-limiting clause ('scheduled or draft') is placed before the field enumeration where it matters most. Nothing is wasted or buried.

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

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

No output schema exists, and the description provides no return information, no partial-vs-full update semantics, and no mention of per-platform overrides despite the schema's large nested platform_configurations object. For a destructive tool of this complexity, the description leaves the agent to infer behavior entirely from the 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 the schema carries most of the explanatory load and the baseline of 3 applies. The description indexes four of the nine params (caption, schedule time, accounts, media) but omits is_draft, media_urls, account_configurations, and — most importantly — the entire platform_configurations override tree, which is the tool's largest and most consequential surface.

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 (update) and resource (post) and bounds the scope to scheduled or draft posts, which is meaningful information. It does not explicitly distinguish itself from siblings like create_post or delete_post, but the scope constraint makes its role reasonably unambiguous.

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

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

The phrase 'scheduled or draft post' implies a precondition (the post must not be published yet) but never states it as an exclusion or names an alternative path. There is no guidance on when to use update versus delete-then-create, nor on prerequisites such as required account permissions.

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 this is a non-read-only, non-destructive, open-world write, so the safety profile is covered. The description adds substantial context the annotations cannot: media_id lifecycle (deleted after the last using post publishes), presigned URL validity of 2 hours, the 3MB vs 500MB caps, and the format restrictions. It does not describe failure behavior or auth requirements, keeping it short of a 5.

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

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

Front-loaded with the purpose and media_id outcome before the mode breakdown, and every sentence carries operational detail (caps, validity windows, alternatives). It is dense and long, but there is little filler; only the PDF/LinkedIn aside is somewhat incidental to the upload task.

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

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

With no output schema, the description takes on the burden of explaining return values and it does so: media_id, presigned upload_url, and an included curl command. Combined with the caps, lifecycle, and downstream usage guidance, 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. The description goes beyond the schema by explaining the mode-combination logic, i.e. which parameters pair with which (size_bytes + mime_type + name with no url/data), the 3MB and 500MB caps, and what each mode returns. That is meaningful semantics layered on top of schema-documented fields.

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

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

States the specific verb (upload) and resource (media), and immediately names the concrete outcome: a reusable media_id. It also enumerates four distinct invocation modes, which is far more than a restatement of the name.

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

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

Explicitly routes the agent by environment and input: mode 1 for URLs, mode 2 for small base64 data, mode 3 for local files when shell commands are available, mode 4 for ChatGPT conversation files. It names exclusions (HEIC not supported) and a fallback alternative (request_upload_link) when neither mode fits.

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