PostQuest

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, non-idempotent), so the bar is lower. The description adds genuinely new behavior: the ticket is short-lived, and it exists only to serve a widget session, which explains the non-idempotency and tells the agent the artifact is ephemeral.

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, both front-loaded with the essential facts (what is returned, who calls it) and zero filler. Nothing could be removed without losing 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?

An output schema exists, so return-value documentation is not required, and the tool has one required parameter with full schema coverage. The description conveys the key constraint (widget-only, short-lived) but omits any ticket lifetime or reuse detail that would make it fully self-contained.

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 session_id parameter already documents that it comes from open_media_uploader. The description adds no further meaning about the parameter, 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 names a specific verb (returns) and resource (a short-lived upload ticket) and scopes it to a media uploader widget session, which separates it from siblings such as open_media_uploader and upload_media. It stops short of explicitly contrasting itself with those siblings, but an agent can tell what the tool produces.

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?

"Called by the widget itself" implicitly signals that an agent should not normally invoke this directly, which is useful routing context. However, it never states when an agent *should* use it versus open_media_uploader or upload_media, nor does it issue an explicit do-not-call directive, so the guidance remains 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=false, destructiveHint=true, idempotentHint=false, openWorldHint=true, so the safety profile is covered. The description adds genuine behavioral context beyond that: creation always lands as a draft unless a flag is set, and timestamps must carry an ISO-8601 offset. The 'not idempotent' sentence merely restates the idempotentHint 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?

Three short sentences, front-loaded with the default behavior and the two mutually exclusive publication paths. No filler; the ISO-8601 constraint is placed where it is needed.

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 rich 9-parameter schema carries the field-level detail. The remaining gap is guidance on how this tool relates to its publish_post/schedule_post/validate_post siblings, which matters given the overlapping capabilities.

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 usefully clarifies the interplay between scheduled_at and publish_now relative to the draft default, but it largely restates what the per-parameter schema text 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?

Clear verb+resource ('Creates a post') with a stated default behavior (saved as draft). However, it never addresses the obvious overlap with sibling tools publish_post and schedule_post, which appear to do what publish_now and scheduled_at do here, leaving an agent unsure which 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 implies usage through the flag semantics (default draft, scheduled_at to schedule, publish_now to publish), but never states when to call this versus publish_post, schedule_post, or validate_post. No prerequisites beyond the schema-level 'requires workspace opt-in' are surfaced in 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 destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered structurally. The description adds real value beyond that by stating the operation is permanent and enumerating the post states in which the call is invalid, which is exactly the missing precondition context. It does not describe failure behavior or any recovery path when the constraint is violated.

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 zero filler; the core action and its eligibility constraint are both front-loaded 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?

An output schema exists, so return values need no explanation, and the annotations carry safety semantics. Combined with the description's permanence and state-restriction statements, an agent has everything needed to decide and 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 coverage is 0% and the single parameter post_id has no description in the schema. The description never mentions post_id, so it adds no format, source, or lookup guidance, though the parameter is largely self-explanatory and implied by the eligibility rules.

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 ('Permanently deletes') and a well-scoped resource ('a draft or scheduled post'), which immediately separates it from publish_post, schedule_post, and update_post. It stops short of naming a sibling outright, but the eligibility constraint supplies the differentiation.

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

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

The negative constraint ('Published posts, partially published posts and posts currently publishing cannot be deleted') effectively tells the agent the only valid state for calling this tool. It provides clear when-to-use context and exclusions, though it never names an alternative tool for the excluded cases (e.g., update_post or unpublish flows).

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), so the bar is lower. The description adds real behavioral context beyond structured fields: a ~24-hour data lag with daily refresh, and the caveat that 'a zero can mean not reported' due to partial platform coverage. That partial-coverage warning materially affects how an agent interprets results.

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 the summary contains, then freshness, then the interpretation caveat. No filler; each sentence contributes either scope or behavior.

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-value documentation is not needed, and the description covers scope, freshness, and the zero-is-ambiguous caveat. The only mild gap is the absence of routing to/from the sibling analytics tools, a minor omission given the otherwise complete picture.

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 parameters (range enum and social_account_id) are already fully documented in the schema, including default and the analytics_history_limit behavior. The description adds nothing parameter-specific beyond restating 'for a date range', 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 ('summarize') and resource ('post performance for a date range') and enumerates the contents (period-over-period totals, daily changes, breakdowns by content format, top posts). This clearly delineates it from per-post tools, but it never names the closest siblings (get_post_analytics, list_post_analytics), so sibling differentiation is left implicit.

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

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

