BulkPublish

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

The description discloses an important side effect: 'on submit it creates the post via create_post.' However, this directly contradicts the annotation readOnlyHint: true. Because the description claims a write behavior while the annotations mark the tool read-only, this dimension scores 1 as an annotation contradiction.

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 and front-loaded with the purpose and user flow. The final sentence repeats the idea of interactive UI/composing somewhat, but overall every sentence adds useful routing or behavior context with little 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-optional-parameter tool with an output schema and low complexity, the description gives enough invocation context: it explains the interactive UI, channel selection, pre-fill behavior, and delegation to create_post. It could add more about scheduling-edge behavior, but the schema and output schema cover the rest.

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 only one optional parameter, content, and the schema already describes it fully as 'Optional initial text to pre-fill the composer.' The description restates pre-filling in prose, but adds no format, length, or behavior details beyond the schema. With 100% schema coverage, 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 names a specific action ('Open an interactive composer') and resource ('social media post'), and clarifies the flow up to creating the post via create_post. It also distinguishes itself from the sibling create_post by being the interactive, review-first 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?

It gives explicit usage guidance: 'Use this when the user wants to compose a post interactively in a UI' and 'prefer this over create_post when they'd review before posting.' This directly tells an agent when to choose this tool over its closest sibling.

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

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

Annotations only mark the tool as non-readonly/non-idempotent and don't describe the side effect. The description adds meaningful behavior: it reserves a URL rather than uploading bytes, and frames it as a large direct browser upload path. It doesn't go into URL expiry or a required finalize step, but the core mutation is clear enough that agents won't assume bytes are sent in this call.

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 and the alternative is named in the second. It is concise overall, though the second and third sentences partly repeat the same routing advice ('use upload_media instead' and 'prefer upload_media for normal files'), keeping it just below a perfect score.

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

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

For a two-parameter tool with a full input schema, an output schema, and an annotation block, the description gives enough selection and invocation guidance. It names the sibling alternative and the conditions that choose between them, so nothing critical is missing for calling this tool correctly.

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

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

Schema coverage is 100% and both parameters have descriptions, so the schema already defines sizeBytes and contentType. The description adds the 'large direct upload' context but no syntax or format details beyond the schema, so 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 and resource: 'Reserve a presigned upload URL for a direct browser upload'. It also scopes the tool to the composer UI and explicitly distinguishes it from upload_media, so an agent can identify what this tool does 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 routing: scripted uploads should use upload_media, and presigned large direct uploads should use this tool, with 'advanced' and 'prefer upload_media for normal files' as guardrails. These are concrete when/when-not conditions, not implied 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 non-read-only, non-destructive, non-idempotent, open-world, so safety is already covered. The description adds genuinely new behavioral context not in the annotations: per-platform media requirements (YouTube/TikTok require video, do not include them for image-only posts) and Instagram's default format with the postTypeOverrides escape hatch. It does not cover approval flow or link-tracking side effects, which live only in the schema.

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

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

Five sentences, front-loaded with the core action and draft/schedule scope, then the platform caveats marked IMPORTANT, then the usage rule. Each sentence carries actionable content and none is padding for a 15-parameter tool.

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

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

With an output schema present, return values need not be explained, and the description covers the main ambiguities: draft vs scheduled, media/platform compatibility, and Instagram format defaults. It omits the approval (requestApproval/publishWhenApproved) and link-tracking behaviors, which are significant for a scheduling tool but are at least fully documented in the schema.

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

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

Schema description coverage is 100%, so the schema already documents all 15 parameters in depth; the baseline is 3. The description only restates field groups at a high level ('platform-specific content overrides, media attachments, labels, and thread format') and notes Instagram's postTypeOverrides need, adding marginal semantics beyond what the schema text provides.

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

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

The description names a specific verb and resource ('Create a new social media post') and immediately scopes it ('saved as a draft or scheduled for a specific time'), which separates it from a publish-style action. It never names a sibling like publish_post or compose_post outright, so the reader must infer the boundary from the 'do not publish immediately unless asked' caveat rather than an explicit pointer.

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

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

It gives an explicit when-to-use: 'Use this when the user wants to draft or schedule one new post (do not publish immediately unless asked).' It also supplies platform-level decision rules (YouTube/TikTok require video; Instagram defaults to feed_photo, use postTypeOverrides for reels). It lacks explicit when-not-to-use language or a named alternative tool for the publish-now case.

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

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

