Post Bridge

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

Annotations declare a mutating, destructive, open-world operation, and the description adds substantial context beyond them: X strips URLs (including bare domains) to avoid surcharges, is_draft is Post-Bridge-only vs TikTok's real draft, media is auto-deleted after publishing, and per-platform caption caps. This is exactly the behavioral detail 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?

It is long, but length is justified by ten platforms and several genuine gotchas. It is front-loaded with purpose, then routing, then critical caveats. Minor redundancy: caption limits are restated in both the description and the per-platform schema fields.

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 9-parameter tool with nested per-platform objects, no output schema, and 100% schema coverage, the description supplies the missing cross-platform judgment (link stripping, draft semantics, caption overflow handling). It does not describe the response shape, though no output schema exists to defer to.

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 adds cross-cutting meaning: media_urls are downloaded by the API from public URLs, is_draft semantics, and the platform caption-limit strategy that ties caption/platform_configurations together. It largely restates rather than extends a few fields, keeping it below a 5.

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

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

States a precise verb (publish/schedule) and resource (social media post) and enumerates the supported platforms plus cross-posting capability. An agent can immediately distinguish this from siblings like update_post or list_posts without opening a schema.

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

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

Gives explicit operational routing: call list_social_accounts first for IDs, omit scheduled_at to post immediately, write platform-specific captions without being asked, and check has_x_premium before writing an X caption. When-to-do-X conditions are spelled out rather than 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?

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?

Annotations only say the operation is not read-only and not destructive; the description adds substantial behavior: the out-of-band consent flow, in-chat connect button and reporting, external_ref filtering, account cap failure pointing to billing, and platform-specific differences (Instagram's own login vs. Facebook's every-Page 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?

Several dense sentences, each carrying distinct information: purpose, recipient flow, in-chat behavior, external ref, account cap, and platform nuances. The most important purpose is front-loaded and there is no filler.

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

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

For a 4-parameter tool with no output schema, the description is complete: it conveys the returned artifact informally ('Get a link'), the flow, the reporting behavior, the cap failure mode, and platform quirks. Nothing essential for an agent to choose or invoke this 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 covers all four parameters, so the baseline is 3. The description adds real value by explaining external_ref's purpose ('so list_social_accounts can be filtered by it later') and platform-specific behavior for the platform parameter. It does not add semantics for expires_in or return_url, but those are already fully described in the schema.

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

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

The description opens with a specific verb and resource: 'Get a link that connects a new Instagram, Facebook or TikTok account to the user's Post Bridge account.' It states the core action, the resource, and the key distinction ('without them opening the dashboard'), which separates it from the upload/link siblings.

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

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

It gives clear context on who should receive the link and what happens after: the account owner approves on the platform's consent screen and is sent back. It does not explicitly say 'do not use for uploading or existing accounts' or name a when-not alternative, so it stops short of a 5.

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

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

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 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 readOnlyHint=false, destructiveHint=true and openWorldHint=true, so the mutation risk is covered structurally. The description adds the useful scope constraint (scheduled/draft only), but omits the critical update semantics — whether unspecified fields are preserved or wiped — and says nothing about auth or platform-side side effects.

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

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

Two short sentences with the primary action first and the editable surface second. Zero filler; every clause carries information.

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

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

Nine parameters including nested platform override objects and no output schema, but the schema itself is exhaustively documented per field (overrides, character limits, failure behavior). The description only needs to frame the operation, which it does adequately.

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 already explains almost every parameter, including the deep platform_configurations overrides. The description names four field categories but adds no syntax, defaults, or interaction rules (e.g. top-level vs per-platform override precedence) beyond what the schema states.

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

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

States a specific verb+resource ('Update a ... post') and enumerates the mutable fields (caption, schedule time, accounts, media). It scopes the target to 'scheduled or draft' posts, which distinguishes it from create_post/delete_post without needing the schema. No explicit sibling routing, though the sibling set makes the intent 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?

Implies a precondition (the post must be a scheduled or draft post) but never states what happens for published posts or when to choose update_post over delete_post + create_post. Usage is inferable rather than spelled out; no exclusions or alternatives are named.

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

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

Annotations only cover safety hints (readOnlyHint=false, destructiveHint=false, openWorldHint=true). The description adds substantial behavior beyond that: 3MB serverless body cap, 500MB presigned limit, 2-hour URL validity, HEIC/HEIF rejection, PDF producing a document-kind media_id with LinkedIn carousel semantics, and the curl command returned in the result.

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

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

Dense but front-loaded: the core purpose and the three modes come first, then format support, then downstream usage. Nearly every clause carries information, though the mode enumeration is long enough that a reader must parse carefully.

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, yet the description explains what is returned (media_id, presigned upload_url, included curl command) and how to use it downstream. Supported and unsupported formats, size limits, and the LinkedIn PDF path are all covered, leaving no operational 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?

Schema coverage is already 100%, so the baseline is 3. The description goes further by grouping parameters into named modes and spelling out cross-parameter rules (url XOR data; size_bytes requires mime_type and name and forbids url/data), which is genuine added meaning over the per-field schema text.

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

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

States a specific verb+resource ('Upload media and get back a reusable media_id') and immediately distinguishes the three input modes. It also names the downstream consumer (create_post/update_post `media` param) and the relevant sibling request_upload_link, so an agent can place it precisely among siblings.

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

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

Explicit routing rules: mode 1 for public URLs, mode 2 for small base64 files (3MB cap), mode 3 for local files when shell commands are available, plus 'Use mode 3 for any local video' and 'otherwise request_upload_link'. Both the when and the fallback alternative are named.

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