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 already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false. The description adds real value beyond them: it discloses how a URL is inspected (size/type read via HEAD) and gives a concrete expected output example. It does not cover error/unsupported-platform behavior, so not a full 5.

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

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

Purpose is front-loaded in the first sentence, and the example and parameter rule follow logically. Slightly long with the quoted example, but each clause (the HEAD mechanism, the ONE-of rule) earns its place.

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

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

With no output schema, the description compensates by showing the shape of the warning ('won't post to Instagram (max 300 MB)') and covers all three input modes. Complete enough for a 0-required, 4-param 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?

Schema coverage is 100%, so baseline is 3, but the description adds the real semantic constraint: 'Provide ONE of' url, media_id, or size_bytes + mime, i.e. the mutual-exclusion rule and the pairing of size_bytes with mime. This is meaning beyond the flat 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+resource (check media compatibility) tightly scoped to 'platforms CONNECTED to this workspace' and to a pre-upload moment. It is clearly distinguishable from write-oriented siblings like upload_media and from list_media.

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

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

Explicitly says when to call it ('when the user gives you a file (URL) ... BEFORE uploading or posting') and what to do with the result ('warn them upfront ... then confirm before uploading'). The workflow placement relative to upload_media is 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?

Annotations already declare destructiveHint=true and openWorldHint=true, yet the description adds substantial context beyond them: X link posts consume credits, failed publishes are never charged, partial failure isolates to the X target only, and a 402 x_credits_insufficient is returned up front rather than at publish. This is meaningful behavioral disclosure for a publish 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?

The opening sentence is front-loaded and clear, but the body is a dense run of bold-headed paragraphs mixing operational rules, error semantics, and edge cases. Much of this is justified by the tool's 29-parameter complexity, but the volume is heavy and some guidance could be tighter.

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 29-param, nested-object tool with no output schema, the description covers the highest-risk cross-cutting behaviors (credits, partial failure, workspace/board resolution). It leaves many per-platform option semantics to the 90%-covered schema, which is appropriate, but does not explain approval-workflow interactions despite siblings like get_post_approval existing.

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 90%, so baseline is 3, but the description adds genuine meaning for several params — the Pinterest board_id auto-default fallback logic, the distinction between x.thread_parts (thread) and content (single tweet), and the workspace selection rule — none of which are fully derivable from schema descriptions alone.

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

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

States a specific verb+resource ('Create a new post and publish it immediately (no scheduling)'), which cleanly distinguishes immediate publishing from scheduled drafting. However, it does not explicitly name create_post or publish_post as the sibling it differs from, leaving the agent to infer the boundary from the parenthetical.

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

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

Provides strong operational guidance for specific cases (workspace selection rule, Pinterest board auto-default, X thread vs single tweet), but never states when to choose this tool over create_post/publish_post or what the prerequisites are. Usage is implied through the referenced create_post rules rather than spelled out.

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

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

Annotations already declare 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 are minimal (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the description carries the behavioral burden, and it does: it discloses the credit/fee model for X URL posts including the 402 x_credits_insufficient error, the reservation model for scheduled link posts, the 100 MB upload cap and per-platform file-size/ffprobe validation, the draft-exempt rule, the type/media validation failures, and the publish-time failure semantics. This is far more than the annotations 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?

Front-loaded with a clear purpose line and a numbered checklist, which is good structure. But the body is very long — large tables that partially duplicate the schema (character limits, video caps), and the Pinterest default flow is repeated in narrative form. It earns most of its length, but the duplication and the 400+ word length keep it out of 4-5.

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

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

For a 31-param, deeply nested mutation tool with no output schema and sparse annotations, the description covers preflight steps, per-platform media requirements, validation error shapes, credit semantics, and scheduling/approval flows. Nothing critical 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 description coverage is 97%, so the schema does most of the work. The description still adds value the schema does not: channel ID list, platform-specific caption object shape with example keys, X thread vs long-form decision path, Pinterest board_id auto-default behavior, character limits table, and video duration/file-size caps. It could go further on some top-level params (link_url, hashtag_set, location_id) but for a 31-param tool this is strong.

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

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

States a specific verb+resource ('Create a new social media post, story, or reel') and enumerates the three content types. The sibling set contains create_and_publish_post, so the description's careful 'save as draft / schedule / publish_now' framing plus the explicit approval_workflow guidance lets an agent distinguish it from the publish-immediately variant.

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 for the major alternatives: it names list_workspaces, list_accounts, upload_media and get_account as required preflight steps, tells the agent to ASK the user for missing info, and gives platform-specific gate conditions (Pinterest board auto-default, X thread vs long-form). The only reason it isn't a 5 is that it doesn't explicitly say 'use create_and_publish_post instead when the user wants immediate publish,' but the approval_workflow paragraph implies the boundary.

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

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

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

Beyond the readOnlyHint/destructiveHint/openWorldHint annotations, the description discloses the scoring methodology, the three possible `basis` values, the 15-post threshold that switches behavior, the audience-online blending limited to Instagram and TikTok Business, the `audience_online` response field, and the required analytics:read scope. This is unusually rich behavioral disclosure for a read tool.

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

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

The core purpose and output shape are front-loaded in the first clause, and the fallback/scope information follows in a logical order. It is dense and some computation internals ('recency-weighted and outlier-damped') are arguably more than needed, but nearly every sentence carries actionable information.

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

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

With no output schema, the description carries the burden of describing returns and does so ('top 3 recommended slots plus a per-day breakdown'), plus the basis values and fallback counts. An agent has everything needed to call and interpret the result 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 adds real meaning: `platform` determines whether audience-online blending applies (only Instagram and TikTok Business) and `timezone` governs how buckets are computed. It goes beyond restating the schema.

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

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

The description states a specific verb and resource ('Get recommended posting times (day + hour) for one platform') and immediately scopes it to workspace posting history. It is clearly distinguishable from the analytics siblings (get_account_analytics, get_analytics_overview), which return metrics rather than recommendations.

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

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

It explicitly names the trigger ('Use this before scheduling when the user asks "when should I post?" or hasn't specified a time'), which functions as both when-to-use and an implicit when-not. It does not name a competing tool, but no sibling actually competes for this job, so the guidance is close to complete.

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

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

Annotations already 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?

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, 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 declare readOnlyHint=true and openWorldHint=true, so safety is covered, but the description adds substantial context: source 'catalog' vs 'pins' behavior, catalog access requirement and how to grant it, 250-Pin scan limit with bookmark pagination, the fact that a refused product never fails the post, and that get_post shows tagged products. This is rich behavioral disclosure beyond what annotations 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 description is front-loaded with purpose and flow, then notes. It is somewhat long but every section earns its place by covering distinct concerns (flow, access, source semantics, failure behavior). Minor verbosity in the catalog-access instructions keeps it from a 5.

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

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

For a read-only list tool with 5 mxed params, no output schema, and clear pagination semantics, the description covers everything an agent needs: when to call, what to do with results, how to paginate, how source resolution works, and failure behavior. Nothing critical 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 documents all four parameters including the enum for source and the default logic. The description reinforces and contextualizes these (source default behavior, bookmark pagination, check_pin semantics) but does not add syntax beyond the schema, so it exceeds the baseline of 3 modestly.

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 (product Pins of the connected Pinterest account) and explains the downstream use case (tagging products on a Pin for shopping). It is clearly distinguished from siblings like create_post and search_* tools by naming the exact workflow it feeds into.

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 'Use this whenever the user wants to tag products on a Pinterest post' and lays out the full flow: call it, show products, pass pin_id values as pinterest.product_tags on create_post/create_and_publish_post/update_post. It also states the check_pin alternative for single Pin checks.

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 declare destructiveHint=true, openWorldHint=true, readOnlyHint=false, and the description adds platform-specific behavior far beyond them: the Meta 24-hour messaging window, TikTok 150-character text-only limit and spam-review delay, YouTube canReply restrictions, X credit-based billing, and the exact semantics of 409 duplicate_reply and 422 reply_not_allowed. This is the kind of disclosure an agent needs to avoid retry loops and misrouted replies.

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

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

The content is valuable but presented as a single dense paragraph with no line breaks or grouping by platform/error code, making it harder to scan than necessary. The first sentence is well front-loaded, but the remainder is a wall of run-on error and platform detail that could be structured into bullets without losing information.

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

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

For a complex, multi-platform mutation tool with no output schema, the description covers success behavior, platform-specific constraints, all important error codes and their required next actions, and the include_next return contract. An agent has everything needed to call this correctly and recover from failures.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description meaningfully enriches parameter usage by explaining why message_id must always be passed for comments (conversation sharing on a post) and how include_next chains into the inbox workflow. It also restates attachment constraints and platform-specific text limits that the schema only partially captures.

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 (reply) and resource (existing inbox conversation) and enumerates the exact platforms covered. It distinguishes itself from siblings like get_next_unanswered and get_inbox_conversation by requiring an already-existing 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?

It gives explicit when-to-use guidance, names alternative tools for adjacent actions (mark_inbox_read, get_next_unanswered), and details the exact error-specific routing for 422, 409, 401 and 402 cases, including when not to retry. The get_next_unanswered → draft → reply_to_inbox(include_next) workflow is spelled out step by step.

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

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

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?

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.

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

The phrase "instead of re-uploading it" implies the use case (fixing an existing asset rather than re-uploading), but there is no explicit when-to-use/when-not or pointer to an alternative tool such as list_folders for the folder_id lookup.

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 it as a non-read-only, non-destructive, non-open-world mutation. The description goes beyond that by disclosing the draft/scheduled-only constraint and the thread ↔ single-post conversion mechanics (including null-to-revert), which are behavior an agent needs. It does not state merge-vs-replace semantics at the top level, leaving some mutation detail to the schema.

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

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

Three tightly scoped, bold-headed blocks front-load the eligibility rule and then cover only the genuinely tricky areas (per-platform shape, YouTube title/content, X threads). For a 27-parameter nested tool this is compact, with little wasted wording.

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 high-complexity, 27-param, deeply nested tool with no output schema, the description covers the highest-risk pitfalls, and the 93%-covered schema handles the rest. Safety is covered by annotations, so nothing critical an agent needs to call it correctly appears missing, though fields like media/collaborators are left entirely to the schema.

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

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

Schema description coverage is 93%, so the baseline is 3 and the schema carries most parameter meaning. The description adds real value over the schema by warning to pass objects rather than JSON-encoded strings and by disambiguating youtube.title from content for Shorts ('changing the caption does NOT rename the Short') and the x.thread_parts 2–25 shape.

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 (update) and resource (existing post), and immediately constrains the eligibility to draft and scheduled posts. It also specifies what the per-platform options and thread fields do, letting an agent distinguish it from create_post/publish_post 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?

The description gives a clear eligibility rule ('Only draft and scheduled posts can be updated') and explains thread-conversion usage ('pass x.thread_parts to convert a draft, null to revert'). It references create_post for shared option shape, but never explicitly states when to choose update_post over create_post or publish_post, so it stops short of full alternative routing.

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

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

Annotations already declare this is a non-read-only, non-destructive, closed-world write, so the safety profile is covered. The description adds nothing behavioral beyond that: it does not say whether omitted fields are preserved or cleared, whether changes take effect immediately, or what permissions are needed for a mutation.

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. It is efficient, though the brevity is partly why behavioral and usage detail are absent.

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 four fully documented parameters, annotations covering the safety profile, and no output schema, the essentials are present. The notable gap for a mutation tool is partial-update semantics (what happens to fields not supplied), which neither schema nor description addresses.

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

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

Schema description coverage is 100%, so the baseline is 3; the schema already documents id, url, events and is_active with types and the HTTPS constraint. The description merely restates the mutable fields in prose and adds no format or semantic detail beyond the schema.

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

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

States a specific verb (update) and resource (webhook) plus the three mutable fields, so an agent can distinguish it from create_webhook, delete_webhook, get_webhook and rotate_webhook_secret. It does not explicitly name a sibling it is not, but the verb+resource pairing 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 when-to-use guidance, no prerequisites (e.g. that the webhook must already exist, or that the ID comes from list_webhooks), and no mention of alternatives such as rotate_webhook_secret for credential changes. Usage is only implied by the tool name.

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

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

Annotations declare only readOnlyHint=false, openWorldHint=true, destructiveHint=false. The description adds substantial non-obvious behavior: token-cap truncation on base64, the 100 MB/1 GB size ceilings, background 'processing' status for large videos, compatibility warnings, PDF page-splitting, and LinkedIn document preservation. These are exactly the traits an agent cannot infer from 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 and well-organized with a numbered method list and labeled sections (size limits, compatibility, PDF, supported formats). It is long but largely justified by the 9-parameter, multi-method surface; the only cost is mild repetition of the 'always try upload_url first' guidance.

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

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

With no output schema, the description carries the burden of describing returns and does so thoroughly: media id, compatibility summary, 'processing' status with list_media re-check, and per-slide media_ids. Given the tool's complexity and nested file object, nothing critical appears 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 genuine operational semantics beyond the schema: it explains method selection, warns that base64 silently truncates above ~50 KB, and clarifies pdf_mode 'slides' vs 'document' downstream effects. It slightly exceeds the baseline by tying parameter choices to failure modes.

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 precise verb+resource ('Upload media to the library') and immediately enumerates the three supported input methods with concrete examples. It clearly distinguishes itself from siblings like list_media, delete_media, and update_media, and even names check_media_compatibility and create_post as adjacent steps.

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 to use each method (url for public links, base64 for tiny files, upload_url for user-attached files), gives a clear preference order, and names conditions and alternatives (check_media_compatibility before uploading, Library UI for >1 GB local files, do NOT compress). 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.