Annotations already declare destructiveHint: true, so the destructive nature is known. The description adds the eligibility constraint (draft/failed only), which is behavioral context beyond the annotation. It also reinforces permanence with 'permanently remove,' adding a nuance not present in the annotation.

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 zero redundancy. The action and constraint are front-loaded, and every word serves a purpose. It is efficient and easy to parse.

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 delete operation with one parameter, annotations cover destructiveness, an output schema exists, and the description provides the essential eligibility rule and usage trigger. Nothing needed for correct invocation is missing.

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

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

Schema coverage is 100% and the postId parameter is already described as 'The post ID to delete.' The tool description adds no additional semantic detail beyond that, 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 ('delete') and resource ('post'), identifies the identifier (postId), and clarifies the scope by limiting eligible posts to draft and failed ones. This clearly distinguishes it from sibling tools like publish_post or update_post.

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

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

It explicitly says 'Use this when the user wants to permanently remove a post,' which provides a direct usage condition. It also adds an eligibility constraint ('Only draft and failed posts can be deleted'), implicitly excluding published posts. However, it does not name alternative tools explicitly, so the guidance is clear but not exhaustive.

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 state the tool is not read-only and not destructive, leaving the mutation nature clear. The description adds that it pairs with create_media_upload and is used by the composer UI, but does not disclose potential side effects (like what happens if called twice) or any authentication requirements. With annotations covering the basic safety profile, a 3 is appropriate.

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

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

The description is concise, with two sentences that front-load the core action and then provide usage guidance. No unnecessary words or repetition.

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

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

The tool has an output schema, so return values are assumed to be documented there. The description clarifies the step in the upload flow and the advanced nature, which is sufficient for a well-defined tool in a pipeline. Minor missing detail: preconditions like having a valid presigned upload, but this is implied by pairing with create_media_upload.

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

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

The schema has 100% coverage, so all parameters are described there. The description specifically mentions r2Key as returned by create_media_upload, which adds useful context, but does not explain the optional nature of width, height, and duration, or when they should be provided. This is adequate but not exhaustive.

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

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

The description clearly states the tool records an uploaded file as a media file after a browser PUT, and explicitly pairs it with create_media_upload. This makes the tool's purpose specific and distinguishes it from the sibling create_media_upload and upload_media, which are likely for different stages of the upload process.

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 provides explicit guidance: 'Use this when a presigned direct upload finished and the file must be registered (advanced).' This tells the agent exactly when to invoke this tool and indicates it is for advanced scenarios, complementing create_media_upload which is the first step.

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 safety is covered. The description adds genuinely new behavior: optional filters narrow every figure, compare returns the previous equal-length window, and it is only available for windows of 15 days or fewer under a 30-day retention cap. That constraint disclosure is exactly what annotations cannot carry.

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

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

Three sentences, no filler, with the output shape and the compare caveat front-loaded before the usage cue. Slightly dense in the parenthetical, but every clause carries information an agent needs.

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

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

Nine parameters, two enums, and an output schema are all covered; the description explains scope, filter interaction, and the compare window limit without re-documenting return fields that the output schema already defines. Nothing required to call it correctly is missing.

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

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

Schema description coverage is 100%, so a 3 would be the floor; the description earns above that by explaining that filters apply to every returned figure rather than just the list, and by restating the 15-day ceiling on compare that the schema itself does not mention.

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 (analytics summary for a date range) and enumerates what comes back: totals, status breakdown, per-platform stats, daily counts. It is clear on its own, but with siblings named view_analytics and get_post_metrics the description never draws the boundary between this tool and those, leaving the agent to infer which analytics endpoint 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?

"Use this when the user asks how their content performed overall, across channels and over a date range" gives a concrete triggering condition. It stops short of explicit exclusions or naming alternatives, so an agent comparing it against view_analytics or get_post_metrics still has to guess.

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 read-only, idempotent, non-destructive profile, and the description adds real behavioral context on top: the 500-message cap, oldest-first ordering, per-message fields, the fact that reading does not mark the conversation read, and the plan-gating refusal. That is substantive disclosure beyond the structured fields.

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

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

Three tight sentences, front-loaded with what is returned and immediately followed by the side-effect caveat and the availability caveat. No filler or repetition.

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

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

An output schema exists, so return values need not be re-explained, yet the description still summarizes the payload fields. Combined with the read-does-not-mark-read note and the plan gating, an agent has everything needed to 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 100% and the single conversationId parameter is documented in the schema as coming from list_conversations, so the baseline of 3 applies. The description adds no format or sourcing detail 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?

