OmniSocials

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

Annotations only give the safety profile (readOnlyHint=false, destructiveHint=true, openWorldHint=true); the description adds substantial context beyond them: ordered step approval, the auth requirement that the user must be a listed approver for the CURRENT step, the meaning of a forbidden error, and the exact resulting state transitions. This goes well past what the structured fields 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?

Dense but front-loaded: purpose first, then precondition, then auth/error semantics, then outcome. Every sentence carries operational weight, though the 'approval_status pending (post status in_approval)' phrasing and the id precondition are mildly redundant with the schema.

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

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

For a mutating workflow tool with no output schema, the description covers everything needed to call it correctly: precondition, prerequisite read, authorization rules, failure interpretation, and post-condition state changes. 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 coverage is 100% with a single parameter whose schema description already states the 'pending' approval_status constraint, so the description's restatement of that constraint adds little. Baseline 3 is appropriate when the schema fully documents the parameter.

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

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

States a specific verb (approve) and resource (the current step of a post's approval workflow), and explicitly frames it as a step-wise action distinct from reject_post or publish_post. An agent can distinguish it from all siblings without opening a schema.

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

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

Explicit preconditions ('Only works on a post with approval_status pending'), a prerequisite action ('check get_post first'), and error handling guidance ('a forbidden error means the user isn't an approver for this step yet — tell them who needs to approve instead, don't retry'). This is textbook when/when-not guidance.

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

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

Annotations only declare readOnly=true, destructive=false, openWorld=true. The description goes well beyond them: it explains the HEAD-based size/type read, the IMAGE FIT rows returned per channel, and the semantics of fits: false with the crop vs. keep choice. This is substantial behavioral detail an agent cannot get from the annotations.

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

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

Front-loaded with the core purpose, and most sentences earn their place. It is on the long side, and the crop-handling / media_fit instructions lean toward create_post's territory, but the density is high and nothing is pure filler.

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

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

There is no output schema, so the description carries the return-value burden, and it does: it describes the size/type acceptance result and the per-channel IMAGE FIT rows including the fits flag. Combined with the read-only annotations, an agent has enough to call it and interpret the response.

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 value by clarifying the mutual-exclusion grouping: 'Provide ONE of: a public url (size/type read via HEAD), an existing media_id, or size_bytes + mime.' That constrains invocation mode beyond the individual field descriptions.

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

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

States a specific verb and resource ('Check whether a video/image will be accepted by the platforms CONNECTED to this workspace') and pins the timing ('BEFORE uploading or posting'). This clearly distinguishes it from siblings like upload_media and create_post without needing to open 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?

Explicit when-to-use: 'Use this when the user gives you a file (URL) so you can warn them upfront.' It also sequences the workflow (check, then confirm before uploading) and routes the follow-up action ('pass the answer as media_fit on create_post'), so the agent knows both when to call it and what to do with the result.

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 this as non-read-only, destructive, and open-world, but the description adds substantial operational context: workspace-asking rules, Pinterest auto-default behavior, X link-post failure handling, and the instruction not to retry or remove links without asking. These are exactly the kind of publish-time behavioral traits an agent needs.

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

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

It is long and dense, but front-loads the core purpose and uses bold headers to separate exceptional cases. Most sentences earn their place given the tool's complexity, though some workspace/media rule repetition could be trimmed.

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 33-parameter nested publishing tool with no output schema, the description covers the most error-prone scenarios and references create_post for shared media/workspace rules. It is nearly complete, but the lack of explicit draft/schedule/publish routing against create_post and publish_post leaves a meaningful contextual 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 coverage is already 91%, so the schema carries most parameter documentation. The description still adds meaningful cross-parameter semantics for tricky cases like pinterest.board_id fallback, linkedin vs linkedin_page independence, x.thread_parts behavior, and link-post handling.

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

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

The description opens with a specific verb+resource and scope: 'Create a new post and publish it immediately (no scheduling).' This clearly distinguishes it from a scheduling/draft workflow, though it does not explicitly distinguish it from siblings like publish_post or create_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 gives clear context for immediate publishing and extensive scenario guidance for Pinterest, X threads, links, and workspace selection. It does not explicitly name create_post or publish_post as alternatives for scheduled or existing posts, leaving that routing inference to the agent.

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

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

Beyond the annotations, the description discloses substantial behavior: DMs are sent in the user's name, Meta's one-private-reply and 7-day/24-hour follow-up rules, the 180-DM-per-hour cap and queueing behavior, and X-specific limits and STOP-list persistence. It also documents concrete error conditions such as 409 x_dms_off and 409 x_not_connected, which is exactly the kind of operational context annotations do not provide.

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 definition is front-loaded with the core purpose and then proceeds through platform rules, scope selection, X caveats, and the create_post alternative. It is dense and delivered as a single long paragraph, but given the 14-parameter surface and complex platform behavior, most sentences carry relevant operational meaning rather than filler.

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

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

The description covers the prerequisites, platform differences, trigger semantics, scope selection, rate limits, error responses, and the alternative tool for attaching automations to new posts. With no output schema, the only minor omission is the response shape, but nothing needed to select or 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 coverage is 100%, so the schema already documents all 14 parameters in detail, making 3 the baseline. The description adds useful cross-parameter meaning, especially the exclusivity of post_id, instagram_media_id, and facebook_post_id for scope 'post', and the X-specific constraints that remove post fields and public replies from consideration.

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

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

The first sentence states a specific verb and resource: creating a comment-to-DM automation on Instagram, Facebook, or X, including the core trigger-to-DM behavior. It also distinguishes platform-specific variants and points to related tools such as create_post for new posts, so the agent can identify the tool's role 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 description gives explicit usage conditions: which platform to choose, how scope 'post' maps to post_id/instagram_media_id/facebook_post_id, that X supports only DM triggers, and that a paused X automation can be created while X DMs are off. It also names an alternative path for new posts via create_post and says update_automation is used later to turn a paused automation on.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the mutation/safety profile is covered. The description adds the workflow role of a folder (a container for later uploads/moves), but says nothing about permissions, whether folders are renameable/removable, or naming constraints. Useful but modest context on top of 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?

Two tightly packed sentences with zero filler: the purpose is front-loaded and the second sentence carries only actionable workflow routing. Every clause earns its place.

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

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

For a simple two-parameter create tool with full annotation coverage and no output schema, the description supplies enough to call it correctly and to know what to do next. Minor omissions (permissions, whether the folder name must be unique) are non-blocking.

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 schema already documents both 'name' and 'parent_id' including the nesting behavior and the list_folders source. The description's example ('win-graphics') merely echoes the schema's own example, adding no syntax or constraint detail beyond it. Baseline 3 is appropriate when the schema does the heavy lifting.

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 ('Create a media-library folder'), which is clearly distinct from sibling create_* tools that operate on posts, hashtags, and webhooks. It does not explicitly contrast itself against those siblings, but the resource noun makes the target unambiguous.

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

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

It gives concrete usage context ('Use it to organize assets') and routes the agent to the correct follow-up tools: upload_media (folder) for uploads and update_media (folder_id) for moving files. There is no explicit when-not-to-use guidance or prerequisite/permission note, 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 already establish this is a non-destructive, non-open-world write, so the safety profile is covered. The description adds genuinely useful behavior beyond that: '#' prefix optional, case-insensitive dedup, order preservation, and a max of 100 tags — all things an agent must know to build a valid call. It omits what happens on a duplicate set name (the schema says unique per workspace) or what is returned.

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

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

Two sentences, zero filler. The core behavior and the example come first, and the follow-up usage note is placed at the end where it belongs.

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 write tool with no output schema, the description covers creation semantics, normalization rules, and how the set is consumed later. It leaves open the duplicate-name failure mode and the return payload, but nothing essential to invoking 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 baseline is 3, and the description goes beyond the schema by specifying normalization semantics for the hashtags array (optional '#', case-insensitive dedup, order retention, 100-item cap). The name parameter gets no extra clarification beyond the schema's 'unique per workspace' note.

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 ('Save a reusable, named group of hashtags') and grounds it with a concrete example ('Fitness Brand' -> #fitness #gym #workout), which separates it cleanly from list_hashtag_sets, update_hashtag_set, and delete_hashtag_set.

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

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

Gives clear downstream context: the set is meant to be applied to a new post via create_post (hashtag_set). It does not, however, mention when to use this versus update_hashtag_set for editing an existing set, so the alternative-selection guidance is partial.

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 readOnly=false, destructive=false, openWorld=false; the description adds far more: validation runs only on schedule/publish (drafts exempt), per-platform 400 validation_error shapes, the x_feature_not_enabled refusal with a 'do not retry as is' instruction, the 100 MB upload ceiling on top of per-platform caps, and exactly which post types fail without media. This is substantial context an agent cannot get from 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?

Front-loaded correctly with the must-know checklist before the reference tables, and the bold headers make a long body navigable. It is still quite long and some limit tables partly restate constraints already present in the schema (poll option counts, some char limits), which is redundant for a 97%-coverage 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 35-parameter, deeply nested mutation tool with no output schema, the description covers validation timing, failure modes, per-platform prerequisites, and the upload-before-create flow for chat images. Nothing an agent needs to call it correctly is missing.

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

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

With 97% schema coverage the baseline is 3, but the description contributes operational semantics the schema does not carry: the video duration and file-size cap tables, the character-limit table per platform, the per-platform caption object pattern, the thread_parts vs long-form X content distinction, and the media_fit crop/keep decision flow. These directly change how parameters must be filled.

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

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

The opening line names a specific verb and resource ('Create a new social media post, story, or reel') and enumerates the three types the tool produces. It never explicitly contrasts with the closest sibling, create_and_publish_post (draft/schedule vs. immediate publish), so an agent must open both schemas to be sure which one to call.

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?

A numbered pre-flight checklist states exactly what to gather (workspace, content, channels, schedule, media) and when to ask the user versus act, including the workspace rule (never silently pick when multiple exist) and the Pinterest board auto-default. It routes to specific alternatives by name: list_workspaces, list_accounts, check_media_compatibility, get_account, upload_media.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered structurally. The description adds domain behavior by explaining what triggers each event (e.g., post.approved fires on the last workflow approval), but says nothing about auth needs, whether a signing secret is issued, or delivery semantics — useful additions against a low annotation-derived bar.

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

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

Two sentences, front-loaded with the action, and the dense event enumeration earns its space by disambiguating valid values. Slightly parenthetical annotation of a couple events could be tightened but nothing is wasteful.

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

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

There is no output schema, so the description could reasonably explain what a successful creation returns (e.g., an ID or signing secret). For a low-complexity two-parameter tool it is mostly adequate, but the post-creation contract is left 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?

Schema coverage is 100%, so the baseline is 3, but the description goes further by enumerating the valid event values and clarifying their trigger conditions, which the schema only calls 'Events to subscribe to'. It does not elaborate on the url parameter, which the schema already defines as an HTTPS URL.

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

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

States a specific verb and resource ('Create a new webhook'), making it clearly distinguishable from the sibling delete_webhook, get_webhook, list_webhooks, and update_webhook. It does not name a sibling explicitly, but the create/list/get/delete verb family makes the intent unambiguous.

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

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

The description gives no when-to-use guidance, no prerequisites, and no comparison to alternatives like update_webhook (for modifying an existing hook) or list_webhooks (for inspecting them). The event list informs invocation but not tool selection.

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

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

Annotations already declare destructiveHint=true, so the danger is known. The description adds real value beyond them by naming what is destroyed (activity log), what is preserved (already-sent DMs stay sent), and requiring user confirmation. That is genuine disclosure of consequences, but it stops short of stating irreversibility, permission requirements, or the response shape.

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

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

Three short sentences, each carrying a distinct fact: scope/effect, the safer alternative, the confirmation requirement. Front-loaded with the action and with zero 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?

For a one-parameter destructive tool, annotations cover the safety profile and the description covers consequences, the alternative path, and the pre-call safeguard. No output schema is needed for a delete, so nothing an agent requires 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?

A single parameter at 100% schema coverage, with the schema itself documenting that the id comes from list_automations. The description adds no format or sourcing detail beyond that, so the baseline 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?

Specific verb (delete) plus the exact resource (comment-to-DM automation), the supported platforms, and the collateral (activity log). It also implicitly separates itself from update_automation and list_automations by naming the latter as the id source.

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

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

Explicitly routes the agent to update_automation with status 'paused' when the intent is only temporary, and adds a 'confirm with the user first' precondition. When-to-use-not and the alternative are both stated, not inferred.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, openWorldHint=false, so the safety profile is covered structurally. The description adds genuine value beyond them by disclosing the blast radius: posts that already used the set retain their hashtags because tags were merged into captions at create time. It does not address reversibility, permissions, or error 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 action, and the second sentence earns its place by preventing a likely misconception about published posts. 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 destructive tool with no output schema, the description covers the action and the side-effect scope, which is what an agent most needs before calling it. It omits what happens on an invalid or already-deleted set_id and whether the delete is permanent, minor gaps given annotations carry the destructiveness signal.

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

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

Schema description coverage is 100% for the single parameter, and the schema already documents set_id including its provenance ("from list_hashtag_sets"). The description adds nothing about the parameter, so the baseline 3 for fully documented params 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 ("Delete a saved hashtag set"), and the resource name is unique enough among the 48 siblings (delete_post, delete_media, delete_webhook) that an agent can tell it apart without opening schemas. It stops short of explicitly naming related siblings such as update_hashtag_set or list_hashtag_sets, so it does not fully earn a 5.

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

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

Usage is only implied: the description tells the agent the effect of deleting (posts keep their tags), which implicitly reassures that deletion is scoped to the saved set, but never states when to delete versus update, nor any prerequisite such as needing a valid set_id. No alternatives or when-not conditions are given.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, and the description goes well beyond them: it discloses the cascade effect (replies under the comment are deleted too), irreversibility, the required user confirmation, and the meaning of a 403 reconnect_required error including the remediation path. That is exactly the extra context 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?

Five short sentences, front-loaded with the action and scope, then cascade behavior, safety, parameter clarification and error handling. Every sentence carries information absent from the schema or annotations; nothing is 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?

Single-required-parameter tool with no output schema and complete annotations; the description covers scope, side effects, irreversibility, confirmation requirements and the one documented error path. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema coverage is 100% on the single parameter, so the baseline is 3, but the description adds a genuine disambiguation: it warns that message_id is the #id in the thread, not the conversation id — a real confusion source given siblings like get_inbox_conversation. It stops short of any id format example, so not a 5.

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

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

The first sentence names a specific verb (delete), the exact resource (a comment on one of the workspace's posts), and the two surfaces affected (platform and inbox). It also carves out platform scope (Facebook, Instagram, TikTok) and explicitly names the sibling it is not (hide_inbox_comment for YouTube). An agent can distinguish this from every other inbox tool without opening a schema.

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

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

It gives explicit when-to-use (FB/IG/TikTok comments), when-not (YouTube, because the API cannot delete others' comments, use hide_inbox_comment), and a mandatory pre-call step ('confirm with the user before calling'). That is the full when/when-not/alternative triad.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is carried structurally. The description adds no behavioral context beyond that: it does not say whether deletion is permanent or reversible, whether it cascades (e.g. to scheduled posts referencing the media), or whether it requires elevated permissions.

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

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

One short, front-loaded sentence with zero padding. The verb and the discriminator (by ID) come first.

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 is simple (one required string param, no output schema, no nesting) and annotations carry the destructive signal, so little prose is needed. However, for a permanent destructive operation on media, the absence of any statement about irreversibility or side effects leaves a meaningful gap.

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

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

Schema description coverage is 100% and the single parameter is fully documented as "The media ID to delete." The description's "by ID" merely restates the schema, so the baseline 3 applies with no added semantics.

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

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

States a specific verb and resource ("Delete a media file") with the identifying parameter, so the agent can distinguish it from update_media, upload_media, and list_media. It does not explicitly name or contrast with those siblings, but the operation is unambiguous.

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

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

"by ID" implies an ID must already be known (presumably from list_media), but there is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives or how to recover the ID. Nothing tells the agent when deletion is appropriate versus updating.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so safety is covered. The description adds a specific behavioral fact beyond that: 'This action cannot be undone,' which tells the agent the deletion is irreversible. It does not mention auth requirements or side effects, but the added irreversibility note is valuable.

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 waste; the action and irreversible warning are both front-loaded and easy to scan.

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 one-parameter delete tool with a complete input schema and annotations covering the destructive nature, the description supplies what an agent needs: what it does, how it identifies the target, and that the result is irreversible. 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%, and the single 'id' parameter is already documented as the post ID to delete. The description repeats 'by ID' without adding format, source, or validation details beyond the schema, so the baseline 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 and resource ('Delete a post') plus the required identifier, so the action is unambiguous. The sibling set contains several delete_* tools for other resources (media, webhook, hashtag set), and naming 'post' is enough to distinguish this tool from them.

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

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

The description says what the tool does but gives no guidance on when to use it versus alternatives like update_post or other delete_* tools, nor any exclusions or prerequisites. Usage is only implied by the verb.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds nothing beyond that: it does not say the deletion is permanent, whether it can be undone, whether it revokes any associated delivery endpoints, or what permissions are required. For a destructive operation it contributes no behavioral context of its own.

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 four-word sentence with zero padding, front-loaded with verb and resource. It is efficient rather than verbose; the only cost is that the brevity leaves behavioral gaps unaddressed elsewhere.

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

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

The tool is simple (one fully documented parameter, no output schema) and annotations carry the destructive/safety signal, so the description is close to sufficient. It is still missing the two things an agent would want before an irreversible delete: confirmation that the operation is permanent and whether related resources are affected.

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 id parameter is already documented as 'The webhook ID to delete'. The description's 'by ID' phrasing adds no format, source, or lookup guidance 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 (Delete) and resource (webhook) with the keying parameter (by ID), so an agent can distinguish it from update_webhook, get_webhook, and the unrelated delete_post/delete_media siblings without opening the schema. It stops short of any scope detail (e.g. workspace/account ownership of the webhook), but the purpose itself is unambiguous.

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

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

There is no guidance on when to use this tool versus alternatives such as update_webhook (which could disable rather than remove) or rotate_webhook_secret, and no prerequisites or warnings about irreversibility. The agent must infer usage entirely from the name.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that: it doesn't say what 'details' are returned, whether access is scoped to the workspace, or any rate/permission behavior. With annotations doing the work, the description contributes no extra behavioral context.

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

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

A single front-loaded sentence with no filler; the verb and resource lead and nothing is wasted.

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

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

There is no output schema, so the description would need to convey what a 'detail' response contains, and it does not — 'details' remains undefined. For a trivial one-parameter read tool with annotations covering safety, this is adequate but leaves the return payload opaque.

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

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

Schema description coverage is 100% and the single parameter 'id' is documented as 'The account ID'. The description adds no format, sourcing, or naming detail beyond the schema, so the baseline 3 for high coverage applies.

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

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

States a specific verb ('Get') and resource ('details of a specific connected social media account'), which implicitly contrasts with the sibling list_accounts (plural enumeration vs. single fetch). It is clear but never explicitly names or differentiates itself from list_accounts.

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 required 'id' parameter implies the caller must already know the account ID, but the description never says when to use this vs. list_accounts to discover IDs, nor states any prerequisite or exclusion. Usage is only implied.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds substantial context beyond that: daily vs lifetime periods, the meaning of a missing key, and a per-object `note` field the caller must relay. It does not discuss auth or rate limits, but the metric-interpretation guidance is genuinely valuable.

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 purpose before diving into metric semantics. It is long for a two-parameter tool and reads as a dense run-on, but with no output schema present most sentences carry needed return-interpretation detail rather than filler.

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

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

With no output schema, the description bears the burden of explaining the return shape and does so thoroughly – platform metrics, audience objects, period values, and the note-relaying requirement. The main gap is the absence of any usage routing relative to the sibling analytics 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 100%, so the date and platform parameters are already documented in the schema. The description references 'the snapshot date' but adds no filtering syntax or defaults beyond what the schema provides. 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+resource ('Get account-level analytics') and enumerates the metrics returned (followers, impressions, reach, engagement, etc.). 'Account-level' implicitly distinguishes it from post-level siblings like get_post_analytics, but it never names them, so the differentiation is left to inference.

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

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

There is no when-to-use/when-not guidance and no routing to alternatives. Siblings get_analytics_overview, get_post_analytics, and get_best_times are never mentioned, so an agent must guess which analytics tool to pick. Only the implicit 'account-level' scope hints at selection.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), so the bar is lower, and the description still adds substantive behavior: the response echoes the resolved range plus today's date, and the agent is told to read those before assuming dates from training data. That is a concrete, non-obvious operational trait that annotations cannot express.

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

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

Front-loaded with the return contents, then parameter modes, then the date-interpretation caveat. Three sentences with no filler; the final sentence is longer but carries a genuinely useful warning that would otherwise be lost.

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

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

No output schema exists, so the description carries the burden of describing returns, and it does list the metrics and the echoed resolved range. Combined with annotations covering safety and a fully documented parameter schema, an agent has enough to call and interpret this correctly; only the sibling boundary remains unaddressed.

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 period defaults, the 7d/30d/90d options, date formats, and the YYYY-MM expansion. The description restates the period values and range combination but adds no syntax or precedence detail beyond the schema, so 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 (analytics overview) and enumerates the metrics returned: total posts, impressions, engagements, engagement rate, per-platform breakdown. It implicitly differs from per-post siblings, but never names get_account_analytics or get_post_analytics to make the boundary 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?

Explains how to drive the two date modes (rolling `period` vs `start_date`+`end_date`) and how to interpret the resolved range, which is real usage guidance. However, it gives no guidance on when to pick this overview tool over get_account_analytics, get_post_analytics, or get_posts_analytics, leaving the alternative-selection decision to inference.

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

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

The annotations already establish that this is a safe, read-only, non-destructive operation. The description adds useful context by naming the configuration fields returned, but it does not cover error behavior, missing IDs, or other operational details.

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 front-loaded sentence with no wasted phrasing. The enumerated return fields are relevant and compact.

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

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

For a one-parameter read tool with read-only annotations and no output schema, the description is largely complete because it explains what the returned automation contains. Minor gaps remain around error cases and how this relates to automation activity.

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

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

Schema description coverage is 100%, and the single parameter is documented as an automation id 'from list_automations.' The description itself adds no further parameter-level detail, 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 uses a specific verb and resource: 'Get one comment-to-DM automation.' It makes the single-resource scope explicit and lists the returned configuration fields, which distinguishes it from list_automations and get_automation_activity.

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

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

The phrase 'Get one' implies retrieving an individual automation, and the schema notes that the id comes from list_automations. However, the description does not explicitly state when to use this versus list_automations or get_automation_activity.

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 it is a safe read; the description adds real operational semantics beyond that: queued answers are gated by the send cap or an X wait request and drain within the hour, opted_out suppresses automatic DMs across every workspace and automation, and failures carry the platform error. It also discloses the return shape (person shown by name on Facebook since there is no @handle), which 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?

The core identity is front-loaded in the first clause, but the tool is described in one very long run-on sentence with a seven-item parenthetical of skip reasons. Each item is substantively useful for the 'why did this person not get it' use case, yet the wall of text hurts scannability and would benefit from being broken into separate sentences or a list.

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

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

No output schema exists, and the description compensates by describing the row contents (comment/message acted on, DM text, queue state, skip reason, opt-out, failure error) and ordering. Combined with annotations covering the safety profile and a fully documented schema, 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 coverage is 100%, so limit/offset/automation_id are already documented and the baseline is 3. The description earns above baseline by defining the meaning of each outcome value used in the `outcome` enum filter (queued vs skipped vs opted_out vs failed), which is the one parameter whose semantics the schema alone cannot explain.

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

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

States a specific resource (the activity log of a comment-to-DM automation), the ordering (newest first), and the row granularity (one row per comment or message acted on). The enumerated outcome taxonomy makes it unmistakable versus get_automation or list_automations, which an agent could otherwise confuse it with.

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

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

Gives concrete answering scenarios: 'how many people got the DM' and 'why did this person not get it', which map directly to counting rows and reading skip reasons. It does not explicitly exclude alternatives (e.g. use get_automation for config rather than activity), 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 already mark it read-only and non-destructive, and the description adds substantial behavioral context beyond that: the recency-weighted, outlier-damped methodology, the audience-online blending for Instagram and TikTok Business, the basis values (`own_data_and_audience`, `audience`, `defaults`), the 15-post threshold, and the required analytics:read scope.

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 and usage trigger are front-loaded, and nearly every clause carries useful information. It is dense and long, but the detail about fallbacks and basis values earns its place; only minor restructuring would improve readability.

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

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

With no output schema, the description steps in to explain the return shape (top 3 slots plus per-day breakdown) and the `basis` and `audience_online` fields. It also covers the sparse-data case and the permission requirement, leaving no major gap for a read-only recommendation tool.

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

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

Schema description coverage is 100%, so both parameters are already documented. The description still adds meaning by emphasizing that results are for one platform, that audience-online support varies by platform, and that bucketing uses the user's timezone.

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: it returns recommended posting times (day + hour) for one platform, computed from the workspace's posting history. It clearly distinguishes itself from analytics siblings by focusing on recommendations rather than raw metrics, and it names the exact output (top 3 slots plus per-day breakdown).

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 before scheduling when the user asks 'when should I post?' or has not specified a time. It also explains fallback behavior when history is sparse, including what to tell the user so defaults are not mistaken for personalized data.

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 openWorldHint=false, so the safety profile is covered. The description usefully adds the grouping semantics (organized by day of the week) and that both scheduled and published posts appear, but says nothing about pagination, ordering, or limits.

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

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

A single, front-loaded sentence with no filler. Every clause (scheduled, published, organized by day of the week) carries information an agent can use.

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 tool with full annotation coverage and complete parameter docs, the description supplies the essential return-shape context (a calendar grouped by weekday). No output schema exists, so it should ideally say a bit more about what each calendar entry contains, but it is close to sufficient.

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

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

Schema description coverage is 100% — all three parameters (status, start_date, end_date) are documented in the schema, including defaults. 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 (Get) and resource (content calendar) and clarifies the shape of the result: scheduled and published posts organized by day of the week. This framing distinguishes it from the flat list_posts sibling, though no sibling is named explicitly.

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

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

The calendar framing implies the use case (viewing posts in a weekly calendar layout rather than a flat list), but the description never states when to prefer this over list_posts or get_post, nor any prerequisites or exclusions. Usage must be inferred.

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, openWorldHint=false, so safety is covered. The description adds real behavior: oldest-first ordering, inclusion of the parent post's caption/link/image, the #id format that other tools consume, and the non-obvious fact that native-app replies surface as outgoing messages.

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 ordered before workflow details. Dense but almost every clause carries information; the parenthetical field list is the only slightly heavy part.

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

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

With no output schema, the description carries the burden of describing the return shape and does so (message ids, per-message data, attached post fields, ordering). Pagination is handled by the schema's limit/cursor, so nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so limit, cursor, and conversation_id are already documented in the schema; baseline is 3. The description adds provenance for conversation_id (source it from list_inbox_conversations) but says nothing extra about limit or cursor semantics.

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

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

States a specific verb and resource ('Get the full message history of one inbox conversation'), plus ordering ('oldest first') and included payload ('the post it belongs to ... for comment/mention threads'). It is clearly distinguishable from list_inbox_conversations, which enumerates conversations rather than one thread.

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

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

Explicitly routes the agent: 'Use the conversation_id from list_inbox_conversations,' and names the downstream consumers of the returned ids (hide_inbox_comment, delete_inbox_comment). No explicit when-not or exclusion criteria are given, but the workflow context is clear.

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 openWorldHint=false, so the safety profile is covered. The description adds substantial behavioral context the annotations cannot: the 30-day lookback, the three-tier ordering with 24-hour window logic, that native-app replies count as answered, and that Instagram mentions are skipped. However it does not state return format or pagination, so against a lower bar it is solid but not exhaustive.

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

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

Long but front-loaded: the first sentence gives the core purpose and payload, and every subsequent sentence carries needed ordering, window, or loop semantics with no filler. The information density justifies the length for a tool with this much selection logic.

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

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

There is no output schema, and the description compensates by stating the return payload (whole conversation plus the post) and the identifiers the agent needs for the follow-up call (conversation id, message #id). Combined with the lookback limit and ordering rules, an agent can invoke this correctly without further 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 coverage is 100%, so the baseline is 3, but the description adds semantic nuance beyond the schema: it explains that ordering preserves group order, that skip-via-exclude is temporary while mark_inbox_read is permanent, and clarifies include_read's role in the workflow.

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 next inbox item that needs an answer') and precisely defines the selection predicate (customer's latest unanswered DM, or unhidden unreplied comment/mention), which clearly separates it from list_inbox_conversations and get_inbox_conversation.

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

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

Explicit when-to-use with a full decision flow: it defines what 'needs an answer' means, names the alternatives for skipping (mark_inbox_read for permanent, include_read for read items), tells the agent what to do when the reply window is closed, and closes with the get_next_unanswered → reply_to_inbox loop.

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

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

Annotations already cover the safety profile (readOnlyHint, destructiveHint=false, openWorldHint=false), and the description goes further by disclosing return semantics: per-platform publish errors, how `retry_of`/`retries` indicate a resolved failure, and that `published_urls` only lists platforms that successfully posted. This is genuine behavioral context an agent cannot get from the annotations.

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

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

The opening clause is well front-loaded, but the body is one sprawling, unparagraphed run-on that mixes content rendering rules, thread handling, poll rendering, and retry semantics. The information is relevant, yet its density and lack of structure make it hard to scan for the one parameter an agent must supply.

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

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

With no output schema, the description shoulders the return-value burden and does so thoroughly, covering content, media URLs, threads, polls, errors, and published URL mapping. It omits only edge behavior such as an invalid or missing post ID, which is a minor gap for a single-resource getter.

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

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

Schema description coverage is 100% and there is a single `id` parameter already documented as 'The post ID.' The description adds no format, source, or lookup guidance for the ID, so the baseline 3 applies – the schema carries the full burden.

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 full details of a specific post' with an enumerated scope (content, channels, media, errors, retry linkage). An agent can tell this is a single-post detail fetch, not a list or analytics call, though it never names the sibling it differs from (get_post_analytics, list_posts) to sharpen the distinction.

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 via the phrase 'enough to fully verify a scheduled post without opening the dashboard.' There is no explicit when-to-use, when-not-to-use, or named alternative such as get_post_analytics for metrics; 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 establish readOnly/openWorld=false/destructive=false, so the description's job is additive — and it delivers: it enumerates the returned metric families and discloses that certain TikTok fields (average_time_watched, full_video_watched_rate, etc.) are conditional on workspace TikTok Business API authorization. That conditional-data caveat is real behavioral context beyond 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?

Two sentences, front-loaded with the core purpose, then the metric inventory and the conditional TikTok caveat. The long metric list ('impressions, reach, views, saves, likes, comments, shares, clicks, engagements, and more') is somewhat enumerative but serves the no-output-schema case, so it earns most of its space.

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

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

With no output schema, the description compensates by describing the return payload per platform, which is exactly what an agent needs to interpret the result. It omits any note on authentication scope or whether metrics can be empty for older posts, minor gaps given the annotation coverage.

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

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

Schema description coverage is 100% and the single parameter already explains that post_id is the numeric OmniSocials id from list_posts, not a platform id. The description adds nothing 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?

States a specific verb ('Get') plus resource ('detailed analytics') scoped to 'a specific published post', which implicitly sets it apart from the plural sibling get_posts_analytics and from get_analytics_overview. It stops short of naming those siblings, so the differentiation is inferential 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?

The phrase 'specific published post' weakly implies the per-post scenario and that drafts are excluded, but there is no explicit when-to-use versus get_posts_analytics, get_analytics_overview, or get_account_analytics, and no stated prerequisites beyond the required id.

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 openWorldHint=false, so safety is covered; the description's 'Read-only' line is largely redundant. It does add genuine behavioral context by describing the returned content and the edge case where a post has no workflow and returns status `none`.

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 payload description, then the usage trigger, then edge cases; each sentence earns its place. The standalone 'Read-only.' fragment restates the readOnlyHint annotation and is the one piece of low-value content.

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

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

There is no output schema, so the description carries the return-value burden, and it does so by enumerating what the approval review contains plus the `none` status for posts without a workflow. Combined with annotation-covered safety, 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% and there is a single required `id` parameter already documented in the schema, so per calibration the baseline is 3. The description adds no syntax or format detail about the post ID beyond what the schema 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?

States a specific verb (read) and resource (the approval review of a post) and enumerates the exact payload: workflow steps, approvers, decisions, rejection reason, and comment thread. This clearly distinguishes it from approve_post, reject_post, and get_post, which an agent can tell apart without opening the schema.

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

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

Gives explicit trigger conditions keyed to a sibling's output: use it when get_post shows status `rejected` or `in_approval`, with the purpose spelled out for each case. It also names the fallback behavior (a post without an approval workflow returns `none`), leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: results are aggregated (totalled into impressions and engagements), the batch cap is 100, and the call is a single request rather than N. It does not discuss pagination, partial failures, or permission requirements, so not a full 5.

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

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

Two sentences, zero waste. The scope and cap are front-loaded, and the routing instruction to get_post_analytics follows immediately after.

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

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

For a one-parameter read tool with annotations covering the safety profile and no output schema, the description supplies what an agent needs: the batching semantics, the cap, the aggregation into impressions/engagements, and the alternative it replaces. 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% and the single parameter is already documented in the schema, including the numeric-OmniSocials-id vs platform-id distinction and the maxItems=100 cap. The description's 'up to 100' and 'published posts' restate the schema rather than adding syntax or format meaning, so the baseline 3 applies.

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

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

States a specific verb (Get) and resource (analytics) with an explicit scope: several published posts at once, up to 100, totalled into impressions and engagements. It names the sibling get_post_analytics and explains how it differs, so an agent can select it without opening either schema.

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

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

Explicitly says to use this instead of calling get_post_analytics in a loop, and gives the reason (single request rather than one per post). This is a clear when-to-use directive with the alternative 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?

The annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false. The description adds that it follows a post while publishing, implying a status/polling behavior, but does not disclose return format, polling expectations, or other behavioral traits beyond 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?

Two short sentences with zero waste, and the most important routing instruction is placed clearly at the end. Nothing extraneous is included.

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, single-parameter status tool with no output schema and clear annotations, the description is nearly complete. It tells agents to avoid it and names the alternative, though it does not describe the status values or polling behavior, which is a minor gap.

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

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

The schema has 100% description coverage for the single id parameter. The description adds no additional meaning about the post ID or its format, so the baseline of 3 is appropriate because the schema fully documents the parameter.

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

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

States a specific verb and resource: following a post while it publishes. It also distinguishes itself from the sibling get_post by telling agents to use that instead. An agent can identify the tool's intended role 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?

Explicitly states when the tool is used (by the OmniSocials post card while publishing) and gives a direct when-not instruction: 'Agents: use get_post instead.' This is unambiguous routing guidance with a named alternative.

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

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

Annotations only cover the safety profile (readOnly/openWorld/non-destructive), and the description adds substantial behavioral context: live-fetch latency, a possible 24h snapshot staleness for X with the billing rationale, the LinkedIn personal-profile permission limitation, which platforms actually expose metrics, and the required analytics:read scope.

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?

Well front-loaded — the core purpose and the list_posts routing come first, caveats after. It is dense and long, but nearly every clause (snapshot staleness, metric availability, duration_seconds, output block) carries actionable information, so little is wasted.

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

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

With no output schema, the description carries the return-value burden and does so thoroughly: a summary table plus a 'Structured data' JSON block with stable post id, permalink, untruncated caption, and exact-integer metrics. Combined with the per-platform metric caveats, an agent has everything needed to call and consume 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 coverage is 100%, so the schema already documents both params, giving a baseline of 3. The description reinforces why limit defaults differ for X (billing) and clarifies platform-filtering intent, adding marginal value over the schema rather than restating it.

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

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

States a specific verb+resource ('Fetch the user's most recent posts') with precise scope ('straight from their connected platform APIs... INCLUDING content published outside OmniSocials'). It explicitly distinguishes itself from the sibling list_posts, so an agent can separate the two without opening either schema.

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

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

Gives an explicit trigger condition: 'Use this when list_posts is empty — e.g. a brand-new workspace that has not published through OmniSocials yet.' The alternative (list_posts) is named and the selecting condition is spelled out, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false. The description adds no behavioral context such as error handling, permissions, or response shape beyond what the structured annotations already provide.

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

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

A single front-loaded sentence with verb, resource, and scope. No filler or wasted words.

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

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

For a simple read tool backed by full annotation coverage and a 100%-documented schema, the description is complete enough to invoke correctly. It does not need to explain return values because no output schema exists, though it lacks routing and error 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?

The single id parameter has 100% schema description coverage, so the schema already documents it. The description's 'by ID' adds no format or constraint detail beyond the schema, making the baseline 3 appropriate.

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

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

States a specific GET operation on a webhook resource, scoped by ID, which separates it from list_webhooks. No explicit sibling is named, but the by-ID scope gives sufficient 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?

Usage is implied by 'by ID'—call this when you have a known webhook ID—but there is no when-to-use or when-not-to-use guidance, and no alternative routing among get/list/update siblings.

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

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

Annotations declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds substantial context beyond it: platform-specific semantics (YouTube 'rejected' plus replies), idempotency when the comment was already deleted, the 'no longer counts as unanswered' side effect, and precise handling for 403 reconnect_required, 422 cannot_hide and 502 hide_not_applied.

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

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

Front-loads the core action and is information-dense with essentially no wasted sentence, but it is delivered as one very long run-on paragraph that is harder to scan than a structured breakdown of error cases would be.

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

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

No output schema exists, yet the description still tells the agent what the success response indicates and how each error code should be handled. For a two-parameter mutation tool with open-world behavior, 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 baseline is 3, but the description adds real disambiguation the schema lacks: it stresses the message id (#id) from get_inbox_conversation/get_next_unanswered is required, not the conversation id, and confirms the default hide=true toggle semantics. It stops short of new syntax detail but clearly earns above baseline.

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

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

States a specific verb pair (hide/unhide) and resource (a comment someone left on the workspace's posts), names the platforms, and clarifies the actor scope ('as the post owner'). An agent can distinguish it from delete_inbox_comment, mark_inbox_read and reply_to_inbox immediately.

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

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

Explicitly states the identifier to pass (message id, not conversation id) and names get_inbox_conversation and get_next_unanswered as the sources. It also gives when-not-to-retry conditions and routes to mark_inbox_read for the 422 case, so alternatives and exclusions are covered.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context beyond that: results are scoped to the active workspace and workspace selection may need to happen first. It omits any note on result volume or pagination.

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, no filler. The core action and its scope are front-loaded, and the workspace prerequisite follows immediately after.

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 parameterless read-only list tool with annotations carrying the safety profile and no output schema, the description covers action, scope and the one workflow dependency an agent needs. Nothing required 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?

The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly implies no filtering or selection arguments are needed, and there is nothing for it to compensate for.

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

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

States a specific verb (list) and resource (connected social media accounts) and constrains scope to the active workspace. That scope constraint is what separates it from the singular get_account sibling without needing to name it.

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 prerequisite and routes to list_workspaces when the user has multiple workspaces, which is real when-to-use guidance. It does not, however, state when to prefer this over get_account or what to do if no workspace is active.

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 openWorldHint=false, so safety is covered. The description adds real behavioral context beyond them: that workflows are created only in the dashboard and this tool merely lists them, plus the side effects (created as in_approval, approvers notified, publishes at schedule_at after final approval) of using a returned 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?

Three sentences, front-loaded with what is listed, then the create-vs-list boundary, then the operational guidance and empty-state instruction. No filler; every sentence changes agent 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?

Despite no output schema, the description specifies the returned content (steps, named approvers) and the empty-list handling. For a zero-parameter read tool with annotations already covering the safety profile, nothing an agent needs 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?

The tool takes zero parameters, so the baseline is 4. The only identifier mentioned (approval_workflow_id) belongs to create_post, not this tool, and the description correctly frames it as a value this tool produces to be consumed elsewhere.

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 with explicit scope: company-wide plus workspace-bound workflows, including that steps and named approvers are returned. No sibling tool overlaps this resource, so differentiation is inherent.

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 exactly when to call it ('Call this first when the user wants agent-created posts to be reviewed/approved before publishing') and what to do on the empty case ('tell the user to create a workflow under Approvals in the dashboard'). It also names the downstream alternative path via create_post's approval_workflow_id.

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, openWorldHint=false, so safety is covered. The description goes beyond them by disclosing domain behavior an agent needs: an automation fires once per matching comment, an optional public reply may accompany the DM, and on X it answers DMs only. Pagination/return shape is not covered, keeping it below a 5.

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

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

Purpose is front-loaded in the first clause, and the second and third sentences each carry distinct load (domain model, then usage triggers). Slightly dense in the middle, but no sentence is expendable.

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?

Read-only tool with no output schema and fully documented optional filters; the description supplies the domain context the schema cannot (what an automation does, cross-platform differences) plus id-reuse guidance. Only the shape of the returned list is unspecified, which is a minor gap given the read-only annotations.

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 two of three parameters carry enums, so the schema already documents status, post_id (including the one-per-platform hint), and platform. The description adds no filter syntax or combination guidance beyond that, so 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?

Specific verb+resource ("List the comment-to-DM automations of this workspace") with platform scope enumerated (Instagram, Facebook Page, X). It also defines what an automation is, which lets an agent distinguish this from get_automation, create_automation, and get_automation_activity without opening a schema.

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

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

Gives three concrete when-to-use triggers: answering "which automations run", pre-checking before creating one on a post that may already have one, and resolving an id for update_automation / get_automation_activity. It names the downstream siblings but doesn't explicitly state when to prefer get_automation (single-record lookup) instead.

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 openWorldHint=false, so the safety profile is covered. The description adds real value by enumerating the returned fields (id, name, parent, item count), which matters because there is no output schema. It does not mention ordering, pagination, or empty-workspace behavior.

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

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

Two sentences, no filler, and the core purpose is front-loaded before the return-value and downstream-usage details. Every clause 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?

For a zero-parameter read-only listing tool with annotations covering safety, the description supplies the one thing not in structured data — the shape of the result — via the enumerated return fields. Nothing essential to calling 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?

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. The mention of folder_id/folder applies to sibling tools rather than this one's inputs, so no additional credit is warranted.

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

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

States a specific verb and resource ('List the media-library folders in this workspace') and adds scope qualifier ('Finder-style organization'), which distinguishes it from create_folder and list_media. An agent immediately knows what it returns and that it enumerates rather than filters.

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

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

Gives clear downstream context: folder ids feed list_media and update_media, folder names feed upload_media. That tells the agent why to call it, but it never states when not to call it or names an alternative folder-listing route (there effectively is none among the siblings), so it falls short of explicit when/when-not guidance.

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

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

With readOnlyHint=true and destructiveHint=false already declaring the safety profile, the description adds useful behavioral context about what applying a set does (append to captions, or post as auto first comment with hashtag_placement='first_comment'). This goes beyond what annotations cover.

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

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

Two tightly written sentences; the core purpose leads, and the follow-on workflow note earns its place without 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?

No output schema exists, yet the description implicitly conveys the return (saved hashtag sets usable by name) and the workflow around them. Adequate for a zero-param list tool, though it could note whether sets are ordered or include counts.

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 baseline is 4. The description still adds semantic value by explaining the hashtag_set and hashtag_placement parameters of the related create_post tool, clarifying how the names returned here are meant to be consumed.

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

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

States a specific verb (List) and resource (saved hashtag sets) scoped to the workspace, which cleanly distinguishes it from create_hashtag_set, update_hashtag_set, and delete_hashtag_set.

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 downstream use case: apply a set to a new post by passing its name via create_post. It gives clear consumption context but does not state explicit when-not-to-use conditions or point to a direct alternative listing tool.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered; the description adds real behavioral context on ordering ('newest activity first') and pagination mechanics ('pass the returned cursor to get the next page'). It does not describe the shape or size of an individual conversation record, but the added pagination/ordering detail goes beyond the annotations.

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

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

The core operation and ordering are front-loaded, followed by pagination mechanics and the sibling routing. The long parenthetical platform inventory is dense but each item is load-bearing for scope. Slightly heavy in one sentence, but no filler.

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

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

With no output schema, the description still tells the agent the ordering and the cursor-pagination contract, and the six optional filters are fully documented in the schema. Combined with annotations covering the read-only profile, nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, with the 'unanswered' filter even spelled out in detail at the schema level, so the description does not need to re-explain parameters. It adds no syntax or format nuance beyond what the schema already provides, making the baseline 3 appropriate.

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

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

States a specific verb+resource ('List social inbox conversations') and enumerates exactly which sources are covered (IG/FB DMs, comments, mentions, LinkedIn, TikTok, YouTube, X, Threads). It also draws the boundary against the nearest sibling by contrasting bulk listing with one-at-a-time triage. An agent can identify the tool without opening the schema.

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

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

It explicitly routes the agent to get_next_unanswered when the goal is working through items one at a time, which is a clear when-to-use-alternative statement. It stops short of covering other adjacent siblings (get_inbox_conversation, mark_inbox_read) or when to prefer the 'unanswered' filter over the sibling triage tool, so it 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 declare this as a safe read operation (readOnlyHint=true, destructiveHint=false). The description adds useful non-annotation context: the exact fields returned, the PDF-as-one-item expansion behavior, and the duplicate-creation warning. It does not cover pagination defaults, but the added behavioral detail is substantial.

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

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

Three sentences, front-loaded with purpose and output summary. The parenthetical about PDF expansion is dense but valuable, and all sentences earn their place. Minor length but no wasted prose.

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 list tool with four optional params and no output schema, the description compensates by naming the returned fields and giving usage guidance. Annotations cover the safety profile. It is complete enough for correct invocation, with only pagination behavior left implicit.

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

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

Schema description coverage is 100%, so the schema already fully documents all four optional parameters. The description reinforces the search-before-upload guidance but adds no new syntax or meaning beyond what the schema 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?

States a specific verb and resource: 'List media files in the workspace,' and enumerates the returned fields. It does not explicitly contrast with sibling list tools like list_folders or list_posts, but the 'media files' resource is distinct enough to be clear.

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

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

Gives a concrete when-to-use: search here before uploading to avoid duplicates. Also points to create_folder / list_folders for organizing assets. It lacks explicit exclusions or comparison to other list tools, but the context is clear.

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, openWorldHint=true, destructiveHint=false, so safety is covered. The description adds substantial non-obvious behavior: only the account's own product Pins can be tagged, catalog access requires a one-time user setup in OmniSocials, one call scans up to 250 Pins so an empty result with a bookmark means paginate, and a Pinterest-rejected product never fails the post.

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

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

Front-loads the purpose and the action flow, then separates caveats into a Notes block, which is well organized. It is on the long side and the notes are dense, but nearly every sentence carries operational 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?

For a four-parameter, paginated, dual-source listing tool with no output schema, the description covers the resolution logic, pagination signal, and refusal behavior well. It could say slightly more about the shape of returned product entries, but an agent has enough 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 coverage is 100%, so the baseline is 3, but the description genuinely adds meaning: it explains the default resolution order for `source` (catalog when catalog access exists, else pins), the pagination implication of `bookmark`, and that `check_pin` accepts a Pin link or ID and answers a yes/no taggability question.

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

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

States a specific verb and resource ('List the product Pins of the connected Pinterest account') plus the reason it exists (tagging products on a Pin). This is clearly distinguishable from siblings like list_posts or list_media 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?

Explicitly says to use it 'whenever the user wants to tag products on a Pinterest post,' then gives the exact flow (list → show → pass pin_id values as pinterest.product_tags on create_post/create_and_publish_post/update_post). It also names the check_pin alternative and when to use it, so nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the exact shape of the returned table (content preview, channels, dates, post IDs), plus the non-obvious *(per-platform)* marker convention that governs how the preview should be read.

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 sentences, each carrying distinct payload: scope, filtering, return shape, and the per-platform reading rule with a routing instruction. Nothing is repeated and the per-platform caveat — the hardest thing to get wrong — is given last as an explicit action.

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

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

There is no output schema, so the description correctly compensates by describing the returned table columns and the preview convention. With annotations covering safety and the schema covering all three parameters, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100% — limit, offset, and the four status values are all documented in the schema itself. The description restates the status filter but adds no syntax, default, or format 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 and resource ('List posts in the workspace') and immediately distinguishes itself from the sibling get_post by naming it as the tool to call for full per-platform variants. An agent can tell this apart from list_media, list_folders, and other list_* siblings without opening a schema.

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

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

Gives clear usage context: filter by status for drafts/scheduled/published/failed, and route to get_post when the *(per-platform)* suffix appears. It names the alternative and the condition that selects it, though it does not explicitly state when not to use this tool (e.g. for a single known post ID).

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 openWorldHint=false, so the safety profile is fully covered without the description. The description usefully adds what a webhook record contains, but says nothing about pagination, ordering, or whether disabled/inactive hooks are included — gaps that matter for a listing 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?

A single front-loaded sentence with no filler. The verb, resource, scope, and returned payload are all packed in without repetition of the title.

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

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

For a no-parameter, read-only list tool with annotations covering safety and no output schema, the description is nearly complete — it even describes the return fields in lieu of an output schema. The only missing piece is pagination/ordering behavior on large webhook lists.

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 and the baseline of 4 applies. The mention of returned fields is a small bonus rather than parameter guidance.

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

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

States a specific verb (List) and resource (webhooks) and adds scope ('all configured') plus the fields returned (status, events, last trigger time). It implicitly separates itself from the singular get_webhook sibling, but never names it explicitly, so the differentiation is left to inference.

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

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

Usage is only implied: 'List all configured webhooks' suggests enumeration, but there is no explicit when-to-use, when-not-to-use, or pointer to the alternatives (get_webhook for a single hook, create_webhook/delete_webhook/update_webhook for other lifecycle operations). An agent can guess the context but is not guided.

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 openWorldHint=false, so safety is covered. The description adds workflow-level behavior beyond that: it tells the agent to surface the list to the user and to mention the workspace name after a successful action. It stops short of describing what a workspace record contains, but the added behavioral context is real.

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

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

Purpose is front-loaded in the first sentence, followed by an ordered rule set that reads as a decision tree rather than filler. It runs longer than a one-line lister normally would, but every sentence maps to a distinct usage case, so the length is largely justified.

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

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

With no output schema, the description should ideally hint at what the list returns (e.g. workspace identifiers usable with switch_workspace), and it does not. It is otherwise complete: purpose, usage routing, and post-call behavior are all covered for a zero-parameter read tool.

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

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

The tool takes zero parameters, so the baseline is 4; there is no parameter syntax for the description to compensate for, and schema coverage is 100% on an empty object. Nothing further is required here.

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

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

States a specific verb and resource ('List all workspaces') and scopes it precisely ('the user has access to'), which separates it from siblings like list_accounts, list_folders, and list_hashtag_sets that also list resources. An agent can identify the tool's output 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?

Explicitly covers all three decision branches: single workspace (use it, don't ask), user-named workspace (proceed and remember it), and multiple unnamed workspaces (call this tool, present the list, ask before posting/switching/fetching analytics). It also names the downstream actions that require confirmation, which is exactly the routing guidance an agent needs.

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 and destructiveHint=false, so the mutation/safety profile is covered structurally. The description adds genuine value by stating the operation is bulk ('all incoming messages in a conversation') rather than per-message, but it does not say whether the change is reversible or what permissions are required.

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

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

A single front-loaded sentence with zero filler, though its brevity also reflects the missing usage and behavioral detail rather than tight editing of richer content.

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

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

For a one-parameter mutation with full schema coverage and annotations carrying the safety profile, this is minimally adequate. The gaps are the absence of guidance about read-state reversibility and any when-to-use context among the crowded inbox siblings.

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

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

Schema coverage is 100% for the single conversation_id parameter, so the baseline is 3. The description's phrase 'all incoming messages in a conversation' does clarify the blast radius of that ID (bulk vs single message), which is a modest addition over the schema's one-line description.

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

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

States a specific verb (mark read), resource (incoming messages), and scope (all messages in a conversation), which distinguishes it from get_inbox_conversation and list_inbox_conversations. It does not explicitly name a sibling or an alternative, 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?

The description offers no when-to-use context, no prerequisites, and no routing against the many inbox siblings (hide_inbox_comment, delete_inbox_comment, reply_to_inbox, get_inbox_conversation). Usage is only inferable from the verb 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=false, destructiveHint=true and openWorldHint=true, so the mutation and safety profile is covered structurally. The description adds genuinely new behavioral context: only posts in draft or scheduled state are eligible, which constrains invocation. It does not state whether publishing is reversible or what happens to the scheduled time, so it falls short of a 5.

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

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

Two sentences, no filler, with the eligibility rule front-loaded ahead of the alternative-tool routing. Every clause earns its place.

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

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

For a one-parameter action tool with full schema coverage and annotations carrying the safety profile, the description covers purpose, eligibility and routing adequately. It omits any indication of what publishing returns or whether the action is queued versus immediate beyond the word 'immediately', a minor gap given no output schema exists.

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

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

There is a single required 'id' parameter whose schema description ('The post ID to publish') already covers it at 100% coverage. The description adds no format, source, or retrieval guidance for the ID beyond the schema, 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 (publish) plus the resource (post) and an explicit precondition (draft or scheduled, published immediately). It also names the sibling retry_post and the state condition that selects it, so an agent can distinguish it from neighboring post 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?

Gives both when-to-use (draft or scheduled posts) and when-not-to-use with a named alternative ('for a failed or partially failed (warning) post use retry_post instead'), including why that alternative exists. Nothing about tool selection is left to inference.

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

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

Annotations cover safety flags (readOnly=false, destructive=false, openWorld=false), but the description adds substantial behavioral context beyond them: the post must be in_approval, only a current-step approver may succeed, and rejection terminates the entire workflow so the post becomes 'rejected' and never publishes. That is exactly the destructive-adjacent consequence an agent needs.

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

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

Four dense sentences, front-loaded with the core action and precondition before the divergence from approval. Slightly long, but each sentence carries distinct operational information rather than repeating the schema.

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

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

With no output schema, the description still tells the agent the resulting state (status becomes 'rejected', no publish) and the permission model. Nothing needed to call 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 coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining that the comment is surfaced to the requester and other approvers in the review thread, clarifying its audience and intent.

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 (reject) and resource (a post's approval workflow) and immediately scopes it. An agent can distinguish it from approve_post 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?

Explicit preconditions: only works on approval_status 'pending', instructs to check get_post first, and names the sibling approve_post with the shared approver requirement. The when/when-not conditions are 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 only flag destructiveHint/openWorldHint; the description goes far beyond them, disclosing the Meta 24-hour window and its 422 outcome, TikTok's 150-char text-only comment limit and spam-review delay, YouTube comment-only scope, X DM-only scope, the 10-minute 409 duplicate_reply semantics, and the permanent 422 reply_not_allowed causes (Facebook #1705, YouTube canReply=false) with the note that the item is auto-dropped from get_next_unanswered.

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

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

Purpose and the core reply constraint are front-loaded, and every clause carries actionable error-handling information rather than filler. It is nonetheless a very long single paragraph; a small amount of the platform-by-platform error prose could be tightened without loss.

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

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

For a destructive, open-world mutation tool with no output schema, the description covers prerequisites (existing conversation, 24h window, Threads reauth), platform limits, per-error recovery paths, and what include_next returns ('nothing waiting' or the next thread), leaving nothing an agent needs before calling 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 coverage is 100% so the baseline is 3, but the description adds genuine meaning: it explains why message_id matters for comment threads (all comments on a post share one conversation, so omitting it posts under the newest comment) and that attachment_url/attachment_type apply only to Facebook/Instagram DMs with text optional.

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 (inbox conversation), enumerates the supported platforms, and draws the boundary 'You can only reply to conversations that already exist.' It clearly distinguishes itself from siblings like get_inbox_conversation, mark_inbox_read, and delete_inbox_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?

Explicit when-to-use and when-not-to-use: names the alternative flow (get_next_unanswered → draft → reply_to_inbox(include_next) → draft), tells the agent to pass message_id for comments but not DMs, and gives concrete do-not-retry instructions for 422/409/401/x_feature_not_enabled cases with the correct fallback (mark_inbox_read, reconnect, tell the user).

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=true, openWorldHint=true), the description discloses that only FAILED platforms are re-published, that succeeded platforms are never reposted, that execution is asynchronous, that the agent must poll get_post, and that there is a max of 3 retries per platform. That is the kind of operational detail annotations cannot express.

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

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

Every sentence earns its place: scope, eligibility, platform-level behavior, async semantics, polling target, retry cap, and sibling contrast. The key constraint (same post, no duplicate) is front-loaded rather than buried.

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

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

No output schema exists, yet the description still tells the agent what to expect after the call (status becomes `published`, `published_urls` gains the live URL) and how to observe it via get_post. For a one-parameter async mutation tool, nothing an agent needs to invoke and follow up 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?

Only one parameter, and schema coverage is 100%, so the schema already documents `id` fully; the description adds no format, ID-source, or validation detail. Baseline 3 is appropriate when the schema carries the parameter burden.

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 ('Retry the failed platforms of a failed or partially failed post') and immediately scopes it ('on the same post, no duplicate created'). It explicitly contrasts itself with the sibling publish_post ('publish_post refuses failed posts; this is the tool for them'), so an agent can route correctly without opening either schema.

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

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

Gives explicit triggering conditions (status `failed` or `warning`) plus what happens in each case, names the alternative (publish_post) and its limitation, and states the escalation path after retries are exhausted ('after that, recreate the post'). Both when-to-use and when-not-to-use are covered.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is partly covered. The description adds a genuinely important behavioral fact beyond that: the new secret is returned only once and is unrecoverable afterward, which changes how the agent must handle the response. It stops short of saying whether the old secret is invalidated immediately and whether existing webhook consumers break.

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 operation and followed by the one critical caveat. Nothing is padded and every clause carries information.

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

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

For a one-parameter destructive mutation with no output schema, the definition covers the essentials and flags the one-time visibility of the returned secret. The remaining gap is the effect on the previous secret and existing integrations, which matters for a destructive rotation.

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 'id' parameter is already documented as the webhook ID, so the schema carries the load. The description adds no format, prefix, or lookup guidance beyond it; 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?

Names a specific verb (rotate) and resource (webhook signing secret), which is immediately separable from the sibling webhook tools (create_webhook, update_webhook, delete_webhook, get_webhook, list_webhooks). No ambiguity about what operation is performed.

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 states what happens but gives no guidance on when to rotate versus using update_webhook, nor any prerequisite or trigger condition (e.g. suspected compromise, scheduled rotation). 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?

Although annotations already declare readOnlyHint/openWorldHint/destructiveHint, the description adds substantial behavioral context beyond them: the licensing limitation that results differ from the Instagram app, and the prerequisite that the workspace must have a Facebook account connected with a linked Page, including an error-handling instruction. This is exactly the kind of hidden constraint that saves an agent from a failed 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 description is front-loaded with purpose, then organized into a Flow and a Notes block. Despite its length, every sentence carries actionable content (examples, the Reels-only limitation, the Facebook prerequisite), so nothing is wasted.

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

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

For a search tool with no output schema, the description supplies the missing pieces: what to do with results (present options, pass audio_id downstream), the return-relevant field name, and the auth/prerequisite conditions. Nothing an agent needs to call it 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 description coverage is 100%, so both parameters (type, query) are already fully documented, including the "OMIT for trending" behavior that the description repeats. The description adds downstream context (audio_id, volume params) but little new meaning about this tool's own parameters, 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 opens with a specific verb and resource ("Search Instagram's licensed music catalog for a track") and scopes it to a REEL, which clearly separates it from media/post/list siblings. An agent can identify the tool's function 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 states exactly when to use it ("whenever the user wants to post a reel WITH music/a song/a sound") with concrete examples, and it also gives an explicit exclusion ("Instagram Reels only — feed posts, carousels, and Stories can't take music via the API"). It further routes the agent to the downstream tools where the result is consumed.

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 safety (readOnlyHint, openWorldHint, destructiveHint), and the description goes further by disclosing failure modes: empty results with a permission note mean the Facebook app can't search arbitrary places, Threads needs a location permission that may require reconnecting, and bad Place IDs are validated at publish. It stops short of describing pagination or result limits, but the behavioral context is rich.

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?

Well front-loaded (purpose, then platform choice, then per-platform flows, then edge-case notes) and every paragraph carries actionable content. It is long, but the density is justified by the multi-step tagging workflow it has to support.

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

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

No output schema exists, so the description carries the return burden and does so ("matching real venues with their addresses and a location ID"), plus error/permission paths and the handoff to post-creation tools. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond it: the two platforms return DIFFERENT id namespaces, so you must search with the platform you'll tag, and it advises using a specific venue name since a broad brand returns individual stores.

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

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

States a specific verb+resource ("Search for a location to tag on a post") and its role in a larger flow, clearly distinct from siblings like search_instagram_audio. An agent knows exactly what it 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?

Gives explicit trigger conditions ("whenever the user wants to post WITH a place/location") plus worked examples, then spells out the per-platform flow and how the returned id feeds create_post / create_and_publish_post / update_post. Alternatives and follow-up routing are unambiguous.

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 a significant behavioral trait beyond the annotations: that all subsequent tool calls (posts, media, analytics) operate on the selected workspace, i.e. a session-wide state change. Annotations only carry the generic readOnlyHint=false/destructiveHint=false/openWorldHint=false safety profile, so the state-scoping note is genuinely additive. It stops short of describing reversibility or any confirmation/error behavior, so not 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?

Front-loads purpose, then the side effect, then the parameter format, then the usage rules. Four sentences, each carrying distinct information (what, effect, format, guardrail) with no filler.

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

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

For a single-param tool with 100% schema coverage, annotations, and no output schema, the description covers purpose, session-wide side effect, value format, and a consent guardrail. 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 3 is the baseline, but the description adds useful format guidance beyond the schema: pass the name 'exactly as shown in list_workspaces' and that the name is preferred because it is unambiguous. That cross-reference to the source-of-truth lister is real added meaning, though the name/id/list-number alternatives largely duplicate 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 ('Switch the active workspace') and immediately differentiates itself from the sibling list_workspaces by referencing it as the source of valid values. An agent can distinguish this state-changing tool from read-only listers without opening a schema.

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

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

Gives explicit when-to-use ('only when the user has explicitly named the target workspace, or after the user has picked one from list_workspaces') and explicit when-not-to-use ('Never call switch_workspace silently... ask first'). The alternative (list_workspaces) is named and the routing condition is 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?

Adds real behavior beyond the annotations: partial-update semantics, the 409 x_dms_off failure mode, and the non-obvious state transition where a 'completed' automation restarts when limits or trigger change. Annotations only supply the readOnly/destructive/openWorld flags, so this extra context is genuinely additive, though it does not describe the response or how the DMs already sent are affected.

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

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

Front-loaded with the updateable fields, then constraints, then the error/state caveats — no filler sentences. It is dense and somewhat long for a description, but each sentence (partial update, platform immutability, 409, completed restart) contributes distinct information.

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

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

For a 15-parameter mutation tool with no output schema, the description covers mutation semantics, a prerequisite failure, and a status edge case. It leaves unaddressed what the call returns and whether moving/max_sends changes affect an in-flight automation, which keeps it from a 5.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds value by grouping post_id/instagram_media_id/facebook_post_id as the mutually exclusive 'move to another post' path and by framing status as pause/resume rather than a raw enum. It stops short of explaining the interaction between scope and those ids beyond a pointer.

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 concrete verb+resource ('Change a comment-to-DM automation') and immediately enumerates the changeable dimensions (status, keywords/match, dm_text, limits, target post). This clearly separates it from create_automation and delete_automation in the sibling list.

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?

States partial-update semantics ('Only the fields you pass change'), an explicit exclusion with a redirect ('The platform cannot change: to move to another channel ... create a new automation'), and a precondition for a specific use (status 'active' on X needs X DMs on, else 409 x_dms_off).

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

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

Annotations already declare non-read-only, non-destructive, closed-world, and the description adds behavior beyond them: hashtags is a full replacement, not a merge, and existing posts that used the set are unaffected. It does not cover permissions or error behavior, so it is strong but not exhaustive.

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

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

Three front-loaded sentences with zero filler: purpose first, then the critical replacement caveat, then the side-effect note. 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 small mutation tool with no output schema and full schema coverage, the description supplies the essential semantics: optionality ('and/or'), replacement behavior, and non-retroactivity. Remaining minor gaps (empty-list handling, permission requirements) are not critical.

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 goes further by spelling out the replacement semantics operationally (pass the complete list) and routing the agent to list_hashtag_sets for current values. That adds usable meaning beyond the schema's terse field descriptions.

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 ('Rename a hashtag set and/or replace its tags'), listing exactly which fields it mutates. This clearly separates it from create_hashtag_set, delete_hashtag_set, and list_hashtag_sets among the 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?

Explains the key operational condition: to add or remove tags you must pass the complete new list, and it points to list_hashtag_sets to obtain the current tags. It gives clear context but stops short of stating when to use this versus other mutation alternatives (e.g. delete/recreate).

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds a genuinely useful trait beyond that: "Only the fields you pass are changed," disclosing partial-update semantics rather than full overwrite.

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 operation front-loaded and the non-clobbering behavior immediately following; nothing is wasted.

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

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

For a simple 3-param update with full schema coverage, annotations and no output schema, the description is essentially complete. It could still mention that folder_id comes from list_folders, but the 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?

Schema description coverage is 100%, so the schema already documents id, name and folder_id including the empty-string clear/move-to-root behavior. The description adds no parameter detail beyond what the schema provides, making the baseline 3 appropriate.

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

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

States a specific verb+resource (rename/move a media file) with a clear scope, and the parenthetical hints at why. It is readily distinguishable from upload_media and delete_media, though it never names a sibling explicitly.

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