AdaptlyPost

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

Annotations already indicate readOnly=false and destructive=false, and the description adds a useful behavioral constraint: all posts share the same platforms and connection IDs. However, it does not disclose partial-failure behavior, validation limits, or what happens after scheduling is complete.

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 with no filler. The core purpose is front-loaded, and the second sentence adds a high-value structural clarification about shared versus per-post inputs.

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 17-parameter tool with many per-platform configs, the description is a solid overview but omits operational context like batch limits, partial failures, or whether scheduled posts can be edited later. The detailed schema and output schema fill many gaps, so this is adequate but not 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%, so the baseline is 3, but the description adds real value by grouping parameters into per-post fields versus shared fields. This helps an agent assemble the correct payload structure without needing to infer the relationship from the large schema alone.

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 — 'Schedule multiple posts at once' — and clearly distinguishes this from single-post tools like create_post. It also explains the per-post versus shared parameter model, which makes 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?

The phrase 'multiple posts at once' implies this is the right tool for bulk scheduling, but it never explicitly names alternatives or states when not to use it. An agent must infer that create_post is for single posts and publish_draft is for existing drafts.

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 signal this is a mutating operation (readOnlyHint=false, destructiveHint=false), and the description adds useful behavior: scheduling vs immediate publishing, draft behavior, and delegation to platform configs. It does not describe every side effect, but the annotations and output schema reduce the burden on the description.

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

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

Three sentences with no filler. The main action is front-loaded, and each sentence adds a distinct decision or category: connection targeting, scheduling/draft behavior, and platform-specific configs.

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 high-complexity, 24-parameter tool, the description supplies the essential workflow: how to target accounts, how to choose immediate vs scheduled vs draft, and where to find platform-specific settings. The schema covers detailed parameters and an output schema exists, so the description is reasonably complete for an agent selecting and invoking this tool.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already explains scheduledAt, saveAsDraft, contentType, and connection IDs. The description adds only high-level grouping ('use the corresponding platform configs') and references list_accounts, which is also in the schema, so it does not materially expand parameter 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 opens with a specific action and resource: 'Create and schedule a post to one or more platforms.' It immediately distinguishes this tool from siblings by covering scheduling, immediate posting, draft saving, and platform-specific options, while also referencing list_accounts for connection IDs.

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

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

The description gives clear operational guidance: pass connection IDs from list_accounts, omit scheduledAt for immediate posting, set saveAsDraft to avoid publishing, and use platform configs for platform-specific settings. It does not explicitly mention alternatives like bulk_schedule_posts or update_post, so exclusions are absent rather than explicitly 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?

Annotations already declare destructiveHint=true, so the destructive nature is known. The description adds value by specifying that only scheduled or draft posts are eligible and published posts are protected, which is behavior not captured in 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 two short sentences. It front-loads the core action and immediately states the key limitation, with no redundant or vague wording.

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

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

For a one-parameter destructive tool with output schema and clear annotations, the description is largely complete. It states what the tool does and a key edge case. It does not describe error behavior when attempting to delete a published post, but that is not essential for 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 input schema covers the only parameter, id, with description 'Post ID to delete,' so schema coverage is 100%. The tool description adds no additional parameter details, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: 'Delete a scheduled or draft post.' It also distinguishes the tool's scope by adding 'Can't delete published posts,' making it clear this tool is not a generic post deletion tool.

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

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

The description gives an explicit exclusion: it cannot delete published posts, which tells an agent when not to invoke it. However, it does not name alternative tools from the sibling list, so the when-to-use guidance is present but not fully explicit.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context by specifying that the result includes per-platform publishing status and error messages, giving the agent a better sense of what the response will contain.

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?

One focused sentence that front-loads the action and resource, then adds the key distinguishing detail about per-platform status and error messages. 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 simple single-ID lookup tool, the description is complete: it names the resource, the identifier, and the notable contents. An output schema exists, so return-value details do not need to be spelled out, and annotations cover the safety profile.

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%, and the only parameter 'id' is already described as 'Post ID' in the schema. The description's use of 'by ID' reinforces the parameter's role but adds no new format or semantic detail beyond the schema.

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

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

The description states a specific verb ('Get full details'), a specific resource ('a single post by ID'), and the useful scope of those details ('per-platform publishing status and error messages'). This clearly distinguishes it from list-style siblings like list_posts and list_post_results.

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

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

The mention of 'a single post by ID' implies this tool is for fetching one known post rather than listing or bulk operations. However, it does not explicitly name alternatives or state when not to use it, leaving the routing decision mostly to inference.

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

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

The description goes far beyond the minimal annotations by disclosing that this tool only mints a URL rather than uploading a file, that the caller must PUT the file separately, and that failing to do so causes create_post/bulk to reject the media. This is critical behavioral context the agent could not infer from readOnlyHint/destructiveHint alone.

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 purpose and includes essential workflow details. It is longer than necessary because the supported-types list duplicates the schema enum, but every other sentence contributes meaningful guidance.

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

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