The description implies the aggregate-view use case but gives no explicit when-to-use versus get_post_analytics or list_post_analytics, and no exclusions. The freshness note ('Numbers appear about 24 hours after a post goes live') weakly signals when the data will be available but is not phrased as 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 declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context – that passing an account ID switches the result to live account-specific limits – but says nothing about auth needs, caching, or rate 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 tight sentences with the base behavior front-loaded and the account-ID variant second. Every clause earns its place and there is no filler.

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

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

An output schema exists, so return values need not be described. The description covers the core behavior and both parameters' effects at a high level, though with 0% schema coverage it could say more about valid platform values.

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

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

Schema coverage is 0%, so the description must carry the load. It does explain the effect of social_account_id (live limits) and implies the platform parameter via 'for each platform', which is better than nothing, but it never states requiredness, allowed platform values, or behavior when platform 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 (Returns) and resource (caption, media and account requirements per platform), which is clearly distinct from siblings like validate_post or get_analytics_summary. It does not, however, explicitly contrast itself with any sibling 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?

The second sentence implies when to supply social_account_id (to get live per-account limits), giving useful conditional guidance. But there is no explicit when-to-use versus when-not-to-use framing, nor any mention of related tools such as validate_post.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description usefully adds that the response carries account-specific captions, publication state and validation warnings, but says nothing about auth/permission scope or behavior for a nonexistent post_id.

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

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

One sentence, front-loaded with verb and resource, no filler and nothing redundant. Every clause (captions, publication state, warnings) adds information.

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

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

With an output schema present, the description needn't document return values, and annotations cover the safety profile, so the remaining need is minimal. Only the missing post_id semantics and sibling routing keep it short of complete.

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

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

A single required post_id at 0% schema description coverage; the description only implies via "one post" that the id selects a single post. It never states the id format, origin, or whether it comes from list_posts, so it does little 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 ("Read") and resource ("one post") and enumerates what the payload includes: account-specific captions, publication state, validation warnings. This distinguishes it from list_posts (plural/bulk) without naming the 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 only implied by the singular "one post"; there is no statement of when to prefer this over list_posts, validate_post, or get_post_analytics, and no prerequisites or exclusions are given for a catalog with many lookalike read 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?

Annotations already declare readOnly, idempotent, non-destructive, non-open-world, so the safety profile is covered. The description adds genuine value by characterising the payload: cumulative totals per day and the day-over-day growth, which tells the agent the granularity and derivation of the returned data.

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

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

A single dense sentence, front-loaded with the core action and resource, with the explanatory clause after the colon earning its place by clarifying the return shape. No 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?

An output schema exists, so the description need not enumerate return fields, and it still sketches the structure (daily cumulative totals plus growth). For a one-parameter read with rich annotations, nothing essential is missing, though naming the sibling tools would round it out.

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 analytics_id's origin (from list_post_analytics or get_analytics_summary) is documented in the schema itself. The description adds no syntax or sourcing detail beyond it, so the baseline of 3 applies.

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

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

