Multi Upload Tool

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

Annotations declare readOnlyHint, so the trailing 'Read-only' is redundant, but the description adds real behavioral context the annotations cannot: the three-state lifecycle, that 'ready' yields mediaUrls, and that 'expired' requires a fresh link. No auth or rate-limit notes, but the state machine is the important disclosure here.

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 dense sentence that front-loads the resource, then the state semantics. Every clause carries usable information with no filler.

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

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

For a one-parameter read-only status check with no output schema, the description supplies exactly what an agent needs: what states are possible, what each implies, and the next action for each. Nothing material is missing.

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

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

Schema description coverage is 100% and the single dropId parameter is fully documented in the schema, including its origin in create_media_upload. The description adds no format or constraint detail beyond that, 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?

States a specific verb+resource: checking the status of an upload link created by create_media_upload, and enumerates the three possible states. Clearly distinguishable from siblings like get_post_status or validate_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?

Gives actionable per-state guidance: 'ready' means pass mediaUrls to create_post, 'expired' means create a new link, 'waiting' means the user hasn't finished. It lacks an explicit when-not-to-use or a named alternative tool, but the workflow routing is 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered and repeating 'Read-only' adds little. What does add value is the disclosure of return content — a post's caption, status, schedule/publication time and platform URL, or an account's details — which is the main thing an agent needs since no output schema exists.

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 front-loads the core purpose and then qualifies the id format and return payload. Nothing is wasted and nothing important is buried.

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

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

With one required parameter, no output schema, and accurate annotations, the description supplies everything needed to call the tool: what it reads, the id format, and what comes back. It omits error behavior for ids that no longer resolve, which is a minor gap rather than a blocking one.

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 goes beyond it by specifying the id's required format ('post:<id>' or 'account:<id>'), a constraint the schema only calls 'An id returned by search.' That format detail is genuinely decision-relevant.

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?

Specific verb ('Read one search result in full') plus the resource and the exact id format it accepts ('post:<id>' or 'account:<id>'). It also names the sibling that produces the input ('by the id search returned'), so an agent can tell it apart from list_recent_posts, get_post_status, and list_accounts without opening a schema.

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

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

Clearly establishes the usage context: this is the follow-up call for an id obtained from search, and it enumerates the two id shapes it accepts. It stops short of explicitly ruling out overlapped siblings such as get_post_status for status-only lookups, so it lacks the when-not clause that would earn a 5.

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

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

Annotations only cover readOnlyHint/openWorldHint, but the description adds substantial behavior: nightly-sync lag, lastRefreshedAt as the measurement timestamp, and the null-vs-0 distinction ('null = not measured, never 0' / 'a platform does not report comes back as 0'). It also flags the timezone-offset pitfall that silently corrupts bestTimes. This is real behavioral disclosure beyond the structured fields.

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

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

Front-loaded with return contents, then invocation modes, then freshness caveats. Every sentence carries information, but it is a dense single block; the caveats about sync lag and null-vs-0 could be tightened.

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 carries the full burden of explaining return shape and it does so: summary semantics, followerHistory granularity, lastRefreshedAt, bestTimes shape and purpose. An agent has everything needed to call and interpret 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 100%, so the 3 baseline applies, but the description adds meaning the schema lacks: the no-argument/accountId/postId selection logic, that source only affects topPosts ranking while 'Totals and summary always cover every post', and the warning to always pass the user's zone. Marginal but genuine value on top of an already-complete schema.

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

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

States a specific verb+resource immediately ('Read published-post performance: views, likes, comments, shares, plus growth over the last 30 days') and enumerates the exact artifacts returned (summary, followerHistory, bestTimes). An agent can distinguish it from siblings like get_post_status or list_recent_posts without opening the schema.

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

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

