PostQuickAI

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

Annotations already declare readOnlyHint=false, idempotentHint=false, openWorldHint=true, and destructiveHint=false. The description adds one genuinely useful trait — that meaning is preserved during the rewrite — but does not clarify whether the stored content is replaced or new text is returned, which matters given the non-read-only hint.

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?

Very short and front-loaded, with the substantive clause first. The redundant 'Adjust tone' line duplicates the tool name and title and could be dropped without loss.

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 non-read-only transformation over user content with no output schema, the description should state what happens to the original copy and what the caller receives back. Neither is addressed, and two of three parameters remain unexplained.

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

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

Schema coverage is only 33%: targetTone has an example list, but content and contentGroupId are entirely undocumented in both schema and description. The description does not compensate, saying nothing about what targetTone accepts or what contentGroupId does.

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

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

The second sentence gives a specific verb and resource: rewriting existing copy into a different tone while preserving meaning. However, it never distinguishes itself from text-editing siblings such as makeConcise, proofread, or customEdit, and the leading line 'Adjust tone' simply restates the tool name.

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 pick this over makeConcise, proofread, or customEdit, all of which operate on the same copy and could plausibly be confused with it. The only implied usage is 'you want a different tone', which is just the name restated.

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 behavior well beyond the annotations: it discloses the 50-item cap, the all-or-nothing transactional guarantee ("if one fails nothing is scheduled"), and the four validation gates (ownership, destination, media, lifecycle). These are exactly the traits an agent needs before firing a destructive, non-idempotent batch write.

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 action in the title line, then adds three tight sentences with no filler. The atomicity guarantee and prerequisite are each given their own sentence, which is efficient and readable.

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

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

For a batch mutation with annotations already covering the safety profile and no output schema, the description covers cap, atomicity, validation, and preconditions. It omits only failure-reporting/retry details on error, which is a minor gap.

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%, so the description must compensate. It partially does by mapping the items array to post/video/story kinds and stating the 50-item cap, but it never explains the id, scheduledFor, platforms, or requestKey semantics (though requestKey/platforms are described in the nested 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 (Schedule) plus the resource and scope (a campaign of up to 50 existing posts, videos, and stories in one transaction). It clearly distinguishes itself from the single-item siblings (schedulePost/scheduleStory/scheduleVideo) by framing itself as the bulk/campaign path.

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

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

Gives a clear operating context (batch scheduling, including republishing unchanged published posts/stories to new destinations) and a prerequisite ("Confirm all destinations and times first"), which implies when to use it. However, it never explicitly names the single-item siblings it should be preferred over, so routing isn't spelled out.

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 and non-idempotent, but the description adds substantive behavior beyond that: atomic batch semantics, that draft schedules revert to drafts, that published content and receipts are preserved when deliveryJobId is supplied, and the explicit no-op on social platforms. This is exactly the kind of outcome disclosure a destructive tool needs.

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?

Five short sentences, front-loaded with the action and scope, then mechanics, then refusals, then the cross-platform disclaimer. Each sentence carries information; density is high but nothing is redundant.

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

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

For a single-parameter, no-output-schema mutation tool, the description covers atomicity, allowed batch size, edge-case behavior for drafts, and refusal conditions, leaving little ambiguity. Authorization requirements and any response/error shape are not mentioned, which is the only meaningful gap.

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 must carry the load, and it does for the non-obvious field: deliveryJobId's source (getCalendar) and its effect (preserving published content and receipts), plus the implicit 50-item cap echoed from maxItems. kind and id are left to the schema's enum/uuid typing, which is largely self-evident.

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

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

The description opens with a precise verb+resource ('Cancel scheduled publishing') and immediately bounds the scope: up to 50 future schedules, atomic. It also explicitly disclaims a plausible misreading ('does not remove anything from social platforms'), which cleanly separates it from publish/delete style 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 supplies a concrete routing rule — pass deliveryJobId from getCalendar for separate cross-post deliveries — and enumerates refusal conditions (publisher-claimed content, already-published content, uncertain outcomes), which function as when-not guidance. No sibling tool is named as an alternative, so it falls short of 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 establish this is a non-read-only, non-idempotent, non-destructive, closed-world mutation. The description adds genuinely non-obvious context: the media is referenced rather than re-uploaded and no additional quota is consumed because the source was already counted. It does not say whether the draft needs a separate publish step or what permissions are required, but the quota/quoting behavior is valuable added context.

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

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

Three tight sentences with the core action front-loaded and the quota rationale second. The opening line largely restates the annotation title ("Create a story draft from an existing post or video"), which is mild redundancy, 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?

For a 4-parameter mutation tool with no output schema and full annotation coverage, the description supplies the key non-obvious facts: draft-not-published output, media referencing, and no repeat charge. Missing details about the return payload and platform selection limits are minor given there is no output schema to explain.

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%, so the description must compensate. It does clarify that `source` selects between generated_posts (default) and video_posts, which is more precise than the schema's generic "Source table" note, and the schema itself covers caption fallback. The `platforms` parameter and the postId format constraint get no additional explanation from either source.

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 ("Convert a post or video into a Story") and immediately clarifies that a draft is produced from existing media rather than new media. This cleanly separates it from createStory/createPost siblings, since the agent can tell conversion-of-existing-content apart from net-new creation 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?

Usage is implied (use this when you already have a source post/video and want to reuse its media), and it gives concrete routing advice for the `source` parameter. However it never states when NOT to use it or names an alternative such as createStory for cases with no existing post.

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

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

Annotations declare non-readonly, non-idempotent, non-destructive. The description adds genuinely useful context beyond them: that only a draft is created (no immediate publishing), that media URLs must be publicly accessible, and that user approval is required. It doesn't address re-invocation/idempotency behavior, so not a full 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?

Front-loads the core action, then sequences constraints and follow-up tool calls. Four sentences, each earning its place. Tight and readable, though slightly dense with three separate tool callouts.

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 10-parameter tool with nested objects and no output schema, the description covers the critical workflow (draft-only, media prep, approval, publish path). Remaining parameter detail is well handled by the 80%-covered schema, so an agent can call 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?

Schema description coverage is 80%, so the schema already documents most parameters including postType requirements and platform limits. The description adds only the publicly-accessible-URL constraint on media, which the schema does not state. Baseline 3 for schema-driven 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?

States a specific verb (Create) plus resource and scope (text, image, or carousel post draft). It cleanly distinguishes itself from siblings like createStory, createVideo, and publishPost without needing their schemas.

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

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

Explicitly routes the agent: call createUploadLink first for local files, ask the user to approve destination/timing before scheduling, and call publishPost for immediate publishing. Names the alternative tools and the conditions that select them.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and the description adds real context beyond them: this only produces a draft, media must be publicly reachable because platforms pull the URL at publish time, and user approval must precede scheduling. It does not address the non-idempotent behavior (e.g., whether repeated calls create duplicate drafts), which is the one notable gap.

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

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

Four short sentences, front-loaded with the core action and constraint; each sentence either routes to a sibling tool or sets an approval expectation. 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?

Covers the draft-vs-publish distinction, prerequisites, and the approval workflow for an 8-parameter tool with no output schema. It never mentions what the draft call returns (e.g., a draft/story identifier the agent would need for subsequent publish), which is the only missing link for a multi-step flow.

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 88%, so the schema already documents mediaUrl, mediaFit, duration, platforms, storyType, and thumbnailUrl thoroughly. The description's only parameter-relevant addition is reinforcing that mediaUrl must be publicly accessible, which the schema already states. Baseline 3 is appropriate.

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

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

States a specific verb+resource ('Create a story draft') plus a key constraint ('from a media URL that is already publicly accessible'), immediately distinguishing it from createUploadLink (local files) and publishStory/scheduleStory (publishing). An agent can place it correctly in the workflow without opening the schema.

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

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

Gives explicit routing for both branches: call createUploadLink first when the media is a local file, and call publishStory after approval when publishing immediately. It also states the required approval step for destination and timing, so when/when-not are both covered.

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 establish it is a non-readonly, non-idempotent, non-destructive mutation. The description adds genuinely useful context beyond those hints: the link expires in one hour, the user must be signed in, and the upload happens manually in the browser, which explains why a human-in-the-loop wait is required.

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

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

Front-loaded with the core action, then the usage condition, then the required follow-up sequence. Three sentences with no filler, though the workflow instructions could be trimmed slightly.

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 helpfully names the returned field (uploadPageUrl) and the downstream tool, giving the agent the full call-and-continue loop. It omits expiry/error handling, but the essential lifecycle is covered.

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 enum values (image/video) already carry the format and size limits. The description only restates 'image or video', adding no new semantics beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource (create a one-hour upload link) plus the constrained scope (image or video, uploaded in-browser while signed in). It also names the follow-up sibling, getUploadLink, so the agent can distinguish this 'prepare upload' step from the retrieval step 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?

Explicitly says when to use it ('for any file the user has, including files shared in this chat') and describes the orchestration sequence: share the URL, wait for the user to confirm, then call getUploadLink. It stops short of stating when NOT to use it or naming an alternative path, so 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?

With annotations already declaring the safety profile (readOnlyHint=false, destructiveHint=false, non-idempotent), the description adds genuinely useful behavior: the URL must be publicly reachable, the media is stored as provided without copying, and human approval is required before publish. It doesn't address retry/idempotency semantics, but the added context is substantive.

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?

Purpose is front-loaded and the sentences are dense with no filler; the semicolon cleanly attaches the upload alternative to the core purpose. Slightly longer than strictly necessary given the approval-workflow sentence could be trimmed, but 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 mutation tool with 16 params and no output schema, the description covers purpose, the upload alternative, storage semantics, and the approval gate, leaving field-level detail to the schema. It omits what a successful call returns (draft/video id) and any failure behavior, which would help an agent chain into publish/schedule.

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 81%, so the schema already documents the URL parameters, aliases, and most fields. The description reinforces the public-URL requirement and 'stored as provided' behavior but adds little that the schema text ('Publicly accessible HTTP(S) video URL') doesn't already say, and it ignores the required contentGroupId and the many optional targeting params.

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 ('Create a video draft from a video URL') plus a scope qualifier ('already publicly accessible') that separates it from generateVideo (which synthesizes media) and from the upload path. An agent can identify the tool without opening the schema.

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

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

It explicitly names the alternative and the condition that selects it: 'for a file the user has, call createUploadLink first.' It also states a workflow precondition (get user approval of destination and timing before scheduling/publishing). It stops short of naming scheduleVideo/publishVideo as the follow-on tools, so the routing is clear but not fully spelled out.

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=false, openWorldHint=true, idempotentHint=false, destructiveHint=false). The description adds almost nothing beyond the action itself: it doesn't say what the edit operates on, whether it persists changes, or how it differs from the deterministic sibling tools.

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 short lines with no padding, and the core action is front-loaded. The leading "Custom edit" line is mildly redundant with the title, but overall it's tight and earns most of its space.

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 3-parameter mutation-style tool with no output schema and low schema coverage, the description is too thin. It leaves the agent without enough to call it confidently alongside its near-duplicate transform siblings.

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

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