States a specific verb (Read) and resource (one post's lifetime metrics plus day-by-day history), and the phrase 'one post's' implicitly scopes it apart from list_post_analytics. It never names the sibling tools, so differentiation is available only by inference from the singular framing.

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 singular 'one post's ... history' implies this is the per-post detail tool versus a listing tool, but there is no explicit when-to-use, when-not, or named alternative. The reference to list_post_analytics and get_analytics_summary is only in 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, non-destructive, and closed-world behavior, so the safety profile is covered. The description adds a genuinely non-obvious trait beyond the structured data: returned preview URLs are signed and expire after five minutes, which matters for caching and downstream use. Pagination behavior for large workspaces is still undisclosed.

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

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

A single sentence, zero filler, with the resource and the most surprising behavior (URL expiry) front-loaded. Nothing redundant with the annotations or title.

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

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

An output schema exists, so return-shape explanation is not required, and the URL expiry note is a useful addition. However, for a paged list tool with two undocumented parameters, the description should at least indicate that results are paginated and that more calls may be needed.

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 limit or offset, so neither the pagination semantics nor the max page size of 100 is explained anywhere in prose. Only the generic mention of 'workspace media IDs' hints at the scope.

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 (lists workspace media IDs) and adds a distinguishing detail about temporary signed preview URLs. It is clear without needing the schema, though it does not explicitly contrast itself with sibling tools like list_posts or upload_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?

There is no when-to-use guidance, no prerequisites, and no named alternative among the many siblings (e.g., list_posts, list_social_accounts). The agent must infer the retrieval context on its own.

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, closed-world behavior, so the safety profile is covered. The description adds meaningful scope context beyond that: metrics are lifetime, include posts made outside PostQuest, and are bounded by plan history. It does not mention pagination or rate behavior, keeping it just 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?

Three short sentences with the core purpose front-loaded and no redundant filler. It is compact, though the middle 'Limited to the plan history' sentence is slightly terse and could be merged or clarified.

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, and the schema richly documents the 7 optional parameters. The description supplies scoping context (lifetime, plan history, external posts), but omits sibling differentiation in a crowded analytics toolset, leaving 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?

Schema description coverage is 86%, so the schema already documents sort, limit, range, platform, post_id and social_account_id in detail. The description's only parameter-related content is 'Sortable by metric,' which merely restates what the schema's sort enum provides, 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?

States a specific verb ('Lists') and resource ('lifetime metrics per published post on connected accounts'), plus a scope note that it includes posts made outside PostQuest. However, it never distinguishes itself from close siblings like get_post_analytics or get_analytics_summary, so an agent cannot tell them apart from the description alone.

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

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

No when-to-use or when-not-to-use guidance is given, and the near-identical sibling get_post_analytics is never named as an alternative. The 'Limited to the plan history' clause is a data-scope constraint, not usage routing, so the agent must infer selection from the name 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed world), so the bar is lower. The description still adds real context the annotations don't: pagination is bounded, and timestamps come back in UTC with the workspace timezone reported, which tells the agent how to interpret returned dates.

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

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

Two tight sentences with no filler, and the purpose/scope is front-loaded ahead of the return-value note. Appropriately sized, though 'bounded pagination' is slightly vague where the schema already caps limit at 100.

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 needn't enumerate returned fields, and it covers scope, pagination bounds, and timezone semantics. It is close to complete for a filtered-list tool, missing only explicit routing guidance versus sibling list/get tools.

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

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

Schema description coverage is 83%, so the schema already documents from/to, limit, status, and platform thoroughly. The description adds nothing about any parameter, so the baseline 3 applies.

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

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

The description gives a specific verb+resource ('List posts') and adds scope ('in the authorized workspace') plus a behavioral constraint ('bounded pagination'). It does not name or differentiate itself from siblings like get_post or list_post_analytics, so it falls short of a 5.

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

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

There is no explicit when-to-use guidance, no condition that selects this tool over get_post/list_post_analytics, and no stated exclusions. Usage is only inferable from the name and 'authorized workspace' scope.

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 the safety profile. The description adds one genuinely new behavioral fact beyond the structured fields: provider credentials are excluded from the response. It says nothing about scoping (per-workspace vs per-user) or empty-result behavior.

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

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

Two short sentences, front-loaded with the payload and closed with the security-relevant exclusion. Every clause carries information and nothing is padded.

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

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

