uplika

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

The description goes well beyond the annotations by stating irreversibility, the need for confirmation, the daily delete quota, and compatibility with Threads app posts. Annotations already flag destructiveHint, but this adds practical 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?

Three compact sentences front-load the main action, then add crucial safety and rate-limit details. No fluff or redundancy.

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 delete tool, the description fully covers what is destroyed, irreversibility, rate limits, and input compatibility. No output schema exists, so return values are not expected to be explained.

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 covers the id parameter with 100% coverage, including the types and link behavior. The description mostly repeats what the schema says ('given the link', 'Threads app'), adding no new parameter-level meaning.

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 purpose: permanently delete a post from the channel. 'For good' distinguishes it from non-destructive actions like hiding, and the resource (post) and scope (channel) are explicit.

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

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

Provides clear operational guidance: confirm with the person first, respects daily rate limits, and works with links from the Threads app. It does not explicitly name alternatives or exclusions, but the context is strong.

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, so the read-only nature is covered. The description adds valuable behavioral detail: views and shares can be null when the platform hasn't reported them yet, and null is not zero. This clarifies a potential data-interpretation pitfall, which is beyond what annotations provide.

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

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

The description is two sentences, front-loaded with the list of metrics, and includes the crucial null-handling caveat. No filler or redundancy exists.

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 only one parameter, full schema coverage, read-only annotation, and a description that enumerates the returned metrics and null behavior, the tool is fully specified for an agent to select and invoke it correctly. No output schema exists, but the description lists the return fields explicitly.

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 input schema has 100% parameter description coverage, explaining that 'id' accepts a publish id, Threads media id, or post link. The description adds no additional parameter semantics beyond reinforcing that the tool targets a single publish. Baseline 3 is appropriate given full schema coverage.

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 returns specific metrics (views, likes, replies, reposts, quotes, shares) for a single publish. This distinguishes it from sibling tools like get_post (which likely fetches post content) and list_posts (which lists multiple posts). The scope ('for one publish') is explicit.

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 for retrieving metrics on a single post, which is clear context. It does not explicitly name alternatives or exclusion criteria, but the phrase 'for one publish' suggests it is not for bulk listing or content retrieval. No explicit when-not-to-use guidance is provided.

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

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

Annotations already indicate readOnlyHint=true, and the description adds meaningful behavioral context: it returns per-target status and failure reasons. No contradiction, though it could mention more about response format or limitations.

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, front-loaded with the core purpose, and the alternative tool named. Every word earns its place with no redundancy.

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

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

The tool is simple (1 param, read-only, no output schema). The description covers what it does, what it returns, and when to prefer another tool. Complete for its complexity class.

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 input schema has 100% coverage for the id parameter, already explaining accepted formats (publish id, Threads media id, post link). The description adds minimal parameter insight beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly identifies the tool as retrieving a single publish, with specific details on per-target status and failure reasons. It explicitly contrasts with open_post for post links, distinguishing it from a sibling 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?

Provides direct usage guidance: 'For a post link you probably want open_post instead.' This tells the agent when not to use this tool and points to the alternative, making the decision clear.

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

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

The description adds substantial behavioral context beyond the readOnlyHint: it clarifies that the quota is live usage, covers posts/replies/deletes, and that the platform has an independent publish speed cap that can cause rate_limited errors despite remaining allowance. This is useful, non-obvious context for the agent.

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 three sentences, each with a distinct purpose: definition, usage timing, and a critical caveat. It is front-loaded with the core answer and contains no fluff or repetition.

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 quota check with one optional parameter, the description covers purpose, use case, and an important platform behavior about rate limiting. No output schema exists, but the description clearly implies the result is a usage amount, which is sufficient for this complexity.

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 input schema covers the only parameter (accountId) with 100% coverage, including its optionality and meaning. The description itself does not mention the parameter, but it does not need to since the schema is complete. Baseline 3 applies.

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

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

