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

Annotations declare the mutation/safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=true), and the description adds real context beyond them: activation causes future public posts to be scheduled and is gated on a content-confirmation flag, otherwise returning EVERGREEN_CONTENT_REVIEW_REQUIRED. It still doesn't say whether activation is reversible or how already-scheduled items are affected.

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 payload: the action, the scheduling side effect, and the precondition with its error code. Front-loaded with the operation and free of 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 inline error code and precondition are exactly the kind of detail an agent needs, and the public-post side effect is disclosed. Missing only secondary behavior such as reversibility or interaction with existing scheduled 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?

Schema description coverage is 0% and the single parameter queueId is never mentioned in the description, so the description does not compensate for the gap. However, queueId is self-describing and the surrounding prose ('a draft or paused queue') gives the entity context, keeping this at a baseline 3 rather than lower.

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 ('Activate a draft or paused queue') and immediately names the effect (scheduling future public posts). It does not, however, distinguish itself from the sibling resume_evergreen_queue, since 'draft or paused' overlaps with what a resume tool would target.

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 one explicit precondition — caption variants must be confirmed via contentConfirmed on create/update — and the failure code if not. But there is no guidance on when to choose activate versus resume or pause, and no statement of the queue state required beyond 'draft or 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 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 already declare readOnlyHint=false, destructiveHint=false and idempotentHint=false. The description adds genuinely useful side-effect boundaries beyond that: creation is a draft that neither activates nor schedules, which is exactly the ambiguity an agent would otherwise resolve incorrectly by assuming creation kicks off runs. It does not address authorization, queue limits, or repeated-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?

Two sentences, zero filler, and the negative boundary (does not activate or schedule) is placed immediately after the purpose so the agent cannot misread it. Nothing needs to be moved or cut.

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 13-parameter mutation tool with no output schema and thin schema descriptions, the description covers purpose and the activation boundary but leaves the scheduling behavior (intervalDays, localHour/localMinute, timeZone, scheduleMode, reviewPolicy) and eligibility rules entirely undocumented. Adequate for the core action, short of what the parameter surface demands.

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 real burden but supplies almost none of it. The phrase 'from an eligible published post' hints that sourcePostId must reference a published post, but the ten undocumented parameters (name, channels, variants, timeZone, expiresAt, localHour/min/intervalDays, reviewPolicy, scheduleMode) get no explanation of scheduling semantics or defaults.

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

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

Specific verb + resource + scope: 'Create a draft Evergreen queue from an eligible published post.' The word 'draft' and 'from an eligible published post' separate it cleanly from update_evergreen_queue, activate_evergreen_queue, preview_evergreen_queue, and create_post without needing to open 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?

Explicitly states what this tool is not responsible for and routes the agent to the correct sibling: 'Creation does not activate it or schedule anything; activate_evergreen_queue does that separately.' It does not define what makes a post 'eligible' nor say what to do when a queue already exists, so the exclusion is clear but not complete.

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 assert readOnlyHint=false, idempotentHint=false, destructiveHint=false, so the safety profile is covered. The description adds genuinely non-structured context: the no-side-effect draft path, deferred publication by a worker, and the media/asset-id dependency. It stops short of stating failure behavior or whether re-scheduling replaces an existing job.

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, front-loaded with the publish/draft decision that most affects the call, followed by argument shape and prerequisites. No filler or restatement of 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?

For a 9-parameter mutation tool with nested targets objects and no output schema, the description covers the critical decision points (draft vs scheduled, single vs multi-channel, media and rules prerequisites). It is close to complete; only edge behavior on scheduling failures or replacement of prior jobs 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%, so the schema already documents channel/targets exclusivity, scheduledAt, mediaAssetIds and deliveryMode; the baseline is 3. The description reinforces the channel-vs-targets choice and the media-id provenance, but adds no syntax or constraint detail the schema lacks.

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 ('Create a post for this brand') and immediately clarifies the draft-vs-scheduled outcome, which is the core behavior. It does not, however, differentiate itself from the many sibling creators (create_posts, bulk_posts, create_evergreen_queue), leaving the multi-channel-via-targets path ambiguous against the plural variants.

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 branch logic: without scheduledAt it is a draft that publishes nothing, with scheduledAt it is queued for the worker. It also sequences prerequisites by naming upload_media and get_channel_rules as things to do first, so the agent knows the ordering and the alternative tools to call.

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

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

Beyond the annotations (which only declare it is a non-readonly, open-world, non-idempotent write), the description discloses the crucial non-atomic failure model: 'Failures are per item' and 'the successful ones are created even when others fail'. That partial-success semantics is exactly what an agent needs to know before retrying or reporting results, and it is not derivable from any structured field.

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 earning its place: capacity, item-field reference, and failure semantics. The cap and the batch framing are front-loaded, and there is 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 usefully describes the return shape ('the response lists ok/error for each'), which covers the main completeness gap for a batch mutation. Rate limits, permissions, and the relationship to bulk_posts are unaddressed, but for a tool with annotation coverage of the safety profile this is largely 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?

