socialclaw

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that publishability is evaluated 'currently,' implying a live state check, but says nothing about refresh timing, caching, or result shape.

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

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

Two sentences, no filler. The capability summary comes first and the parameter-scoping rule second, which is the right order for an agent deciding whether the tool fits.

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 name the key fields (allowed media, text limits, publishability). It stops short of describing structure or granularity, but is sufficient to decide and invoke the tool correctly.

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

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

Schema coverage is 100%, so the two parameters are documented, but the schema only says 'Optional account id'/'Optional provider filter' without resolving their interaction. The description supplies the missing semantics: pass one, the other, or neither for all accounts.

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 publish capabilities/provider rules for connected accounts) and enumerates the concrete payload: allowed media, text limits, publishability. This clearly separates it from list_accounts and the various get_instagram_* insight tools.

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 explains how to scope the call (accountId for one, provider to filter, neither for all), which is useful selection context, but it never says when to reach for this over siblings like list_accounts or validate_schedule, and gives no 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 declare the operation non-read-only, open-world, non-destructive, and explicitly not idempotent; the description usefully complements this by explaining that passing an idempotencyKey prevents duplicate runs on retry, and that delivery happens via connected accounts. It stops short of covering permissions, rate limits, or irreversible side effects on already-published posts.

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

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

Three short sentences, zero waste, front-loading the core action and then the key operating instruction. 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 mutation tool with no output schema, the description covers what happens (a run is created, posts go out through connected accounts) and the idempotency behavior, while the schema fully documents the nested document. Missing only auth requirements and any description of the run result, which an agent would likely want.

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 nested schedule shape is documented in impressive detail, so the schema carries the parameter burden. The description's note on idempotencyKey largely restates the schema's 'Stable key to deduplicate retries,' adding the retry rationale but no new format or constraint detail.

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 publishing run from a schedule document,' and clarifies that posts are scheduled or published through connected accounts. It does not, however, differentiate itself from adjacent siblings like validate_schedule or preview_campaign, so an agent gets no help distinguishing near-neighbors.

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

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

The description implies when to use it (after you have a schedule document ready to run) and gives retry advice via idempotencyKey, but it never names alternatives such as validate_schedule or preview_campaign, nor states prerequisites (e.g., accounts must be connected). Usage is inferable but not explicit.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered structurally. The description adds only the pre-publication window constraint and says nothing about required post status, permissions, or what a cancelled post becomes.

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 action and its constraint are stated immediately.

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 whose annotations already carry the destructive/idempotent profile, the description is nearly sufficient. It could still note the failure mode for already-published posts, which is the main ambiguity given the 'before it publishes' framing.

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

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

There is one parameter (postId) with 0% schema description coverage, so the description carries the full burden of explaining it — yet it adds no format, source, or lookup guidance for the id. It neither compensates for the coverage gap nor clarifies which post ids are cancellable.

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?

A specific verb (cancel) plus resource (scheduled post) with a clear precondition ('before it publishes'). It is distinguishable from publish_draft and retry_post by the word 'cancel', 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 'before it publishes' implies the timing condition for use, but there is no explicit when-not guidance (e.g. what to do after publication) and no alternatives are named among the many post-related 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 write, non-idempotent, open-world behavior, and the description adds substantial context beyond that: SocialClaw never sees the password, most providers return an authorizeUrl, and Telegram/Discord require pre-created tokens/webhooks. This is rich behavioral disclosure that the structured fields do not provide.

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

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

Front-loaded with the action, then the provider branching, then the safety note. Three sentences, each earning its place, though slightly long. No filler.

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

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

Covers the full connect workflow including provider-specific parameter requirements and safety guidance. No output schema exists, but the return of authorizeUrl is mentioned, making it complete for an agent to act.

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 explains provider-specific parameter usage (which parameters apply to Telegram vs Discord) and stresses only passing user-provided values, adding meaning 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+resource (connect a social account) and scopes it to the user's own accounts and their SocialClaw workspace. It is clearly distinguishable from siblings like list_accounts or delete_instagram_comment.

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

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

Gives clear usage context: the user signs in with the provider, and Telegram/Discord special cases are explained. It doesn't explicitly name an alternative tool, but the flow (start connecting, then hand URL to user) makes when-to-use 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 destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is covered. The description usefully reinforces permanence and irreversibility, but adds nothing about cascading effects (e.g. replies), required permissions, or rate limits.

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

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

