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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds genuine context beyond that: activation causes future public posts to be scheduled (external, world-visible side effect) and a specific failure mode with the EVERGREEN_CONTENT_REVIEW_REQUIRED code. It does not explain what is mutated or why the operation is flagged 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?

Three short sentences with no filler, ordered effect-first and precondition-second. Every sentence carries information an agent needs: what it does, what it causes, and what blocks it.

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 mutation with no output schema, the description covers purpose, side effect, prerequisite, and error behavior, which is close to sufficient. The remaining gap is the undisambiguated relationship with resume_evergreen_queue and the undocumented queueId source.

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?

There is one required parameter with 0% schema description coverage — queueId is typed only as an untyped string with no documentation of format or where to obtain it. The description mentions contentConfirmed on sibling tools but says nothing about queueId, so it fails to compensate for the schema gap. The only available meaning is inferred from the tool name.

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 specific verb+resource ('Activate a ... queue') and explains the effect ('schedules future public posts'). It does not distinguish this from the sibling 'resume_evergreen_queue', which an agent could reasonably confuse with 'activating a paused queue' — the qualifier 'draft or paused' partially helps but leaves the activate-vs-resume boundary ambiguous.

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 states a concrete precondition for use — caption variants must be contentConfirmed via create_evergreen_queue or update_evergreen_queue — which is exactly the kind of gating information an agent needs before calling. It stops short of naming resume_evergreen_queue as the alternative for already-active queues, and gives no explicit when-not guidance.

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

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

Annotations already declare destructive=true, idempotent=false, and openWorld=true. The description adds useful behavior: per-post failures are reported individually, and it clarifies conditional parameter requirements for each action. It does not contradict 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 three compact sentences with no filler. The bulk scope, action requirements, failure behavior, and removal alternative are all 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 bulk mutation tool with no output schema, it covers the key operational details: max batch size, conditional parameters, and per-post failure reporting. It could say more about the response shape or required permissions, but annotations already 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?

With 50% schema coverage, the description compensates by explaining action values and conditional requirements: reschedule needs scheduledAt, status accepts draft or scheduled. It does not describe the ids array format beyond schema limits, but covers the key conditional 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?

The description states a specific bulk operation on posts, names the two supported actions (reschedule, status), and clarifies the 25-post limit. It distinguishes itself from per-post tools by saying 'up to 25 posts' and from delete_post for removal.

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

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

It gives clear context for bulk rescheduling/statusing and explicitly states the alternative for removal: 'use delete_post on each draft.' It does not explicitly compare against update_post or create_posts, but the bulk scope is implied clearly.

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 mark this as a non-read-only, non-idempotent, non-destructive write; the description adds the key behavioral fact that the result is an inert draft with nothing scheduled or activated. That is meaningful value beyond the annotations. It does not address what happens on a duplicate retry given idempotentHint=false, nor that captions must be confirmed via contentConfirmed for later activation.

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, zero filler, and the draft-versus-activate distinction is front-loaded in sentence two where an agent will read it before invoking. Nothing repeats the title or 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?

The description nails the lifecycle position of the tool, which is the single hardest thing to infer among ~33 siblings. For a 13-parameter creation tool with no output schema, though, it omits what the returned draft looks like, what makes a post eligible, and how defaults for interval/schedule govern future runs.

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?

With 13 parameters and only 23% schema description coverage, the description carries a large compensation burden and offers no parameter meaning at all — nothing about variants, channels, intervalDays, scheduleMode, or reviewPolicy. The most consequential params (productId, contentConfirmed) are documented only inside the schema, so the description adds nothing on this dimension.

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?

"Create a draft Evergreen queue from an eligible published post" names a specific verb, a specific resource, and the input it derives from. The second clause distinguishes it from activate_evergreen_queue, a sibling in the same family, so an agent can route 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?

It clearly separates creation from activation and scheduling, naming the sibling that performs the latter — a real when-to-use signal. It stops short of naming preview_evergreen_queue or update_evergreen_queue as alternatives, and gives no prerequisites for "eligible" published post beyond the adjective.

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

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

Annotations already flag destructiveHint=true, openWorldHint=true, and idempotentHint=false, but the description adds genuinely useful context: nothing is published without scheduledAt, and with it a worker publishes at that time — which explains what the 'destructive' flag actually means here. It does not cover failure modes, validation errors, or what a partial multi-channel failure looks like, so it is not fully transparent.

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 short sentences, front-loaded with the draft-vs-scheduled distinction that determines the tool's whole effect, then prerequisites, then parameter exclusivity. No filler or redundant restatement.

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

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

For a 9-parameter, nested-object creation tool with zero required params and no output schema, the description covers the decision-critical behavior (draft vs. publish), the two mutually exclusive channel forms, media prerequisites, and the channel-rules prerequisite. Gaps are minor: nothing about which channels require caption (schema covers it), destinationId usage, or what is returned on success.

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 every parameter's meaning, enum values, and nested settings. The description mainly restates this (channel vs. targets exclusivity, scheduledAt omission) and only adds the sourcing hint that media asset ids come from upload_media. Baseline 3 is appropriate.

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

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