The description clearly states what the tool does: it reports how much of the 24-hour allowance is already used for posts, replies, and deletes. It distinguishes itself from sibling tool list_platforms by explicitly noting that this is live usage, not static limits.

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 advises to 'Check this before a burst of publishing', provides an alternative tool (list_platforms) for static limits, and warns about a separate account-level rate limit that can cause publish to return rate_limited even when quota remains. This gives clear when-to-use and interpretation 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 description adds behavioral context beyond the destructiveHint annotation by explaining that hide: false shows the reply again, indicating reversibility. It also clarifies the relationship between replyId and postId. However, it doesn't discuss permissions or edge cases like idempotency.

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 concise sentences with the primary action front-loaded. Every sentence adds value without redundancy.

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 toggle tool with all parameters documented and no output schema, the description is sufficiently complete. It explains the core behavior, reversibility, and parameter relationships. Lack of edge-case handling is acceptable given the tool's simplicity.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description reinforces that replyId comes from list_replies and postId is the publish, but adds minimal new meaning beyond the schema's property descriptions.

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: 'Hide a reply on the channel, or show it again with hide: false.' This specific verb+resource description distinguishes it from siblings like delete_post (permanent removal) and reply (creating). The toggle behavior is explicit.

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 mentions that 'reply id comes from list_replies' and 'postId is the publish it belongs to,' but provides no guidance on when to use this tool versus alternatives like delete_post. It does not specify moderation scenarios or exclusions.

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

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

Beyond the readOnlyHint annotation, the description discloses the meaning of item fields, especially the 'active' status requirement for publishing, and explains that the IDs returned are the same ones used in publish calls. It also covers the empty-list edge case, providing rich 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?

The description is slightly long at seven sentences, but every sentence contributes meaningful information: item structure, account ID usage, active status logic, and empty-list handling. It is front-loaded with the core concept and reads efficiently despite the length.

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

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

With no output schema, the description fully covers the return value structure (id, platform, handle, status), the usage context (before publishing), and the customer-facing action for an empty list. It leaves no critical gaps for correct tool invocation.

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

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

The tool has zero parameters, so the baseline score is 4. The description correctly focuses on return values and their meaning rather than parameter details, adding no unnecessary parameter noise.

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 'Connected social accounts' and details the item fields, making it clear this tool lists accounts, but it lacks an explicit verb like 'list' in the description itself. It is distinct from sibling tools like list_platforms and list_posts by focusing on account objects with status and handle.

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 an explicit directive: 'Call this before publishing anything.' It also provides conditional guidance: if no channel is named, target every active account, and if the list is empty, send the user to a dashboard URL. This satisfies when-to-use and what-to-do with results.

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 provide readOnlyHint=true, so the description carries less burden but adds value by noting the inclusion of Threads app posts and that each item includes a permalink usable by open_post, reply, or delete_post. No contradiction with annotations.

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

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

The description is two sentences, front-loaded with the core purpose ('What is actually on the channel right now'), and every sentence adds useful information without fluff.

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

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

With no output schema, the description usefully discloses that each item has a permalink and how that permalink can be consumed by other tools. It also clarifies scope (including Threads app posts). Minor omissions like ordering or pagination are covered by the limit parameter description.

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

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

Schema coverage is 100%, so the schema already fully documents limit and accountId. The description does not add parameter-level detail beyond the schema, which is acceptable given the schema's completeness.

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 what the tool does: it lists posts currently on the channel, including Threads app posts, and frames itself as a way to find a post without a link. This distinguishes it from generic list tools like list_posts, though it does not explicitly name a sibling alternative.

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 an explicit use case: 'Use this to find a post when you do not have its link.' This tells the agent when to choose this tool, though it does not mention when not to use it or explicitly compare to alternatives.

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

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

Beyond the readOnlyHint annotation, the description explains status values (live, beta, soon) and charCount semantics, which are important behavioral details. It also reassures that beta channels can publish but only testers can connect, adding value.

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

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

The description is front-loaded with the core function, then adds use-case guidance and status/charCount explanations. Each sentence adds meaningful context without fluff.

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

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