Two short sentences with zero waste; the destructive action and scope come first, with the sibling routing advice trailing. 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 destructive tool whose annotations already carry the safety profile, the description covers what the tool does, its permanence, and the safer alternative. It omits whether the deletion can be undone and whether it affects child replies, which a careful agent might want.

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

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

Schema coverage is only 50%: 'account' is documented in the schema, but 'commentId' has no description anywhere. The description contributes no parameter meaning at all, leaving the undocumented parameter to be inferred from its name.

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

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

States a specific verb ('Permanently delete') plus resource ('an Instagram comment on the user's media'), and the permanence qualifier distinguishes it from non-destructive siblings. An agent can tell it apart from hide_instagram_comment 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 names the alternative sibling ('Prefer hide_instagram_comment when unsure'), which is real routing guidance. The trigger condition ('when unsure') is a heuristic rather than a concrete criterion, so it falls short of a fully specified when/when-not rule.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety behavior is covered. The description adds no behavioral context beyond those annotations—no mention of data freshness, window behavior, rate limits, or what a snapshot contains—so it does little work here.

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 then the parameter constraint. Efficient and free of filler, though the second sentence is largely a restatement of the schema's required/enum constraints.

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

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

For a 3-parameter read-only tool with no output schema, the description need not explain return values, but it leaves gaps: it never mentions the 'window' parameter, gives no sense of what snapshots include, and does not route the agent away from refresh_analytics.

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

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

Schema description coverage is only 33%, so the description must compensate, and it partially does by explaining that 'scope' must be post/account/run and that 'id' is the matching identifier. However, the optional 'window' parameter is never mentioned, leaving a real coverage gap.

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

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

States a specific verb and resource ('Get analytics snapshots') and enumerates the three possible scopes, so the agent understands it is a targeted analytics fetch. It does not, however, distinguish itself from the sibling refresh_analytics, which is the most likely confusing alternative.

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

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

The description implies you call it to fetch analytics for a post/account/run and restates that scope and id are required, which is implied usage. It gives no explicit when-to-use, when-not-to-use, or alternative selection guidance (e.g., versus refresh_analytics).

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds useful behavior context that it returns a daily time series over a rolling window, but says nothing about rate limits, freshness/latency, or data availability gaps.

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

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

One sentence, front-loaded with the verb and resource, with the qualifier about output granularity placed in a parenthetical. No 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 read-only time-series fetch with a fully documented schema and no output schema, the description is nearly sufficient. It could note valid metric coverage or the response shape, but nothing needed to invoke the tool correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents days (2-30, default 14), metric (default reach, with examples), and account. The description reinforces the 'last N days' window and gives 'reach' as an example metric, matching rather than extending the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Get an Instagram account's insight trend'), and clarifies the return shape is a daily time series. It differentiates reasonably from the media-level sibling (get_instagram_media_insights) by scoping to 'account', though it never names the alternative explicitly.

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

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

Usage is only implied: an agent infers this is for account-level trend retrieval from the phrase 'account's insight trend'. There is no explicit when-to-use, when-not, or routing to sibling tools such as get_instagram_media_insights or get_analytics.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and openWorld, so the safety profile is covered. The description adds the useful constraint that this only reads the user's own posts and chains from list_instagram_media, but adds nothing about rate limits or pagination behavior beyond what the schema documents.

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 read scope is front-loaded and the prerequisite tool is mentioned only once, with no redundancy.

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

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

For a read-only list tool with full schema coverage and no output schema, the description supplies the prerequisite and the scope of posts. It leaves return shape and pagination flow to the schema, which is appropriate, though a note on the own-posts restriction being enforced would round it out.

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

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

Schema description coverage is 100%, so all four parameters (account, mediaId, limit, after) are already documented with defaults, caps, and cursor semantics. The description only reinforces where mediaId originates; it adds no syntax or format 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 (read) and resource (comments and replies) with clear scope: on one of the user's own Instagram posts. This cleanly distinguishes it from siblings like reply_instagram_comment, delete_instagram_comment, and hide_instagram_comment.

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

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

Gives explicit workflow guidance: 'Use list_instagram_media first to get a mediaId,' which is the prerequisite for the required parameter. It also states the intent (review and answer), though it doesn't state when NOT to use it or compare against alternatives beyond the prerequisite.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered by structured data. The description adds the metric set, which is useful, but says nothing about metric availability by media type, latency, or rate limits. With annotations carrying the behavioral burden, a 3 is appropriate.

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

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