Schema coverage is only 33% (only instruction is documented in the schema). The description does not compensate for the undocumented content and contentGroupId parameters, so the agent gets no plain-language help on what to pass or why.

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: apply a free-form natural-language edit to existing copy. The word "free-form" implicitly distinguishes it from the fixed-transform siblings (adjustTone, makeConcise, proofread), 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?

No when-to-use guidance and no routing versus the many sibling transform tools. It does not tell the agent when to pick customEdit over adjustTone, makeConcise, or proofread, which is the exact ambiguity this tool sits in.

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, it discloses several non-obvious traits: output is a new hosted image, existing posts are untouched (reinforcing destructiveHint=false), edits count against the image allowance by model cost, and failed edits are refunded. These billing and non-destructive guarantees are exactly the context 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?

Four short sentences, front-loaded with the core action and free of filler. Minor redundancy: the first line 'Edit an image' merely repeats the title annotation, but the rest of the content 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?

For a mutation tool with no output schema, the description covers the essential behavior: source constraint, return value ('new hosted image'), and cost/refund semantics. The remaining gap is parameter documentation, but the overall picture is sufficient to invoke correctly.

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

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

Schema description coverage is 0% for all three parameters (model, prompt, imageUrls). The description offers only indirect hints ('media library' for imageUrls, 'model cost' for model) and says nothing about the prompt's role, limits, or the multi-image array. It 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?

States a specific verb and resource ('Edit an image') and clarifies it operates on uploaded images via a prompt. It is clearer than a bare name, but it never distinguishes itself from the sibling 'customEdit' nor from 'generateImage', leaving some ambiguity about which editing tool to pick.

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 supplies one real prerequisite ('Source images must be in your PostQuickAI media library'), which is useful. However, there is no explicit when-to-use vs when-not-to-use guidance and no routing to alternatives such as 'generateImage' for new images or 'customEdit', so usage is only implied.

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

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

Annotations already declare non-read-only, non-idempotent, open-world behavior, and the description adds genuinely useful non-structural context: that the call consumes '1 AI text generation' and that brand grounding is optional. It still doesn't say whether the generated caption is persisted or returned only, which is the main remaining gap.

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 short sentences with the key facts front-loaded and no padding. The leading 'Generate a caption' restates the tool name and title, which is minor redundancy rather than bloat.

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 3-parameter generation tool the definition covers cost and grounding, but with no output schema it never indicates what is returned (caption text only, or a saved asset), which is the one thing an agent would need before chaining this into a post-creation flow.

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 all three parameters are already documented in the schema. The description's mention of brand-profile grounding largely restates the contentGroupId schema text and adds no new syntax, defaults, or format detail, so the baseline 3 applies.

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

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

States a specific verb and resource: 'Generate a social media caption with AI.' An agent can tell it produces caption text, but it does not distinguish itself from the closely related siblings generateCarouselCaption and generateVideoCaption, so it is clear without being sibling-differentiating.

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

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

Usage is only implied by the purpose and by the note that grounding in a content group's brand profile is optional. There is no explicit when-to-use guidance and no direction to the carousel/video caption siblings, so the agent must infer routing.

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?

With annotations already declaring readOnlyHint=false, openWorldHint=true, non-idempotent and non-destructive, the safety profile is covered by structured data. The description adds a genuinely useful behavioral trait beyond that: the call consumes 1 AI text generation credit, which matters for quota-aware planning and is not derivable from annotations or schema. It says nothing about what is persisted or returned, which keeps it short of a 5.

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

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

Two short sentences, front-loaded with the action and followed by scope and cost. The opening line duplicates the tool name, which is mild redundancy, but nothing is padded or verbose.

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

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

For a two-parameter AI-generation tool with no output schema and annotations covering safety, the description is minimally adequate: it conveys scope and cost. It leaves open whether the caption is returned to the agent, written to the content group, or needs a follow-up call, which an agent planning a workflow would want to know.

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 both contentGroupId and existingContent are already documented in the schema, and the baseline is 3. The description adds no parameter-level detail, such as whether existingContent is the full prior caption or what happens when it is omitted.

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 (Generate) plus a specific resource (carousel caption), and the second sentence narrows the scope to a multi-slide carousel post, which implicitly separates it from the generic generateCaption and the video-oriented generateVideoCaption siblings. It never names those alternatives explicitly, so the differentiation is inferred rather than stated.

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: 'tailored for a multi-slide carousel post' tells the agent the right context, but there is no explicit when/when-not guidance and no routing against generateCaption, which is the obvious competing sibling for caption text. The cost note is helpful but is not usage guidance.

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

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

The description usefully discloses output behavior: 15 hashtags returned by default, adjustable via count (1-30). Annotations already declare readOnlyHint=false, openWorldHint=true, and non-idempotent, so the generation is opaque/creative by nature. Nothing is contradicted, but auth requirements and whether results persist are unstated.

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 that front-load the core action and then the output/parameter detail. Nearly zero waste, though the title restatement 'Generate hashtags' plus 'AI-generated hashtags' is slightly redundant.

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

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

For a 4-parameter generation tool with no output schema and only 25% schema coverage, the description covers count and platform adequately but leaves contentGroupId and the nature of the content input unexplained. Adequate but with clear gaps.

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

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

Schema coverage is only 25% (platform is the lone documented property). The description compensates for count by stating the 1-30 range and default, and gestures at platform semantics, but says nothing about contentGroupId or what content should contain.

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 clear verb+resource ('Generate hashtags') and clarifies these are AI-generated and optionally platform-targeted, which cleanly separates it from siblings like generateCaption or generateImage. It does not name a sibling directly, 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?

'Optionally optimized for a target platform' implies the platform parameter's purpose, so usage is inferable. However, there is no explicit guidance on when to prefer this over siblings or on prerequisites (e.g., whether content is required context).

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

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

Annotations declare a non-read-only, non-destructive, non-idempotent, open-world operation, and the description adds context those hints cannot carry: the call has a metered cost tied to the model's image allowance, the result is hosted (not posted to any account), and no publishing side effect occurs. It doesn't say whether repeated calls reuse or duplicate assets beyond the idempotency hint, leaving one small gap.

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, zero filler, with the primary action and return value front-loaded and the cost/selection guidance plus scope clarification trailing. Every sentence earns its place.

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

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