Given the output schema exists, return values are covered structurally. The description supplies everything else needed: when to use it, how the returned URLs relate to create_post, the required manual upload step, the error consequence, and the preferred sibling alternative.

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 documents files, fileName, and mimeType with 100% coverage, so the baseline is 3. The description adds 'For each file, provide fileName and mimeType' and repeats the supported types, which mirrors the enum rather than adding substantial new semantics about the parameters themselves.

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: 'Get presigned upload URLs for direct file uploads.' It clearly differentiates this tool from the upload_media sibling by noting that upload_media performs the upload, making the scope of get_upload_urls unmistakable.

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 recommends 'Prefer the upload_media tool, which performs the upload for you,' giving a clear alternative. It also explains the sequential requirement: PUT to uploadUrl and confirm a 2xx response before using publicUrl, with a concrete failure mode ('Media file(s) not found in storage').

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

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

Annotations already mark the operation as read-only and non-destructive. The description adds useful behavioral context beyond annotations: it lists the exact platforms covered, states that connection IDs are returned, and flags that Facebook page accounts include a pageId because pages have no username. No contradictions with 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 concise and front-loaded: it states the core behavior in the first sentence and adds only the most relevant nuance about Facebook pages in the second. Every sentence adds value without 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?

Given there are no parameters and an output schema exists, the description is complete for an agent to select and invoke the tool. It explains the tool's purpose, who might need it, and an important output nuance that is not obvious from the schema.

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

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

The tool has no parameters, so the baseline is 4. The description adds meaningful context about what the returned identifiers are used for, even though there are no parameter definitions to clarify.

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

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

The description uses a specific verb ('List') and a clear resource ('all connected social media accounts'), enumerates the supported platforms, and states that it returns connection IDs needed for creating posts. This clearly distinguishes it from sibling tools focused on posts and scheduling.

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

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

The phrase 'Returns connection IDs needed for creating posts' clearly signals when to use this tool: before creating posts. It does not explicitly name alternative tools or provide exclusions, but the usage context is obvious given the listed siblings.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds that the operation inspects per-platform delivery status and error details. It does not mention rate limits, authorization requirements, or pagination, but for a read-only lookup backed by an output schema those omissions are minor.

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?

A single sentence that opens with the verb and object, then specifies the exact returned information. There is no redundant filler, making the description easy to scan.

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 one-parameter read-only tool with an output schema and safety annotations, the description is largely sufficient. It could be more complete by hinting that this is the tool to use after scheduling or publishing to verify delivery, but nothing essential to invoking it correctly is missing.

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

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

Schema coverage is 100% and the sole parameter 'id' is already described as 'Post ID to check results for'. The description does not add new parameter-level 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 uses a specific verb ('Check') with a clear resource ('per-platform posting results') and defines the scope ('success/failure status with error details for each platform a post was sent to'). This distinguishes the tool from siblings like get_post or create_post, which target the post itself rather than per-platform delivery outcomes.

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

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

The description implies this tool is used after a post has been sent to platforms to check delivery outcomes, but it does not explicitly say when to prefer it over get_post or whether get_post also surfaces similar results. No when/when-not guidance or named alternatives are 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 declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds behavioral context by noting optional filters and pagination support. It does not contradict the annotations, and mentioning pagination is a genuine behavioral trait beyond the structured annotation data.

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, compact sentence with the core capability front-loaded. Every phrase adds useful information—filters, pagination—and there is no redundancy or filler.

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

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

For a read-only listing tool with no required parameters and an output schema present, the description plus annotations and input schema provide a complete enough picture. Minor details like default ordering or pagination limits are already covered by the schema, so the description does not need to restate them.

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 seven parameters including limit, offset, statuses, platforms, dates, and sortOrder. The description's mention of 'status, platform, or date range' maps to those parameters but adds no new semantic meaning beyond what the schema provides.

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

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

The description states a specific verb ('List') and resource ('posts'), and names the optional filtering dimensions (status, platform, date range) plus pagination. This clearly distinguishes it from mutation siblings like create_post, update_post, and delete_post, and from get_post, which targets a single post.

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

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

The description conveys that the tool is for listing posts with filtering and pagination, so usage context is implied. However, it does not explicitly say when to prefer this over list_post_results or get_post, and it offers no exclusionary guidance or mention of 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?

Annotations already indicate this is not read-only, not destructive, and open-world, so the basic mutation profile is clear. The description adds the immediate-vs-scheduled distinction but does not disclose additional behavioral context such as external side effects, irreversibility of publishing, or validation rules around scheduledAt.

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?

One concise sentence with no filler. It front-loads the core action and includes the key behavioral distinction. Every word earns its place.

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

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

The output schema and annotations cover return values and the basic safety profile. Still, the description does not address scheduling edge cases such as requiring a future scheduledAt or how timezone is applied, and it does not mention when to prefer bulk_schedule_posts. For a mutating external-world tool, a bit more context would be expected.

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

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