Two short sentences, with the core purpose and metric list front-loaded before the prerequisite. Every clause earns its place; 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 usefully enumerates the return metrics, and it covers the two required parameters plus the media-id source. It is nearly complete, but omits how mediaProductType affects which metrics come back and whether values can be null for unsupported post types.

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

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

Schema coverage is 67%: 'account' and 'mediaProductType' (with its FEED/REELS/STORY hint) are already documented in the schema. The description compensates for the one undocumented parameter, mediaId, by pointing at list_instagram_media as its source, adding meaning beyond the schema.

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

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

The description names a specific verb and resource ('Get analytics for one Instagram post') and enumerates the exact metrics returned (reach, likes, comments, saved, shares, views). The phrase 'one Instagram post' plus the sibling name-drops distinguishes it from get_instagram_account_insights and get_analytics without opening any schema.

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

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

It gives an explicit prerequisite/alternative: 'Use list_instagram_media for the mediaId,' which tells the agent how to obtain the required identifier. It does not, however, state when to prefer this over get_instagram_account_insights or get_analytics, so the routing 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 already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that — no note on pagination behaviour, result ordering, or rate limits — so it does not go beyond the structured fields.

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

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

A single front-loaded sentence with no waste. It is efficient, though arguably under-specified rather than maximally informative.

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 schema documentation, complete annotations, and no output schema, the definition covers everything needed to invoke it. Return-format explanation is unnecessary, so only minor pagination guidance is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no parameter meaning beyond the schema (e.g. how the 'after' cursor interacts with 'limit'), so it neither helps nor hurts.

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 (messages in an Instagram DM conversation), which is enough for an agent to distinguish it from list_instagram_conversations (conversations, not messages). It does not explicitly name the sibling it complements, so it falls short of a 5.

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

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

There is no when-to-use guidance, no mention of alternatives (e.g. list_instagram_conversations to obtain conversationId, or send/react tools), and no stated preconditions. The agent must infer usage from the schema alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety and side-effect profile is fully covered. The description adds the concrete shape of the result (followers/follows/media/bio), which is useful since there is no output schema, but it says nothing about permissions, rate limits, or what happens with private/suspended accounts.

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 front-loaded sentence with no filler; the verb, resource, and return payload are all in the first clause.

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 single-parameter read tool with full annotation coverage and no output schema, the description is nearly sufficient, and enumerating the returned fields partially substitutes for the missing output schema. The only real gap is the absence of any routing hint among the many Instagram/profile 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 description coverage is 100% and the single 'account' parameter already documents that it accepts a connected-account id or handle. The description adds no further meaning beyond what the schema provides, 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 (Instagram account profile) and enumerates the returned stats (followers, follows, media count, bio), which is more informative than the title. It does not, however, distinguish itself from close siblings such as get_profile or get_instagram_account_insights, leaving the agent to infer which profile-level tool applies.

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

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

The description offers no when-to-use guidance, no prerequisites (e.g. that the account must be connected), and no mention of alternatives like get_instagram_account_insights or get_profile. The agent must guess from the name alone.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds useful return-content context by naming delivery state and provider identifiers, which is valuable given there is no output schema. It does not cover auth needs, error behavior, or rate limits.

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

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

The description is a single front-loaded sentence with no wasted words. It efficiently communicates the core action and the extra data returned.

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 read tool with rich annotations, the description is mostly complete. It helpfully mentions return content despite no output schema, but it omits parameter details and error or empty-result behavior.

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

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

Schema description coverage is 0%, so the description should compensate for the undocumented postId parameter. It does not explain what postId is, its format, or where to obtain it beyond implying that it identifies a single post. The parameter name is self-evident but largely undocumented.

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

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

The description states a specific verb and resource: get one post. It adds scope by noting inclusion of delivery state and provider identifiers. It does not explicitly name sibling alternatives such as list_posts, so it falls short of full sibling 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?

There is no guidance on when to use this tool versus alternatives like list_posts or get_analytics. The description only implies retrieval of a single post. No exclusions, prerequisites, or context are provided.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds value annotations do not: it discloses the returned payload (id, name, plan), which matters since there is no output schema. It stops short of noting auth prerequisites or behavior on failure.

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

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