Opens with a specific verb and resource ("Create a post for this brand") and immediately clarifies the two outcomes (draft vs. scheduled). It does not, however, differentiate itself from the sibling tools create_posts, bulk_posts, or publish_post, so an agent comparing them has no explicit routing hint.

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 sequencing guidance: upload media with upload_media first, read get_channel_rules before posting, and pass either channel or targets. It also names the condition that changes behavior (omit scheduledAt = draft). It stops short of saying when to prefer this over create_posts, bulk_posts, or publish_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 the write/destructive, non-idempotent, open-world profile, so the description's job is to add behavior beyond that. It does so with the key non-obvious trait: per-item ok/error results and partial success ('successful ones are created even when others fail'). It stops short of stating default scheduling/publish behavior when scheduledAt is omitted.

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: capacity first, item shape second, failure semantics last. Every sentence carries information an agent needs and nothing is repeated from 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?

For a batch-create tool, the highest-risk misconception is expecting all-or-nothing behavior, and the description pre-empts that clearly. Remaining gaps are default publish-vs-schedule behavior and the unmentioned bulk_posts sibling, both of which matter for correct tool selection.

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?

There is a single top-level 'posts' parameter with no description in the schema, so the description must compensate. It adds the crucial semantic that each item mirrors create_post's fields and reinforces the 25-item cap, but it delegates all item-field meaning to another tool's docs, which the agent may not have loaded.

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?

Names a specific verb and resource with scope: 'Create up to 25 posts in one call', and implicitly positions itself as the batch counterpart of create_post. It does not distinguish itself from the sibling bulk_posts, so an agent cannot fully tell the two apart from this description alone.

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 'for example a week of scheduled content' implies the intended use case (batching scheduled content), but there is no explicit when-not guidance, no direction on choosing between create_posts, bulk_posts, or repeated create_post calls, and no note about atomicity trade-offs when deciding to batch.

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 and idempotentHint=false, so safety is partially covered. The description adds state-dependent constraints — published posts cannot be removed from here and mid-publish posts are blocked until the run settles — which are useful behavioral facts not in the annotations. It stops short of saying whether this is a hard delete or a cancel-to-state, but the state gating is well disclosed.

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, all load-bearing: scope, exclusion, and the mid-publish edge case. The primary action is front-loaded and nothing is repeated from the title or annotations.

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, the description covers scope, exclusions, and the transitional-state caveat, while annotations carry the destructive/idempotency profile and no output schema is needed. Nothing an agent requires to call this correctly is missing.

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

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

There is a single parameter (postId) with 100% schema description coverage, so the schema already documents it. The description adds no format or sourcing detail for the id beyond what the schema provides, 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 (delete/cancel) applied to a specific resource (draft or scheduled/failed/waiting post), and immediately draws the boundary that published posts are out of scope. An agent can distinguish this from siblings like update_post or publish_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?

Explicit when-to-use (draft, scheduled, failed, waiting-to-be-posted) and when-not-to-use (published posts, which remain in Markaestro with the user; mid-publish posts must wait until the run settles). Both the positive and negative conditions are stated, plus the owning alternative.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the extra value here is real: the window is clamped to the plan's history and reported as maxDays, unavailable provider metrics come back as null rather than zero, and data spans both Markaestro-published and platform-discovered posts. It does not describe response shape, but no output schema exists and the sections are enumerated.

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?

Information-dense and front-loaded, with every sentence adding something. However the first sentence is an unusually long dash-chained list, and the fragment 'coverage.' is duplicated awkwardly at the end of sentence one and again in 'coverage.bySource says how many of each'.

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 7-parameter, all-optional analytics tool with no output schema, the definition does the heavy lifting: it enumerates the returned sections, explains the account coverage model, and warns about history clamping and nulls. Missing only explicit deltas against the other analytics siblings.

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% with per-parameter descriptions, so the three-baseline applies. The description does add genuine meaning beyond the schema by explaining the productId semantics (omitted = whole workspace; single-brand connections always report their own brand) and by tying source to coverage.bySource.

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 scope: performance for the connection's brand, or workspace/all-brands via productId, with an enumerated list of returned sections (per-channel rollups, daily series, heatmap, insights, coverage). The account-wide vs per-post distinction is implicit in 'Covers the whole account', but no sibling such as get_evergreen_analytics or list_post_analytics is named, so routing still needs inference.

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?

'Read this before recommending what, when, or where to post' gives clear usage context and signals this is the source-of-truth analytics call. No exclusions or explicit alternative-selection rules against the several analytics siblings are given.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is fully covered by structured data. The description's 'Read-only' merely restates that, and it adds no auth, rate-limit, caching, or not-found behavior. The enumeration of returned fields is modest added value.

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

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

Three short sentences, front-loaded with the resource contents followed by the usage trigger. 'Read-only' is redundant against the annotations and does not earn its place, but nothing else is wasted.

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 must convey what comes back, and it does via the field list. Combined with a single well-documented parameter and complete annotations, an agent has enough to call it correctly; only edge-case behavior (missing id, empty profile) is absent.

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% (productId: 'Brand id from list_products'), so the schema already documents the sole parameter, including its provenance. The description adds nothing about productId, which is acceptable at the baseline for 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 names the specific resource and enumerates its contents (description, website, categories, voice, visual identity), so an agent knows exactly what is returned. It is not a verb-first statement, and there is no sibling brand-profile tool to contrast against, but the resource is unambiguous.

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

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