States a specific verb and resource ('Get the messages of one Inbox conversation') and pins the scope to a single conversation, which clearly separates it from list_conversations. An agent can tell what it retrieves 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 an explicit trigger ('Use this when the user wants to read one Inbox conversation in full') and a pre-condition (Pro/Business plans, otherwise the call is refused). It never names a sibling such as list_conversations or reply_to_conversation as the alternative, so routing is clear but not fully disambiguated.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds valuable behavioral nuance about thread posts: threadParts and threadMediaFiles behave differently from mediaFiles, which is not inferable from annotations or the schema.

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

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

Three sentences, each earning its place: the core purpose, the thread nuance, and the usage trigger. The most important information is front-loaded, and there is no redundant filler.

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

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

For a single-parameter read tool with a full output schema, the description covers the needed call context and clarifies a non-obvious data placement behavior. Nothing essential is missing for an agent to invoke it correctly.

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

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

Schema coverage is 100% and the only parameter, postId, is already documented as 'The post ID.' The description reinforces that the ID selects a single post but adds no additional format or constraint details beyond the schema.

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

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

The description states a specific action ('Get a single post by ID') and resource, with an explicit enumeration of what 'full details' includes. It clearly distinguishes this from sibling tools like list_posts and get_post_metrics by anchoring on a single post ID.

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

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

The final sentence gives an explicit trigger: 'Use this when the user references one specific post by its ID.' It does not name alternatives such as list_posts for multiple posts, so there is a clear usage context but no explicit exclusions.

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

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

Annotations only cover the safety profile (readOnly/idempotent/non-destructive); the description goes far beyond them. It explains that a metric absent from `supportedMetrics` is stored as 0 and must be reported as unavailable, enumerates per-platform coverage gaps, discloses that `linkClicks` is measured by BulkPublish and must never be summed with platform `clicks`, and notes bot/link-preview exclusion plus the TikTok-insights and X-sync gating. This is exactly the interpretive context an agent needs to avoid reporting wrong numbers.

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 first sentence front-loads purpose and return shape well, but the body is a dense run-on covering every platform's metric coverage. With an output schema present, much of that return-value enumeration is redundant with structured documentation, and the linkClicks passage is longer than the decision it supports.

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

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

For a single-parameter read tool whose real complexity lies in interpreting per-platform metric availability, the description covers the edge cases (zero vs. unavailable, platform gaps, linkClicks double-counting, insight/sync gating) that the schema and annotations cannot express. Nothing an agent needs to report results correctly is missing.

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

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

There is a single parameter and schema description coverage is 100%, so the schema already fully documents `postId`. The description adds no format, range, or sourcing detail about the ID, which is the expected baseline when the schema does the work.

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

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

States a specific verb and resource ('Get engagement metrics for a published post') and enumerates the returned metric families, so the agent immediately knows this is per-post performance data rather than an account-level rollup. The scope word 'published post' cleanly separates it from the analytics/view_analytics siblings 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?

The closing sentence gives an explicit trigger: 'Use this when the user asks how a specific post performed (likes, views, engagement).' That is clear context, but it never names an alternative (e.g., get_analytics for aggregate reporting) or states an exclusion, so the agent must infer the boundary itself.

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

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

Annotations already declare readOnlyHint, destructiveHint, and idempotentHint, covering the safety profile. The description adds useful behavioral context beyond those annotations: the tool returns a scheduledAt value intended to be passed to update_post for queue repositioning, and it frames the result as the next available or end-of-queue slot. No contradiction with annotations.

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

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

Three short sentences with no filler. The tool's core action is front-loaded, followed by the use-case guidance and the companion-tool workflow. Every sentence contributes to selection or invocation.

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, idempotent tool with zero required parameters, full schema parameter coverage, and an output schema present, the description is complete. It explains when to reach for the tool and what to do with its result, while the structured data handles parameter details and return shape.

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

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

The input schema already provides 100% coverage with detailed descriptions for all parameters, including the position enum, timezone format, and excludePostId semantics. The description adds only general context about 'top or bottom of the queue,' which maps loosely to the position parameter but does not materially improve on the schema. 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 uses a specific verb-resource pair: "Get the organization's next available queue slot." It also clarifies the purpose as finding the next optimal scheduling time, and it implicitly distinguishes itself from the content-management siblings by framing the tool as a scheduling-position query rather than a post creation or editing operation.

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

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

The description explicitly states when to use the tool: when the user asks for the next available scheduling slot or wants a post moved to the top/bottom of the queue. It even names the follow-up action, update_post with the returned scheduledAt, which gives the agent a clear invocation path.

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 valuable behavioral context by explaining that the tool returns a `capabilities` object that indicates whether the caller may create, publish, or approve posts, and advises checking it before a write to avoid a 403. This goes beyond the annotations and helps the agent understand the tool's role in the workflow.

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

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