An output schema exists, so the description is not obligated to explain return values, and it supplies the one caveat structured fields cannot convey (no credentials). The main omission is scope — whether results are limited to the current workspace — which an agent may need before chaining into publishing tools.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; the description correctly avoids inventing filtering arguments.

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

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

The description names a specific resource and enumerates the returned fields (account IDs, timezone, publishing opt-in, content pillars), so an agent knows exactly what it gets. It does not differentiate itself from any sibling, though with no sibling listing accounts the risk of confusion is low.

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 call this versus alternatives, no prerequisites, and no hint about downstream use (e.g., that the returned IDs are needed before create_post or schedule_post). Usage must be inferred entirely from the tool 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?

Annotations only declare the non-read-only, non-idempotent, non-destructive profile, so the description adds real value: it explains that this is an interactive widget, that the chosen media IDs come back in the conversation, and that an upload_url exists for browser-based clients. It omits permission/auth requirements and any note on what happens if the user cancels the widget.

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 no filler; the core action is front-loaded and the fallback mechanism is placed last, in the order an agent would need 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?

An output schema exists, yet the description still usefully characterizes the return payload (media IDs, upload_url), and it covers the interaction model, the fallback path, and the file scope. Nothing an agent needs to decide and invoke this zero-parameter widget tool is missing.

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

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

Zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No parameter noise is introduced.

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 ('Shows an upload widget where the user picks images or videos... into the media library') and adds the discriminating condition 'for files without a public URL', which separates it from upload_media/upload_media_file/create_media_upload_ticket without naming them. An agent can tell what this tool does and roughly who it's for from the first sentence.

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 clear use conditions: files lacking a public URL, and clients that cannot render widgets (use the upload_url fallback). It stops short of explicitly naming alternative siblings such as upload_media_file, so the agent must infer the routing rather than being told it outright.

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 irreversibility and external-effect profile is covered. The description adds genuinely new behavior context: it requires the workspace agent publishing opt-in and a publish:now API key ability, which the agent must verify before calling.

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 compact sentences with the action front-loaded and the prerequisite conditions following. No filler and nothing that could be cut.

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

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

An output schema exists so return values need not be described, and the two authorization prerequisites are disclosed. Only minor gaps remain, such as what happens if the opt-in is missing or whether publication can be reversed.

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 full burden for the single post_id parameter. It only implies the ID refers to an already-existing post; it never states the expected ID format, where to obtain it (list_posts/get_post), or whether the post must be validated first.

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 (publishes) plus resource (an existing post) and qualifies timing with 'immediately', which cleanly separates it from the sibling schedule_post. An agent can identify the operation 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?

The word 'immediately' implies the use case of publishing now rather than scheduling, and the opt-in/ability prerequisites give some context. However, no sibling is named and there is no explicit when-not guidance (e.g. use schedule_post if you need a future time).

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 idempotentHint and destructiveHint, and the description usefully adds specifics: validation of content, media and quota occurs before scheduling, and idempotency is scoped precisely to 'same post and timestamp.' It does not explain what the destructiveHint actually affects (e.g., replacing an existing scheduled time), leaving one gap against 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?

Three short sentences, each carrying distinct information (action, timestamp constraint, validation, idempotency), with the core purpose front-loaded. No filler or restated title.

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

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

An output schema exists, so return values need not be described, and the description adequately covers validation behavior, timestamp format and idempotency for a two-parameter tool. The only missing piece is the meaning/required state of post_id, which is an ambiguity an agent would need resolved.

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%: scheduled_at is documented in the schema, but post_id has no description anywhere. The description reinforces the timestamp constraint ('must contain Z or an explicit timezone offset'), which duplicates the schema text rather than adding new meaning, and says nothing about what post_id must reference. Baseline 3 for 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 specific verb (schedules) and resource (post) with a clear scope modifier: 'for future public publication,' which implicitly separates it from publish_post and create_post. It does not name a sibling outright, but the temporal framing makes the distinction readable without opening schemas.

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

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