Explicitly maps invocation modes to intent: 'Call with no argument for every account at once, with accountId for one account, or with postId for a single post', and names create_post as the downstream consumer of bestTimes. It does not state when NOT to use it versus siblings such as get_post_status, so the exclusion side is missing.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description's 'Read-only' is consistent with rather than contradicting them. It adds real behavioral value beyond the annotations by disclosing the state machine and what payload accompanies each terminal state. Polling cadence, whether jobs expire, or how long a url remains valid are not covered.

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 tight sentence that front-loads the resource and then enumerates states in a scannable slash-delimited list. Zero filler; every clause carries information an agent needs.

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

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

No output schema exists, and the description compensates well by spelling out the return shape per status (url on completed, error on failed). What remains thin is operational context such as whether the caller should poll and how often, which matters for a status-check 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% and the single jobId parameter is documented in the schema as coming from add_captions, so the description need not repeat it. It adds no format, lifetime, or validity semantics for jobId. 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?

Specific verb+resource ('State of an add_captions render') with the full status vocabulary enumerated, including what each terminal state carries (url on completed, error on failed). An agent can distinguish this from get_post_status or check_media_upload purely from the description.

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?

Implicitly situates the call after add_captions via 'an add_captions render' and jobId linkage, and gives an explicit next step for the completed case (url 'ready for create_post'). It stops short of naming when not to use it or what to do instead for non-caption jobs.

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

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

The annotations already declare a safe read (readOnlyHint=true, openWorldHint=false), yet the description still adds real behavior: the vsAccountAverage > 1 interpretation, the 6-month / 2-post thresholds for 'best performing', and the Instagram-specific rejection list. It omits anything about data freshness beyond that window or how per-platform guidance is shaped.

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 return contents and the exclusion of hashtag generation are answered directly in two sentences, with nothing wasted. The first sentence is long and nested with parenthetical definitions, but front-loads the critical information.

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

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

With no output schema and only 2 parameters — one of which is undocumented in the schema — the description does the heavy lifting by naming both result sets, defining their scoring metric, and flagging platform-specific extras. An agent has enough to call it correctly and interpret the response.

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 documents 'limit' (default 20, max 30) but leaves 'platform' as a bare enum; the description compensates by explaining that platform governs the scope of results and that output differs per platform (e.g. the Instagram rejection list). It adds genuine meaning on top of the schema rather than restating it.

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 ('Return') with a precisely scoped resource ('hashtags this user has used most often ... on the given platform') and names two distinct result sets (yourTopHashtags, bestPerformingHashtags). It also explicitly separates itself from hashtag generation, so an agent can distinguish it from siblings like validate_post or get_analytics without opening a schema.

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

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

The closing sentence gives a clear when-not condition ('Does NOT generate new hashtags — use your own creative ability for that') and explains the unique value ('historical preferences which you cannot see otherwise'). It stops short of naming a specific sibling tool as the alternative for generating or validating hashtags, which keeps it from a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds that this is a prerequisite lookup feeding create_post, but says nothing about caching, freshness, or that results are static reference data per platform.

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, both earning their place: the first enumerates the payload, the second gives the sequencing instruction. Front-loaded and waste-free.

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 enumerates what is returned (limits, daily cap, media types, platformSettings schema), which is what an agent needs to know to build a create_post call. Missing only notes on freshness or whether results can be cached.

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 0%, but the single parameter is a self-documenting enum of nine platform names. The description only implies the parameter via 'for a given platform' and adds no format or value guidance beyond the schema's enum list.

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?

Specific verb ('Return') plus a concrete enumeration of the resource contents: character limits, daily post cap, supported media types, and the platformSettings schema. This clearly separates it from validate_post and get_post_status, though it overlaps somewhat with the sibling get_upload_limits, which is not addressed.

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 states the sequencing context: 'Call this before create_post to ensure inputs are valid.' That gives the agent a clear trigger condition. It does not, however, mention when NOT to use it or name the near-neighbor siblings (get_upload_limits, validate_post).

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered; the description goes beyond that by disclosing the observable state machine (pending | processing | completed | scheduled | failed) and the failure payload shape (code, retryable, nextAction). It stops short of saying whether completed is terminal or how long results are retained.

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 tightly packed sentence plus a parenthetical for the failure branch, with the purpose front-loaded before the return detail. No filler or restated boilerplate.

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

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