With no output schema, the description carries the return-value burden and does so ('hosted imageUrl'), and it also covers selection guidance, cost awareness, and the no-side-effect guarantee. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, and the description goes slightly beyond it by explaining where the model id comes from (GET /v1/models?kind=image / listModels) and that the choice affects cost. Prompt is left to the schema's own text, so this is not a full 5.

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 ('Generate an AI image from a prompt') plus the concrete output ('hosted imageUrl'), which separates it from editImage, customEdit, generateVideo and createVideo without opening a schema. The downstream consumers (createPost/patchPost) are named, so its place in the workflow 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?

Gives a clear pre-step ('Use listModels with kind=image to choose a model and check its image allowance cost') and an explicit boundary ('Nothing is posted'). It doesn't contrast against the obvious alternative editImage for modifying an existing image, so it stops short of 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 the non-destructive, non-idempotent, open-world profile, and the description stays consistent with them. It adds real context beyond the annotations: the result is persisted to the media library as a hosted WAV, nothing is published or mutates video, and there is no separate credit allowance with normal API rate limits applying.

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 core action, then adds scope and constraint sentences that each carry information. Minor redundancy between the title-like first line and the opening of the second sentence, but no filler overall.

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 four-parameter generative tool with no output schema and zero schema descriptions, the description omits the most decision-relevant facts: what the parameters mean, sensible value ranges, and any cost/latency expectations beyond rate limits. The safety and side-effect story is covered, but an agent still cannot call this 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 description coverage is 0% across four parameters (prompt, mood, bpm, duration) with no descriptions in the schema, so the description carries the full burden. It mentions no parameter at all — nothing about how prompt text should be phrased or how bpm/duration/mood are interpreted — leaving all four 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+resource ('Generate background music') and names the underlying service and the concrete artifact produced ('hosted WAV in your media library'). This clearly separates it from siblings like generateVideo, generateImage, and generateCaption.

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?

'Does not publish or change any video' implies a negative scope, so an agent knows this is a standalone asset-generation call rather than part of a publish flow. However, it never says when to reach for this versus generateVideo/mixVideoAudio, nor what prerequisites (e.g. brand context, model selection) are needed.

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

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

Annotations already establish this is a non-readonly, non-idempotent, open-world write, so the bar is lower. The description adds genuinely useful context beyond that: generation consumes credits (a cost the agent must confirm with the user), and the finished video lands as a draft rather than being published. It implies async execution via the getVideoStatus pointer but never states that the call returns immediately.

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

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

Four short sentences with zero filler. The core action is front-loaded, followed by model selection, cost confirmation, and result tracking in the order an agent would actually need them.

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

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

For an async generation tool with no output schema, the definition covers the important post-call reality (draft, unpublished, poll with getVideoStatus). The one gap is that it never says what the call itself returns, such as a job or video identifier that getVideoStatus would consume.

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 80%, so the schema already documents model ids, defaults, supported durations, and the aspect-ratio enum. The description adds no parameter syntax or format detail beyond what the schema provides, so the baseline of 3 applies.

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

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

The description opens with a specific verb and resource: 'Start AI video generation from a prompt.' That is unambiguous about what the tool does, and it implicitly separates itself from publishVideo by stating the output is a draft. It does not, however, distinguish itself from the similarly named sibling createVideo, which an agent could easily confuse it with.

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 explicit prerequisites and routing: use listModels with kind=video to check models, supported lengths, and credit costs, confirm the model and cost with the user first, and check progress with getVideoStatus. Both the model-selection step and the progress-tracking alternative are named concretely, so nothing is left to inference.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true and non-idempotent, so the safety profile is covered. The description adds cost/consumption context the annotations cannot convey — 'Counts as 1 AI text generation' — which is directly relevant to an agent deciding whether to call it. It stops short of describing what downstream state changes (if any) occur.

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?

Short and front-loaded, with platform targeting and cost placed after the core purpose. The first line 'Generate a video caption' largely restates the tool name and the following sentence, a minor 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?

For a 3-parameter, no-output-schema generation tool, the description covers purpose, platform optimization, and credit cost — enough to call it correctly. It could improve by naming the sibling it replaces and by clarifying whether it only returns a draft or also persists anything.

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

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

Schema coverage is 67%, and the two documented parameters (contentGroupId brand grounding, existingContent as an improvement target) already carry their meaning in the schema. The description adds no parameter-level detail and leaves videoTitle entirely unexplained in both places, 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?

Specific verb+resource ('Generate a video caption') with concrete scope: short-form vertical video platforms (TikTok/Reels/Shorts) and output style (hooks, CTAs). It distinguishes itself somewhat from generateCaption by the 'video' qualifier, but never explicitly contrasts with the sibling generateCaption or generateCarouselCaption, so an agent must infer the boundary.

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 rather than stated: 'for a video post' signals the context in which to pick this over generic captioning. There is no explicit when-not guidance and no named alternative (generateCaption, generateCarouselCaption) despite three near-identical siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context: data is populated by a daily cron, so freshness is bounded to one day, and the response contains both history and a latest snapshot. It stops short of stating pagination or what happens if an account was only recently connected.

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

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

Three short sentences with the resource stated first and the return shape second; nothing is wasted. Minor redundancy: 'connected account' is repeated as 'connected social account' in the next sentence.

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 explaining the return payload and does so ('daily follower-count history ... plus the most recent snapshot'). Combined with the cron-freshness note, an agent has enough to call it correctly; only freshness edge cases and account prerequisites are 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%, so the schema already documents both 'days' (default 30, clamped to [1,365]) and 'accountId'. The description only adds that the series is daily, which lightly clarifies how 'days' is interpreted, but adds no syntax or format detail beyond the schema. 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 resource (daily follower-count history for a connected social account) and a concrete output (history plus most recent snapshot). It is clear what the tool does, though it never contrasts itself with adjacent tools like getAccountHealth or getAnalyticsOverview, which an agent might reasonably consider for the same goal.

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 a use case ('tracking growth over time without scraping public profile pages'), which is implied guidance rather than an explicit when/when-not rule. No alternatives are named and no prerequisites (e.g., the account must be connected and cron-populated) are stated as conditions for choosing this over getAnalyticsOverview.

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 readOnly/idempotent annotations, it discloses genuinely useful behavior: no secrets are returned, stale or absent validation surfaces as 'unknown', and no active validation or reconnection occurs. This is real added context, though it says nothing about result shape or limits.

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

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

Three tight sentences that front-load the capability and then add the important caveats about staleness and side effects. No filler, though the opening 'Get connection health' fragment is slightly redundant with the following sentence.

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 does describe the substance of the return (token health, missing permissions, unknown status), which is a plus. But for a health-check tool the undocumented contentGroupId parameter and lack of any indication of result structure leave a meaningful gap.

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 contentGroupId is never mentioned in the description. The agent gets no hint whether the UUID scopes the health check to one content group or is optional context, 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 states a specific verb and resource: read saved token health and missing social permissions for connected accounts. It is clearly distinct from listAccounts or getAccountFollowers, though it never explicitly names a sibling to differentiate itself from.

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 a clear exclusion — 'does not actively validate or reconnect accounts' — which tells the agent this is a passive read, not a fix. However, it names no alternative for agents that actually want to revalidate or reconnect, so the when-to-use routing is only implied.

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, non-destructive and closed-world, so the safety profile is covered. The description earns credit for adding a genuine data-quality caveat — 'No available metrics is missing data, not proof of zero performance' — which changes how an agent should interpret empty results. It omits anything about freshness/sync timing (relevant given a refreshAnalytics sibling) or result size.

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 short blocks, front-loaded with the purpose and then the payload contents plus caveat; every sentence contributes. The opening line duplicates the annotation title verbatim, which is mildly redundant but functions as a headline.

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

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

With no output schema, the description usefully enumerates what comes back (platform totals, top posts, follower counts, daily trends) and warns about absent metrics. What's missing is any treatment of the period parameter or data-freshness expectations for an 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 0%, so the description carries the burden for the single 'period' enum parameter, and it says nothing about it — no window semantics, no interaction with 'daily trends' granularity, no hint that the ranges are capped at 90d. The enum values are largely self-explanatory, which keeps this above a 1.

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 (compare/read) and resource (social performance) and scopes it to all content groups, which distinguishes it from per-group/per-post siblings like getGroupAnalytics and getPostAnalytics. It stops short of naming those siblings explicitly, so an agent must infer the boundary.

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?

Scope wording ('across all your content groups', 'compare across brands') implicitly signals this is the aggregate/cross-brand view rather than the per-group or per-post analytics tools. However, there is no explicit when-to-use statement, no exclusion of the sibling analytics tools, and no prerequisite 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, openWorldHint=false), so the bar is lower. The description adds genuinely useful context beyond them: the call returns a stored profile plus website URL and performs no crawl or scan, which tells the agent there is no network fetch or side effect.

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 short sentences, front-loaded with what is returned and followed by the key negative constraint. Every sentence earns its place with no filler.

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

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