Usage is implied by 'for future public publication' – an agent can infer this is for deferred publishing rather than immediate publish_post. However, there is no explicit when-to-use statement, no prerequisites (e.g., does the post need to exist as a draft first?), and no named 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 already declare the mutation and safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true). The description adds real value on top: the key naming convention (platform or platform:account_id) and the assurance that other post fields survive the call, which is the key behavioral fact for a partial update.

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, no filler, and the core operation is front-loaded ahead of the key-format and preservation details. Every sentence carries information the 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?

An output schema exists, so return values need not be explained, and annotations cover the safety profile. The description supplies the key format and non-destructive partial-update semantics; it could still say whether validation or a publish step follows, but it is otherwise complete enough 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 coverage is only 50% (post_id is undocumented), so the description has to compensate, and it does so for the non-obvious parameter by spelling out exactly what the object keys must be: 'platform names or platform:account_id'. Only post_id is left implicit, which is a minor gap given its 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 description pairs a specific verb ('Tailor captions') with a clear resource scope ('per selected platform or account'), and the closing clause 'Other post fields are preserved' implicitly separates it from update_post. It does not explicitly name the sibling, but an agent can still tell this is a per-platform caption override rather than a general post edit.

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: reach for this when captions must differ per platform instead of a single shared caption. There is no explicit 'use X instead when...' guidance and no mention of prerequisites such as the post being a draft or needing validation against platform rules, despite validate_post and get_platform_requirements existing as 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?

Goes well beyond the annotations by disclosing the rate limit, the expected latency ('results arrive within a few minutes'), and the automatic 24-hour cadence. The annotations establish idempotent/non-destructive/non-read-only, and the description layers operational behavior an agent needs to avoid redundant calls.

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

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

Three short sentences, each carrying distinct load: what it does, the automatic cadence, and the rate limit plus latency. No filler and the action is front-loaded.

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

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

For an asynchronous trigger with an output schema present, the description covers everything an agent needs: async timing, throttle limits, and auto-sync behavior. Return-value details are correctly left to the output 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%, and the single optional parameter is fully documented there including the 'omit to sync every account' semantics. The description adds no parameter-level 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 ('queues a refresh of post metrics') and makes the async nature explicit, which separates it from the read-oriented siblings get_post_analytics, list_post_analytics, and get_analytics_summary. An agent can tell this triggers a refresh rather than fetching 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?

Tells the agent when a manual sync is unnecessary ('also sync automatically every 24 hours') and the throttling constraint ('once every 15 minutes per workspace'), which is real guidance about when calling is worthwhile. It does not, however, name an alternative tool for simply reading existing metrics, so the when-to-use-vs-sibling routing is implied rather than stated.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuine value beyond them: partial-update/merge semantics ('omitted fields are preserved') and the conditional nature of non-idempotency ('not idempotent when publish_now is set'), which is more precise than the blanket annotation. It stops short of covering permission requirements or error behavior on already-published posts.

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, each carrying distinct information (scope, publish semantics, idempotency caveat) with no repetition of the schema. The most important constraint, the unpublished-post scope, is front-loaded.

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

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

An output schema exists, so return values need not be explained, and the description covers scope, merge behavior, and publishing side effects for a 9-parameter nested tool. It omits what happens when the target post is already published and whether publish_now's workspace opt-in failure mode matters, 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?

Schema description coverage is 89%, so the baseline is 3, but the description adds consequence-level meaning the schema does not: that scheduled_at controls when the post publishes publicly and that publish_now triggers immediate publication. It does not clarify post_id, social_account_ids, or platform_captions 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?

Specific verb (updates) plus resource (an existing unpublished post) with an explicit scope constraint that separates it from create_post, publish_post, and schedule_post. An agent can identify the tool's domain 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?