It gives an explicit usage trigger: 'Read it before writing captions so they sound like the brand.' This tells the agent when to reach for it. It stops short of naming alternatives or stating when not to use it, so it is not a full 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, idempotentHint, destructiveHint=false and a closed-world scope, so the safety profile is fully covered. The description only adds content scope (what the rules govern), not behavioral traits such as result stability, caching, or freshness, which is the expected baseline when annotations carry that burden.

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

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

Two tight sentences: the first says what the payload covers, the second front-loads the actionable instruction. No filler, no restatement of the name.

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 must hint at the returned data, and it does: media, caption, and delivery-mode rules plus the draft-then-publish model. It is a bit high-level about the exact shape of the rules, but complete enough for a zero-parameter read that gates post creation.

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

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

The tool takes zero parameters, so per the rules the baseline is 4. There is nothing parameter-related the description could clarify, and it correctly avoids inventing arguments.

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 names the specific resource and its contents: per-channel media, caption, and delivery-mode rules, plus the draft-then-publish model. It is clearly a read of platform constraint data, not a CRUD operation. It does not need sibling differentiation because no other tool in the list exposes channel rules.

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?

"Read before creating posts" gives an explicit trigger condition and points at the create_post/create_posts workflow. It stops short of stating when this is unnecessary (e.g. updating or deleting posts), so it is clear usage guidance without full when-not 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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so safety is covered. The description adds a genuinely useful behavioral trait beyond that: unavailable provider metrics are returned as null rather than zero, which directly affects how an agent should interpret missing 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?

Two tight sentences, front-loaded with the metric inventory and ending on the high-value null-vs-zero caveat. The metric list is long but each item earns its place by telling the agent what is returned.

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 burden of describing returns, and it does so by naming the metric families and clarifying null semantics. Only the queueId input semantics are left unaddressed, which is a minor gap for a one-parameter 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?

There is a single required queueId parameter with 0% schema description coverage, and the description never explains what queueId refers to or its expected form. The name is largely self-explanatory given the queue-centric sibling set, but the description does not compensate for the coverage gap as required when coverage is below 50%.

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 enumerates the exact metric families returned: source metrics, queue-lifetime metrics, tracked clicks, attributed conversions, and recent run outcomes. The 'queue-lifetime' and 'run outcomes' framing ties it to the Evergreen queue domain well enough to separate it from generic get_analytics, though it never explicitly names that sibling.

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 by the Evergreen/queue wording, but there is no explicit when-to-use or when-not-to-use guidance relative to get_analytics, list_post_analytics, or list_evergreen_runs, which an agent could easily confuse with 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds one useful piece of behavioral context beyond that: the response includes caption variants. It does not address error behavior for an invalid queueId, and no output schema exists to compensate.

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, front-loaded sentence with zero filler; the key scope qualifier ('one') and the return-content hint ('including its caption variants') are both delivered efficiently.

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 minimal read-only getter with one parameter and no output schema, the description is adequate but thin. It omits how to source the queueId and what happens on failure, leaving the agent to infer the workflow from sibling 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 description coverage is 0% – queueId is documented only as a bare string with no description. The description never mentions queueId, its expected format, or where to obtain it, so it fails to compensate for the schema gap on the tool's only (required) parameter.

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 (Intelligent Evergreen queue) and scopes it to a single item ('one'), implicitly distinguishing it from the sibling list_evergreen_queues. The sibling is not named explicitly, but the singular framing makes retrieval vs. listing 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?

Usage is only implied: 'one' signals this is a single-item lookup as opposed to the list tool, but there is no explicit when-to-use statement, no note that a queueId must first come from list_evergreen_queues, and no mention of alternatives like preview_evergreen_queue or list_evergreen_runs.

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, idempotentHint=true and destructiveHint=false, so the safety profile is fully covered without the description. The description adds the set of terminal/non-terminal states and notes that a message and details are returned, but says nothing about polling cadence or when a run stops changing state.

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 sentence, front-loaded with the verb and resource, with the state enum and return contents appended as useful detail. No filler or redundancy.

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

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

With no output schema, the description carries the return-value burden and does so adequately by naming the status values and the accompanying message/details. It stops just short of what an agent would want on error cases or unknown run ids.

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 0% and the single required parameter 'runId' has no type or format notes in the schema. The description partially compensates by saying the id comes from publish_post, but gives no shape, format, or example of the value.

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 ('check the status of a publish run') and enumerates the possible states (queued, running, succeeded, failed), so the agent knows exactly what surface it reads. It is clearly distinguishable from the sibling list_job_runs, which lists runs rather than retrieving one.

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 ties the tool to its origin ('returned by publish_post'), making the intended workflow — polling a run you just started — clear without spelling it out. It never names an alternative or a when-not condition, so it stops short of full routing guidance.

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

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

Annotations already declare the safety profile (readOnly, idempotent, non-destructive, non-open-world), and the description adds genuine value on top by enumerating the returned fields, including 'processing state,' which hints the asset may not be immediately usable. It still omits permissions requirements and any behavior when the asset is missing or mid-processing.

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, front-loaded sentence that names the action first and the returned payload second, with no filler. It is appropriately sized for a one-parameter read 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?

For a simple, non-destructive read of a single record with annotations covering safety and no output schema, listing the returned fields largely covers what an agent needs. The remaining gap is how to acquire a valid assetId, which is not addressed anywhere in the definition.

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?