With no output schema, the description covers the essential output aspects: channel rules, status meanings, and charCount usage. It fully compensates for the lack of structured output documentation.

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 no parameters, so the schema is empty. The description focuses on output semantics (status, charCount), which is the relevant information for an agent; baseline 4 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 tool lists every channel and its rules (character limit, media requirements, status). This is distinct from sibling tools that manage posts or accounts, so the scope is 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?

It tells the agent to read this before calling publish to check limits, providing a specific when-to-use scenario. It doesn't explicitly name alternative tools, but the context strongly implies it complements publishing operations.

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

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

Beyond the readOnlyHint annotation, the description discloses default limit (20), maximum (100), ordering (newest first), pagination mechanism (hasMore and nextBefore), and scope (only posts made through us). This gives a complete mental model of the tool's behavior.

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

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

The description is compact—three sentences—and front-loaded with the core purpose. Every sentence contributes useful information: what is listed, defaults, pagination, and the sibling alternative. No 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?

Given the tool's moderate complexity (pagination, filtering, scope), the description covers all essential aspects: what is returned, ordering, defaults, pagination, and exclusion. The lack of an output schema is mitigated by explaining hasMore and nextBefore. It also proactively addresses the most likely confusing sibling.

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?

While the input schema already documents each parameter, the description enriches their semantics by explaining how limit, before, and hasMore interact for pagination. It also clarifies the meaning of 'before' as a publish id from the previous page's nextBefore, adding value beyond the schema.

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

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

The description states the tool lists recent publishes made through the service with per-target status each. It clearly distinguishes from sibling list_channel_posts by noting that pre-existing channel posts are excluded, making the resource and scope 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?

It explicitly directs users to list_channel_posts for posts that already existed on the channel, providing a clear alternative. It also describes pagination behavior (hasMore, nextBefore) so users know when and how to page through results.

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

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

Annotations declare readOnlyHint=true, and the description adds behavioral traits: the response may be truncated (indicated by a `truncated` field), nested replies are included, and the count can differ from get_insights. This gives the agent awareness of output shape and edge cases, adding value beyond the annotation without contradiction.

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 sentences long and well-structured. The first sentence states the core function concisely, and the second adds essential caveats about truncation and count differences. Every word earns its place, with 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?

The description covers the key aspects: what is returned (full thread with nested replies), potential truncation via the `truncated` flag, and the relationship to get_insights. Given there is no output schema, it could detail the reply object fields, but for a straightforward listing tool with one parameter and read-only annotations, the description is sufficiently complete.

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

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

Schema coverage is 100%: the id parameter's description already fully documents accepted formats (publish ID, media ID, URL) and notes the connected-account requirement. The tool description does not add additional parameter-level detail beyond referring to 'a post', 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 defines the tool's purpose: retrieving the entire reply thread under a post, including nested replies. It uses a specific verb ('list') and resource ('replies'), and distinguishes itself from get_insights by noting the count differs from the replies metric, and from reply/hide_reply which are mutating operations.

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 when to use the tool (to access the full reply thread) and explicitly contrasts it with get_insights, clarifying that the count here is the actual raw thread, not the metric. It does not explicitly name alternatives like get_post or list_posts, but the distinction from get_insights provides a clear usage context without confusion.

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 indicate it is neither read-only nor destructive. The description adds that the tool verifies the file landed and flips the media to a ready state, which is useful. However, it lacks details on failure behavior, idempotency, or consequences of premature invocation, leaving some 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?

The description is three short sentences, each adding distinct value: context, usage timing, and behavioral outcome. No redundant wording or restating of the tool name; it is front-loaded and efficient.

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 1 parameter, no output schema, and basic annotations, the description provides the core context: what, when, and effect. However, it omits mention of return values or error handling, which is a noticeable gap for a state-changing API. It is adequate but not comprehensive.

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 has full coverage (100%) for the single parameter 'id' with description 'Media id from media_presign'. The description reinforces the source of the id by referencing step 2 and media_presign in the schema, but adds no new parameter-level detail beyond the schema, so it rests at the baseline.

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

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