With no output schema, the description must convey the return value, and it does (saved brand profile and website URL). For a one-parameter read-only tool this is nearly complete; only finer detail about the profile's fields is absent, which is a minor gap.

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 (groupId) with 100% schema description coverage, so the schema already documents it as the content group UUID. The description only adds the qualifier that the group must be 'owned', which is marginal added meaning beyond the schema 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?

States a specific verb (Get) and resource (saved brand context / brand profile and website URL) scoped to an owned content group. It also implicitly distinguishes itself from the sibling scanWebsite by clarifying that it does not crawl or scan the website, 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?

The description gives clear context: this is the read path for an already-saved brand profile tied to an owned content group, and it explicitly excludes crawling/scanning. It stops short of naming scanWebsite as the alternative when a fresh scan is desired, so routing is implied rather than spelled out.

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, and non-destructive, so safety is covered. The description does add genuine behavioral context (93-day max range, timezone-qualified timestamps, pagination), but it references 'nextOffset' while the actual schema field is 'offset' — a naming mismatch that can mislead an agent invoking the tool.

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

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

Front-loaded with the tool's purpose and kept to three tight sentences. The opening line slightly duplicates the title, but otherwise every sentence contributes concrete 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?

No output schema exists, but the description adequately characterizes the return (timezone-qualified scheduled items) and scoping. It falls short only on the limit parameter and the offset naming inconsistency, leaving minor gaps for a read-only tool.

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

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

Schema description coverage is 0%, so the description carries full burden for 5 parameters. It conveys the date-range concept and alludes to content groups and offset paging, but never explains start/end format, the limit default/max, or the offset default — and it renames offset to 'nextOffset'.

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 clear verb+resource combination: read scheduled posts, videos, and stories aggregated into a publishing calendar. The 'across your owned content groups' scope meaningfully distinguishes it from the granular listPosts/listStories/listVideos siblings, 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?

Only guidance offered is 'Use nextOffset to page through busy calendars', which implies usage for large result sets but doesn't say when to prefer this over siblings like listPosts or getGroupAnalytics. No when-not conditions or 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. The description adds genuine behavioral value by disclosing the payload composition — associated platforms, social accounts, and brand instructions — which tells the agent what it will actually receive.

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 short sentences, front-loaded with the action verb and with no filler. The second sentence partially restates the first ('a single content group') before adding the useful payload detail, a minor redundancy that keeps it below a 5.

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 present, the description's enumeration of returned fields (platforms, social accounts, brand instructions) is the only source of return-value information, and it supplies that adequately. Combined with annotations covering the read-only/idempotent profile and a fully documented single parameter, the definition is nearly complete for a simple getter.

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 exists (groupId) and schema description coverage is 100%, with the UUID meaning fully documented in the schema. The description adds no additional meaning about the identifier, so the baseline of 3 applies.

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

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

The description gives a specific verb+resource ('Retrieve a content group') and clarifies scope by saying it returns 'a single content group', which implicitly separates it from the sibling listContentGroups. It does not, however, name that sibling or any other alternative 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, no statement of prerequisites, and no mention of when to prefer listContentGroups (bulk) or updateContentGroup (mutation) instead. Usage is only inferable from the verb.

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 without the description. The description adds result-shape context (platform/content-type breakdown, top posts, daily trend), which is useful, but discloses no behavioral traits such as rate limits, auth requirements, or how 'top posts' are ranked.

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 scope and then the breakdown contents; nothing is wasted. The leading 'Group analytics' header is a minor restatement of the tool name, which keeps it just below a 5.

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 analytics tool with full schema coverage and safety annotations, the description supplies the aggregation scope and a sketch of the return contents (platform, content type, top posts, daily trend), which is valuable given there is no output schema. It stops short of naming the sibling tools or clarifying cost/pagination behavior.

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%, with limit, period, postsLimit and groupId all documented in the schema itself (including the limit/postsLimit alias precedence rule). The description adds no parameter-level meaning, so the baseline 3 is appropriate.

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

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

The description states a specific verb+resource ('Aggregate social performance analytics for all posts in a content group') and scopes it to a group, which implicitly distinguishes it from getPostAnalytics (single post) and getAnalyticsOverview (account level). It never names those siblings explicitly, so the differentiation is left to inference.

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

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

Usage is only implied by the scope phrase 'all posts in a content group'; there is no explicit when-to-use, when-not-to-use, or pointer to getPostAnalytics/getAnalyticsOverview/refreshAnalytics. An agent can infer the right context from the scope, but nothing 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 the full safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false), so the behavior contract is covered. The description adds the returned field set, which is genuinely useful given there is no output schema, but it does not disclose anything beyond payload contents (no error behavior for a missing group, no auth notes).

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 the action and immediately followed by the concrete contents of the response. No filler; the only mild redundancy is the restated 'Get brand instructions' header.

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-param read tool whose annotations cover the safety profile and which has no output schema, the description compensates well by enumerating the returned fields. It is only missing the disambiguation from sibling getters and any failure-mode context, which keeps it short of a 5.

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 with 100% schema description coverage; the schema already documents groupId as the content group UUID with a pattern constraint. The description adds no syntax or format meaning beyond the schema, 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 ('Get') and resource ('brand instructions'), and expands it with the exact payload fields (brand profile, generation settings, tone, auto-generation flags, YOLO mode). The purpose is unambiguous on its own, but it never distinguishes itself from similarly named siblings like getBrandContext or getContentGroup, so an agent cannot route confidently between them.

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 prerequisites, and no mention of alternatives such as getBrandContext or getContentGroup. The agent is left to infer from the name alone when this tool is the right choice.

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 by structured data. The description adds nothing beyond that – no note on what fields come back, whether a missing ID errors, or any auth/access scope. It is pure restatement.

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?

Short and front-loaded, but the two sentences are near-duplicates: 'Retrieve a post' and 'Fetch a single post by ID' convey the same fact. The second sentence only earns its place for the 'single/by ID' qualifier, so this is efficient but partly redundant.

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

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

For a one-parameter read tool whose annotations already cover the safety profile, the description is minimally sufficient. However, with no output schema, it gives no hint about the returned post shape or behavior when the ID does not resolve, leaving minor gaps.

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

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

There is a single parameter with 100% schema description coverage ('Post ID', plus a pattern constraint), so the schema carries the full burden. The description says 'by ID' but adds no new meaning such as ID source or format. Baseline 3 is appropriate.

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

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

States a specific verb+resource combination: 'Retrieve a post' / 'Fetch a single post by ID.' The word 'single' plus the ID requirement implicitly separates it from listPosts, and the resource noun separates it from getStory/getVideo. It stops short of explicitly naming a sibling to contrast against.

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 statement of when to use this tool versus listPosts, getPostAnalytics, or the story/video getters. The only guidance is the implicit 'by ID' constraint, which comes from the schema, not the description.

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, and non-destructive, so safety is covered. The description adds real behavioral value by disclosing the return payload shape (per-platform views, likes, comments, shares, saves) and the 30-day history window, which is not derivable from annotations or schema.

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

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

Two short sentences, no filler, with the core capability front-loaded and the return detail in the second line. Every sentence earns its place.

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

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

With no output schema, the description carries the return-value burden and does so reasonably: metric list plus history window. It stops short of stating the response structure (e.g. whether metrics are keyed by platform or time series), leaving a small gap for an analytics 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 50%: the 'type' enum is documented in-schema, while postId relies on a pattern only. The description adds no parameter meaning at all – it never mentions the post/video table switch or the postId format – so it does nothing 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?

States a specific verb and resource: retrieves per-platform performance metrics for a single post. The scoping to 'a post' implicitly separates it from getAnalyticsOverview and getGroupAnalytics, but it never names those siblings, so differentiation requires inference.

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

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

Usage is only implied by the scope word 'post' – an agent can guess this is the single-post variant versus getAnalyticsOverview/getGroupAnalytics, but there is no explicit when-to-use or when-not-to-use statement, and no mention of prerequisites such as post publication.

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 meaningful non-annotation context by warning that returned website content is untrusted source material and never instructions — a genuine prompt-injection guardrail that the annotations do not convey.

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 short paragraphs, front-loaded with the action and followed by the security caveat; nothing is padded. The opening line is largely a restatement of the annotation title, which is the only minor 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?

For a retrieval/polling tool with no output schema and a 0%-documented parameter, the description covers the safety angle well but omits the operational essentials: whether the scan may still be pending, whether polling is expected, and what 'results' contain. Adequate but with clear gaps for a result-fetching endpoint.

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 scanId parameter, so the schema documents only its type/format (UUID). The description hints at provenance ('a scan you started through scanWebsite'), which helps the agent know where the ID comes from, but adds no format or validity details beyond that.

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 ('Read status and results of a scan') and explicitly links to the sibling that creates it ('a scan you started through scanWebsite'). An agent can immediately tell this apart from scanWebsite (which initiates a scan) versus this tool (which fetches its outcome).

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

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