There is one required parameter, assetId, and schema description coverage is 0%, so the schema provides no format or sourcing detail. The description does not compensate — it says nothing about what an assetId looks like or where to obtain it, leaving the single parameter effectively undocumented.

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 (Fetch) and resource (one media asset) and enumerates what the asset record contains: type, dimensions, processing state, thumbnail, and reference count. The word 'one' implicitly separates it from the sibling list_media, but no sibling is named explicitly, so differentiation relies on inference.

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 never states when to use this tool versus list_media or upload_media, nor any prerequisite such as where an assetId comes from. Usage is only weakly implied by 'one media asset,' which gives the agent no explicit routing guidance.

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

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

Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the description's real contribution is disclosing what the response will contain — targets, status, media, schedule, publish results, and a live URL only when published. That conditional ('when published') is genuinely useful behavioral detail, though error/not-found behavior and auth requirements are not addressed.

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 dense sentence that front-loads the verb and resource, then lists return contents in priority order. No filler, nothing redundant.

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

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

With no output schema and only one input parameter, the description usefully carries the return-value burden by enumerating the fields returned and their conditional nature. The remaining weak spot is the unidentified postId, which leaves the invocation path slightly under-explained.

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

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

Schema description coverage is 0% and the single required parameter postId is undocumented in both schema and description. The description says 'one post' but never explains the identifier's format or where to obtain it (e.g., from list_posts), so it does not compensate for the coverage gap.

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 ('Fetch') and resource ('one post'), and enumerates the payload (targets, status, media, schedule, publish results, live URL). This clearly separates it from list_posts and the mutation siblings (create_post, update_post, delete_post), though it never names those siblings explicitly.

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?

There is no when-to-use guidance: nothing tells the agent to use this after list_posts returns an ID, or to prefer it over get_post_analytics / list_post_analytics for these fields. The singular 'one post' weakly implies retrieval by a known ID, but no alternative or exclusion is 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 readOnly, idempotent, closed-world, and non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: the exact snapshot cadence, the special case for posts published directly on the platform ('starts with a discovered snapshot'), the 'polling is still active' flag, and the cross-brand error contract (NOT_FOUND). It doesn't discuss rate limits or latency, so a 4 rather than 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?

Two sentences, front-loaded with what the tool returns and scoped to the provenance and error behavior in the second. It is dense but nearly every clause carries information; the parenthetical about the discovered snapshot is a slight digression but still relevant.

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 correctly carries the burden of describing the return payload (snapshots, growth deltas, totals, polling state) and the failure mode (NOT_FOUND outside the brand). For a single-parameter read tool with full annotation coverage, nothing an agent needs to invoke or interpret it 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 0% on a single required postId param, so the description must compensate. It does so meaningfully by specifying that the id can come from either get_analytics or list_post_analytics, telling the agent the acceptable id provenance. It never states the type/format (string) or whether ids are interchangeable across tools, leaving a small gap.

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 ('how one post earned its numbers over time') and enumerates the exact payload: metric snapshots at 1h/6h/24h/72h/7d/14d/30d/60d/90d, inter-stage growth, current totals, and polling status. This clearly distinguishes it from siblings like get_analytics (aggregate) and list_post_analytics (list), so an agent can choose 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?

It explicitly routes input sourcing: 'Takes any id from get_analytics or list_post_analytics,' which tells the agent how this tool chains with those siblings. What's missing is an explicit when-to-use statement versus get_analytics (current totals vs. historical trajectory) and any exclusions, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely non-obvious behavior: the options are account-scoped, they gate Direct Post construction, and test keys return a sandbox answer without contacting TikTok. It stops short of describing result shape or failure modes (e.g., what happens with no connected account).

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 scope statement is front-loaded, the exclusions follow, and the workflow constraint plus the sandbox caveat close it out. Four sentences, none of which repeat the title or the schema, and 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?

With no output schema, the description correctly enumerates the returned fields, and with one optional schema-documented parameter the input side needs no further explanation. The Direct Post dependency and sandbox behavior are the details an agent would otherwise get wrong, and both are present.

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

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

Schema coverage is 100% and the single optional productId is fully documented in the schema, so the baseline of 3 applies. The description implies the account is the caller's connected creator account but never mentions the all-brands/brand-selection case, so it adds no meaning beyond the schema here.

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

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

The description opens with a specific verb+resource ("Read posting options ... for the user's already connected TikTok creator account") and enumerates exactly what is returned: allowed privacy levels, comment/duet/stitch flags, and max video length. It also explicitly excludes neighboring behaviors ("Does not publish, change settings, or query arbitrary creators or URLs"), which separates it from publish_post and create_post 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?

It states the operative workflow rule: TikTok requires a Direct Post to use these, so read them right before building one and pass the chosen privacyLevel into the tiktok settings. It also lists what the tool is not for, giving an agent both the when and the when-not, plus the downstream dependency.

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, idempotentHint, and destructiveHint=false, so the safety profile is known. The description adds useful specifics about what is returned (ids and delivery modes) and the destination types, but says nothing about pagination, auth requirements, or ordering.

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, front-loaded with the core action and scope, followed by the actionable integration hint. 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 read-only list tool with full annotation coverage and no output schema, the description is nearly complete: it explains what is listed and why the result matters for create_post. Only minor gaps (pagination/ordering) remain.

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?

With a single parameter at 100% schema coverage, the schema already documents productId and its source. The description only implies the brand/product scope via 'of a brand' and adds no format or edge-case 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?