Top-level schema description coverage is 0% and the single parameter is a complex array of nested post objects, so the description must compensate. It does so partially by delegating item-field semantics to create_post and stating the 25-item cap, but the nested target/settings/deliveryMode structure is only documented inside the schema itself, so the description adds limited independent meaning.

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

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

The description states a specific verb and resource with a batch limit: 'Create up to 25 posts in one call', and it explicitly anchors item fields to the sibling create_post ('Each item takes the same fields as create_post'). It does not, however, distinguish itself from the other bulk-oriented sibling bulk_posts, so an agent still has to guess between those two.

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?

'for example a week of scheduled content' gives a concrete usage scenario for the batch case, implying when a bulk call is preferable to repeated create_post calls. But there is no explicit when-not guidance and no routing away from the sibling bulk_posts, which appears to overlap.

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 declare readOnly/idempotent/non-destructive, and the description adds real behavioral context beyond them: the window is clamped to plan history with maxDays reported, unavailable provider metrics are null rather than zero, and coverage spans both Markaestro and natively discovered posts via coverage.bySource. These are meaningful operational caveats not present in the annotations.

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

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

Front-loads the purpose and scope before the enumeration, and every sentence carries information. It is dense and the first sentence is long, but nothing is padding and the caveats (clamping, null metrics) are isolated at the end.

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 takes on the burden of explaining return contents and does so thoroughly (the list of rollups, series, insights, and coverage). Edge cases like history clamping and null-vs-zero metrics are covered; only pagination/response sizing is unaddressed, which is minor for an aggregate analytics read.

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 (tz, days, since/until, source, channel, productId). The description adds minor scope nuance around productId/all-brands behavior, but essentially restates what the schema encodes; baseline 3 is correct 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?