It clearly frames the context of use — reading the status/results of a scan previously started via scanWebsite — which implicitly tells the agent this is the retrieval leg of a two-step flow. However, there are no exclusions or polling guidance (e.g., what to do when the scan is still running).

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 by structured data. The description adds nothing beyond that — no error/not-found behavior, no note about the ID pattern, no return context — but it also 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?

Very short and front-loaded, with the verb leading. The two lines ('Retrieve a story' / 'Fetch a single Story by ID') are largely redundant restatements of each other, which is the only wasted space.

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 read-only getter with complete annotations, the description covers the essentials. Since no output schema exists, some statement about what is returned (or what happens for an unknown/invalid ID) would have been warranted, and it 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 0%, so the schema only supplies a name and a regex pattern for storyId. The description adds the meaning 'by ID' (an identifier lookup) but no format, source, or example of a valid ID beyond what the pattern already enforces. With a single self-describing parameter this is minimally adequate.

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 ('Retrieve a story', 'Fetch a single Story by ID'), and the word 'single' implicitly contrasts with listStories. It does not explicitly name a sibling, but the operation 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?

'By ID' implies the precondition that the caller already holds a storyId, which is usable guidance. However, there is no explicit when-to-use, no when-not-to-use, and no named alternative among the many story-related siblings (listStories, updateStory, getPost, getVideo).

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, and non-destructive. The description adds value by disclosing the two status states and the handling for each, which is behavior beyond the safety annotations. With no output schema, it partially covers the return contract.

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

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

Three tight sentences, front-loaded with the action and followed by the two conditional outcomes. Every sentence earns its place with no filler.

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

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

With no output schema, the description must convey return semantics, and it does by naming status and mediaUrl and their downstream use. It could clarify the full set of possible status values, but it is complete enough to call correctly.

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

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

Schema description coverage is 100% for the single uploadId parameter, so the schema already carries the semantics. The description adds no additional syntax or format detail about uploadId beyond what the schema provides, making the baseline 3 appropriate.

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

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

States a specific verb and resource ("Check an upload link") and implies the read-vs-create split against its sibling createUploadLink. It stops short of naming createUploadLink directly, but an agent can distinguish the polling step from the link-creation step.

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 clear workflow context: check status, and if "uploaded" pass mediaUrl downstream; if "pending" prompt the user. This tells the agent both when to use it and what to do next, though it does not explicitly contrast with createUploadLink.

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 read-only safety profile is fully covered. The description adds only that the lookup is by a single ID; it says nothing about permissions, behavior on missing/invalid IDs, or what is returned, so it barely exceeds the annotation baseline.

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 short, front-loaded sentences with no filler. They are, however, near-synonymous ('Retrieve a video' / 'Fetch a single video post by ID'), so one sentence would have carried the same 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?

For a single-ID getter with no output schema and full annotation coverage, the definition is minimally viable. It omits failure behavior and any hint of the returned video shape, which an agent calling this in a pipeline would benefit from knowing.

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

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

There is one required parameter with 0% schema description coverage, so the schema documents nothing beyond type and a pattern. The phrase 'by ID' confirms the videoId is a lookup key, which adds minor meaning, but no format, example, or accepted-ID guidance is provided 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?

States a specific verb and resource ('Retrieve a video', 'Fetch a single video post by ID'), and 'single ... by ID' implicitly separates it from listVideos and getVideoStatus. However, it never names or routes against those sibling getters, so the differentiation is left to inference.

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

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

No when-to-use guidance and no exclusions. With siblings like getVideoStatus, getPost, and listVideos present, the definition should say when this retrieval is appropriate versus a status check or a list call, but it offers nothing.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description instead earns credit for non-obvious response semantics: the snapshot lives under `data.video`, not flat `data`, and `data.video.publishing` is authoritative over the legacy `video.status`. It stops short of disclosing auth needs, polling/freshness behavior, or error states for a still-generating video.

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?

Purpose is front-loaded in the first line, followed by dense, non-repetitive detail about where the payload lives and how to read publishing state. Every sentence carries information; the parenthetical '(not a flat `data` object)' is slightly clunky but warranted given no output schema.

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

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

With no output schema, the description carries the return-value burden well: it specifies the nesting path, the per-platform publishing fields, `retryable`, and the legacy status enumeration with its resolution rule. It omits the generation-side status values and any polling/freshness guidance, so it is strong but not exhaustive.

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 description says nothing about `videoId` — not its format, not where it comes from, not what happens if it is unknown. The rule for sub-50% coverage is that the description must compensate, and here it adds zero meaning beyond the parameter's self-evident name.

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

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

The first line gives a specific verb+resource pair ('Check video generation and publishing status'), so an agent immediately knows this is a read-only status probe rather than a mutation. It does not, however, contrast itself with the sibling getVideo or listVideos, which an agent might reasonably confuse with a status-check tool.

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

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

There is no explicit 'use this when...' statement or named alternative. The note that '`retryable` determine[s] retry safety' implicitly signals this should be consulted before retryVideoPublish, and the publishing source-of-truth guidance implies post-publish checks, but both must be inferred rather than read.

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

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

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful scope detail by enumerating platforms and stating that accounts are gathered across all content groups, but it does not mention pagination, ordering, or authentication requirements.

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

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

The description is two sentences, front-loads the tool's purpose, and then elaborates on the return scope. The platform enumeration is useful and does not read as 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 simple, no-parameter, read-only listing tool with no output schema, the description is nearly complete. It states the resource and scope, but could mention whether results are paginated or ordered, which leaves a minor gap.

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?

This tool has zero input parameters, so the baseline is 4. The empty schema means there are no parameter semantics to document, and the description appropriately avoids discussing 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?

The description states a specific verb and resource: list connected social accounts. It enumerates the supported platforms and clarifies the scope as all of the user's content groups, distinguishing it from sibling listing tools such as listContentGroups, listMedia, and listPosts.

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 explains what the tool returns but does not say when to use it, when not to use it, or which alternative tool to choose. No usage context or 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 readOnly, idempotent, non-destructive, and closed-world, so the safety burden is covered. The description adds real value by defining the result set (every group owned by the authenticated user) and the domain term, but says nothing about ordering, pagination, or result shape.

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 short lines with zero filler: the action first, then the definition and scope of what comes back. Every sentence earns its place.

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

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

For a no-parameter, annotation-covered list tool with no output schema, the description supplies what an agent needs to choose and call it. Only pagination or ordering behavior is unaddressed, a minor gap for a small owned-collection list.

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?

Zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The scope sentence usefully confirms the implicit filter is the authenticated user rather than any request 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?

Specific verb+resource ("List content groups") plus a clarifying gloss that a content group is an "app" — one per brand/project — scoped to the authenticated user. It implicitly contrasts "every" group against the singular getContentGroup sibling, but never names it or any other sibling 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?

No statement of when to use this rather than getContentGroup, updateContentGroup, listAccounts, or getGroupAnalytics. The only routing signal is the scope phrase "owned by the authenticated user," which is context rather than 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 safety is covered. The description adds genuine behavioral context beyond that: results are name-ordered consistently (a stable sort guarantee) and the listing includes files nested inside upload folders, plus the cursor-based paging mechanism.

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 the scope front-loaded before the pagination note. There is mild redundancy between the header line 'List saved media' and the opening clause 'List your saved images, videos, and audio', but the second sentence carries new information rather than 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, three-parameter list tool with no output schema, the description covers scope, ordering stability, and paging, which is most of what an agent needs. It omits the response shape and whether any auth/account context is required, but those are minor for this tool class.

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 33% — only 'cursor' is documented, as 'Opaque nextCursor from the previous page; keep the same filters.' The description reinforces the cursor flow but adds nothing about 'type' filtering semantics or the 1–100 'limit' bound, so it only partially compensates 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?

States a specific verb and resource ('List saved media') and enumerates the covered media kinds (images, videos, audio) plus upload-folder contents, which meaningfully separates it from the narrower listVideos sibling. It stops short of naming siblings explicitly, so an agent must infer the boundary with searchMedia/listVideos.

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 'List your saved images, videos, and audio, including files inside upload folders' — the agent can infer this is the broad saved-media enumerator — but there is no explicit when-to-use versus searchMedia or listVideos, and no exclusions. The only guidance given ('use nextCursor for subsequent pages') concerns pagination, not tool 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds real behavioral context beyond that: results are paged, ordered newest-first, include short descriptions and real prices, and paging requires reusing the same kind and search values.

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?

Purpose and ordering are front-loaded and the pagination rule follows logically. Mostly efficient, though 'Cost follows each model's real price' is a redundant restatement of 'what it costs'.

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-shape burden and does so adequately: each item has a name, short description, and cost, sorted newest-first and paged. An agent has enough to call it and continue paging correctly.

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

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