Two tight sentences with no filler; the resource identity is front-loaded and the second sentence adds the when-to-use cue. 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 trivial zero-param read with no output schema, disclosing the return fields (id, name, plan) is the key completeness requirement and it is met. Minor gap: no mention of what happens without a connection or how stale the plan/id might be, but nothing an agent needs to call it correctly is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly implies no input is required to identify the current workspace.

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 ('Identify') plus the exact resource ('the connected SocialClaw workspace') and even enumerates what it exposes (stable id, name, plan). This cleanly separates it from siblings like list_accounts or workspace_health, which deal with other resources.

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

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

Gives a clear usage context: 'Use it to confirm which workspace you are acting on.' That is explicit about when the tool matters, but there is no statement of when not to use it or which sibling to prefer for adjacent needs (e.g., capabilities or usage stats).

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, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is largely covered. The description reinforces the reversible toggle semantics ('Set hidden=false to unhide'), which is genuinely useful given destructiveHint=false, but adds nothing about permissions, rate limits, or effects on comment visibility.

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 immediately followed by the toggle instruction. No filler or redundancy.

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

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

For a mutation tool with no output schema, the description covers the core action and its reverse but omits return behavior, error cases (e.g., comment not found), and the meaning of the undocumented commentId parameter. Adequate but with clear gaps.

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

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

Schema coverage is 67%, with commentId having no description at all. The description only repeats the hidden boolean polarity already documented in the schema and says nothing about commentId format or account identifier handling, so it does not compensate for the coverage gap.

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

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

States a specific verb (hide/unhide) and resource (Instagram comment) and clarifies the dual-mode behavior via hidden=false. An agent can distinguish it from delete_instagram_comment or reply_instagram_comment because 'hide' implies reversible moderation. It does not name siblings, but the resource and action are 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 implies usage (hide a comment, or unhide by setting hidden=false) but gives no explicit when-to-use guidance, no contrast with delete_instagram_comment (irreversible removal vs. hiding), and no prerequisites such as needing the comment to belong to the user's media.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and non-destructive behavior, so the safety profile is covered. The description adds the optional provider filter, but does not disclose pagination, rate limits, or return format beyond what annotations imply.

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 that are front-loaded with the core purpose and then the optional filter. Efficient, though the provider enumeration is lengthy and could be moved to parameter description.

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

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

Given a simple list tool with one optional parameter and full schema coverage, the description is complete enough for correct invocation. It lacks details on output or pagination, but these are not critical for an agent to call it.

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

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

Schema description coverage is 100%, so the single parameter is fully documented in the schema. The description lists valid provider values, which is helpful, but does not add syntax or format details 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 (List) and resource (connected social accounts) scoped to the SocialClaw workspace. It clearly distinguishes from siblings like list_posts or list_assets, which handle different resources.

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

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

The description implies usage via 'Optionally filter by provider', but provides no explicit guidance on when to use this tool versus alternatives or any exclusions. It requires the agent to infer context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered structurally. The description adds valuable context beyond annotations: the default sort (newest first) and, critically, that each asset carries a publicUrl directly usable as media_link. It does not mention pagination or the 48 cap, which are left 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 tight sentences, front-loaded with the resource and scope, followed by the key output affordance (publicUrl for scheduling) and filters. Every clause earns its place with no redundancy.

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

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

For a read-only list tool with full schema coverage and no output schema, the description covers purpose, usage, output affordance, and filters. It omits pagination/cap behavior and whether results are workspace-scoped, which would be useful but are minor for this tool's complexity.

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 each parameter (kind, mime, sort, limit, query) is already documented in the schema. The description restates the filter options (kind, mime, query) in prose but adds no syntax or format detail 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 ('List media... the user has uploaded to their SocialClaw library') and distinguishes itself from siblings like list_instagram_media by scoping to the user's own upload library. An agent can tell it apart from upload_asset and list_posts 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 says when to use it: 'Use this to find a previously uploaded file (e.g. from the dashboard) to post,' and names the downstream tools (validate_schedule/apply_schedule) that consume its output. No alternative-selection ambiguity remains.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds behavior annotations don't carry: result ordering (most recent first) and the shape of each item (counterpart, participants including the account itself). Pagination behavior itself is left 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?

Two compact sentences; scope and ordering come first, then the actionable detail about counterpart.id. No redundant restatement of the name or schema.

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

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