Names a specific resource (brand performance analytics) and fully enumerates what the response contains (totals with prior-period deltas, per-channel rollups, daily series, heatmap, insights, coverage). It also states the scope resolution (connection's brand vs all-brands workspace vs productId brand), which lets an agent distinguish it from sibling analytics tools.

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

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

Provides one usage cue — 'Read this before recommending what, when, or where to post' — which implies a decision-support context. However, it never distinguishes itself from close siblings like get_evergreen_analytics, list_post_analytics, get_post_analytics_history, or suggest_post_times, leaving the agent to infer which analytics tool to pick.

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 readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds live/sandbox behavior, the dependency on Direct Post, and the need to use the returned privacyLevel — relevant context beyond structured fields.

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

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

Three sentences, front-loaded with what is returned, then when to call it, then the sandbox caveat. There is no redundant or wasted language.

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

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

For a one-parameter, read-only tool with no output schema, the description supplies the returned fields, the Direct Post prerequisite, and test-key behavior. Together with the rich annotations and fully described schema, it is complete for correct invocation.

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

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

Schema description coverage is 100%, so productId is already fully documented in the schema. The tool description adds no parameter syntax or meaning beyond that baseline.

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

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

The description states a specific verb and resource: get the connected TikTok creator's live posting options. It enumerates the returned fields (allowed privacy levels, comments/duets/stitches enablement, longest video), so an agent can distinguish it from generic get tools.

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

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

It explicitly says to read these options right before building a Direct Post and to pass the chosen privacyLevel in the tiktok settings. The test-key sandbox note adds useful context, though no explicit when-not or alternative tool is named.

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 establish read-only, idempotent, non-destructive behavior, so the bar is lower. The description adds real value beyond them: it explains that canTakeDown is informational and that taking a live post down is a user action in Markaestro, not delete_post — a genuinely useful safety clarification absent from 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?

One dense paragraph that is front-loaded with the row-level scope before drilling into source, sort, and pairing advice. Every clause is informative, though the canTakeDown parenthetical is slightly tangential to a listing tool.

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

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

With 8 optional parameters and no output schema, the description usefully enumerates the returned metrics and clarifies window/source/scoping behavior. It leaves channel and the explicit since/until pairing mechanics to the schema, a minor gap for an otherwise well-covered tool.

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

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

Schema coverage is high (88%), so the baseline is 3. The description goes modestly beyond the schema by explaining productId scoping (connection brand vs. all-brands workspace vs. named brand) and by giving interpretive meaning to the sort options ('to find what worked'), which the schema merely enumerates.

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 (post analytics) with precise scope: every post in the window with its latest metrics, one row per post, sorted. It lists the returned metric set and clarifies the markaestro/native source distinction, letting an agent separate it from get_post (full caption/media) and get_post_analytics_history 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 concrete usage direction: use sort=engagements or sort=views to find what worked, sort=published_at for a chronological read, and pair with get_post for caption/media of a Markaestro post. It lacks an explicit when-not-to-use against get_analytics or get_post_analytics_history, but the context provided is strong.

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

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

Annotations already declare readOnlyHint, 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?

The annotations already disclose that this is a non-read-only, non-destructive, closed-world, non-idempotent operation. The description adds useful behavioral context beyond that: it records a state transition and explicitly says nothing is sent to any platform, which clarifies the lack of external side effects.

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

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

Three short sentences, front-loaded with the core action and state transition, then the required precondition and the key side-effect clarification. No wasted text.

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 state-transition tool with annotations covering safety and no output schema, the description is nearly complete: it explains the action, eligibility condition, and lack of platform delivery. The main gap is that postId remains undocumented in both the description and the schema.

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

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

Schema description coverage is only 50% because postId has no schema description. The tool description does not explain either parameter: it does not clarify that postId identifies the post to update, nor does it add meaning for externalUrl beyond the schema's own description.

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 ('Record'), the resource ('post'), and a precise state transition from platform_action_required to published. It clearly distinguishes this from publish_post or update_post by limiting it to manual-reminder or TikTok-inbox posts the user already posted natively.

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 when-to-use conditions: only for posts currently in platform_action_required and only when the user has already posted them. It does not explicitly name alternative tools to use in other cases, but the preconditions are specific enough to guide selection.

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

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

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?

Adds substantial behavior beyond annotations: it discloses the rate limit ('a few calls a minute'), the non-atomic nature of the operation ('how many posts were updated and how many remain... a large window may take more than one refresh'), and the exact scope of what gets refreshed. This meaningfully supplements the readOnlyHint=false / idempotentHint=false 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?

Three dense sentences, front-loaded with the core action and its contrast to scheduled polling, followed by response behavior and the rate limit. Every sentence carries information; no obvious padding.

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

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

Despite no output schema, the description explains the return payload (counts of updated and remaining posts) and the partial-completion caveat, and covers the parameter interactions and rate limit. Sufficient for an agent to invoke it correctly.

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

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

With 67% schema coverage, the schema documents days and productId but leaves channel's enum undocumented. The description compensates by explaining 'optionally one channel, or one brand on an all-brands connection', clarifying how the two optional filters interact and what 'window' means for days.

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

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

States a specific verb+resource ('Pull live metrics from the platforms') and contrasts it with the scheduled poll, so the agent understands it forces an on-demand refresh rather than reading cached data. It does not name sibling tools like get_analytics, so differentiation is only implicit.

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?

'Now instead of waiting for the next scheduled poll' implies when to reach for it, and the rate-limit note constrains usage. However, it never names an alternative (e.g., get_analytics) or states when-not-to-use, so the agent must infer the boundary.

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/idempotency profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false). The description adds genuine value by explaining that resuming recomputes the next occurrence from the current time, which is a non-obvious side effect consistent with the non-idempotent hint, but it omits whether already-scheduled posts are dropped, shifted, or duplicated.

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 key side effect in the second clause. Nothing is padded.

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 no output schema, the description covers the core action and the scheduling side effect, which is the main thing an agent needs. It still leaves the parameter undocumented and does not explain the observable result of the recomputation.

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 queueId parameter is entirely undocumented in both schema and description. The name is fairly self-explanatory, but the description adds no meaning (no format, no source of the ID, no behavior on an invalid/unknown ID).

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 ('Resume') and resource ('a paused queue') plus the scheduling consequence, so the action is unambiguous. It does not, however, distinguish itself from the sibling activate_evergreen_queue, which an agent could reasonably confuse with resuming.

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 'a paused queue' implicitly tells the agent the precondition (the queue must already be paused, presumably via pause_evergreen_queue), but it never states when to choose this over activate_evergreen_queue or what happens if the queue is not 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 the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds genuinely new behavioral context beyond them: the operation consumes the workspace's monthly upload quota, and it documents the return value and how it is consumed downstream. It does not cover size/format limits or quota-exhaustion 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?

Two tight sentences, front-loaded with the action and accepted inputs, followed by the return/consumption note and the quota caveat. No filler or restatement of 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?

With no output schema, the description correctly carries the return contract (returns the media asset, use its id in create_post) and flags the quota cost. It omits practical constraints such as accepted formats, size limits, and failure modes, which a write/upload tool would ideally surface.

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%, so the schema already documents source and contentType. The description repeats the source formats verbatim from the schema and adds nothing about fileName or contentType inference, so it neither compensates for the gap nor adds meaning beyond the schema.

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

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

States a specific verb (Upload) and resource (image or video media) plus the three accepted source types. It also distinguishes itself from siblings by explicitly naming create_post as the downstream consumer of the returned media asset id.

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 defines a clear work-flow context: upload first, then pass the returned id in create_post mediaAssetIds. It stops short of naming alternatives (e.g., list_media/get_media for existing assets) or stating when not to re-upload, so it is strong but not exhaustive.

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