Schema description coverage is 100%, so the parameters are already fully documented. The description adds no new parameter-level meaning beyond what the schema provides, making the baseline 3 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 states a specific verb ('publish'), a specific resource ('draft post'), and the two modes: immediate or scheduled. The word 'draft' differentiates it from siblings like create_post and update_post, making the operation unambiguous even without naming an 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 implies the tool should be used when you have an existing draft and want to publish it, whether now or later. However, it gives no explicit guidance on when to choose this over bulk_schedule_posts or how it relates to update_post and create_post.

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

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

Annotations already communicate that this is a mutating operation (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds the 'retry on failed platforms' semantic but does not disclose additional behavioral traits such as partial-failure handling, idempotency, or side effects. With annotations present, this is adequate but not rich.

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

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

Two tightly written sentences with no filler. The core action is front-loaded, and the parameter source hint is included without unnecessary detail.

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 two-parameter tool with full schema coverage, an output schema, and annotations, the description covers the essential workflow and parameter sourcing. It is slightly light on operation outcomes, but the output schema and annotations compensate, making it 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 description coverage is 100%, so the baseline is 3. The description adds extra value by telling the agent that platformIds should come from list_post_results, which is important provenance information beyond the schema's generic 'Failed platform IDs to retry.'

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, 'Retry publishing on platforms that failed,' targeting a clear resource. It differentiates itself from siblings like publish_draft and create_post by emphasizing failed platforms, so an agent can identify when this tool applies.

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

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

The description gives clear context: use this tool for platforms that previously failed, and it even tells the agent where to get the required platform IDs ('Get platform IDs from list_post_results'). It does not explicitly list alternatives or when-not-to-use conditions, but the workflow context is strong enough for correct selection.

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 one useful behavioral constraint beyond annotations: published posts cannot be updated. However, it does not disclose whether this is a partial update where omitted fields remain unchanged, or whether all provided fields replace existing values. For an update tool with 24 optional parameters, that semantic is important for correct invocation. The annotations already indicate this is not read-only and not destructive.

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 short, information-dense sentences. It front-loads the main purpose and immediately states the most important limitation. There is no filler or repetition of schema content.

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

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

Given the tool's complexity—24 parameters across many platform-specific configs—the description is minimal but sufficient for basic selection. It identifies the resource, the allowed updates, and the critical published-post restriction. However, it lacks guidance on update semantics (partial vs full replacement) and on how the various connectionIds and configs interact, which leaves some ambiguity for an agent handling complex multi-platform updates.

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 92%, so the schema already explains the parameters well. The description adds broad categories like 'caption, schedule, accounts, media, or platform configs,' which help orient the agent, but it does not provide parameter-level details beyond what the schema already contains. This is an acceptable baseline given the high 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 action ('Update') and the exact resource ('a scheduled or draft post') with the specific fields that can be changed: caption, schedule, accounts, media, or platform configs. It further distinguishes itself by explicitly excluding published posts, which sets it apart from publish_draft and create_post. This gives an agent a precise understanding of what the tool is for.

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 a clear context for when to use the tool: when a scheduled or draft post needs modification. It also provides a key exclusion: cannot update published posts. However, it does not explicitly point to alternative sibling tools like publish_draft or create_post, so the routing guidance is slightly incomplete.

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, destructiveHint=false), the description reveals meaningful behavior: the server downloads and re-uploads URLs, files are accepted as base64, and the returned URLs are for internal use only. These details help the agent predict side effects and downstream usage. No contradiction with annotations is present.

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-organized. The opening sentence states the purpose, the two modes are numbered clearly, and the crucial downstream instruction about passing mediaUrls to create_post is front-loaded. Every sentence contributes necessary 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?

The description covers both parameter modes and the return flow, which is sufficient for basic invocation. However, given the sibling get_upload_urls, it omits explicit disambiguation about when to choose server-side upload_media versus generating upload URLs. It also does not mention constraints like file size limits or whether both urls and files can be provided together. These gaps make it adequate but not fully complete for an AI agent navigating the toolset.

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 100% of parameter descriptions, but the tool description adds value by explaining the behavioral distinction between the two modes: 'server downloads and re-uploads them' for URLs, and 'when the user attaches an image in the conversation' for files. This enriches the schema's otherwise structural definitions.

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 precise verb-resource statement: 'Upload media files for use in posts.' It then enumerates two concrete modes (URLs and base64 files), making the tool's purpose and scope explicit. The reference to returning mediaUrls for create_post further distinguishes it from sibling tools like get_upload_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?

The description gives clear situational guidance for each mode: URLs for public media, base64 files for user-attached content. It also states the output should be passed to create_post and that the user should not see the returned URLs. However, it does not explicitly contrast with the sibling get_upload_urls or state when NOT to use this tool, leaving some ambiguity in tool selection.

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