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

Annotations only declare readOnly=false and destructive=false. The description discloses independent item processing, partial failure isolation, immediate publishing for past scheduledAt, and the exact result structure with instruction to read every row. These are valuable behavioral details beyond 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 dense; it front-loads the core capability and then covers behavior, prerequisites, and alternatives. While it could be organized into bullets for easier scanning, every sentence contributes needed information 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?

Given the tool's complexity (17 parameters, multiple platforms, output schema), the description covers prerequisites, platform-specific requirements, partial failure behavior, return format, and how to interpret results. It leaves nothing critical for correct invocation unexplained.

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%, but the description adds meaning by distinguishing shared vs per-item parameters and highlighting required platform configs (tiktokConfigs, pinterestConfigs). It clarifies that each post item supplies its own text/contentType/scheduledAt/media while platforms and connection arrays are common.

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: 'Schedule up to 100 posts in one call to the same platforms and accounts.' It explicitly distinguishes from create_post by noting the bulk capability and the absence of a draft mode, making the tool's 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 says to use create_post for a single post or draft, names list_accounts as a prerequisite, and gives platform-specific requirements (TikTok needs tiktokConfigs with privacyLevel, Pinterest needs pinterestConfigs with boardId). This clearly tells the agent when to choose this tool and what to prepare first.

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 publishing is asynchronous per platform, that the response is not the final outcome, and that callers should read list_post_results to see per-platform success or failure. It also reveals draft validation deferral and the mediaUrls dependency, going well beyond the sparse 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 dense and front-loaded with the core purpose and key behavioral caveats. The amount of detail is justified by the number of platform-specific parameters, though it is presented as a single paragraph rather than structured sections.

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 essential workflow dependencies, async outcome checking, platform-specific requirements, and sibling tool distinctions. It does not enumerate every output field or failure mode, but it gives enough context for an agent to call the tool and verify results correctly.

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

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

Although the schema already has 100% property description coverage, the tool description adds important cross-parameter meaning: scheduledAt is absolute and omission/past means immediate, timezone only affects display, each platform requires its matching connection-id array, TikTok configs need privacyLevel, and Pinterest needs a board id with no API to list boards.

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 creates one post for one or more platforms and immediately distinguishes publish-now, schedule, and draft modes. It also names sibling tools like bulk_schedule_posts, update_post, and publish_draft, so an agent can tell this tool apart.

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 to use bulk_schedule_posts for many posts on the same accounts and update_post or publish_draft for existing posts. It also instructs callers to call list_accounts first and to source mediaUrls from upload_media or get_upload_urls, giving clear when-to-use 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 reveals that deletion only removes the record, not the actual platform content for already-published posts. It also discloses irreversibility, workspace access restriction, and the exact error message for unauthorized or missing posts.

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 yet comprehensive, organized logically from action to usage guidance to caveats to error handling. It packs necessary details without redundancy, making it easy to scan and understand.

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 destructive operation, the description covers all relevant context: what it does, when to use it, side effects on different post statuses, workspace restrictions, expected return value, and irreversibility. No important 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?

The only parameter (id) is fully described in the input schema ('Post ID to delete, from list_posts or create_post'), so coverage is 100%. The tool description does not add additional parameter semantics beyond what the schema already provides, keeping the score at the baseline for full 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 states a clear, specific action ('Delete a post record from AdaptlyPost by id') and distinguishes it from siblings by noting when to use update_post instead. It also clarifies the tool's scope (only DRAFT or SCHEDULED posts cancel publishing).

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

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