No output schema exists, and the description partially compensates by naming the returned fields and ordering. Combined with full schema coverage and annotations covering the safety profile, an agent has enough to call it correctly; only pagination/cursor round-tripping is 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 coverage is 100%, so the baseline is 3, but the description adds cross-tool semantics the schema cannot: the counterpart.id is the recipientId to use when replying, and participants includes the account itself. That is meaningful beyond the 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 ('List the Instagram direct-message conversations for an account') plus ordering ('most recent first'), which clearly separates it from get_instagram_messages or send_instagram_message. It does not name a sibling explicitly, so it stops short of a 5.

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

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

There is no explicit when-to-use vs when-not guidance relative to sibling tools. The description does give forward-looking context ('use its id as the recipientId when replying'), which implies a workflow, but that is usage of the result rather than selection of this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds value by enumerating returned fields — important because there is no output schema — though it says nothing about pagination behavior or rate limits.

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

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

Two tight sentences with the purpose and returned fields front-loaded and the parameter note last. No filler or 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 three-parameter read tool with no output schema, the description covers purpose, returned fields, and usage context, while annotations carry the safety profile. Pagination depth and response shape details are left to the schema cursor description, which is acceptable.

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 account, after, and limit are already documented in the schema. The description only restates the account parameter, adding no syntax or format detail 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 (list) and resource (Instagram media) plus the scope of what is returned (caption, permalink, timestamp, comment count). The stated intent 'find one to read or moderate comments on' distinguishes it from siblings like get_instagram_media_insights and get_instagram_comments.

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

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

Gives a clear downstream use case ('so you can find one to read or moderate comments on'), which tells an agent when this list-then-act pattern applies. It does not name explicit alternatives or exclusions, so it stops just short of full routing 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 readOnly, idempotent, open-world and non-destructive, so the safety profile is covered. The description usefully adds the webhook-capture origin, hinting that completeness depends on webhook availability, but it says nothing about ordering, freshness windows, or pagination 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?

One front-loaded sentence with no filler; the scope and data source are stated immediately and 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 read-only, single-parameter list tool with no output schema, the description covers what is listed and where the data originates. Ordering and freshness semantics are the only notable omission, which is minor at this complexity level.

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 'limit' parameter is fully documented there (default 30, capped at 100). The description adds no parameter-level meaning, so this is the baseline case where the schema does the work.

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

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