The description clearly identifies this as 'Step 2 of attaching an image' with a specific role: finalizing the upload and marking the media ready. It distinguishes from siblings by its position in the sequence (after upload, before publish) and includes a concrete verb phrase 'check the file really landed before marking it ready.'

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 explicit when-to-use guidance ('Call it after the upload finishes') and a prerequisite ('Only a ready media id can be passed to publish'). It does not explicitly compare with alternative steps like media_upload_status, but the sequential framing provides clear context.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description discloses that the tool downloads, copies into storage, and returns a media ID. It also mentions constraints (https only) and failure modes (share links return HTML, not files). This gives the agent a clear behavioral model.

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 concise and front-loaded, starting with the core action. It uses 7 sentences but each adds value: main function, internal process, output, one-step nature, protocol restriction, failure case, and altText guidance. Slightly long but all content is pertinent and well-structured.

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

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

For a tool that downloads external media, the description covers prerequisites (public, https, direct URL), the process (download, copy, return media id), and a common failure scenario. It also clarifies how this differs from sibling upload tools. Without an output schema, the description still conveys what the agent receives (a media id).

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

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

Schema already covers both parameters (url, altText) with descriptions, so baseline is 3. The description adds extra semantics: explains that the URL must be the direct file path, not a share link, and advises writing altText if an image is visible. This goes beyond the schema's literal descriptions.

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: attaching an image or video from a public URL by downloading it into storage and providing a media ID for publishing. It uses a specific verb ('Attach') and resource ('media from URL'), and distinguishes itself from sibling upload tools like media_upload_link.

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

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

Provides explicit when-to-use guidance: for public web media that can be directly fetched. It gives exclusions ('Google Drive and Dropbox share links do not work') and a rule of thumb ('Use a direct file URL that ends in the file itself'). Also instructs when to add altText, which is practical 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 description goes well beyond the annotations (readOnlyHint=false, destructiveHint=false) by explaining the one-time nature of the uploadUrl, the media expiry behavior, and the media_expired error on publish. It also adds constraints like size limits and aspect ratio, which are not in the schema. No contradiction with annotations.

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

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

The description is slightly verbose but every sentence adds value: workflow, constraints, return semantics, and error behavior. The most critical information (step 1, returns id and URL) is front-loaded. It is not bloated with 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?

Despite having no output schema, the description fully compensates by explaining the response fields (media id, uploadUrl, mediaExpiresAt) and the next step (media_complete). It covers limitations, error conditions, and the intended usage flow, making the tool's behavior complete for an agent.

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?

Even though schema coverage is 83%, the description enriches parameter understanding. It explains how bytes and contentType are used in the PUT request, gives concrete limits (up to 8MB, aspect ratio up to 10:1), and instructs when to provide altText ('If you can see the image'). It does not describe width/height in detail, but the schema already covers them.

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 role as 'Step 1 of attaching an image' and specifies the return values (media id, one-time uploadUrl). It distinguishes itself from siblings like media_complete by framing the workflow, so there is no ambiguity about what this tool does.

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 explicit usage context: it is the first step in a two-step process, with instructions to 'PUT the file bytes to uploadUrl' and then call media_complete. It also notes restrictions like 'Images only for now' and acceptable content types. However, it does not explicitly mention when NOT to use this tool or compare it to media_upload_link or media_from_url.

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 provide readOnlyHint=false and destructiveHint=false, so the description carries the burden of explaining behavior. It discloses the short-lived nature of the link, the need to poll media_upload_status with the token, and the sequencing/dependency on publish. This goes beyond annotations and helps the agent understand the tool's non-trivial behavior, though it doesn't cover failure modes or exact token details.

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 concise and well-structured: it starts with the core action, then provides the workflow, a caution, and an alternative. Every sentence adds necessary information without fluff, making it efficient and easy to parse.

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

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