No output schema exists, so the description must carry the return contract, and it does: status enum, caption, videoUrl on publish, and the failure object. An agent has everything needed to call and interpret 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?

Only one parameter and schema description coverage is 100%, with the schema already explaining that postId comes from create_post or list_recent_posts. The description adds nothing beyond that, 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?

States a specific verb and resource (get the status of one post) and enumerates exactly what the response contains. It is clearly distinguishable from siblings like list_recent_posts, get_analytics, or validate_post without opening any schema.

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

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

Usage is implied (poll a post's status after creating it) and it routes failure handling to retry_post via '(see retry_post)', but there is no explicit when-to-use vs. list_recent_posts or guidance on polling cadence/terminal states. Adequate but leaves the alternative-selection logic 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?

Beyond the readOnlyHint/openWorldHint annotations, the description adds real behavioral context: the daily cap semantics, the reset timing, and the credit economics (balance, 1 credit per post, 15 with a link, plus packs) with the failure mode spelled out. This is information an agent cannot get from the annotations or 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?

Front-loaded with the primary answer, then layers in the X-credit detail and the usage cue. Every sentence earns its place except the trailing 'Read-only.', which merely restates the annotation.

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

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

There is no output schema, so the description carries the return-value burden and does: it names remaining count, reset time, and the xCredits fields. Nothing an agent needs to call or interpret this tool 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?

Single parameter with 100% schema description coverage, and the schema already points to list_accounts as the source of the id. The description adds no format or constraint detail beyond the schema, 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?

States a specific resource and what it returns: remaining posts available today, the reset time, and X-specific xCredits details. This clearly distinguishes it from siblings such as get_platform_capabilities (static capability info) and validate_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?

Explicitly says to check it before a batch of create_post calls and explains the consequence of not doing so (an X post fails without enough credits). No alternative tool is named and there is no explicit when-not-to-call, which keeps it below a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: the returned field set (compensating for the absent output schema), the workspace-vs-user account scope, and the 'active' status requirement for publishing. It does not mention pagination or result-size limits, which keeps it short of a 5.

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

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

Four sentences, front-loaded with purpose, then returns, then call-order, then filtering guidance. No sentence is redundant and none restates the schema.

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 compensates by listing the returned fields and the field that gates publishing. Optional filters, scope, and call sequencing are all covered; pagination is the only unaddressed item and the narrowing guidance implies it is not 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by framing all three filters as a single narrowing strategy for large workspaces ('Workspaces can hold many accounts'), which tells the agent when to combine them rather than how each is typed.

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 ('List the social media accounts') plus the exact scope ('connected to the authenticated user or current team workspace'), and enumerates the returned fields. An agent can distinguish this from sibling tools like list_pools or search without opening a schema.

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

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

Gives explicit call-order guidance ('Call this first to discover which accountIds can be used in create_post'), a when-not-to-read-everything rule ('narrow with platform, tag or search instead of reading the whole list'), and a prerequisite rule ('Only accounts with status active can publish').

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the 'Read-only' sentence is partly redundant. However, the description adds real behavioral context beyond the annotations: the weekly-slot scheduling model and the plan prerequisite. Return shape is only partially implied ('with how many items are queued').

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 tight sentences with the core definition front-loaded and no filler. The trailing 'Read-only.' restates annotation data rather than adding information, which is the only minor waste.

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 zero-parameter list tool with no output schema, the description covers the resource being listed, what it contains, and the access prerequisite. It stops short of describing pagination or full return structure, but nothing critical for correct invocation is missing.

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

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

The tool takes zero parameters, so the baseline of 4 applies. There is nothing for the description to disambiguate and it correctly avoids inventing parameter behavior.

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

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

States a specific verb ('List') and resource ('upload pools'), then defines the domain term inline as 'queues of videos drip-fed to accounts on recurring weekly slots (time, days, accounts)'. This distinguishes it cleanly from siblings like list_accounts or list_recent_posts.

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

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

Gives an explicit gating condition: 'Requires a plan with upload pools', which tells the agent when this tool is applicable. It does not name alternatives (e.g. get_upload_limits) or state when-not to use it, so 4 rather than 5.

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

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

Goes well beyond the readOnlyHint/openWorldHint annotations: it discloses that captions are truncated at 200 characters, explains the hasMore pagination flag, and prescribes the correct narrowing strategy instead of raising limit. This is exactly the operational context annotations cannot carry.

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

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

Three tightly packed sentences, front-loaded with purpose then behavioral caveats. Every sentence earns its place: the truncation warning and hasMore explanation both change how an agent calls the tool.

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 supplies the return-shape essentials an agent needs: the status categories covered, the 200-character caption cap, and the hasMore pagination signal. Nothing material is missing for correct 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?

Schema coverage is 75% (limit, platform and accountId documented; status is enum-only with no description). The description adds practical meaning by naming accountId, platform and status as the preferred narrowing filters and by implying limit is a page size rather than a way to reach older posts.

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

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

States a specific verb (list) and resource (recent posts) with a clear scope: posts published, scheduled, or failed by the authenticated user. It also implicitly separates itself from get_post_status, which it names as the tool for full caption text.

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 concrete reasons to use it (avoid duplicates, reference past content, audit failures) and routes the agent to get_post_status when full text is needed. It also advises narrowing with accountId/platform/status instead of raising limit, but offers no explicit when-not-to-use condition.

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?

Read-only is stated, though it duplicates readOnlyHint=true, so little credit there. The real added value is the disclosed return shape '{ results: [{ id, title, url }] }' and the id-to-fetch workflow, which the agent cannot get from annotations and which matters because there is no output 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?

Three tight clauses: what is searched, what comes back and how to drill down, and the safety profile. Nothing is padded and the search scope is front-loaded.

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

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

For a single-parameter read tool with no output schema, the description covers scope, return shape, and the follow-up call, which is close to everything an agent needs. A note on result limits or ordering would make it fully 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% and there is only one parameter, whose description already gives examples ('a product name or a hashtag'), so the baseline of 3 applies. The description adds only that matching is keyword-based against caption and title, which is marginal 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 gives a clear verb (search) plus the searched surface (post caption and title, connected accounts) and the matching mode (by keyword), which is far more specific than the bare tool name 'search'. It does not explicitly contrast itself with siblings like list_recent_posts or get_hashtag_history, so it stops short of a 5.

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 routes the agent forward explicitly: 'pass an id to fetch for the full record', naming the sibling fetch and the condition that selects it. It gives no guidance on when to prefer this over list_recent_posts or the hashtag tools, so it is clear context without full alternatives coverage.

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

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

Goes well beyond readOnlyHint=true by enumerating the checks performed and, critically, the limit of the validation ('mediaUrls are not downloaded: file format, size and duration are only checked when the post is actually published'). That caveat is exactly the kind of non-obvious behavior an agent cannot infer from structured fields.

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 blocks — what it does, when to call it, what it returns — front-loaded with the dry-run framing and no filler. Every sentence carries distinct information.

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

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

There is no output schema, yet the description supplies the return shape ({ valid, errors, targets }) and even explains the accountId-null edge case. Combined with the check list and caveats, nothing needed to call 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 description coverage is already 100%, so the baseline is 3. The description still adds meaning by flagging that required platformSettings are validated and that mediaUrls are accepted but not verified, which steers parameter usage more than the schema alone does.

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

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

States a specific verb+resource ('Dry run of create_post') and immediately scopes it by listing the exact checks it performs, so an agent knows precisely what it does. It is explicitly differentiated from the sibling write operation it mirrors.

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 ('Call it before create_post on any batch, or whenever unsure') plus the consequence of skipping it ('a post rejected here would otherwise fail later, sometimes hours later for scheduled posts'), which names the alternative and the selection condition.

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