States a specific verb (List) and resource (@mentions of the workspace's Instagram accounts) with the novel detail that data comes from webhooks. This separates it from siblings like list_instagram_media and list_instagram_conversations, though it does not explicitly name a competing tool.

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

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

Usage is implied by the name and the 'recent ... captured from webhooks' phrasing, which suggests it is for reading incoming mention events. There is no explicit when-to-use, when-not-to-use, or pointer to an alternative sibling, so guidance stays at the minimum-viable level.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds no behavioral context beyond the annotations and schema — no pagination behavior, result ordering, or default/cap behavior (which lives only in the limit param).

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 or repetition. It earns its place but is arguably too terse for a 7-parameter tool, leaving useful space unused.

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 7-parameter list tool with no output schema and 43% of parameters undocumented, the description leaves significant gaps: what fields a returned post has, how filters combine, and what the three undocumented filter params do. Annotations cover safety but not the operational context an agent needs.

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

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

Schema coverage is only 57%: limit, offset, status, and account are documented in the schema, but runId, provider, and campaignId have no descriptions anywhere. The description says 'optional filters' generically and does not compensate for these undocumented parameters.

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

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

States a specific verb ('List') and resource ('posts') with scope ('in the workspace'), which distinguishes it from the singular get_post sibling. It does not, however, explicitly differentiate itself from other list_* tools or explain what a 'post' covers.

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 'with optional filters' hints at filtering capability but gives no when-to-use guidance, no mention of the get_post alternative for single-record retrieval, and no exclusions or prerequisites. An agent must infer selection criteria from the name alone.

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

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

Annotations already declare this a read-only, idempotent, non-destructive, non-open-world call, so safety is covered. The description adds the useful disclosure that results include provider error details, but says nothing about ordering, pagination, or retention of attempt history.

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

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

Two short sentences, no filler, with the core purpose front-loaded before the debugging hint. Nothing to trim.

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 single-param read tool with full annotation coverage and no output schema, the description covers what the tool does and roughly what it returns. Missing only result shape/ordering details, which are minor here.

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 (postId) with 0% schema description coverage; the phrase 'for a post' implicitly maps it to that parameter. Baseline for a single, self-evident identifier is mid-range – the description adds no format, ID-type, or scoping detail.

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 publish attempts for a post') and adds the salient content detail (provider errors). It doesn't explicitly contrast with near-siblings like get_post, list_posts, or retry_post, so it stops short of a 5.

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

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

'Use this to debug failed posts' gives a clear context for using it, but offers no when-not guidance and never mentions related tools such as retry_post or run_status that an agent might need instead.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered structurally. The description reinforces this with 'without creating anything' but adds little new behavioral context such as output detail 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?

A single front-loaded sentence with zero waste that conveys both the operation and its non-mutating nature. Nothing could be trimmed without losing meaning.

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 stating what the preview produces (concrete posts and steps). Combined with annotations and a richly documented schema, it is nearly complete, though error/validation behavior on malformed schedules is 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% and the single 'schedule' parameter is documented in depth (minimal shape, campaign documents, provider settings), so the schema does the heavy lifting. The description adds no parameter detail 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 (preview) and resource (campaign schedule document) with clear scope: it expands the document into concrete posts and steps. It implicitly distinguishes itself from apply_schedule via 'without creating anything', though it does not name that 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 'without creating anything' implies a dry-run use case before applying, but the description never explicitly says when to use this instead of validate_schedule or apply_schedule. Usage is left to inference.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the safety profile is covered. The description adds little beyond that: it doesn't explain what publishing does to the draft (does it immediately execute posts?), whether it can be undone or cancelled, or what openWorldHint=true implies for external side effects.

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 the action first and the optional parameter last; no filler or redundancy.

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

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

For a two-parameter mutation tool with no output schema, the definition is roughly adequate but leaves the agent guessing about the consequence of publishing, the default when startAt is omitted, and any follow-up call to check the result via run_status.

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 runId and startAt are already documented in the schema. The description only echoes the ISO-8601 format for startAt, adding no new semantics such as timezone handling, default behavior when omitted, or past-vs-future constraints.

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) and resource (a previously created draft run), with the optional timing modifier. It is distinguishable from siblings like run_status, retry_post and cancel_post by acting on drafts, though it never names those alternatives 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 'previously created draft run' implies the prerequisite that a draft must exist first, which is useful context. However there is no explicit when-to-use/when-not guidance and no routing to related tools such as run_status or cancel_post.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true. The description adds no behavioral context beyond this - it does not mention what happens on repeat reactions despite idempotentHint=false, nor any permission or rate-limit considerations.

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 the core verb-resource pairing stated immediately and zero filler. It is concise, though the brevity comes partly from under-specification rather than disciplined editing.

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

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

For a five-parameter mutation tool with four required ids and no output schema, the description is thin: it omits required permissions, the constraint that the message must have been received, and any behavior on duplicate reactions. Annotations cover the safety profile but not the operational prerequisites.

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 60%, with messageId and conversationId left undocumented in both schema and description. The description only echoes the reaction value hint ('e.g. love') already present in the schema, so it adds minimal parameter meaning. Baseline 3 fits.

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 (react) and resource (a received Instagram direct message), with an example reaction ('e.g. love'). It is distinguishable from the sibling send_instagram_message by targeting an existing received message rather than sending a new one, though it never names that 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?

There is no guidance on when to use this instead of send_instagram_message, replying, or other message tools, and no stated preconditions beyond 'received'. The agent must infer usage from the required ids alone.

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

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

Annotations declare it is a non-read-only, idempotent, open-world mutation, and the description adds real context beyond that: it writes a new snapshot, enumerates supported providers, and warns that unsupported providers yield an 'unsupported snapshot'. Auth requirements and rate limits are not covered, but the provider/fallback behavior is genuinely useful disclosure.

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 the core action, then the provider caveat, then the routing hint. Slightly list-heavy with the provider enumeration, but 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?

For a mutating fetch-and-snapshot tool with no output schema, it covers what the operation does, which providers work, what happens otherwise, and when to prefer it. It does not describe the returned snapshot's shape, which is 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?

Schema coverage is 100%, so postId and window are already documented with the lifetime default. The description adds no syntax or format detail for either parameter, so the schema does the heavy lifting and 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 chain — fetch fresh analytics from the provider, store a snapshot, return it — and names the resource (published post analytics). It is clearly distinguishable from the sibling get_analytics, which reads stored data.

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

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