The tool has no output schema, so the description must convey return values and usage context. It mentions the link and the token, explains the follow-up status polling, and differentiates from a sibling tool. It is sufficiently complete for a simple one-parameter tool, though it could mention the lack of a return schema explicitly, but the context is clear.

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 input schema fully describes the only parameter (note) with 100% coverage, so the description doesn't need to add extra parameter details. The description adds no additional semantic value beyond what the schema provides, resulting in a baseline score 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 purpose: asking the person to upload files and returning a short-lived link. It explicitly distinguishes itself from media_from_url, so it's easy to identify when to use this 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 provides explicit usage guidance: use it when the file is on the person's device, and use media_from_url when the file has a public https address. It also explains the full workflow (give link, wait, poll status, then publish), including the caution not to publish before ready.

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 readOnlyHint annotation already establishes this as a safe read operation. The description adds valuable context about the possible return statuses (waiting, ready, expired) and how the returned media IDs can be passed to publish, which goes beyond the annotation.

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

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

The description is two sentences with no filler. The first sentence immediately states the core purpose and output, and the second sentence provides actionable guidance, making it highly efficient.

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 tool with one parameter and no output schema, the description fully covers the return values (statuses and media IDs) and their downstream usage. It omits only edge-case details like what 'expired' means operationally, but the essentials are present.

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

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

Schema coverage is 100% and the token parameter is described as coming from media_upload_link. The description reinforces this by referring to 'that link' and explaining the token's role, but it doesn't add substantial new 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 states the tool's function as checking upload status, enumerates the possible statuses (waiting, ready, expired), and mentions that it returns media IDs. It also implicitly distinguishes itself from siblings like media_upload_link and media_complete by focusing on status checking and providing next-step guidance.

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 a clear workflow: use this tool to check whether an upload has occurred via a link, then use the returned media IDs in a publish call. While it doesn't explicitly state when not to use it, the context and sibling list make the use case unambiguous.

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

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

With readOnlyHint=true, safety is already disclosed, but the description adds valuable behavior: replies/metrics can return null if the platform refused that part, and it bundles all data into one call. This goes beyond the annotation without contradicting it.

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

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

Two tight sentences: the first front-loads the main function, the second gives a use case and a caveat. No wasted words, earning a top score.

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 tool with no output schema, the description fully covers scope, content, and a potential null behavior. It is complete enough for an agent to know what it will receive and what could go wrong.

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

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

Schema coverage is 100% and the id parameter description already explains accepted formats (publish id, media id, post link). The tool description adds no extra parameter meaning, so the baseline 3 applies.

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

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

The description clearly states what the tool does: returns everything about one post (text, full reply thread, metrics) in a single call. It also identifies the specific use case of having a post link, which distinguishes it from siblings like get_post or list_replies.

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

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

It explicitly says 'This is the right tool when someone hands you a post link,' providing clear context for when to use it. However, it does not name alternatives or state when not to use it, so it falls short of full exclusion 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?

Beyond the destructiveHint annotation, the description discloses critical behavioral traits: 'This publishes immediately,' 'Returns while the post is still publishing. The permalink is null at that moment,' failure semantics for threadItems ('If a later item fails, the ones already up stay up'), and the character-limit failure mode ('Over the limit nothing goes out to any channel'). It even explains the UTF-8 byte behavior for emoji. No contradiction with annotations.

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

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

The description is long but every sentence earns its place, covering channel selection, character limits, media handling, scheduling limitations, async behavior, wait semantics, and thread alternatives. It is front-loaded with the core purpose ('Post to social channels') and then systematically addresses operational details. Given the tool's complexity, this density is appropriate and not redundant.

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

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

For a complex publishing tool with no output schema, the description is remarkably complete: it covers prerequisites (account selection, media id acquisition), constraints (500 chars, UTF-8, topic tag rules), failure modes, async return behavior, and how to follow up (call get_post). It even addresses the unsupported scheduling case with a user-facing fallback. This leaves little ambiguity for an agent.

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?

Even with 100% schema coverage, the description adds substantial meaning to parameters: it explains how to obtain accountIds, how media ids are obtained via three distinct sibling tools based on file location, that threadItems handles ordering/waiting, and that wait:true behavior carries timeouts. It clarifies semantics like 'emoji count as UTF-8 bytes' and 'each item obeys the character limit on its own.' This goes far beyond the schema descriptions.

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 purpose: 'Post to social channels' with immediate publication semantics. It distinguishes itself from siblings by explicitly noting there is no scheduling/draft mode and by positioning threadItems as an alternative to 'publish-then-reply' for long posts. The first sentence gives a specific verb+resource, and subsequent details reinforce what this tool does that others don't.

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 when-to-use and when-not-to-use guidance: 'Get accountIds from select_channels — do not guess which channel the person meant,' 'If the user asks to post later, tell them uplika cannot schedule yet,' and 'For a long post use threadItems instead of publish-then-reply.' It also explains when to use wait:true and how to handle async responses. This is exemplary usage guidance for an agent.

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

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