States a specific verb and resource ('List the publishable destinations ... of a brand'), enumerates examples (Facebook Page, Instagram account, TikTok account), and names the returned fields (ids and delivery modes). It is clearly distinguishable from siblings like list_products or list_posts.

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

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

The second sentence gives a concrete consumption rule: use a destinationId on create_post only when a channel has more than one destination. This ties the tool to create_post and tells the agent when the output matters, though it doesn't formally state when not to call this list tool itself.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds value beyond that by disclosing what each queue entry carries (activation evidence, cadence, next run, status), which is the key behavioral context for a read tool with no output schema. Only pagination/size limits are unaddressed.

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 front-loaded sentence with no filler. The resource is named first and the returned fields follow compactly, so nothing needs trimming.

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 parameters, no output schema and no nested objects, the description covers the essentials by enumerating the returned fields. It is slightly short of complete because it does not state ordering, pagination, or behavior when no queues exist.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for parameterless tools 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 ('List') and resource ('this brand's Intelligent Evergreen queues'), with scope limited to the current brand. It is distinguishable from singular read siblings like get_evergreen_queue, though it never names them explicitly.

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 listing intent is implied by the verb and brand scoping, so an agent can infer when to call it. However, there is no explicit when-to-use guidance, no exclusions, and no reference to alternatives such as get_evergreen_queue for a single queue or list_evergreen_runs for execution history.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds a small amount of value by characterizing the returned data as 'generated occurrences and evaluation outcomes,' but omits pagination, ordering, or history-limit behavior.

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

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

A single front-loaded sentence with no filler or redundancy. It is efficient, though its brevity is part of what leaves the gaps elsewhere.

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 what the caller gets back, and 'generated occurrences and evaluation outcomes' is too vague to do so. Combined with the undocumented parameter, the definition is not complete enough to invoke confidently.

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 0% and the single parameter (queueId) has no type/format description anywhere. The phrase 'for a queue' only loosely implies queueId and provides no syntax or sourcing guidance, so the description fails to compensate for the coverage gap.

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 verb ('List') and resource ('generated occurrences and evaluation outcomes for a queue'), but the terminology drifts from the tool name's 'runs' to 'occurrences and evaluation outcomes,' leaving the exact object ambiguous. It is enough to guess intent but does not crisply distinguish it from siblings like list_job_runs or preview_evergreen_queue.

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?

There is no when-to-use guidance, no exclusions, and no named alternatives among the many sibling list/get tools. The agent must infer from the name alone that this is the read path for a queue's run history.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds only the 'recent' scope qualifier, omitting pagination behavior and result ordering/limits that would enrich an agent's expectations.

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

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

A single efficient sentence with the resource front-loaded and filters after. No wasted words, though it is brief enough that it leaves semantic gaps rather than being over-packed.

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 for a read-only list tool whose annotations already cover safety, the description is adequate but thin, omitting pagination semantics and the shape/ordering of returned runs that an agent would want.

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 only 25%, so the description must compensate, and it does explain the status and resourceId filters including the post-id interpretation. However limit and cursor go entirely undocumented in both places, leaving half the parameters unexplained.

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 publish runs), and the plural 'list' vs the sibling get_job_run's singular 'get' is inherently distinguishable. It is clear but does not explicitly differentiate itself from list_evergreen_runs or other list siblings.

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

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

It notes optional filtering by status or resourceId, which implies some usage context, but gives no when-to-use guidance, no prerequisites, and never names an alternative like get_job_run or list_evergreen_runs. Usage is implied rather than 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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the useful fact that reference counts are returned, but omits pagination behavior despite a cursor parameter.

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 front-loaded sentence with zero filler; the listing purpose and payload contents come before anything else.

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, 0% parameter coverage, and a cursor-based pagination parameter, the description should explain filtering and paging semantics. It leaves the agent unable to determine how to narrow or page results.

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%, so the description carries the burden for all three parameters, yet it explains none of them. The word "type" in the description refers to a returned field's type, which is ambiguous against the 'type' enum filter parameter, and limit/cursor are never addressed.

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 (uploaded media assets) and enumerates the returned fields. It is clearly distinguishable from the singular get_media sibling, though it does not name that sibling explicitly to reinforce the split.

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?

No guidance on when to use this versus get_media or upload_media, and no mention that the type filter or cursor pagination exist. The agent must infer usage entirely.

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real context beyond them: native posts are included, each row's source field distinguishes markaestro vs native, and canTakeDown is explicitly informational because takedowns happen in Markaestro rather than via delete_post. It does not discuss metric freshness/staleness or pagination behavior past the limit, which keeps it below 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?

Content is front-loaded with the core result shape, then sorting guidance, then the sibling pairing, so the agent's most important questions are answered first. The opening sentence is long and parenthesis-heavy (scope clause nested inside the resource clause), which slightly harms scannability but no sentence is 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 an 8-parameter analytics listing with no output schema, the description covers row shape, scope resolution, sorting, and the get_post follow-up well. It leaves notable gaps: nothing about whether metrics are stale or require refresh_analytics first, and nothing about behavior when limit is exceeded (truncation vs pagination).

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?

With 88% schema coverage the baseline is 3, and the description earns more by explaining the productId scoping model (single-brand connection always reports its own brand; omit for whole workspace) and the meaning of each sort enum in practical terms. The window concept behind days/since/until is referenced but the explicit-range interaction is left entirely to 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?