Explicitly routes the agent: 'Call this before get_analytics when you need current numbers rather than the last stored snapshot.' This gives both the alternative and the condition that selects this tool over it.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond the title: no mention that the reply is publicly visible, that posting is non-idempotent (duplicates possible on retry), or any auth/rate-limit note.

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 short, front-loaded sentence with no filler. It is appropriately sized, though arguably sized down by under-specification rather than efficiency.

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 public, non-idempotent write operation with no output schema, the definition is thin: it omits visibility of the reply, error/duplicate behavior, and any prerequisite. Annotations cover the safety flags, but the agent still lacks the context needed to invoke this confidently versus related 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 coverage is 67% — 'account' and 'message' are documented in the schema, but 'commentId' has no description. The description adds no parameter meaning at all beyond implying the target is a comment on the user's media, so it fails to compensate for the one undocumented 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 (Reply) and resource (Instagram comment) with the scope qualifier 'on the user's media'. This distinguishes it from the read/list siblings (get_instagram_comments) and the other mutators (delete_instagram_comment, hide_instagram_comment), though it does not name any 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 description offers no when-to-use guidance, no prerequisites (e.g. the comment must exist, account must be connected), and no comparison to alternatives such as send_instagram_message or hide_instagram_comment.

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, idempotentHint=false, and openWorldHint=true, so the agent knows this is a non-idempotent write against an external system. The description contributes only the 'failed' precondition; it does not say whether a retry re-queues, publishes immediately, or can duplicate an already-sent post – the main hazard for a non-idempotent 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?

One short sentence, front-loaded with the verb and resource, with zero filler. It is efficient, though arguably under-specified rather than optimally concise.

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

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

For a non-idempotent mutation with no output schema and a fully undocumented parameter, the description leaves key questions open: what state qualifies as 'failed', what happens on success, and whether the retry can loop or duplicate. Annotations cover safety signalling but not operational behavior.

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

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

Schema description coverage is 0% and the single parameter postId has no description in either the schema or the description text. It is inferable from the name, but with one required undocumented parameter the description should clarify what identifier it expects (post ID vs attempt ID vs platform media ID).

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

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

The description gives a specific verb ('Retry') and resource ('post') with a stated precondition ('failed'), so the action is unambiguous. It does not, however, differentiate itself from neighbors such as post_attempts or publish_draft, which an agent might also consider for a stuck post.

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

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

'Retry a failed post' implies the trigger condition but never states when to use this versus publish_draft, post_attempts, or get_post. No exclusions, prerequisites, or alternative routing are given.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description does add the useful scope detail that the response covers both the run and its posts, but it says nothing about behavior for an unknown runId or how stale the status data may be.

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. It is efficient, though arguably too terse for a tool with an undocumented required parameter and no output schema.

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

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

With no output schema, the description partially covers return content by stating it is a status summary of the run plus its posts, but it does not describe the status values or the shape of the returned data. Combined with the undocumented runId, the definition is only minimally 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 0%, so the schema documents nothing about runId, and the description only hints that the string identifies 'a publishing run'. It gives no format, origin, or example for the required parameter, leaving the agent to guess where runId comes from.

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 ('status summary of a publishing run and its posts'), which is enough for an agent to distinguish it from list_posts, get_post, or post_attempts. It does not name a sibling explicitly, but the resource scope 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 statement of when to use this tool versus post_attempts, get_post, or retry_post, and no mention of prerequisites such as needing a valid completed or in-flight run. Usage context is entirely 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 declare the safety profile (readOnly=false, openWorld=true, non-idempotent), so the description's job is to add policy context — and it does, disclosing the 24-hour messaging window and the tag override (HUMAN_AGENT). It does not note rate limits, failure modes, or confirmation behavior, keeping it short of a 5.

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

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

Two sentences, zero filler, with the core action and the key constraint both front-loaded. Every clause carries information an agent needs.

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

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

For a non-idempotent mutation tool with no output schema and full schema coverage, the description covers purpose, content modes, and the critical 24-hour policy. Return value expectations remain unstated, but the safety-relevant behavior is adequately conveyed.

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

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

Schema description coverage is 100%, so the schema already documents all 7 parameters including tag, text, attachment_url, and attachment_type. The description echoes the tag/attachment concepts but adds no syntax, format, or validation detail beyond the schema — baseline 3 applies.

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

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

Specific verb+resource ('Send an Instagram direct message') with the two supported content modes named (text reply vs. attachment_url). It clearly separates itself from siblings like get_instagram_messages (read) and reply_instagram_comment (public comments).

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

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