The description discloses that the operation returns before the reply is live, mirroring publish, and instructs calling get_post with the returned id to check status and link. This adds significant context beyond the annotations (readOnlyHint=false, destructiveHint=true) and does not contradict them.

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

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

The description is two sentences, front-loaded with the primary purpose, and makes efficient use of a reference to sibling tool publish. No wasted 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 tool with 3 parameters and no output schema, the description covers the core action, the async behavior, and how to retrieve the final result. It is self-contained and sufficient for an agent to select and invoke the tool 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 67% (id and replyTo have descriptions, content does not). The description adds meaning for replyTo by explaining nesting semantics and how to reply to the post itself, going beyond the schema. content is self-explanatory, so no additional detail is necessary.

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: 'Reply to a post or to a reply.' This clearly distinguishes it from sibling tools like publish or list_replies, and it explicitly covers both top-level replies and nested replies.

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 explicit guidance on the replyTo parameter: leave empty for the post itself, or pass a reply id from list_replies to nest. It references publish as a behavioral comparison, but does not explicitly state when to choose this over publish or exclude alternatives.

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

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

Beyond the annotations (destructiveHint true), the description adds important behavioral context: it never double-posts, only affects failed targets, and returns nothing_to_retry if nothing failed. This is valuable nuance that helps the agent predict side effects and edge cases.

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 compact yet complete: four short sentences each serve a purpose—what it does, idempotency, edge-case behavior, and scope. No fluff or redundancy.

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 tool with annotations and full schema coverage, the description covers the core action, safety, result on no-op, and applicability. It is functionally complete for an agent to select and invoke correctly.

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

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

The input schema already covers 100% of the parameter documentation (id formats and examples). The description adds no additional parameter-specific information, so 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 tool retries failed publish targets, distinguishing it from siblings like publish (which creates) and delete_post (which removes). It adds a scope constraint ('Only applies to posts published through us') that further clarifies its unique role.

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 when to use (after a publish has failures) and provides a safety guideline (won't double-post). It also notes the scope limitation. However, it doesn't explicitly mention alternatives or when not to use, but the context is clear enough.

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

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

Beyond the readOnlyHint annotation, the description discloses several key behaviors: duplicate folding, dropping of expired/not-yet-live channels into `skipped` with reasons and reconnect links, the meaning of `limits` as the tightest rule, and the specific condition of both accountIds and candidates being empty. This is rich, actionable behavioral detail not present in 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?

Every sentence in the description carries distinct and necessary information: purpose, when to call, scope usage, dedup/skip behavior, output guidance, limits semantics, edge case handling, and a fallback URL. No filler or redundancy—it is dense yet clearly organized.

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

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

Despite having no output schema, the description compensates by explaining exactly what comes back (accountIds, candidates, skipped, limits) and what to do with it (pass to publish, respect limits). It also covers the edge case of no connected channels and provides a concrete remediation path. The description is complete for a selection tool with this complexity.

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 input schema describes scope briefly, but the description adds substantial meaning: it explains the default behavior (omit for candidate list), gives concrete examples of valid values ('threads', '@vibe.trender', account ids), and describes how mixed types are handled. This goes far beyond the schema's minimal explanation.

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 'Pick which connected channels to post to,' which precisely identifies the tool's action and resource. It clearly distinguishes this from siblings like publish (which actually posts) and list_accounts (which lists accounts generally) by framing it as a pre-publish selection step.

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 'Call this before publish and show the result to the person,' providing clear temporal guidance. It also explains when to use scope='all' vs an array, and what to do when nothing is connected (send user to the dashboard link and retry), covering usage context and fallback behavior.

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