The description is compact and front-loaded: it states the core purpose first, then the return fields, then the capabilities warning, then the usage trigger. Every sentence earns its place, and the structure is logical for an agent scanning for when to use the tool.

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

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

The tool has an output schema, so return values are documented elsewhere. The description covers the key behavioral aspect (capabilities check) and the usage context. It doesn't mention pagination or rate limits, but for a simple list tool with one optional parameter and an output schema, the description is sufficiently complete. A 4 is appropriate because it adds the capabilities context that is crucial for the agent's decision-making.

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 single parameter `active` is fully documented in the schema. The description doesn't add extra parameter semantics beyond what the schema provides, but it does mention the default behavior ('Defaults to true') which is already in the schema. Baseline 3 is appropriate since the schema carries the parameter documentation.

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

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

The description states a specific verb ('List') and resource ('all connected social media channels'), enumerates the platforms, and lists the returned fields. It distinguishes itself from sibling tools like view_channels by focusing on the channel listing with token status and capabilities, making it clear what this tool does.

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

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

The description explicitly says 'Use this when the user wants to see which social accounts are connected.' It also provides a clear directive to check the `capabilities` object before attempting a write, which guides the agent on when to use this tool versus attempting a write operation directly. This is strong 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description still adds substantial context beyond them: newest-activity-first ordering, the exclusion of internal team notes, the canReply/replyNotice mechanism, cursor-based paging, and the Pro/Business plan gate that causes a refusal with an explanatory message. That is genuinely useful behavior an agent cannot infer from structured fields.

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

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

Front-loaded with the verb and resource, then ordering, contents, exclusions, pagination, plan gate, and when-to-use — each sentence carries distinct information. It is dense rather than padded, though the field-level enumeration of conversation contents is arguably redundant given the output schema exists.

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 paged, plan-gated list tool with eight optional filters and an output schema, the description covers everything an agent needs: what is returned at a summary level, what is excluded, how to page, and the failure mode on non-Pro plans. The output schema handles return-value detail, so nothing material is missing.

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

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

Schema description coverage is 100%, so all eight parameters are already documented, including the q, kind, limit, cursor, status, assigned, channelId and platforms filters. The description only reinforces the cursor round-trip ('pass nextCursor back as cursor'), which is a minor addition over the schema's own wording. 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 Inbox conversations') and immediately enumerates the three kinds it spans (direct messages, reviews, comment threads). This distinguishes it from get_conversation (single item) and list_post_comments (post-scoped) without the agent opening a schema.

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

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

The final sentence gives a clear triggering condition: 'Use this when the user asks about their direct messages, reviews or comment threads, or what is waiting for a reply.' It also flags the plan prerequisite and the refusal behavior. It does not explicitly name which sibling to use instead for a single conversation or for post comments, so it falls short of a 5.

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

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

Annotations already convey read-only, idempotent, non-destructive behavior, so the description does not need to repeat those. It adds some context about the return metadata, URLs, dimensions, and labels, and optional search/pagination, but it does not go beyond the schema for behavior like pagination or total counts.

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

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

The description is concise, front-loaded with the core action, and contains no filler. All three sentences earn their place: what the tool does, what it returns, and when to use it.

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

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

For a simple read-only list tool, the description plus a 100%-covered schema and output schema is sufficient for correct invocation. It covers purpose, triggers, and result kinds, and there are no required parameters or special prerequisites 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 description coverage is 100%, so parameters already have meaningful descriptions. The tool description additionally notes that search/pagination exist but does not add notable parameter semantics beyond what the schema already documents.

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: 'List uploaded media files with optional search and pagination'. It clearly identifies the tool's task and return content, and is easily distinguishable from list_posts/list_channels, though it does not explain how it differs from the similarly named view_media sibling.

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

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

The description has an explicit usage trigger: 'Use this when the user wants a list of their uploaded media files.' This is strong contextual guidance, but it lacks when-not-to-use guidance or references to alternatives such as view_media or list_posts.

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 readOnly/idempotent/non-destructive, so the bar is lower, and the description adds genuine context beyond them: per-channel response shape, the postPlatformId/commentActions fields, and explicit unsupported-platform notices. It stops short of noting pagination or rate behavior, but the coverage is strong for a read 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?

Three dense sentences, front-loaded with purpose and response structure before usage. Every sentence carries information, though the last usage sentence overlaps somewhat with the routing already implied earlier.

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?

An output schema exists, so return values need not be explained, yet the description still sketches the per-channel/per-comment structure and the commentActions field. Combined with platform caveats and usage routing, an agent has everything needed to call and interpret it.

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 postId and commentsLimit (including default and max). The description adds no syntax or format detail 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 (list), resource (comments and reactions), and scope (one published post, per channel, read from each platform). It also distinguishes itself from sibling tools reply_to_comment and moderate_comment by naming them as consumers of the returned ids.

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

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