Schema coverage is 75% with limit, offset, and search already documented. The description adds a cross-parameter constraint not in the schema: when following nextOffset you must keep kind and search unchanged, which is genuinely useful for correct pagination.

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 image or video models') and clarifies these are generation models currently available. It differentiates reasonably from generateImage/generateVideo, though it does not explicitly separate itself from the similarly named listMedia or listVideos 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?

Usage is implied (browse model catalog with descriptions and costs) and pagination workflow is spelled out, but there is no explicit statement of when to use this versus listMedia/listVideos or when-not to use it. Adequate but leaves sibling selection to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and a closed-world scope, so the safety profile is fully covered by structured data. The description adds only the 'owned content group' ownership constraint; it says nothing about pagination flow, result volume, or what a page contains beyond what the cursor/limit schema fields 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?

Two short sentences with no wasted prose, and the required-scope constraint plus the usage hint are front-loaded. The leading line 'List posts' merely restates the name/title, a small redundancy, but the body is tight.

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 should at least hint at the shape of a returned page, but it never does. Cursor-based pagination is covered by the schema's cursor field, so the only real gap is the return payload, leaving the definition adequate but not complete.

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

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

Schema description coverage is 100%, so limit, cursor, status and contentGroupId are all fully documented in the schema, including pagination mechanics and the status enum semantics. The description adds no parameter detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('List posts') and scopes it to a required owned content group, which an agent can distinguish from the single-post getPost sibling implied by 'before acting on a specific one'. It never names a sibling explicitly, so differentiation rests on inference rather than direct routing.

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?

'Use this to enumerate posts before acting on a specific one' gives a clear workflow context for when to reach for this tool versus acting on an individual post. It offers no exclusions or named alternatives among the many sibling list tools (listStories, listVideos, listMedia), so it stops short of the top band.

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

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

Read-only, idempotent, and non-destructive behavior is already declared by annotations, so the description doesn't need to restate safety. It adds the content-group scoping constraint, but says nothing about ordering, result size, or how the opaque cursor interacts across pages beyond what the schema already notes.

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?

Short and front-loaded, with the scoping requirement stated first. The first line ('List stories') largely duplicates the tool title, so there is minor redundancy, but nothing is padded out.

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 filtered-list tool with read-only annotations and full schema coverage, the description is adequate. With no output schema, however, it offers no hint about the return shape (array of stories, pagination semantics), which an agent would need to infer.

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 limit, cursor, status, and contentGroupId are all already documented in the schema — including the rich 'partial' status explanation. The description's status example adds only marginal value on top, so the baseline of 3 applies.

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

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

The description states a specific verb and resource ('List stories for a content group') and names the required scoping parameter, so an agent knows it returns a collection of stories rather than a single one. It does not explicitly contrast itself with listPosts or getStory, but the distinct resource makes the intent clear.

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 conditional usage hint ('Filter by status if you only need a subset, e.g. status=scheduled'), which is genuinely useful. However, it never says when to reach for this tool versus getStory, listPosts, or listContentGroups, so alternative selection is left to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds only that results are scoped to a content group; it says nothing about pagination behavior or result volume, which the cursor parameter implies but the prose never confirms.

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 short sentences, front-loaded with the resource and scope, and the filtering hint follows immediately. The leading 'List videos' line is a redundant echo of the name and title, which is the only waste.

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

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

For a simple read-only list tool with 100% schema coverage and no output schema, the definition covers the required scope and the main filter. It is quiet on pagination (cursor/default 50) and on the shape of returned video records, but those gaps are minor 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 100%, so limit, cursor, status, and contentGroupId are fully documented in the schema itself. The description only echoes the status filter with an example and restates the content-group scoping — no syntax or semantics beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource: list video posts (Reels) scoped to a content group. The parenthetical '(Reels)' and the content-group scoping help separate it from listPosts and listStories, though no sibling is named 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?

Gives one concrete usage hint — 'Filter by status if you only need a subset (e.g. status=scheduled)' — but never states when to choose this over listPosts, listMedia, or getVideo, nor any prerequisites. Usage is implied rather than routed.

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, openWorldHint=true), so the bar is lower. The description adds one meaningful behavioral guarantee — 'preserving meaning' — but says nothing about output length guarantees, whether the result is returned or applied, or any limits.

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 short sentences, front-loaded with the purpose and followed by the use case. The leading 'Make concise' line duplicates the tool name and title, which is minor waste.

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

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

For a one-parameter text transformation with no output schema, the description is minimally sufficient — an agent can call it — but it omits what the return value looks like (rewritten text vs. confirmation) and whether any length target is honored, which matters given the 280-char framing.

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 'content' parameter, so the schema carries no semantics. The description's word 'copy' implies the input is the text to be tightened, which partially compensates, but it never confirms that 'content' is the text payload versus, say, a target length.

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+resource: tightening copy while preserving meaning. It implicitly distinguishes itself from neighbors like proofread (correct errors) and adjustTone (change tone), though it never names them. Clear but not explicitly differentiated from siblings.

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

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

One concrete scenario is given ('Useful for Twitter/X 280-char limit'), which implies when to reach for it, but there is no when-not guidance and no named alternative among the many text-transformation siblings (proofread, adjustTone, customEdit).

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 (destructiveHint=true, idempotentHint=false), the description discloses that rendering happens at publish time via the existing publisher, that no pre-rendered preview is returned, that original video duration is preserved, and that the change propagates to scheduled videos. These are non-obvious behavioral traits an agent must know before invoking a destructive edit.

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 purpose is front-loaded in a one-line summary, followed by scoping and warning sentences that each add information. Slight redundancy between the title line and the first body sentence, but overall tight for the amount of behavior disclosed.

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 destructive mutation tool with no output schema, the description adequately explains lifecycle behavior (publish-time render, scheduled-video impact) but leaves most of the 10-parameter surface undocumented, so an agent cannot confidently set volume, fade, loop, or start-time options from the definition alone.

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% across 10 parameters, so the description carries the full burden, yet it only indirectly covers 'mode' (mixing vs. replacement) and constrains audioUrl to a hosted library file. Eight parameters (fadeIn, loopAudio, trackName, audioVolume, audioStartTime, originalVolume, videoStartTime) get no semantic explanation anywhere.

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 concrete verb and resource ('Attach background audio to a video', 'Configure audio mixing or replacement on an unpublished video'), which is specific enough to separate it from generateMusic, generateVideo, or adjustTone. It clarifies that this edits an existing video rather than creating one, but never names a sibling tool directly.

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 real preconditions: the video must be unpublished, the audio must already be a hosted file in the user's own media library, and scheduled videos will pick up the change so the agent should confirm first. It stops short of naming alternative tools for related needs (e.g., generating music or editing an already-published video).

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, idempotentHint=false and the title 'Edit an unpublished post'. The description adds value beyond them by disclosing the refusal condition for published posts and the side effect that editing a scheduled post alters what will ultimately be published. It stops short of describing auth requirements or the response shape.

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 behavior and constraint, then the caution and the alternative. No filler or restated schema content.

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

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

There is no output schema and annotations are modest, yet the description covers the highest-risk behavioral question (which posts may be edited and what editing a scheduled post implies). With 9 parameters at 33% schema coverage, the description leaves meaningful parameter-level gaps that keep it from being fully complete.

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

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

Schema coverage is only 33% across 9 parameters, so the description carries the burden of compensating and does not: content, imageUrl, postType, imageUrls, platforms, threadParts, facebookTarget and linkedinTarget are unexplained in both places. The phrase 'only the provided fields' signals partial-update semantics, which is useful, but no field meaning or inter-field rules are added.

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 (change only the provided fields) and a precise resource (draft or not-yet-published post), matching the PATCH-style partial-update contract. The publication-state constraint cleanly separates it from publishing/scheduling siblings like publishPost and schedulePost.

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 names when the tool is valid (draft/unpublished), when it is refused (already-published posts), an alternative for a related need (schedulePost for timing), and a confirmation prerequisite for scheduled posts. An agent has everything needed to route correctly.

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, openWorldHint=true, idempotentHint=false and destructiveHint=false, so the safety profile is covered. The description adds one genuine behavioral trait beyond them – that voice and style are preserved in the output – but says nothing about what is returned, whether the operation consumes credits, or any length constraints.

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 short lines with no filler and the key constraint front-loaded. The leading 'Proofread' heading merely restates the tool name and title, which is minor redundancy rather than bloat.

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 should clarify what comes back (the corrected text, a diff, a list of edits) and whether the original content is returned or replaced. It also omits any input size limits. For a text-transformation tool this leaves real gaps, though the core behavior is conveyed.

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 'content' parameter, so the description would need to compensate but does not mention it at all. The parameter's meaning (the text to proofread) is trivially inferable from the tool name and required-string schema, so this is adequate rather than poor.

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 concrete operation (grammar and spelling fixes) and states a scoping constraint (preserving voice and style), which implicitly separates it from siblings like adjustTone or makeConcise. It is clear what the tool does, though it never names an alternative tool 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, no exclusions, and no mention of the many adjacent text tools (adjustTone, makeConcise, customEdit, convertToStory). The agent must infer that this is the correct tool for pure grammar/spelling correction from the purpose sentence alone.

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?