States an explicit operating constraint: only allowed within 24 hours of the recipient's last message unless a message tag is supplied. That is real when/when-not guidance, though it does not name a sibling alternative or spell out prerequisites like account permissions.

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

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

With annotations already covering safety (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false), the description adds real context: the file lands in the user's media library and the response contains an asset id and public URL. It does not mention that repeat uploads create new assets, but the non-idempotent hint covers that.

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, all front-loaded with purpose, then inputs, then return/usage. No filler or redundancy.

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

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

No output schema exists, and the description compensates by describing the return values (asset id, public URL) and how they feed schedules. For a 3-param upload tool with full annotation coverage, 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 description coverage is 100%, so baseline is 3, but the description adds the mutual-exclusivity constraint between sourceUrl and contentBase64 that the schema only hints at. It still does not state that at least one of the two must be supplied, which the schema leaves ambiguous given only filename is required.

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

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

Specific verb (upload) plus resource (image/video asset) and the reason it exists ('so it can be attached to a post'). This clearly separates it from sibling read tools like list_assets.

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 input choice ('either sourceUrl ... or contentBase64') and downstream usage ('use as media_link in schedules'), giving strong context. It stops short of naming when to prefer a URL over base64 or pointing at a sibling for asset listing.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description reinforces it with 'WITHOUT creating any posts' and enumerates the validation dimensions, which is genuine added context. It stops short of describing what a failed validation yields (errors vs. warnings), which a dry-run tool would benefit from.

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, zero filler, with the non-mutating guarantee and the ordering prerequisite front-loaded. 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 pure validation tool the description covers intent, scope, and sequencing, and the nested schema is rich. The only meaningful gap is that no output schema exists and the description never indicates what validation returns (pass/fail shape, error list), which is the tool's entire product.

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

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

Schema coverage is 100% and the single nested 'schedule' parameter is documented in detail in the schema itself (minimal shape, campaign variant, per-post settings like tiktokPostMode). The description only refers to 'a schedule document,' adding no meaning beyond the schema, so the baseline 3 applies.

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

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

Specific verb (validate) plus the exact resource (schedule document) and the full scope of checks (provider rules, media limits, account state, publish times). 'WITHOUT creating any posts' cleanly separates it from apply_schedule, so an agent can distinguish it from siblings without reading schemas.

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

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

Explicitly states the usage rule: 'Always run this before apply_schedule.' That is both a when-to-use directive and a dependency on a named sibling, 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, idempotentHint, and destructiveHint=false, so the safety profile is fully covered. The description adds that results aggregate connection state across providers, which is modest extra context but says nothing about permissions, rate limits, or what happens when a provider is unreachable.

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

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

Two short sentences with no filler, and the core purpose is front-loaded before the optional-parameter hint. 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 read-only tool with no output schema, the description covers what is returned at a high level (connection state across providers) and how to scope it. It stops short of describing what a healthy versus unhealthy result looks like, which would have made it fully self-contained.

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

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

Schema coverage is 100% and there is only one optional parameter, so the schema already carries the semantics; baseline is 3. The description restates that provider narrows the check to one provider, adding little beyond the schema's own description of the same field.

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 (workspace health) plus the scope of what is returned (connection state across providers). It does not explicitly distinguish itself from the sibling workspace_usage, which is the closest potential point of confusion, 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 second sentence implies usage of the optional provider argument to narrow the check to a single provider, which is a useful hint. However, it gives no when-to-use versus when-not-to-use guidance and never names the alternative workspace_usage for a workspace-wide metric view.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is fully covered. The description adds which kinds of figures are returned (counters, entitlement consumption) but says nothing about freshness, aggregation window, or scope of the counters.

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

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

One sentence, front-loaded with the primary resource and no filler. Every word 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 parameterless read-only tool with full annotation coverage and no output schema, the description is close to sufficient. It stops short of naming the units or the plan context an agent might expect from 'entitlement consumption'.

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 scoping inputs are needed.

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 workspace usage counters') plus the second facet it returns ('plan entitlement consumption'). An agent can distinguish it from workspace_health and account_capabilities by resource scope, but the description never explicitly contrasts with those 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?

No guidance on when to call this versus workspace_health, account_capabilities, or get_analytics, nor any stated trigger such as checking quota before scheduling. Usage is only inferable from the name and resource.

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