Explicitly says when to use it ('when the user asks who commented... or needs a comment's id to reply to or moderate it') and routes to the sibling tools that need that id. It also documents platform exclusions (TikTok, Pinterest, Google Business, Telegram, Snapchat), which is real when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds genuine behavioral context beyond annotations: pagination, platform statuses and metrics in results, and the exact ordering rule (publishedAt if live, else scheduledAt, else createdAt). This is useful operational detail not present in the annotations.

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

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

Three sentences with no wasted words. It front-loads the core purpose and filters, then gives return/ordering behavior, then a usage context. 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 complex 13-parameter list tool, the description covers what the tool returns, how results are ordered, pagination, and when to use it, while the schema and output schema cover parameter details. No critical aspect needed to invoke the tool correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all 13 parameters in detail. The description adds a helpful high-level summary of filter categories and clarifies the ordering semantics, but it does not meaningfully add parameter-level meaning beyond what the schema already provides.

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

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

The description states a specific verb and resource ('List posts') and immediately enumerates the optional filter dimensions: status, search text, date range, channel, and label. It also distinguishes itself from visual-dashboard siblings by explicitly positioning this tool as returning raw data, so an agent can tell list_posts from view_posts.

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

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

The description gives a clear trigger: 'Use this when the user wants to browse, filter, or check the status of existing posts as raw data.' It also implies a boundary with 'not the visual dashboard,' but it does not explicitly name alternative tools or state when not to use them, so it stops short of full exclusionary 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?

Discloses traits the annotations cannot express: likes/hides are reversible while delete is permanent, delete requires a publish-capable role, hiding/deleting removes the comment from the Inbox, and two distinct refusal paths (dead channel connection needing reconnect; replies unavailable on Free). This is consistent with destructiveHint=true and readOnlyHint=false.

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 set and scope, then ordered preconditions, side effects, failure modes, and the usage trigger. Every sentence carries information, though it runs long as a single dense paragraph rather than being broken into scannable units.

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-required-param mutation with an output schema and full annotations, the description covers reversibility, permissions, side effects, and failure/refusal conditions. Nothing an agent needs to decide or invoke correctly appears to be missing.

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

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

Schema coverage is 100% and every parameter is described there, so the schema carries the load. The description adds only the provenance hint that commentId/postPlatformId come from list_post_comments and that supported actions vary per channel's commentActions, which is useful but not parameter-level semantics beyond 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?

Names the exact verb set (like, unlike, hide, unhide, delete) plus the resource (a comment on a published post) and the acting identity (the channel the post was published to). An agent can distinguish it from reply_to_comment or update_conversation without opening a schema.

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

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

Ends with an explicit trigger: 'Use this when the user wants to like, hide or delete a comment on one of their published posts.' It also routes the agent to list_post_comments for commentActions and IDs, so the alternative source of truth is named.

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

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

Adds significant context beyond the annotations: the post is queued to all target channels, requires a post:publish role, and publishing a pending/rejected post as an approver implicitly approves it. These side effects and permission boundaries are not conveyed by readOnlyHint, destructiveHint, or idempotentHint.

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 longer than minimal, but each sentence earns its place: action and effect, permission requirement, contributor failure mode, approval workaround, implicit approval behavior, and final use-case summary. It could be tightened slightly, but there is no filler.

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

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

For a single-parameter mutating tool, this covers when to use it, who can use it, the failure mode, the workaround, and the queuing side effect. An output schema exists, so return-value details are not needed, and nothing essential is missing for correct invocation.

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

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

The input schema already documents the single parameter postId at 100% coverage, so the description does not need to restate it. It usefully implies the post must already be a draft or scheduled post, but adds no format or validation detail beyond the schema.

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

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

Opens with a specific verb and resource: 'Publish a draft or scheduled post immediately.' Closes with the precise use case ('existing draft or scheduled post right now'), which clearly differentiates it from create, update, retry, and delete 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?

Explicitly tells when to use this tool and when not to: contributors get 403 APPROVAL_REQUIRED and must instead use create/update with requestApproval. It even provides the exact create_post parameters for the approval-based 'publish now' path, leaving no ambiguity about alternatives.

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

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

Annotations only give the generic write/destructive/open-world profile; the description adds the material specifics: the reply is published publicly and immediately under the channel's identity, it cannot be undone from here, there is a 2,000-character ceiling, and the call is refused (with an explanatory message) when the channel connection is broken or the plan doesn't include replies.

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, visibility, irreversibility and eligibility are front-loaded and every sentence carries information. The public/immediate posting and irreversibility points are stated twice in slightly different words, which is minor padding.

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

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

With an output schema present, return values need no explanation, and the description covers the remaining agent-relevant context: public posting, irreversibility, length cap, and both refusal paths (broken connection, plan restriction). Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the 2,000-character limit that the schema's maxLength already encodes and says nothing about postId, commentId, postPlatformId, or the rootCommentId used for threaded replies.

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 (reply) and resource (a comment on one of the workspace's published posts), and scopes it away from conversation replies and comment moderation, which are handled by siblings like reply_to_conversation and moderate_comment.

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?

Ends with an explicit trigger: 'Use this when the user wants to answer a comment on one of their published posts,' plus concrete eligibility conditions (all plans except Free; connection must be live). It does not name an alternative tool or state when not to use it, so it stops short of a 5.

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

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

Annotations only mark this as non-read-only, non-idempotent and destructive; the description adds substantial operational detail beyond that: the message is irreversible ('cannot be unsent'), the 24-hour channel window, refusal conditions for broken channel connections, and plan-based refusal behavior. This is exactly the kind of behavioral context the annotations 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?

It is a single dense paragraph, but it is front-loaded with the action and its irreversibility, then layers limits, channel constraints, and plan gating in a logical order. Every sentence carries a distinct constraint, though the block could be broken up for faster scanning.

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 an output schema present, return values need no explanation, and the description instead covers the dimensions an agent actually needs: reversibility, channel-specific time limits, media/text restrictions, and the failure modes (refused calls) for connection and plan issues.

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 a baseline of 3 applies, but the description adds real meaning: the 4,000-character text limit, the cap of four media files, the fact that reviews and comment threads are text-only, and that replyToMessageId is comment-thread specific. These constraints go beyond the raw schema field types.

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 ('Send a reply in an Inbox conversation') and scopes it to direct messages, reviews and comment threads. This clearly separates it from sibling tools like reply_to_comment, create_post, or moderate_comment without needing to open any schema.

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

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

It gives explicit trigger context ('Use this when the user wants to answer a direct message, review or comment thread in their Inbox') plus concrete preconditions: 24-hour Messenger/Instagram window, channel connection health, and Pro/Business plan gating. It stops short of naming alternative tools for out-of-window or non-Inbox cases, so the routing is implied rather than 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 flag destructive and non-idempotent behavior, but the description adds critical context: it explains that only failed platforms are retried, that unconfirmed platforms are excluded unless republish=true, and that using republish can duplicate posts. It also discloses the exact error behavior (400 with code UNCONFIRMED_REQUIRES_REPUBLISH) and instructs how to handle it. This goes well beyond the annotations and is essential for safe invocation.

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 thorough and slightly long, but every sentence contributes necessary details: purpose, platform scoping, unconfirmed handling, error guidance, and usage condition. It is front-loaded with the core action and then elaborates logically. No redundancy is present; it earns its length, though it could be trimmed slightly without losing value.

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

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

Given the tool's complexity (subtle platform statuses, error handling, user interaction) and the presence of an output schema, the description covers everything an agent needs: purpose, scope, parameter semantics, error behavior, and actionable guidance. The output schema handles return values, so no gaps are apparent. This is a complete, self-sufficient description.

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 both parameters are documented. The description adds significant meaning for republish: clarifying the exact condition for passing true (after user confirmation), the risk of duplication, and the error scenario. It also reinforces the purpose of postId. While the baseline for full schema coverage is 3, the added semantic depth for republish justifies a 4.

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: 'Retry publishing a failed or partially failed post.' It immediately clarifies scope by stating it only retries failed platforms, not successful ones, which distinguishes it clearly from sibling tools like create_post or publish_post. The purpose is unmistakable and precise.

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

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

The description explicitly states when to use the tool: 'Use this when a post failed on some platforms and the user wants to retry just those.' It also provides detailed conditions for the republish parameter, explains the UNCONFIRMED_REQUIRES_REPUBLISH error case, and advises how to interact with the user. This is exemplary usage guidance, including both when-to-use and when-not-to.

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

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

Annotations only cover the safety profile (not read-only, idempotent, non-destructive). The description adds genuinely non-obvious behavior: the 90-day snooze ceiling, that assigning notifies the teammate, that no message is sent and no platform state changes, that at least one field must be supplied, and that the call is refused on non-Pro/Business plans or before Inbox availability.

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 operations and side-effect caveat, and each sentence carries information. The final sentence restates the same four operations already enumerated in sentence one, which is mild redundancy but also serves as an explicit usage trigger.

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 an output schema present, the description need not explain returns, and it covers the remaining agent-critical gaps: plan gating, refusal behavior, no outbound message, teammate notification, snooze bounds, and the minimum-field requirement. An agent can call this correctly without further inference.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description contributes constraints the schema does not state: the 90-day maximum for snoozedUntil and the 'send at least one field' requirement beyond the single required conversationId. It does not add format or interaction detail (e.g., that status clears a snooze) beyond what the schema already says.

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 how the workspace handles) plus the resource (one Inbox conversation) and enumerates the four concrete operations. It is immediately distinguishable from get_conversation, list_conversations, and reply_to_conversation, especially via the explicit note that nothing is sent to the other person.

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

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

The closing sentence gives a clear when-to-use trigger ('Use this when the user wants to mark a conversation read or unread, archive or reopen it, snooze it, or assign it to a teammate') and the 'nothing is sent' clause implicitly excludes reply_to_conversation. It never names an alternative sibling tool explicitly, so it stops short of a full when/when-not/alternative treatment.

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 destructive/openWorld/idempotent, but the description adds concrete behavior beyond them: a failed post is reset to draft, a partial post stays partial, scheduling a partial post re-queues only its failed channels, and approval can be forced server-side for contributor API keys. These are non-obvious side effects an agent must know before mutating.

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 and constraints; each sentence carries a distinct rule. The trailing 'Use this when the user wants to edit an existing post' is mild filler that restates the opening.

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?

An output schema exists and the input schema is exhaustively documented, so the description need not explain returns or per-platform options. It covers the state-machine and re-queue behavior well, though it is silent on the concurrency/ifUnmodifiedSince editing discipline that a careful editor would want surfaced.

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 description only restates the field list already documented in the schema (content, schedule, media, labels, status, platform settings). It adds the status-legality rule, but that is also spelled out in the status parameter description, so it does not meaningfully exceed the schema.

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

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

States a specific verb and resource ('Update an existing post') and enumerates the mutable fields, then explicitly routes immediate publishing to the sibling publish_post. An agent can distinguish this from create_post/publish_post/retry_post without opening any schema.

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

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

Gives explicit eligibility rules ('Only draft, scheduled, failed, or partial posts can be edited'), the state-machine consequence of editing each, and a named alternative with its triggering condition ('use publish_post to publish immediately'). It also states the user intent that selects this tool.

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

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

Annotations indicate readOnlyHint=false (write operation) and openWorldHint=true (side effects). The description discloses the storage side effect ('The file is stored in BulkPublish'), supported formats, size limit, and the exclusivity constraint. It does not mention potential error scenarios or sync/async behavior, but it adds meaningful behavioral context beyond the annotations, such as the storage location and format/limit 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?

Three concise sentences: first states the action and purpose, second lists supported formats and size, third gives the either/or constraint and usage guidance. No redundant phrasing, information is front-loaded, and every sentence contributes to understanding the tool.

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

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

Given the presence of an output schema (for return values), the description covers purpose, input constraints, formats, and usage context. It does not detail the relationship with sibling tools like create_media_upload and finalize_media_upload, which might be part of a multi-step upload workflow. This is a slight gap for an agent deciding whether this tool is sufficient or if those steps are needed. Overall, it is largely complete but missing that orchestration context.

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 parameters are documented in the schema. The description adds the exclusive-or constraint (url OR filePath) and reinforced the meaning of filename derivation from URL/path, which is partially in the schema. It also conveys format and size constraints that affect parameter choices, adding value beyond the schema.

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

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

The description states a specific verb ('Upload') and resource ('media file'), elaborates the input sources (URL or local path), and clarifies the file is stored in BulkPublish for later posts. It clearly differentiates from siblings like create_media_upload and finalize_media_upload by describing the entire upload action, and it explicitly ties to the use case of attaching media to a post.

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

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

The description provides a clear when-to-use condition: 'Use this when the user provides an image/video to attach to a post.' It also gives an explicit constraint ('Provide either url OR filePath, not both'). However, it does not mention alternatives or the specific workflow involving create_media_upload and finalize_media_upload, which could be relevant for multipart uploads or larger files, leaving some ambiguity about when to choose this tool over those.

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, covering risks. The description additionally clarifies the tool's behavior (interactive dashboard) and what the view contains, which goes beyond the structured annotations. It does not mention any auth/rate constraints, but these are not necessary given the pervasive read-only safety profile and the annotation coverage.

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 lead with the precise action, list the dashboard content, and give selection guidance. There is no filler and each 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?

The description gives sufficient context for a tool that already has an output schema and annotations for side-effect behavior. It clearly conveys what the dashboard includes and when to use it. The 'interactive' nature is described with enough clarity for typical agent invocation; a slightly deeper note about return format would be a minor embellishment, but output schema covers that.

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

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

The input schema fully describes both parameters with dates and defaults (100% coverage), so the description adds no new parameter semantics; it only repeats the concept of a date range. With the schema doing the heavy lifting, baseline 3 is right.

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 explicitly says 'Open an interactive analytics dashboard' and lists the contents: totals, status breakdown, per-platform stats, daily post counts. It also distinguishes itself from get_analytics by noting that this is the visual alternative. This fully disambiguates it from sibling tools without ambiguity.

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 provides a clear decision rule: 'Use this when the user wants an interactive analytics dashboard — prefer over get_analytics for a visual view.' This explicitly states when to select it and names the actual alternative, so an agent can decide without inspecting other tools.

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=true, destructiveHint=false, and idempotentHint=true, covering the safety profile of the tool. The description adds the 'interactive' nature and the data content shown, but it does not describe how interaction works, whether there are any side effects or state changes, or any other behaviors beyond what the structured annotations imply. The 'interactive' wording is a valuable addition, but the overall disclosure is modest.

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

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

The description is two short sentences, the first stating the action and content, the second giving the trigger condition. No fluff or repetition; every sentence earns its place and the key verb and resource are front-loaded.

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

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

For a barrier-less, parameterless tool with a read-only and idempotent annotation set and an output schema, the description is sufficiently complete for an agent to know why and when to use it. A slight gap is the lack of a suggested contrast with 'list_channels' to make the selection fully unambiguous, but that mostly affects usage differentiation rather than invocation correctness.

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

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

With 0 parameters, the schema covers 100% of the interface by definition, so the description does not need to explain any parameter. It correctly omits parameter details and instead focuses on the action, which is the right baseline for a parameterless tool.

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

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

The description clearly states the action ('Open an interactive view') and the resource ('connected social channels'), and it enumerates the visible content (platform, account, connection/token status). It differentiates from siblings through the 'interactive view' phrasing, but it never names the natural alternative 'list_channels', so the distinction remains implicit rather than explicit.

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 direct usage cue: 'Use this when the user wants an interactive view of their connected channels.' This communicates the intended scenario, but it does not mention when not to use it or point to an alternative like 'list_channels', which would be the analogous non-interactive read tool.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive. The description adds relevant behavior beyond that: it opens an interactive gallery with thumbnails and metadata, clarifying the experience the user will get. No contradiction with 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?

Two short sentences that immediately state the action and the intended use case. No redundant filler or schema repetition.

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

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

For a simple read-only gallery tool with one optional parameter and an output schema, the description provides sufficient context. It could be slightly stronger by explaining the role of the limit parameter or by distinguishing itself from list_media, but it is not a major 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?

The input schema fully describes the only parameter (limit) with a default value, so the description doesn't need to add much. It adds no extra detail about how the limit applies to the gallery, but the schema coverage is complete.

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

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

The description clearly states the action ('Open an interactive gallery') and the resource ('uploaded media files'). It also conveys the visual browsing purpose, which differentiates it from a plain data-returning list tool like list_media.

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

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

It explicitly says to use this when the user wants to visually browse their media library. It does not explicitly contrast it with sibling tools like list_media, but the visual-gallery framing gives enough direction for most 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 readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds the behavioral nuance of being 'interactive' and 'visual,' which goes beyond the annotations. It doesn't contradict them, and it provides useful context about the nature of the UI.

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

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

The description is a single, tightly written sentence that leads with the primary purpose and includes routing advice. Every word earns its place; there is no filler.

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

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

For a read-only, non-destructive tool with only two optional parameters, a clear purpose, and an existing output schema, the description fully covers what an agent needs: what it does, when to use it, and how to differentiate it. Nothing essential is missing.

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

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

Schema description coverage is 100%, so both parameters (limit and status) are already well-documented. The description merely reiterates that status filtering is optional, which is already implied by the schema's non-required status. It adds no new meaning beyond the schema, so the baseline of 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 ('Open'), a resource ('interactive list of posts'), and the key attributes (status, schedule, channels). It explicitly differentiates from sibling list_posts by saying 'prefer over list_posts for a visual view,' making the tool's distinct purpose unmistakable.

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

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

It provides direct when-to-use guidance: 'Use this when the user wants to see their posts as an interactive dashboard.' It also names the alternative (list_posts) and the selection criterion (visual vs. non-visual), leaving no ambiguity about tool choice.

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