Explains the two meaningful usage modes: changing scheduled_at alters public publish time, and publish_now publishes immediately. It does not, however, name sibling alternatives (e.g., publish_post or schedule_post) or state when to prefer them, so the routing 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 cover the safety profile (readOnly=false, idempotent=false, destructive=false, openWorld=true), and the description adds real operational context beyond them: a 3 MiB decoded size ceiling, quota consumption until deletion, and rejection of redirects and private-network URLs. It stops short of stating auth/permission requirements or explaining idempotency behavior for repeat uploads.

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, zero filler, each carrying a distinct fact (input modes, size limit, return value, quota side effect, validation rejections). The most important framing information is front-loaded.

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

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

An output schema exists, so the description need not detail return values, yet it still notes the returned media ID. Combined with annotation coverage of the safety profile, the description supplies enough to call the tool correctly, though permission/scope prerequisites remain unstated.

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

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

With 67% schema coverage, the description usefully supplements the schema: it specifies that the URL must be public HTTPS with no redirects, and restates the 3 MiB decoded ceiling for base64. It does not independently clarify the filename parameter's role beyond what the schema already states.

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 ('Imports media into the media library') and clarifies the two accepted input modes (public HTTPS URL or base64). It is clear about scope, but it never names or distinguishes itself from close siblings such as upload_media_file, create_media_upload_ticket, or open_media_uploader, so an agent must infer which upload path 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?

Usage is only implied: 'Returns a media ID for use in posts' and the base64 schema note 'Not for conversation images' hint at context, but there is no explicit when-to-use statement and no guidance on when to prefer a sibling upload tool. The tool has no required parameters, which makes the absence of routing guidance more consequential.

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

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

Annotations already declare the write profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), lowering the burden. The description adds useful context—it needs ChatGPT's file reference and it yields a media ID—but omits non-idempotence (re-importing the same reference likely duplicates the asset) and any note about the temporary nature of the download link or upload/polling latency.

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

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

Two sentences, zero padding, front-loaded with what gets imported and constrained by scope. The return-value clause is compact and directly useful.

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?

Output schema exists, so the return value (media ID) needn't be elaborated further, and annotations carry the safety profile. The only real gap is behavioral nuance around repeated imports and the temporary-link lifetime, which matters given idempotentHint=false.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning by explaining that the file reference (file_id/download_url) originates from ChatGPT itself and points at a supplied temporary link. That provenance is actionable knowledge the schema alone does not convey.

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 (imports) and resource (image/video from a ChatGPT conversation into the media library), with the source constraint that distinguishes it from generic media uploads. It never names the close siblings upload_media or create_media_upload_ticket, so the distinction is implied by scope 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?

"using the file reference ChatGPT supplies" implies the precondition for using this tool (you must have a ChatGPT conversation file reference), but there is no explicit when-to-use vs upload_media / open_media_uploader guidance or exclusion. Usage is inferable but not 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 establish readOnly/idempotent/non-destructive, yet the description adds substantive behavior beyond them: no saved post, no reserved quota, no upload, no schedule, no publication, executed inside a rolled-back transaction, plus the shape of the returned issue data. This is exactly the side-effect disclosure an agent needs for a validation 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 dense sentences with zero filler, front-loading the single most important fact (read-only dry run) before the guarantee of no side effects and the return shape. Nothing is repeated from the title or schema.

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

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

For a 9-parameter tool with nested platform_configurations, the description covers the essential risk question (does this write anything?) and defers parameter detail to a 100%-covered schema and return detail to the existing output schema. Nothing an agent needs to invoke 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 schema already documents all 9 parameters (media_ids, is_draft, publish_now, platform_configurations, etc.) in detail. The description adds only the single note that it takes existing media IDs, which mildly reinforces media_ids semantics but adds little 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 precise verb+resource ('validate a proposed post' via a read-only dry run of publish-time validation) and immediately differentiates itself from the write siblings create_post/publish_post/schedule_post by declaring it saves nothing. An agent can tell it apart from the write tools 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?

It gives clear context for use: run the real publish-time validation path before actually publishing, and it notes it 'takes existing media IDs', implying media must already be uploaded. It never names an explicit alternative (e.g. publish_post/create_post) or states a when-not condition, 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.