With annotations only flagging this as destructive/non-idempotent/open-world, the description supplies the missing operational truth: it publishes only to unreached destinations, keeps already-published content unchanged, returns acceptance rather than delivery confirmation, and forbids new keys on uncertain retries. That is exactly the context the hints cannot convey.

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 approval precondition and publishing scope are front-loaded, and each following sentence adds a distinct, actionable fact (idempotency, response semantics, polling, retry rule) with no filler.

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

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

There is no output schema, and the description compensates by defining the return as acceptance only and routing the agent to getPost for real results. Combined with partial-publish and idempotency semantics, an agent has everything needed to call and interpret this correctly.

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

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

Schema coverage is already 80%, so the bar is met by the schema alone, but the description adds real meaning: the platforms list is effectively filtered to destinations not yet reached, and the Idempotency-Key must be one per approved request and reused with identical settings. It still does not explain facebookTarget/linkedinTarget selection, which is left entirely to the schema.

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

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

The description gives a specific verb and resource ('publish now' a content group's drafts to specified social destinations) and scopes it to destinations the content has not already reached. It implicitly separates itself from scheduling siblings via 'publish now' and from read paths by pointing at getPost, but never names schedulePost or publishStory/publishVideo 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?

It states a clear precondition ('after the user approves the content group, draft and exact social destinations') and a clear follow-up path ('poll getPost for platform IDs and results'), plus a hard retry rule. It stops short of explicit when-not-to-use guidance, e.g. that this is not the tool for scheduling or for stories/video.

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

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

The description adds substantial behavioral context beyond the annotations: it requires prior user approval, explains idempotency-key reuse after lost responses, warns that acceptance does not confirm delivery, instructs polling via getStory, and cautions against retrying uncertain outcomes with a new key. These details are exactly the kind of retry, safety, and side-effect information an agent needs for a destructive open-world publish operation.

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

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

The description is dense and front-loads the key action and prerequisite. Every sentence carries operational information, though the phrasing around reusing the same ID while keeping published content unchanged is slightly ambiguous and could be tightened.

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

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

For a complex publish operation with no output schema and nested parameters, the description covers prerequisites, idempotency, retry safety, and result polling. It does not explain platform-specific nested settings such as facebookTarget or tiktokSettings, but it is otherwise complete enough for an agent to call the tool responsibly.

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 40%, so the description must compensate. It adds useful meaning for the Idempotency-Key and for platform destinations, but it does not explain storyId beyond reuse behavior, nor does it clarify facebookTarget's pageId/pageName or the opaque tiktokSettings object. Partial compensation results in a minimum-viable score.

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: publishing a story now to social destinations. It also specifies scope ('destinations this content has not reached') and timing ('publish now'), distinguishing it from scheduling tools like scheduleStory and related publish tools for posts and videos.

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 prerequisites ('after the user approves the story and exact social destinations') and operational guidance ('Use one unique Idempotency-Key per approved request', 'Poll getStory'). It does not explicitly compare itself to sibling alternatives such as scheduleStory or publishPost, but the context is sufficient to know when to invoke it.

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 cover the safety profile (readOnlyHint=false, destructiveHint=true, openWorldHint=true), and the description adds substantial context on top: the operation is asynchronous, it does not confirm a platform post, repeated calls with the same key and recognized settings replay the original accepted snapshot even after completion, and changed recognized settings yield a 409. That is exactly the kind of side-effect and retry behavior an agent cannot infer 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?

The purpose is front-loaded in the first sentence, followed by the async caveat and then the idempotency rules in a logical order. It is dense but nearly every sentence carries distinct information; the only mild redundancy is re-stating the 1–128 printable ASCII key constraint that the schema already spells out.

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 nested, six-parameter mutation with no output schema, the description covers the important behavioral ground: async enqueue, no confirmation of the platform post, idempotency recovery, and conflict behavior. It stops short of saying what the accepted job snapshot contains (e.g. a job id usable with getVideoStatus) or what permissions/account connections are required.

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 83%, so the parameters are largely self-documenting and the baseline would be 3. The description adds meaning beyond the schema by defining what counts as the "same" request for idempotency comparison (JSON formatting, property order, and unrecognized fields are ignored; recognized setting changes produce 409), which directly governs how a caller should construct this call.

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 opening line names a specific verb and resource ("Queue a video publish") and the follow-up clarifies the semantics: an atomic durable enqueue that returns an accepted job snapshot rather than a completed platform post. That distinguishes it from a synchronous publish, though it never explicitly names siblings like publishPost, publishStory, retryVideoPublish, or scheduleVideo.

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 implied usage context (this is a queue/enqueue, not a confirmation) and a concrete recovery instruction for using the Idempotency-Key when the response is lost. However, it never states when an agent should choose this over publishPost, scheduleVideo, or retryVideoPublish, so the routing decision is left to inference from the name.

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

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

Goes well beyond the annotations by disclosing a per-user rate limit ('one refresh per user every five minutes across instances'), batch caps (100 posts, 50 videos), early termination under a time budget with 'skipped' counts, a cooldown before individual re-refresh, and result semantics ('missing metrics are not zero performance'). This is rich operational context that annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false) 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?

Front-loads the core action in the first two sentences, then layers constraints and post-refresh guidance. It is information-dense rather than padded, though the run of caveats (batch, timeout, cooldown, rate limit, result semantics) makes it longer than a minimal definition.

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 a state-changing, rate-limited, open-world operation, the description supplies most of what an agent needs to call it correctly, including limits and partial-completion behavior. It stops short of describing auth/permission requirements or the precise response shape beyond 'successes and failures'.

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 must carry parameter meaning. It conveys the concept of targeting 'one post or video' and that omitting a target triggers a batch refresh, which maps loosely to postId/postType. But it never names the fields, the uuid format, or the enum values ('post'/'video'), leaving the schema to do the rest.

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 ('Refresh') and resource ('social performance data' / 'platform metrics') and clarifies scope: single post/video or a bounded recent batch. This clearly distinguishes it from read-oriented siblings such as getAnalyticsOverview and getPostAnalytics.

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?

Describes the two targeting modes (single item vs. bounded batch) and adds a follow-up path ('Refresh those posts individually after the cooldown'). However, it never names a sibling tool to distinguish this refresh action from the read-only analytics retrieval tools, so the when-not guidance is implied rather than explicit.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description goes beyond them by disclosing the 409 failure semantics for ineligible platforms, the partial-retry behavior when one platform needs review, and a warning not to derive eligibility from legacy video status. It adds no auth or rate-limit context, and never references the Idempotency-Key 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?

Four short sentences, front-loaded with purpose before the eligibility rules and error codes, with no filler. The 'safe failed sibling' sentence is slightly dense and could be split, but it conveys a non-obvious partial-retry case worth the words.

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

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

For a destructive, open-world, 6-parameter tool with nested objects and no output schema, the description covers the critical decision inputs (eligibility, 409 conditions, legacy-status caveat) and implies the queueing outcome. It stops short of describing the success response shape or the idempotency-key reconciliation path, which matters for a non-idempotent retry.

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 already 83%, so the baseline is 3, but the description adds real meaning to `platforms` by stating the eligibility rule (confirmed failed, retryable, present in data.video.publishing.platforms) that the schema only gestures at. It says nothing extra about videoId or the target/settings objects, which the schema handles.

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

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

The description opens with a specific verb+resource ('Retry confirmed failed video platforms') and immediately narrows scope to only explicitly named, confirmed-failed, retryable platforms. That scope statement is what separates it from publishVideo/scheduleVideo siblings, which operate on any publishable platform, so an agent can route correctly without opening the schema.

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

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

It gives explicit preconditions (must be confirmed failed, retryable, and present in data.video.publishing.platforms) and explicit exclusions (successful, queued/running, needs_review return 409), plus the partial-retry case. The one gap is that it never names a sibling to use instead when the platform isn't eligible (e.g., a status tool), leaving that step to inference.

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

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

Annotations already declare the operation is not read-only, is open-world, not idempotent, and not destructive. The description adds key behavioral context beyond annotations: the scan is asynchronous and requires polling with getScanResult, and it falls back to a saved website URL when none is supplied.

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?