States a specific resource (every post in the window) with a specific payload (latest metrics: views, reach, likes, comments, shares, saves, clicks, engagements, engagement rate) and a row granularity (one row per post, sorted). It explicitly differentiates from siblings get_post (full caption and media) and delete_post (not for takedowns), so an agent can choose without opening schemas.

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 routing guidance: sort=engagements or sort=views to find what worked, sort=published_at for a chronological read, and pair with get_post when captions/media are needed. It also states scope selection rules (connection's brand, workspace, or productId on an all-brands connection), which is the main ambiguity for 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 declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavior: results are ordered newest-first, and cursor values are consumed from a previous page to fetch subsequent pages. It does not mention rate limits or result shape, but the added context is meaningful.

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, each carrying distinct information: scope + sort order, filter values, brand scoping, and pagination. The most important facts are front-loaded and there is no redundant restatement of the title or annotations.

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

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

For a read-only list tool with full annotations and no output schema, the description supplies sorting, the full status vocabulary, brand scoping, and pagination mechanics. The remaining omission (pagination termination / whether a next cursor is returned) is minor, and the annotation set already covers the safety dimension.

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 only 50% and status has no enum in the schema, yet the description enumerates all seven valid status values, effectively documenting that parameter. It also explains cursor pagination and the all-brands condition for productId, compensating for the undocumented cursor. Only 'limit' is left entirely to the schema, which already states default 25 / max 100.

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 posts') plus an ordering guarantee ('newest first'), so an agent can immediately distinguish it from get_post. It does not name any sibling as an alternative, but the list/get distinction is self-evident from the name and 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?

It gives conditional guidance for productId ('On an all-brands connection, pass productId to list one brand') and explains that cursor continues paging, which is real when-to-use information. However, it never states when to prefer this tool over alternatives such as list_media or get_post, so usage remains implied at the tool level.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds value beyond them by disclosing scope behavior (single-brand vs all-brands connection) and what the payload contains (brands plus their connected channels), which annotations cannot express.

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 resource identity and scope come first, followed by the actionable 'call this first' directive - well front-loaded and 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?

With no output schema, the description carries the burden of describing returns and does so adequately, naming the key field (productId) and the connected-channels payload. It stops short of detailing the full response shape, but for a zero-parameter, read-only discovery tool this is nearly sufficient.

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

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

There are zero input parameters, so there is nothing for the schema or description to clarify. Per the baseline for parameterless tools, a 4 is appropriate; the description correctly spends no space on nonexistent parameters.

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 (brands/products), and explicitly reconciles the name/title mismatch by equating 'brands (products)'. It also defines scope precisely - one brand for single-brand connections, all brands for all-brands ones - so an agent knows exactly what set is returned.

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 a strong ordering directive: 'Call this first to learn each productId and which channels can be posted to.' This establishes the tool as a discovery entry point and implies why it precedes posting tools. It lacks any explicit when-not guidance or named alternative, but no sibling lists brands, so no disambiguation is 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 declare destructiveHint=true, idempotentHint=false and openWorldHint=false, so the safety bar is lower. The description adds real context beyond them: the specific source and target states, and the assurance that no platform call is made, which is exactly what an agent needs to avoid confusing this with publishing. It omits error behavior when a post is not in platform_action_required and says nothing about reversibility or repeat-call behavior.

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

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

Three short sentences, each carrying distinct information: the action, the state transition, the eligibility constraint, and the no-side-effect guarantee. The state transition is front-loaded and nothing is redundant.

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

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

For a two-parameter mutation tool whose annotations already cover the safety profile and which has no output schema, this is nearly sufficient. The remaining gaps are the undocumented postId parameter and the absence of any statement about what happens if the post is not in the required state.

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 only 50%: externalUrl is documented in the schema but postId is bare. The description never mentions either parameter, so it adds no meaning about what postId must identify or when externalUrl should be supplied.

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?

Names a specific verb ('Record that a person has posted') and resource ('manual-reminder or TikTok-inbox post') and states the exact state transition from platform_action_required to published. The clause 'Nothing is sent to any platform' separates it from publish_post, so an agent can distinguish it from siblings 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?

'Only for posts in platform_action_required that the user has already posted themselves' gives an explicit precondition that acts as a when-to-use and implicit when-not rule. It does not name publish_post as the alternative for the platform-sending case, leaving that routing 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?

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false. The description goes beyond them by disclosing exactly what is destroyed: pending occurrences generated by the queue are unscheduled, not just the queue state flipped. It stops short of saying whether already-scheduled runs are cancelled or how state can be restored.

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 front-loaded sentence with no filler; the primary action and its consequence are both present and nothing is wasted.

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 mutation with annotations covering the safety profile and no output schema, the description supplies the key missing behavioral detail (pending occurrences are unscheduled). The remaining gap is the undocumented required queueId.

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?

There is a single required parameter (queueId) with 0% schema description coverage, so the description carries the full burden of clarifying it. The description never identifies queueId, its format, or how to obtain it (e.g. from list_evergreen_queues), leaving a real gap for a required input.

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 (pause) and resource (an Evergreen queue), and adds the side effect of unscheduling pending occurrences, which distinguishes it from a bare 'pause'. It does not explicitly name the obvious counterpart (resume_evergreen_queue / activate_evergreen_queue), so it falls 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?

Usage is implied by the action: an agent can infer you call this when you want a queue to stop firing. However, there is no explicit statement of when to prefer this over update_evergreen_queue, deactivate/delete, or resume_evergreen_queue, and no prerequisites are given.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered structurally. The description adds real value beyond that by disclosing the eligibility gate ("mature measured performance") and the non-mutating confirmation, though it says nothing about auth requirements, rate limits, or what happens when the post is not yet eligible.

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: the capability first, the non-mutating guarantee second. No filler, no repetition of the title, and the key constraint is front-loaded where an agent will read it.

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

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

For a single-parameter, read-only preview with no output schema, the description conveys the two things the caller needs back: eligibility and a suggested cadence. It leaves open the definition of "mature measured performance" and never mentions the return shape when the post is ineligible, which is a minor gap given the tool's simplicity.

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

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

Schema description coverage is 0% for the single required parameter sourcePostId. The description only implicitly characterizes the input as "a published post," which hints at the expected identifier but does not specify format (post ID string vs. URL) or whether unpublished posts are rejected.

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 names a specific verb (check) and resource (published post's measured performance) plus the byproduct (recommended Evergreen cadence), and immediately separates itself from the create/update/activate queue siblings by stating it does not create or schedule anything.

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 negative boundary ("does not create or schedule anything") tells the agent when this tool is not the right choice, which implicitly positions it as the pre-flight check before create_evergreen_queue. It stops short of explicitly naming that sibling as the follow-up action, so it lacks the full routing guidance of a 5.

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

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

Annotations already declare destructive/non-idempotent/open-world, yet the description adds real behavior beyond them: the async job-run model, the polling contract, the eventual public visibility on success, and the alternate manual_reminder path that does not publish at all. These are meaningful operational facts an agent cannot get from 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?

Three sentences, front-loaded with the action, each carrying distinct information: the async result, the polling step, the reminder edge case, and the visibility consequence. 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 single-parameter tool with no output schema, the description covers the mutation semantics, the return artifact (job run), and how to follow it up. Permission requirements or failure modes are not addressed, which keeps it just short of 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?

Only one parameter (postId) with 0% schema description coverage; the description implies it is a draft post but adds no format, ID source, or validation detail. Baseline is limited to 3 because the single required param is left essentially undocumented in both places.

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 ("Queue an immediate publish of a draft post") and clarifies the scope as a draft post going live immediately, which separates it from create_post/update_post and from the evergreen queue siblings. It does not explicitly name which sibling it replaces, 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?

Gives clear context for use (immediate publish of a draft) plus the follow-up procedure (poll get_job_run until succeeded or failed), and notes the manual_reminder branch that queues a reminder instead of posting. No explicit when-not-to-use, so not 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 declare destructiveHint=true and idempotentHint=false, and the description explains exactly what is destroyed and what survives: each post's latest stored reading is replaced while readings from earlier stages are kept. It also discloses rate limiting ('a few calls a minute'), partial-completion semantics ('a large window may take more than one refresh'), and what the response reports.

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 scope constraint before the exclusions, and every sentence carries information. Some sentences pack several ideas (window scoping, follower counts, and response contents) into one line, making it denser than strictly necessary, but nothing is redundant.

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

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

There is no output schema, and the description compensates by describing what the answer returns (posts updated vs. remaining). For a mutating, rate-limited, potentially partial tool it covers permissions scope, mutation effect, exclusions, and result shape — nothing an agent needs 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 coverage is 67% and the description adds real meaning: filters are optional and mutually scoping (one channel or one authorized brand), and follower counts are always today's regardless of the window. It does not mention the 90-day maximum on days or the full channel enum, so it does not fully compensate for the uncovered portions of 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?

States a specific verb and resource (refresh stored analytics) plus precise scope: only the user's authorized brands and already connected social accounts. It explicitly distinguishes itself from read-only siblings (get_analytics, list_post_analytics) by noting it rewrites stored readings, and explicitly rules out arbitrary accounts, URLs, and public search.

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 clear when-to-use context (refreshing stored post metrics and follower counts within a window, optionally narrowed to one channel or one brand) and explicit when-not conditions (no arbitrary accounts/URLs/public search, no publishing). It does not name the sibling tools an agent should pick instead for read-only access, which keeps it short of a 5.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety bar is lower. The description usefully adds that the next occurrence is recomputed from the current time — implying skipped occurrences may be dropped — but it never explains what the destructive flag actually affects or what state is lost.

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 short sentence with the action front-loaded and the side effect trailing it. Nothing is wasted or restated from the title.

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?

This is a destructive, non-idempotent, open-world mutation with no output schema and no documented parameters. The description omits preconditions, permission requirements, consequence of the destructive flag, and any indication of what a successful resume returns, which is too thin for a tool of this risk 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 coverage is 0% and the description never mentions queueId, its format, or how to obtain a valid one. With a destructive, non-idempotent mutation the single parameter carries real weight, and the description does nothing to compensate for the schema gap.

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 names a specific verb (resume) and resource (paused queue) and adds a concrete side effect — recomputing the next occurrence from the current time. It does not, however, distinguish this from sibling tools like activate_evergreen_queue or pause_evergreen_queue, leaving the resume-vs-activate distinction to inference.

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 only implied by the word 'paused', which suggests a precondition but never states it as a requirement. There is no explicit guidance on when to choose this over activate_evergreen_queue, and no note on what happens if the queue is not currently paused.

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 cover the safety profile (read-only, idempotent, non-destructive), and the description adds real behavioral context beyond them: the result may be null until sufficient history exists, and a readiness signal reports how much history is available. The Intelligence-plan dependency is a genuine prerequisite not visible in 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?

Three dense sentences, front-loaded with the purpose and null/readiness behavior, with no filler. The phrasing is slightly clipped but every clause carries information.

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

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

With no output schema, the description compensates by naming the returned concepts (timing, readiness) and their null semantics, plus the prerequisite. An agent can call it correctly; only the concrete shape of the response is left implicit.

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 parameter productId is already documented, including the all-brands vs single-brand distinction. The description adds nothing about this parameter, 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 names a specific output ('When this brand's audience responds best') and its data source (Markaestro Intelligence, brand's own post history, not an industry table), which cleanly separates it from the generic analytics and listing siblings. It stops short of naming a specific alternative tool the agent might otherwise reach 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?

It states the action it feeds ('Use it to pick scheduledAt') and a hard prerequisite ('Needs a plan with Intelligence'), which is exactly the routing information an agent needs. No explicit when-not or named alternative is given, so it is not a full 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 destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuine value with the optimistic-concurrency rule (stale version rejected, concurrent edits not overwritten), but it does not clarify whether unspecified fields are left untouched or what destructive replacement of the variant set entails.

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 waste. The update scope is front-loaded and the version workflow requirement follows immediately, so the most operative detail is not 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?

For a mutation tool with rich annotations and no output schema, the description covers purpose, key field categories, and the concurrency contract. However, with 12 parameters at 8% schema coverage, the missing timeZone and partial-update semantics leave real ambiguity about what a call actually changes.

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 only 8% across 12 parameters, so the description has to compensate. It maps several fields to business terms (cadence, review policy, expiry, name, caption-variant set) and explains the version parameter, but timeZone and the enum meanings (scheduleMode, reviewPolicy) are never addressed, leaving substantial gaps.

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 specific verb and resource and enumerates the updatable surfaces (cadence, review policy, expiry, name, caption-variant set), which lets an agent distinguish it from create/activate/pause/resume siblings by name alone. It stops short of explicitly routing to those siblings, but the purpose is unambiguous.

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

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

It states a concrete prerequisite workflow: pull the current version via get_evergreen_queue and pass it, because stale versions are rejected. That is real when-to-use guidance. It does not say when NOT to use it (e.g., use activate/pause/resume for state changes rather than 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 declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, but the description adds real context beyond them: partial-update semantics ('omitted fields stay as they are'), cross-channel rule validation, the constraint that a scheduled post must remain publishable, and the immutability of channel targeting after creation. It stops short of describing failure modes or response shape, so it is strong but not exhaustive.

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 tight sentences, no filler, and the editability scope is front-loaded before the eligibility restrictions and alternative tool. Each sentence carries distinct information (what changes, partial semantics, validation, restrictions).

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 5-parameter mutation tool with nested settings, no output schema, and no enum parameters, the description supplies the needed eligibility rules, validation behavior, and channel-fixity constraint. Minor gaps remain around error/failure behavior and concurrency, but nothing essential 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?

With 60% schema description coverage, the schema documents settings, scheduledAt, and mediaAssetIds, but the description adds a key constraint the schema does not express: settings may contain only ONE channel's settings, selected via settings.__type, and scheduledAt is meaningful only for scheduled posts. postId remains undocumented in both, though its meaning is obvious from context.

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

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

States a precise verb (change) plus the resource (draft or scheduled post) and enumerates exactly what is editable: caption, media, one channel's settings, scheduled time. It also explicitly distinguishes itself from the sibling create_post ('to post somewhere else, create a new post'), so an agent can route correctly without opening either 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?

Covers when to use it (draft/scheduled posts), when not to (published and failed posts cannot be edited), and the alternative tool when the goal is different channels (create_post). The 'omitted fields stay as they are' note further clarifies the invocation contract for callers.

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 non-read-only, non-idempotent, non-destructive, open-world behavior, so the safety profile is covered elsewhere. The description adds two things annotations cannot convey: the return value (a media asset with an id) and the quota side effect that each upload counts against the workspace's monthly upload quota. It omits size/format limits and failure modes, keeping it below 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?

Three short sentences with no filler: capability first, downstream usage second, cost/limit last. Every sentence carries distinct information an agent needs before calling.

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 does the work of explaining the return (media asset, use its id) plus the quota constraint. For a three-parameter upload tool with reasonable annotation coverage, that is close to sufficient; supported file formats, size caps, and error behavior are the notable remaining gaps.

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

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

Schema coverage is 67%: source and contentType are documented in the schema, and the description's source options largely restate the schema text. fileName has no description in either place and is not addressed, so the description does not compensate for the remaining coverage gap, but it also adds nothing misleading.

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 (upload) and resource (image or video media asset) and enumerates the accepted source forms: local path, http(s) URL, data: URL. It also positions the tool relative to create_post by explaining where the returned id goes, so an agent can separate it from post-creation siblings 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 a clear usage chain: call this first, then pass the returned id in create_post mediaAssetIds. That is strong implied when-to-use guidance for the create_post workflow. It stops short of explicit exclusions or alternatives (e.g., when to re-upload vs. reuse an existing asset from list_media).

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