Explicitly tells when to use this tool ('Use it to cancel a DRAFT or SCHEDULED post before it goes out') and when to prefer an alternative ('Prefer update_post to change a post instead of deleting and recreating it'). Also explains behavior for COMPLETED or PARTIAL_FAILURE posts, giving complete usage 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 indicate readOnlyHint=true, destructiveHint=false, openWorldHint=false. The description adds valuable context about workspace scope ('visible only within the token's workspace') and error behavior ('any other id returns "Post not found or access denied"'), enhancing transparency without contradicting 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 concise but informative, using three sentences to convey the tool's purpose, returned content, and usage guidance. It avoids redundancy while providing necessary distinctions from sibling tools.

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 tool's primary function, output contents, error/access behavior, and relationship to other tools. Given the simple parameter and the provision of an output schema (not shown but indicated), it provides sufficient context for an agent to use 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?

The single parameter 'id' is fully described in the schema (coverage 100%) and the description reinforces its origin ('Post ID from create_post, bulk_schedule_posts, or list_posts'). This adds practical context beyond the schema's basic type definition.

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 retrieves a single post's full record by ID and enumerates the included fields (text, contentType, status, scheduledAt, timezone, platforms with connection/status/errorMessage/media). It distinguishes itself from related tools 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?

Explicitly instructs when to use this tool ('inspect content before update_post or publish_draft') and when to use alternatives (list_post_results for per-platform outcomes, list_posts for finding IDs). This provides clear selection 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 only provide readOnlyHint=false and destructiveHint=false, so the description carries the full burden of behavioral disclosure. It clearly reveals that the tool 'only mints a URL' and does not actually upload the file, and it warns about the rejection error if the subsequent PUT is not completed. This is critical behavioral context beyond the structured 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 dense but efficient: each sentence carries essential information. It front-loads the purpose, then immediately clarifies return values, the critical usage sequence, the preferred alternative, and required parameters. No fluff or redundancy; every sentence 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?

Given the tool's moderate complexity and the presence of an output schema, the description covers all essential operational context: what is returned, how to use the returned URLs, the failure mode, a preferred alternative, and the required input fields. Nothing an agent needs to invoke this correctly is missing.

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

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

The input schema already provides 100% coverage, with descriptions for files, fileName, and mimeType, plus an enum for mimeType. The description repeats 'provide fileName and mimeType' and lists supported types, but adds little new semantic meaning beyond reinforcing the schema. Baseline 3 is appropriate because the schema handles 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?

The description clearly states the tool's function: 'Get presigned upload URLs for direct file uploads.' The verb-resource pairing is specific and distinct. It differentiates itself from sibling tools by naming upload_media as the alternative that performs the upload, and by explaining its role in the create_post workflow.

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

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

The description provides explicit when-to-use guidance: 'Prefer the upload_media tool, which performs the upload for you.' It also details the required sequence (PUT to uploadUrl, confirm 2xx before using publicUrl) and states the consequence of non-compliance (create_post/bulk rejects). This leaves no ambiguity about when and how to use the tool.

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 clearly states it takes no arguments and returns a read-only list of accounts, aligning with the readOnlyHint annotation. It doesn't mention potential throttling or data pagination, but no destructive or side-effect behavior is hidden; annotation and description are consistent.

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 and well-structured: it states the result, the key usage imperative, the alternative for other use cases, and the no-arguments fact. Every sentence adds necessary guidance 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?

Given the empty schema and no parameters, the description covers everything an agent needs: what it returns, when to call it, how to use the IDs, and which sibling tools handle related but different tasks. The output schema likely provides the return structure, so no further detail is needed here.

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

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

The tool has zero parameters and the schema already reflects that with an empty properties object. The description reinforces 'Takes no arguments,' so there is no missing parameter guidance; a small deduction because no mention of output schema details, but that's not parameter semantics.

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?

Clearly states the tool lists social accounts connected to the workspace across all nine platforms, and enumerates the returned fields. It also contrasts with related tools for posting and analytics, making its purpose 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?

Explicitly instructs to call this before create_post, update_post, or bulk_schedule_posts to obtain IDs, and tells which ID arrays to use for each platform. It also directs users to list_posts or list_post_results for post history/publishing status, leaving no ambiguity about when to use this tool.

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 it read-only; description adds the critical behavior that each platform reports separately and that publishing is asynchronous, so responses only confirm queueing and you must poll until no PENDING/PUBLISHING. This goes beyond annotations.

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

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

Four sentences, each earning its place: purpose, return shape, usage guidance, and alternative. Well structured but could be slightly more concise with bullets; still 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 an output schema exists, description covers the return shape and the polling logic, plus how to use FAILED rows for retry_failed_platforms. Complete for an agent to call 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 covers 100% of the single parameter (id) with sources (create_post, publish_draft, etc.). Description doesn't add extra semantics beyond the schema, so baseline 3 applies.

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

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

States a specific verb (Get) and resource (one post's per-platform publishing outcomes), and distinguishes from get_post (which gets content and schedule) and list_posts. It clearly defines what it returns: { postId, status, 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?

Explicitly says when to call it (after create_post, publish_draft, or retry_failed_platforms), explains the asynchronous nature and polling requirement, and names get_post as the alternative when content and schedule are also needed.

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 and non-destructive behavior. The description adds useful context about return shape and pagination semantics but does not contradict annotations or introduce unexpected 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?

The description is a single paragraph with two sentences, but it repeats some schema details (e.g., date bounds, pagination). It is not overly verbose but could be slightly more concise by omitting redundant parameter explanations.

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 fully specifies what is returned (posts array with status and platforms, total, hasMore) and how to paginate. It also mentions appropriate use cases and sibling tools, making it complete for an agent to decide when and how to call it.

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

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

Schema descriptions cover 100% of parameters with clear explanations of filters and pagination. The description reinforces date and status semantics but does not add significant new meaning beyond the schema; still, it helps clarify usage.

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 posts in the workspace with filtering and pagination, and explicitly distinguishes it from get_post and list_post_results. The verb 'list' and resource 'posts' are specific.

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 provides explicit guidance: 'Use this to find post ids or check what is already queued.' It also mentions alternatives for single-post details and per-platform outcomes, and explains filtering/pagination usage.

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?

Clearly discloses side effects: moves to PENDING, queues per-platform publishing, content reaches networks and cannot be recalled, and explains failure conditions (disconnected account, missing TikTok privacyLevel). This matches the readOnlyHint=false annotation and adds important behavioral context beyond the schema.

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

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

The description is dense but every sentence carries necessary information: accepted statuses, scheduling behavior, failure modes, and cross-references to sibling tools. No redundant filler or vague phrasing.

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 output schema exists and the tool has moderate complexity, the description fully covers preconditions, post-conditions, failure modes, and follow-up actions. It leaves no critical ambiguity about what the tool does or when to use it.

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

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

The schema already covers all three parameters with descriptions, and the tool description adds crucial semantics: timezone does not shift scheduledAt, and omitting scheduledAt or passing a past time publishes immediately. This goes beyond simple field listings.

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

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

States a specific verb and resource ('Publish a DRAFT post'), clarifies that SCHEDULED posts are also accepted, and explicitly distinguishes from create_post for new content. This makes the tool's purpose unmistakable and differentiates it from 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?

Gives explicit when-to-use guidance: publish now or schedule, accepts DRAFT/SCHEDULED, fails on other statuses, and directs users to update_post for fixes and create_post for new content. Also recommends checking list_post_results afterwards, which is actionable.

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 (readOnlyHint=false, openWorldHint=true, destructiveHint=false), the description reveals key behaviors: only FAILED rows are reset, other ids are ignored, failure condition if none match, post moves to PUBLISHING, retry is asynchronous, and content cannot change. These are critical behavioral details that annotations do not capture.

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 information-dense. It front-loads the core action, then adds conditions, async behavior, prerequisites, and retry criteria in a logical flow. No redundant sentences; 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?

Given the tool's complexity, the description covers all essential aspects: operation, conditions, error case, async behavior, dependency on list_post_results, retry criteria, and immutability of content. The output schema exists, so return value details are not required. The description is fully sufficient for an agent to use 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?

The schema already fully documents both parameters (id and platformIds) with clear descriptions, including the requirement that platformIds come from FAILED rows of list_post_results. The description reinforces this and adds context about the retry logic and source, but does not introduce new parameter meanings beyond what the schema provides. Since schema coverage is 100%, the baseline is 3; the description adds a small extra value by tying the parameters to the retry workflow.

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 on a specific resource: 'Re-queue publishing for a post's FAILED platforms.' It clearly distinguishes the tool's scope (only FAILED platforms) and mentions the sibling list_post_results for gathering prerequisites, making its purpose unambiguous.

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

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

The description provides explicit when-to-use guidance: get platformIds and errorMessage from list_post_results first, retry only after fixing the cause (reconnected account, replaced media), and explicitly warns not to retry platform-side restrictions that will just fail again. It also notes the async nature and where to check outcome, giving clear context for appropriate use.

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 thoroughly explains behavioral nuances: partial updates for most fields, full replacement of targets when platforms is sent, media verification for SCHEDULED posts, and the return value. It also notes that certain parameters (mediaUrls) have dependencies, which goes beyond the annotations.

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

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

The description is dense but well-organized, front-loading the core behavior and then covering exceptions and dependencies. It avoids unnecessary words while conveying essential information. Slightly long but appropriate for the complexity.

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 main behavior, failure conditions, alternative tools, and dependencies on other tools (upload_media, list_accounts), and states the return value. Given the presence of an output schema, it does not need to detail the response structure, making it complete for effective usage.

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 provides descriptions for all parameters, so the baseline is 3. However, the description adds value by clarifying conditional relationships (e.g., mediaUrls only with platforms) and specifying source of values (publicUrl from upload_media). This enriches understanding 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 action ('Update a DRAFT or SCHEDULED post in place') and the resource (post). It also differentiates from sibling tools by naming publish_draft, delete_post, and create_post as alternatives for different 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?

Provides explicit when-to-use conditions: only DRAFT or SCHEDULED posts are allowed, with failure otherwise. It also gives guidance on when to use alternatives (publish_draft for status change, delete_post for cancel, create_post for new). Additional constraints like 'mediaUrls only take effect together with platforms' are clearly stated.

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 files are stored publicly and immediately, that URLs are downloaded and re-hosted, and that base64 files are uploaded. It goes beyond the minimal annotations by explaining the server-side behavior and output shape, though it does not mention rate limits or authentication.

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

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

The description is dense and informative, but it is a single long paragraph with some repetition (e.g., 'post or no post'). It could be slightly more structured, but the key information is front-loaded and no unnecessary filler is present.

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 two parameters and nested file object, the description is complete: it covers both input modes, supported MIME types, the required fields for files, the error case, and the return format. It ties the output directly to the expected mediaUrls field used by sibling post-creation tools.

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 description adds important behavioral context: urls are downloaded and re-hosted, files are for attached media, the two sources can be combined, and omitting both is an error. This goes well beyond the raw property names and enum values.

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 uploads images or videos to storage and returns public URLs for use in post creation tools. It explicitly differentiates itself from get_upload_urls by explaining the server re-hosts content rather than just minting URLs.

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 names the exact downstream tools (create_post, update_post, bulk_schedule_posts) and explains when to use each parameter source. It also provides an explicit alternative (get_upload_urls) and states the error condition when both sources are omitted.

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