Very concise and front-loads the core action and follow-up polling instruction. The first line 'Scan a website' is a redundant restatement of the tool name/title, but the rest is efficient.

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 annotations cover the safety profile, but the description omits critical parameter details for a tool with three parameters at 0% schema coverage. The agent still does not know what the jobType options mean or when to supply contentGroupId.

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 must compensate, but it only partially explains websiteUrl's fallback behavior. It says nothing about the jobType enum values (brand_scan, competitive_analysis, full_scan) or the optional contentGroupId.

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 ('Scan a website') and expands the goal to 'Start brand or competitor research using the website-scanner service,' clearly distinguishing it from the sibling getScanResult which is only for polling results.

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

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

Explicitly says to use this tool to start research and to poll with getScanResult afterward, and notes the saved URL fallback. It lacks explicit when-not-to-use guidance or alternatives for other research contexts.

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, openWorldHint=true, and idempotentHint=false. The description adds genuinely useful context beyond those flags — existing receipts stay unchanged, and deduplication depends on reusing the same Idempotency-Key and settings. It does not explain the destructive scope (what a reschedule replaces or removes), which is the most important missing behavior for a destructive write.

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?

Five short sentences, front-loaded with the action, then constraints, then retry/polling advice. Dense and mostly waste-free, though the telegraphic style occasionally drops subjects and forces the reader to reconstruct the sentence.

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 five-required-parameter destructive write with no output schema and no annotations on return shape, the description covers the critical agent needs: idempotent retry, verification path via getPost/getCalendar, and non-modification of published content. Missing only the meaning of contentGroupId and any error/partial-failure behavior.

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 40%, so the description must carry weight. It adds meaning for postId (reuse the same ID, do not copy published content), platforms (destinations), scheduledFor (time), and Idempotency-Key (reuse after lost responses), but contentGroupId is never explained in either the schema or the description, leaving one required parameter opaque.

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 plus scope: scheduling an existing (possibly already-published) post to destinations it has not yet reached. It implicitly separates itself from createPost/publishPost via 'do not copy or edit published content', but never names the close siblings bulkSchedule, scheduleStory, or scheduleVideo, so an agent must still infer which scheduling tool applies.

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

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

It gives concrete operating guidance: confirm destinations and time, reuse the same post ID, reuse the Idempotency-Key and settings after a lost response, and poll getPost/getCalendar for delivery jobs. That covers retry and verification behavior well, but there is no explicit when-not-to-use or routing to bulkSchedule for multi-post cases.

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, openWorldHint=true, and non-idempotency, so the bar is lower. The description adds real value beyond them: retries are safe only if you reuse the identical Idempotency-Key and settings, earlier receipts are preserved, and the story must be unchanged. The retry guidance is complementary to idempotentHint=false rather than contradictory, since the key is what supplies idempotency.

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 action and scope, with the retry instruction and the read-tool pointer following. Every clause carries information; nothing is padded. It is terse to the point of being slightly telegraphic, which costs a little on readability.

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 mutating, open-world tool with six parameters, nested objects, and no output schema, the description covers the essential caveats: story must be unchanged, only unreached destinations, receipts preserved, retry via key. It leaves unaddressed whether facebookTarget/tiktokSettings become required per selected platform, but that is the schema's domain rather than a missing behavioral disclosure.

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 50%: platforms, scheduledFor, facebookTarget and Idempotency-Key are documented in the schema, while storyId (pattern only) and tiktokSettings are not. The description echoes 'destinations', 'time', 'settings', and the key but supplies no format detail for the undocumented parameters. Baseline 3 is appropriate given partial 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?

States a concrete verb+resource (schedule a saved story) with two sharp scoping qualifiers: 'unchanged' and 'destinations it has not reached'. These distinguish it from publishStory (immediate send) and bulkSchedule (many items), even though no sibling is named outright. The core action an agent must identify 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?

Gives two actionable directives: confirm destinations and time, and consult getStory/getCalendar for delivery jobs. It also covers the retry path with the Idempotency-Key. However, it never states when to prefer this over publishStory, schedulePost, or bulkSchedule, which is the primary routing decision among these siblings, so usage is implied rather than established.

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, and the description adds a genuine state-gating constraint not present in structured data. However it never explains the destructive implication (e.g., whether rescheduling replaces an existing slot) or how platform targeting behaves when platforms is omitted, which is exactly the gap the annotations flag.

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

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

Front-loaded with the action, then two short supporting sentences with no filler. The opening 'Schedule a video' line is a near-duplicate of the following sentence, a minor 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?

Preconditions are covered and annotations carry the safety profile, but with no output schema and only 40% parameter coverage on a 5-param tool with nested objects, the description leaves multi-platform targeting behavior and the effect on an existing schedule unexplained.

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

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

Schema description coverage is only 40% across 5 parameters including two nested target objects, and the description mentions none of them by name. It adds no syntax, default, or targeting semantics for platforms, scheduledFor, facebookTarget or linkedinTarget, so it 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?

States a specific verb+resource ('Schedule a video... for future publishing') and the resource type alone differentiates it from schedulePost and scheduleStory. It also distinguishes scheduling from immediate publishing by naming the 'future publishing' intent.

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 preconditions in both directions: the video must be in one of the listed source states, and pending/generating videos must finish generation first. It stops short of naming alternatives (e.g., publishVideo for immediate publish, bulkSchedule for multiples), so usage is well-contextualized but not fully routed.

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. The description adds genuinely new behavioral context: literal-text matching (no wildcard patterns) and that results are hosted URLs for reuse. No return-format detail beyond that, but the safety profile is already covered.

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

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

Front-loaded with the core action in the first line, then three short supporting sentences. No filler and 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?

Annotations cover the read-only/idempotent safety profile and the description covers the literal-search behavior and URL return, so most agent needs are met. Remaining gaps are parameter semantics for type and limit, which neither the description nor schema prose fully documents.

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 25% (just cursor), so the description must carry weight. It implies filename matching via the 'search' field, but adds nothing about the 'type' enum or the 'limit' bounds/default, leaving those documented only by the schema structure.

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 ('Search saved media') and elaborates with 'Search your saved files by filename, across upload folders.' This distinguishes it from listing tools like listMedia or listVideos, though it doesn't name a sibling 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?

Usage is implied by 'by filename, across upload folders,' but there is no explicit when-to-use vs when-not guidance. It never states how it relates to listMedia or when a browse should be preferred over a search.

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=false, destructiveHint=true, idempotentHint=false). The description adds meaningful behavioral context by clarifying exactly what the mutation touches (name and description) and explicitly listing what it does not affect (content movement, social connections, automatic publishing). This narrows the destructive hint usefully.

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 short, front-loaded, and every sentence adds scope information. However, the first sentence ('Update a content group') largely restates the title and is redundant with the second sentence's expansion.

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 update tool with annotations already covering safety and no output schema, the description gives adequate purpose and boundary information. It remains incomplete regarding parameter specifics (especially the required groupId and name/description constraints) and does not explain return behavior.

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 must carry parameter meaning. It implies the 'name' and 'description' parameters via 'Rename' and 'update its description', but it never mentions the required 'groupId' or any format constraints (e.g., UUID pattern), leaving a significant 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?

States a clear verb+resource ('Update a content group') and immediately narrows the scope to renaming or updating the description, with explicit exclusions ('Does not move content, alter social connections, or enable automatic publishing'). This distinguishes it from broader update operations, but it does not name a sibling tool to disambiguate further.

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

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

The description implies when to use it: to rename or update a description. The negative scope statements ('Does not move content…') serve as implicit when-not guidance, but no alternative tools are named and no prerequisites or conditions are 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 cover the safety profile (destructiveHint=true, idempotentHint=false), so the bar is lower, and the description still adds real behavioral context: the refusal preconditions and the fact that editing a scheduled story mutates its future public content. It does not say whether unspecified fields are preserved or cleared, which matters for a non-idempotent partial-update tool.

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

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

Four short sentences, front-loaded with the core action and with the alternatives placed last where they belong. Slight redundancy between 'Edit an unpublished story' and 'on an unpublished story' keeps it from being maximally tight.

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 10-parameter mutation with nested objects, no output schema, and zero schema descriptions, the description covers preconditions, side effects, and routing well but leaves the parameter-level contract largely undocumented. An agent can still call it, but cannot confidently predict partial-update semantics or field interactions.

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% across 10 parameters, so the description carries the full burden, yet it only groups fields into 'caption, media, and destinations' without adding meaning beyond the property names. Duration, mediaFit enum values, thumbnailUrl behavior, and the relationship between platforms and facebookTarget/tiktokSettings are all left 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?

Specific verb (Edit) plus resource (unpublished story), and it enumerates the editable surface: caption, media, destinations. It also distinguishes itself from siblings by naming scheduleStory and cancelSchedule as the timing tools, so an agent can route without opening the schemas.

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

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

Explicit when-to-use (unpublished stories), explicit when-not (refuses active, partially published, or already posted stories), and explicit alternatives for a related need (scheduleStory / cancelSchedule for timing). It also states the boundary condition 'edits do not publish', which is exactly the kind of routing rule an agent needs.

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