socialclaw

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

With no annotations, the description carries full burden. It discloses the nature of the return data (media allowances, text limits, publishing status) and the filtering behavior. While it doesn't explicitly state read-only or mention permissions, the verb 'Get' implies non-mutating access, making this sufficiently transparent for a simple read operation.

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

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

The description is two sentences, front-loaded with the main purpose, and the second sentence efficiently covers parameter usage. No redundancy or excessive detail.

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

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

Despite lacking an output schema, the description adequately covers return content (media, text limits, publishability) and parameter options. For a tool with two optional parameters, this is complete and self-contained, requiring no additional context to invoke correctly.

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

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

Schema already provides descriptions for both parameters. The description adds value by explaining the combinational semantics: accountId and provider are optional, can be used alone or together? Actually says 'or' implying exclusive, and 'neither' for all. This clarifies how the parameters interact beyond their individual 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?

The description clearly states the tool retrieves publish capabilities and provider rules for connected accounts, listing specific aspects (media, text limits, publishability). It distinguishes itself from siblings like get_analytics and get_post by focusing on capability checks rather than usage or content retrieval.

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

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

Provides clear instruction on parameter usage: passing accountId for one account, provider to filter, or neither for all. This gives strong contextual guidance, though it doesn't explicitly compare to alternative tools or state when not to use 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?

No annotations are provided, so the description carries the transparency burden. It discloses that posts are 'scheduled or published through connected accounts' and that idempotencyKey prevents duplicate runs on retries. However, it does not mention side effects, error behavior, or what exactly constitutes a 'publishing run' in terms of irreversible actions.

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

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

The description is two sentences, front-loaded with the primary purpose, and every sentence adds useful information. No fluff or repetition of schema details.

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

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

With no output schema, the description should cover return values or how to monitor success; it does not. It covers the core purpose, connected-account behavior, and idempotency, but for a mutation tool with potential multi-step publishing, more detail about what happens after the call would improve completeness.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the practical purpose of idempotencyKey ('so retries do not create duplicate runs') beyond the schema's 'Stable key to deduplicate retries,' and the schedule parameter is already well-documented in 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 clearly states the tool's action and resource: 'Create a publishing run from a schedule document.' It distinguishes from siblings like publish_draft (single draft) and validate_schedule (validation only) by focusing on batch/schedule-driven publishing.

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: if you have a schedule document, apply_schedule is the tool to use. The idempotencyKey note gives retry-related guidance, but there is no explicit comparison to alternatives or when-not-to-use conditions, unlike the calibration example that named a sibling 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?

No annotations are provided, so the description must carry behavioral disclosure. It discloses the timing constraint ('before it publishes') but does not describe side effects, idempotency, or error cases.

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?

Single clear sentence, front-loaded with the action.

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

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

For a mutation tool with no annotations and an undocumented parameter, the description is too thin. It lacks information about outcomes, errors, or 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 has one parameter with no description, and schema coverage is 0%. The description does not explicitly define postId, though it's implied. It fails to compensate for the missing schema documentation.

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

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

The description clearly states the tool cancels a scheduled post, using a specific verb and resource. It is distinct from siblings like publish_draft or retry_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?

Provides clear context that this applies to scheduled posts before publishing, but does not explicitly mention alternatives or when not to use 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?

There are no annotations, so the description carries the full burden. It discloses the OAuth authorizeUrl behavior and the required inputs for Telegram and Discord, but does not elaborate on side effects (e.g., whether the connection is immediately active), authentication requirements for the tool itself, or error scenarios.

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

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

Three short sentences, front-loaded with the main action, and no unnecessary detail. Every clause adds information about the connection flow or provider requirements.

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

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

The description adequately covers the main flows and provider-specific requirements. The lack of an output schema is partially mitigated by mentioning the authorizeUrl return for OAuth, but it does not explain the return value for Telegram/Discord or describe the overall connection lifecycle.

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

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

The schema already has 100% coverage with descriptions for each parameter. The description adds provider-dependent parameter semantics, noting that botToken/chatId are needed for Telegram and webhookUrl for Discord, which goes beyond the individual property 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?

The description opens with a specific verb and resource ('Start connecting a new social account') and clarifies the tool's role relative to siblings like list_accounts and account_capabilities. It also mentions provider-specific behaviors (OAuth authorizeUrl, Telegram/Discord parameters), which further distinguishes the tool's purpose.

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 when to use the tool (to start connecting a new account) and provides conditional guidance: OAuth providers require a browser authorization step, while Telegram and Discord take specific parameter sets. However, it stops short of explicitly naming alternative tools or stating when not to use 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?

With no annotations provided, the description carries the transparency burden. It discloses the irreversible nature ('permanently delete') and the scope ('on the user's media'). However, it does not mention required permissions, behavior toward replies, or error scenarios, so it is not fully transparent but still offers strong context.

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

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

The description is two sentences, with the primary action front-loaded and the usage guidance as a direct follow-up. Every word earns its place; there is no redundancy or 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?

Given the tool's simplicity (two params, no output schema), the description covers the essential operational context: what it does, scope, and when to prefer an alternative. It lacks details about how to obtain commentId or what the response indicates, but these are somewhat inferable from sibling tools like get_instagram_comments. Overall, it is adequate with minor gaps.

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

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

Schema description coverage is 50% (account has a description, commentId does not). The tool description does not add further meaning for either parameter, leaving commentId's format/source unclear. It provides some context by mentioning 'user's media' but does not compensate for the 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?

The description clearly states the tool's action ('permanently delete an Instagram comment') and resource ('on the user's media'), distinguishing it from the sibling tool hide_instagram_comment by emphasizing permanence and the explicit preference for the less destructive alternative when uncertain.

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

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

The description provides explicit guidance: 'Prefer hide_instagram_comment when unsure.' This directly tells the agent when not to use this tool and which alternative to choose, making usage context 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?

With no annotations, the description carries the burden of behavioral disclosure. It implies a read-only operation via 'Get' and clarifies the scope/id relationship, but it does not explicitly state read-only behavior, describe return format, or clarify the meaning of 'snapshot' (e.g., cached vs. live data).

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

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

Two concise sentences with no filler. The main action and required constraints are front-loaded, making the purpose immediately clear.

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 analytics getter, the description plus schema are sufficient. The schema documents the optional 'window' parameter, and the description covers the two required parameters. No output schema exists, but the return value is implicitly analytics data; a bit more detail about the 'snapshot' nature could improve completeness, but it is not critical.

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

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

The description adds meaning beyond the schema by explaining that 'scope' must be one of post/account/run and that 'id' is the matching identifier for that scope. This is valuable given the schema only describes 'window' and leaves 'id' and 'scope' without descriptions (33% schema coverage).

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

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

The description clearly states the verb ('Get') and the resource ('analytics snapshots'), and specifies three distinct scopes (post, account, run). It differentiates itself from sibling tools like get_post or run_status by focusing on analytics rather than raw resource retrieval.

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

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

The description provides no guidance on when to use this tool versus alternatives. It only outlines required parameters (scope, id) but does not mention any conditions, exclusions, or comparison with sibling tools like workspace_usage or run_status.

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?

No annotations are provided, so the description carries the full burden. It clearly indicates a read-only operation (getting a trend) and even clarifies that the output is a daily time series. However, it does not disclose any additional behavioral details such as required account connection, rate limiting, or error conditions.

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 that efficiently communicates the core purpose and output shape. Every word earns its place, with no fluff or redundant information.

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

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

With no output schema, the description partially explains the return value as 'a daily time series', giving the agent a sense of the data shape. It does not detail exact fields or format, but for a simple time-series tool this is reasonably complete. The low complexity helps justify the brevity.

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

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

The schema covers 100% of the parameters with descriptions, and the description directly references the 'last N days' concept matching the 'days' parameter. It does not add new meaning beyond the schema, but it does reinforce the metric concept with examples (reach, profile_views). This meets the baseline for full schema coverage.

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

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

The description uses a specific verb 'Get' and identifies a clear resource: 'an Instagram account's insight trend'. It further specifies it returns a daily time series (e.g., reach) over the last N days, which clearly distinguishes it from sibling tools like get_instagram_media_insights (which targets media insights) and get_analytics (which is more generic).

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 for account-level insights by naming 'account' in the resource, but it does not explicitly state when to prefer this tool over alternatives like get_instagram_media_insights or get_analytics. No exclusions or alternative recommendations are given, leaving the selection somewhat inferred.

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

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

No annotations are provided, so the description carries the full burden. It indicates a read operation via the verb 'Read', and mentions the prerequisite, but it doesn't disclose pagination behavior, permissions, or any side effects. The description is minimal but not misleading.

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

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

Two sentences, front-loaded with purpose, and no superfluous words. Highly concise and well-structured.

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

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

The tool has 4 parameters, no output schema, and no annotations. The description covers purpose and prerequisite but omits pagination details, rate limits, or expected return format. It's adequate but leaves some gaps in operational context.

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

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

Schema coverage is 100% with clear descriptions for each parameter. The description adds no new parameter semantics beyond what the schema already provides; the mediaId reference to list_instagram_media is already in the schema. Baseline 3 is appropriate.

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

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

Description clearly states 'Read the comments (and replies) on an Instagram post' with a specific verb and resource, distinguishing from sibling tools like delete, hide, and reply comment 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?

Provides an explicit prerequisite: 'Use list_instagram_media first to get a mediaId.' This gives clear context for usage, though it doesn't explicitly mention when not to use or name alternative tools 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?

With no annotations, the description carries the full burden. It discloses the metrics returned, giving insight into the tool's output behavior. However, it does not mention any required authentication/preconditions, potential errors, or that the operation is read-only. This is a moderate level of transparency for a simple analytics fetch.

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

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

The description is two short sentences. The first states the purpose and key outcomes, and the second provides a direct pointer for obtaining a required parameter. Every word earns its place with no fluff.

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

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

Given the tool's simplicity, the description covers the primary context: what it does, which metrics are returned, and how to obtain the mediaId. It does not discuss return format or error handling, but for a single-post analytics tool this is sufficient. The lack of annotations and output schema is partially offset by the clear description.

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

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

The schema covers account and mediaProductType descriptions, but mediaId has no description. The description compensates by advising to use list_instagram_media for the mediaId, adding valuable semantic context. With 67% schema coverage, this extra guidance elevates the parameter semantics above the baseline.

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

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

The description clearly states the tool gets analytics for one Instagram post and lists specific metrics (reach, likes, comments, saved, shares, views). This clearly distinguishes it from sibling tools like get_instagram_account_insights (account-level analytics) and get_analytics (generic).

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

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

The description explicitly instructs the user to use list_instagram_media for the mediaId, which provides concrete guidance on a prerequisite. It also implicitly differentiates from account-level insights by saying 'one Instagram post', but does not explicitly state when not to use this tool or mention alternatives as clearly as it could.

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?

There are no annotations, so the description carries the full burden. It only says 'Read', implying a non-destructive operation, but it does not disclose pagination behavior (via 'after' cursor), whether messages are marked as read, rate limits, or what happens if the conversationId is invalid. This is insufficient for a tool interacting with a messaging API.

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, concise sentence that is front-loaded with the core purpose. It contains no filler words or redundant information, making it highly efficient. Though it is brief, the conciseness dimension rewards appropriately sized content without waste.

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

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

Given the tool's moderate complexity (4 parameters, no output schema, no annotations), the description is too minimal. It does not explain return format, pagination behavior, or the relationship between the 'after' cursor and previous responses. The schema covers parameter descriptions but not the overall behavior or edge cases, leaving gaps for an agent.

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

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

The input schema has 100% coverage with descriptions for all four parameters, including the pagination cursor and limit. The description adds no additional parameter meaning beyond what the schema already provides. Per the rubric, baseline is 3 when schema coverage is high, and there is no extra value from the description.

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

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

The description clearly states the tool reads messages in an Instagram DM conversation, using the specific verb 'Read' and the resource 'messages in an Instagram direct-message conversation'. It distinguishes from siblings like list_instagram_conversations (which lists conversations) and send_instagram_message (which sends) by focusing on reading messages within a specific conversation, though it doesn't explicitly name alternatives.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, such as needing a conversationId from list_instagram_conversations, nor does it state any exclusions or limitations. There is no explicit 'when to use' or 'when not to use' 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?

No annotations are provided, so the description carries the full burden. It discloses the return values (followers, follows, media count, bio) but does not mention permissions, rate limits, or whether the account must be connected. As a read-only operation, the impact is lower, but the description does not explicitly confirm read-only behavior or any additional constraints.

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

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

The description is a single, efficient sentence that immediately opens with the verb and resource, followed by a succinct list of the returned stats. No filler words or redundant information, making it appropriately sized and front-loaded.

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

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

The tool is simple with one parameter and no output schema, but the description lists the return values, which is helpful. However, it does not specify whether the account must be connected or if any public handle works, nor does it mention error behaviors or prerequisites. Given the lack of annotations, the description could be more complete around these boundary conditions.

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% since the single parameter 'account' is described as 'Instagram connected-account id or handle.' The tool description adds no further semantic detail about the parameter; it only lists the return fields. Therefore, the schema already provides the necessary meaning, and the description doesn't enhance it.

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

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

The description clearly states the tool's function: retrieving an Instagram account's profile stats (followers, follows, media count, bio). The verb 'get' and the specific resource 'Instagram account's profile stats' make it distinct from sibling tools like get_instagram_comments or get_instagram_media_insights.

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 when basic profile stats are needed, but it does not explicitly differentiate from similar tools like get_instagram_account_insights or list_instagram_media. No exclusions or alternative tool mentions are provided, leaving the agent to infer usage from the 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It only mentions the response contents and does not disclose error behavior, authentication needs, or side effects. For a read operation, it is insufficiently transparent.

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 that immediately conveys the core function. It contains no filler or redundant information, making it highly concise and well-structured.

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 get tool, the description conveys the main output but lacks behavioral details and usage context. Given the absence of annotations and output schema, it is minimally viable but incomplete in explaining error cases or 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?

The description omits the postId parameter entirely, and schema description coverage is 0%. While the parameter name is self-explanatory, the description adds no meaning beyond the schema and fails to compensate for the lack of parameter documentation.

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

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

The description clearly states the verb 'Get', the resource 'one post', and specifies key output details (delivery state, provider identifiers). This distinguishes it from siblings like list_posts and post_attempts.

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 for fetching a single post's details, but it does not explicitly mention when to use this tool versus alternatives like list_posts or provide exclusions. The context is clear enough for a simple get operation, but no direct guidance is 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?

With no annotations, the description carries the full burden. It implies reversibility by mentioning unhide and clarifies the hidden parameter's toggle behavior. However, it does not disclose permission requirements, whether the comment must belong to the authenticated user, or any side effects (e.g., changes to comment visibility counts). It is not misleading, but notably sparse.

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 sentence, front-loaded with the action verb, and includes a crucial usage hint about the hidden parameter. There is zero fluff or repetition.

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

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

For a simple toggle tool with three flat parameters and no output schema, the description provides the essential scope (user's media) and toggle behavior. It omits return values and error scenarios, but these are less critical given the simplicity. The lack of annotations raises the need for more detail, but the description is adequate.

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 67%; account and hidden have descriptions in the schema, while commentId lacks one. The description merely restates the hidden parameter's schema description ('Set hidden=false to unhide'), adding no new semantic value. It does not help clarify commentId, though the parameter name is self-explanatory.

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?

Description clearly states the action: 'Hide or unhide an Instagram comment on the user's media.' The verb is specific and the resource (Instagram comment) is identified, with a scope ('user's media'). This distinguishes it from siblings like delete_instagram_comment and reply_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?

Provides clear context: the tool hides or unhides a comment, with an explicit note on setting hidden=false to unhide. However, it does not mention alternatives or when to use this over delete or reply, so it lacks explicit exclusion/alternative 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?

No annotations are provided, so the description must convey behavioral traits. It indicates a read-only listing operation ('List') and that it shows 'connected' accounts, but does not disclose details like rate limits, pagination, or authorization requirements. For a simple read operation, the behavior is mostly transparent, but the description could add more safety info.

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 sentence that clearly states the purpose and then lists provider options. No wasted words, and the key action is front-loaded. The provider list is long but necessary for usability.

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 list tool, the description is mostly complete: it names the workspace, the resource type, and the filter. It does not mention the return format or pagination, but with no output schema, the implicit expectation is a list of account objects. Could be slightly more explicit but is adequate.

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 fully documents the single 'provider' parameter. The description adds value by enumerating accepted provider values (x, facebook, etc.) which are not in the schema as enums. This extra context helps agents select valid filters.

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

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

The description clearly states 'List connected social accounts in the SocialClaw workspace' with a specific verb and resource. It distinguishes from sibling tools like connect_account or list_posts by focusing on accounts.

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

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

The description implies when to use this tool: when you need to see connected accounts. It also mentions an optional filter, but does not explicitly exclude alternatives or state when not to use it. The context is clear, though no exclusionary guidance is 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the ordering ('newest first'), the nature of the returned data ('Each asset includes a publicUrl'), and the scope ('the user has uploaded'). These add meaningful context beyond a simple list call, though it does not discuss error cases 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 three sentences, each serving a purpose: stating the core function and ordering, noting the publicUrl usefulness, and giving a concrete use case with optional filters. There is no filler or redundancy, making it concise and front-loaded with the most important 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?

Despite having no output schema, the description covers the essential context: what the tool returns (media with publicUrl), how it can be used with other tools, and the available filters. It sufficiently informs the agent about how to invoke it for finding previously uploaded files. It doesn't mention the array format explicitly, but 'List' implies it.

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

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

Schema coverage is 100%, with each parameter having a clear description. The tool description mentions kind, mime, and query filters, but these repeat what the schema already provides. It does not add significant new semantics beyond the structured parameter definitions, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'List media (images/videos) the user has uploaded to their SocialClaw library, newest first.' It identifies a specific verb (list), resource (media assets), and scope (user's library). It also distinguishes from sibling tools by mentioning publicUrl and its use in validate_schedule/apply_schedule, which is unique to asset handling.

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

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

The description explicitly says when to use it: 'Use this to find a previously uploaded file (e.g. from the dashboard) to post.' It also explains how the output integrates with other tools ('usable directly as media_link in validate_schedule/apply_schedule'). No explicit exclusions are given, but the context clearly differentiates it from listing accounts or posts.

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

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

Without annotations, the description provides useful behavioral details: it returns conversations with a 'counterpart' field (to be used as recipientId) and notes that 'participants' includes the account itself. It does not mention side effects, but the read-only nature is implied by 'list'.

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

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

The description is concise yet comprehensive, covering purpose, output structure, and a special note about the counterpart field. It is well-structured and free of 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?

With no output schema, the description partially fills in the return structure (mentions counterpart and participants). It does not list all possible fields, but provides enough context for basic usage. Pagination handling is also explained via parameters.

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?

All three parameters have descriptive text: 'after' as pagination cursor, 'limit' with default and max, and 'account' with type and format. These add meaning beyond the schema types.

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

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

The description clearly states the tool's function: listing Instagram direct-message conversations for an account, ordered most recent first. It also explains key output fields, making the purpose 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 does not explicitly mention when to use this tool versus alternatives (e.g., other list tools). It implies a read-only listing operation but lacks explicit conditions or exclusions.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the return fields and that posts are 'recent', giving some insight into behavior, but it does not explicitly state that the operation is read-only, mention pagination behavior, or address error cases.

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 that efficiently conveys the action, scope, return fields, and purpose. No redundant or irrelevant information is present.

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

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

The tool has a simple parameter set, no annotations, and no output schema, so the description must explain return values. It does list the returned fields and gives a clear purpose. While it does not detail pagination or edge cases, it is sufficiently complete for a straightforward list operation.

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 only repeats the 'account' parameter definition ('connected-account id or handle') and adds no new meaning for the 'after' or 'limit' parameters beyond what the schema already provides.

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

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

The description clearly states the tool lists an Instagram account's recent posts with specific fields (caption, permalink, timestamp, comment count) and a purpose (to read or moderate comments). This distinguishes it from sibling tools like list_instagram_conversations or list_posts.

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

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

The description provides a clear usage context ('so you can find one to read or moderate comments on'), indicating when this tool is appropriate. However, it does not explicitly exclude alternatives or name specific sibling tools for comparison.

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?

No annotations are provided, so the description must disclose behavior. It adds context that mentions are captured from Instagram mention webhooks, clarifying data scope, but does not mention ordering, pagination, permissions, or return format, which are relevant for a list operation.

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

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

A single sentence front-loads the action and resource, then adds a relevant parenthetical about the data source. Every word earns its place without unnecessary detail or repetition.

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

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

For a simple list tool, the description explains what it lists and where the data comes from. However, without output schema or annotations, it lacks details on return fields, ordering, and the exact meaning of 'recent', leaving some ambiguity.

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 sole parameter 'limit' is fully documented in the schema with default (30) and cap (100), so the description does not need to elaborate. Baseline 3 applies due to 100% schema description coverage.

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

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

The description clearly states 'List recent @mentions' with a specific verb and resource (Instagram accounts). It distinguishes from siblings like get_instagram_comments and get_instagram_messages by focusing specifically on mentions, not comments or messages.

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 explicit when-to-use or alternative tools are mentioned. The phrasing implies use when needing recent mentions, but does not provide exclusions or comparisons to sibling list tools, leaving usage inferable rather than explicit.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It only states the basic function and does not reveal pagination behavior, default limits, output format, or any side effects. This is a significant gap for a list operation with 7 parameters.

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 that wastes no words. It clearly conveys the primary action and scope, making it an appropriate length for the tool's purpose.

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 7 optional parameters, no annotations, and no output schema, the description is insufficiently complete. It does not explain return values, pagination, filtering specifics, or relationship to sibling tools, leaving significant gaps for an agent to understand its 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 57%, and the description merely says 'optional filters' without enumerating or explaining any parameters. It adds no semantic value beyond the schema, and leaves undocumented parameters (runId, provider, campaignId) entirely unexplained.

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

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

The description clearly states a specific verb ('List') and resource ('posts'), scoped to 'the workspace' with 'optional filters'. This sufficiently distinguishes it from sibling tools like get_post (singular post) and list_accounts (accounts).

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

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

The description provides no guidance on when to use this tool vs. alternatives, such as get_post or list_accounts. There is no mention of use cases, exclusions, or preferred scenarios.

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 no annotations, the description carries the full burden. It discloses the operation type (list) and that results include provider errors, but does not mention pagination, permissions, or whether all attempts or only failed ones are returned. It is sufficient for a simple list tool but not rich in behavioral detail.

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

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

The description is two short sentences, front-loaded with the main action and purpose. No redundant or filler content; 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?

The tool is simple (one parameter, no output schema), and the description provides the essential purpose and usage context. It does not explain return format or specific failure behavior, but for a list operation with low complexity, this is adequate and not a significant gap.

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

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

Schema coverage is 0%, but the description's phrase 'for a post' clarifies that postId is the post identifier, adding some meaning beyond the bare schema. However, it does not provide format, constraints, or examples, so it only partially compensates for the lack of schema 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?

The description clearly states the tool's function with a specific verb ('List') and resource ('publish attempts for a post'), and adds a distinguishing detail ('including provider errors') that separates it from siblings like list_posts and get_post.

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

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

The second sentence explicitly gives a use case: 'Use this to debug failed posts.' This provides clear context, though it does not explicitly mention alternatives or when not to use, which is a minor gap.

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 no annotations provided, the description carries full responsibility for disclosing side effects. It does state the critical guarantee 'without creating anything', which signals safe, non-mutating behavior. Yet it does not describe other behavioral aspects such as whether it validates the schedule, performs network calls, or has rate limits. The coverage is minimal but not misleading.

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

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

The description is a single, tightly constructed sentence that packs the core purpose, the expansion outcome, and the side-effect-free guarantee. It is front-loaded with the action verb 'Preview' and contains no filler or redundant content.

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

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

For a preview tool with one nested parameter and no output schema, the description gives a clear high-level idea of the output ('concrete posts and steps'). It lacks specific return format details, but the schema's parameter documentation compensates for input complexity. Considering sibling tools and the overall simplicity, this is reasonably complete, though not exhaustive.

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

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

The input schema already provides a highly detailed description of the 'schedule' parameter, including minimal shape, campaign document variants, and provider-specific settings. Since schema description coverage is 100%, the tool description itself adds no extra parameter semantics. The baseline of 3 applies because the schema does the heavy lifting.

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

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

The description uses a specific verb 'Preview' and clearly identifies the resource ('campaign schedule document') and the outcome ('expands into concrete posts and steps'). It also explicitly states a key differentiator: 'without creating anything', distinguishing it from apply_schedule and publish_draft. This makes the tool's purpose unmistakable and distinct from 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?

The phrase 'without creating anything' strongly implies a read-only, exploratory use case, indicating you would use this tool when you want to see the expansion before actually applying the schedule. However, it does not explicitly name alternative tools like apply_schedule or validate_schedule, so it leaves room for clearer when-to-use guidance.

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

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

With no annotations, the description carries full responsibility for behavioral disclosure. It only restates the action and optional start time, without explaining consequences, permissions, or idempotency. This is a significant gap for a mutating tool.

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

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

The description is a single, direct sentence that is concise and front-loaded, with zero redundancy. It could be more informative, but the structure and brevity are appropriate.

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

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

For a simple two-parameter tool, the description covers the core purpose and the start time option. However, it omits contextual details like immediate vs. scheduled publishing and the effect on the draft status, which would matter to an agent with no additional annotations or output schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats the ISO-8601 format already in the schema but adds no new semantic meaning beyond that.

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

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

The description states a specific action ('Publish') and resource ('previously created draft run'), clearly distinguishing it from siblings like cancel_post or retry_post. It unambiguously identifies the tool's function.

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 when a draft run exists and needs to be published, but provides no explicit guidance on when not to use it or alternatives (e.g., apply_schedule). It lacks clear context for tool selection.

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

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

With no annotations, the description carries the full burden of behavioral transparency. It only discloses that the message must be 'received,' but does not mention side effects (e.g., whether it replaces existing reactions), permission requirements, errors, or response 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?

The description is a single, concise sentence with no unnecessary words. It communicates the core purpose effectively in a compact format.

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 no annotations, no output schema, and moderate schema coverage, the description is too terse to provide complete context. It omits important details about prerequisites, effects, or behavior in edge cases, making it insufficient for an agent to fully understand the tool.

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

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

Schema description coverage is 60%, so the description should compensate for the undocumented messageId and conversationId, but it does not. The only parameter-related addition is 'e.g. love' which merely repeats the schema default and adds no new semantics.

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

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

The description uses a specific verb ('React') and a clear resource ('received Instagram direct message'), which clearly distinguishes this tool from siblings like send_instagram_message and reply_instagram_comment. The example 'e.g. love' further clarifies the action.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives. It only implies that it applies to received messages, but does not mention when to prefer it over sending a message or replying, nor any exclusion criteria.

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?

No annotations exist, so the description carries the full disclosure burden. It does disclose the key behavioral traits: the write side-effect ('store a new snapshot'), the refresh-and-return flow, and the fallback outcome for unsupported providers ('others return an unsupported snapshot'). It stops short of explaining failure/slow fetch behavior or side effects on storage, but for a mid-complexity tool the essential behavioral profile is visible.

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 with zero waste: the first covers action, side effect, return value, and provider scope; the second covers routing guidance and the provider exclusion case. Information is front-loaded 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 two-parameter tool with 100% schema coverage, the description covers purpose, side effect, provider support, fallback behavior, and relationship to get_analytics; with no output schema, the return shape is only gestured at ('return it'). Slightly more detail about failure states or what the returned snapshot contains would fully close the gap, so it falls just short of complete.

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

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

Schema description coverage is 100%, with postId and window already self-documenting formats and defaults ('7d (default lifetime)'). The description adds provider context that helps the agent reason about valid postId values, but it does not materially extend parameter semantics beyond the schema. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

States a specific verb+resource+outcome: 'Fetch fresh analytics for a published post from the provider and store a new snapshot, then return it.' It also enumerates supported providers and explicitly differentiates from sibling get_analytics by referencing the 'last stored snapshot' vs 'current numbers' distinction. An agent can reliably tell this tool apart from the other analytics 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?

Provides explicit when-to-use guidance: 'Call this before get_analytics when you need current numbers rather than the last stored snapshot.' This names the alternative and the selection condition, leaving no inference about the main decision point. The unsupported-provider fallback note also informs whether the call is worth making at all.

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?

No annotations are provided, so the description carries the full burden. It only states the action 'reply' without disclosing required permissions, effect on the comment thread, rate limits, or whether the reply is publicly visible. This is insufficient for a mutation 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?

Single sentence, ten words, front-loaded with action and resource. No filler or redundant explanation. Extremely 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?

The tool is simple (3 flat parameters, no output schema), but with no annotations and minimal description, the agent lacks context about when to use it vs alternatives, what a successful reply returns, and what preconditions exist. The description is far from complete for real-world invocation.

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

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

Schema coverage is 67% (account and message described, commentId not). The description adds little beyond the schema: it confirms 'reply' context but does not clarify the commentId format or how the account handle relates to the user's media. The agent must infer meaning mostly from parameter names.

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

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

The description uses a specific verb ('Reply') and resource ('Instagram comment on the user's media'), clearly distinguishing action from sibling tools like delete_instagram_comment or 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?

The description implies usage (replying to a comment on user's own media) but does not explicitly mention alternatives or when not to use it. Sibling tools like react_instagram_message or send_instagram_message are not referenced.

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?

No annotations are provided, so the description carries full responsibility for behavioral disclosure. It only states 'Retry a failed post,' which adds no information beyond the tool's name. It does not mention side effects, whether it creates a new attempt, required permissions, or failure/retry behavior. This is effectively a tautology.

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 redundant words, earning credit for conciseness. However, it is under-specified to the point of being minimal, lacking essential behavioral context. It is efficient but at the cost of completeness.

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 no annotations, no output schema, and only one parameter, the tool is simple, but the description is too sparse. It does not explain what 'retry' entails (e.g., whether it reschedules, republishes, or creates a new attempt), nor how it relates to sibling tools like post_attempts or publish_draft. The description is not sufficient for reliable invocation in a broader context.

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

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

The schema has one parameter, postId, with no description coverage (0%). The tool description does not explain postId's meaning or format beyond the name itself. While postId is self-explanatory, the description adds no value in clarifying the parameter's role or constraints, failing to compensate for the low schema coverage.

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

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

The description uses a specific verb ('Retry') and resource ('a failed post'), clearly indicating the tool's function. It distinguishes from siblings like cancel_post or publish_draft, though it does not explicitly name alternatives. The purpose is clear and non-tautological.

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 explicit guidance is given on when to use this tool versus alternatives. The phrase 'a failed post' implies it should be used after a post fails, but the description does not provide conditions, prerequisites, or exclusions. With many sibling tools, this lack of guidance leaves the agent to infer usage 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?

With no annotations, the description carries the full burden of behavioral disclosure. It mentions 'status summary' but does not clarify what statuses are possible, whether the operation is read-only, or how errors are handled, which are significant 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?

The description is a single sentence with no filler or redundant information. It is appropriately front-loaded with the core purpose.

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

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

The tool has no output schema, so the description should provide more detail on return values and usage context. It only says 'status summary' without specifying status types, data structure, or when to use it, leaving the agent under-informed.

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

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

The schema has 0% description coverage for runId, and the description does not explain what runId is, its format, or how to obtain it. The agent is left with an ambiguous string parameter and no guidance, making parameter semantics very weak.

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

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

The description uses a specific verb 'Get' and resource 'status summary of a publishing run and its posts', which clearly identifies the tool's function. It is distinct from sibling tools like get_post or list_posts, but it doesn't explicitly call out this distinction.

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

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

No guidance is given on when to use this tool versus alternatives, nor any prerequisites or conditions. The description simply states what it does, leaving the agent to infer appropriate usage.

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?

No annotations are provided, so the description carries the full burden. It discloses the 24-hour window and the tag exception, which is important behavioral context. However, it doesn't cover other traits like error behavior, side effects of sending, or what happens if both text and attachment are provided (though schema partially covers this).

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

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

The description is two sentences, front-loaded with the core function and followed by the key constraint. Every word earns its place; no redundancy or fluff.

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 send operation with no output schema, the description covers the core behavior and the primary restriction. It doesn't discuss return values, but that's not critical for successful invocation. The missing edge-case details are sufficiently handled by the schema, so the description is complete enough.

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 slight context by framing text and attachment_url as alternative send modes, and ties the tag parameter to the 24-hour restriction. But the schema already describes each parameter adequately, so the additional value is marginal.

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 'Send an Instagram direct message' with explicit modes ('a text reply, or an image/video attachment via attachment_url'). This clearly defines the tool's action and resource, and distinguishes it from sibling tools like react_instagram_message or reply_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?

It provides a clear usage constraint: 'Only allowed within 24 hours of the recipient's last message unless a message tag (e.g. HUMAN_AGENT) is supplied.' This gives context on when the tool is permitted. It doesn't explicitly mention alternatives, but the scope is well defined enough for an agent to select it appropriately.

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 no annotations, the description carries the burden of disclosing behavior. It explains that the server downloads from a public URL or accepts base64, and returns an asset id and public URL. However, it omits important traits like file size limits, supported formats (beyond 'image or video'), and authentication requirements. This provides some transparency but not full.

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

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

Two sentences, front-loaded with the primary action and resource. Every word contributes: target storage, input methods, and return value. No redundancy or fluff.

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 low-complexity tool with no output schema, the description covers the essential return values (asset id, public URL) and usage context (media_link). It doesn't mention edge cases like both parameters being provided or error handling, but those are not critical for basic invocation. Minor gaps like size limits are acceptable given the simplicity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by stating that sourceUrl is a public URL the server downloads and that contentBase64 is an alternative, implying mutual exclusivity and the server-side fetching behavior. This goes beyond the schema's basic property 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?

Description uses a specific verb 'Upload' and names the resource 'media to SocialClaw hosted storage'. It clearly distinguishes from sibling tools like list_assets and get_post by focusing on the write operation. The scope is well-defined: images or videos.

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 conveys when to use the tool (to upload media for use as media_link in schedules) and explains two input methods (sourceUrl or contentBase64). It does not explicitly exclude any scenarios or name alternative tools, but there are no apparent upload-specific siblings, so the context is sufficient.

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 no annotations, the description carries the full behavioral burden. It effectively discloses the key side-effect boundary by stating 'WITHOUT creating any posts,' which is critical for a validation tool. However, it does not mention what happens on validation failure (e.g., error vs. result object) or whether any state is otherwise modified, leaving some transparency 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?

The description is two sentences with no wasted words. The first sentence states the function and scope; the second gives a clear directive. Information is front-loaded, and the behavioral note ('WITHOUT creating any posts') is effectively embedded.

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

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

The tool has a complex nested input and no output schema, but the description covers the tool's purpose, non-mutating nature, and when to use it. It does not explain the return value or error behavior, which would improve completeness for a validation tool. However, the provided detail is sufficient for an agent to select and invoke the tool correctly in most cases.

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?

Although schema coverage is 100%, the description enriches the single 'schedule' parameter with concrete shapes (minimal and campaign documents) and a specific example of provider settings (TikTok inbox mode). This goes well beyond the raw schema, providing actionable semantics for constructing valid input.

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

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

The description uses a specific verb ('validate') with a clear resource ('schedule document') and enumerates the validation dimensions (provider rules, media limits, account state, publish times). It also explicitly contrasts with the sibling tool 'apply_schedule' by noting it does not create posts, making the tool's purpose unmistakable.

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

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

The description provides explicit when-to-use guidance: 'Always run this before apply_schedule.' This clearly positions the tool as a pre-flight check for another tool, giving the agent a direct workflow cue. No alternative tools are named, but the directive resolves ambiguity.

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 no annotations, the description must carry the full burden. It mentions the connection state and the provider filtering behavior, but does not disclose return format, side effects, or error scenarios. It adds some behavioral nuance beyond the name, but not much.

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

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

The description is two concise sentences, front-loaded with the main action and a clear optional parameter usage. 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 simple health-check tool with one optional parameter and no output schema, the description is adequate but incomplete. It tells what it checks (connection state) but does not describe output shape or potential response types, which could be relevant without an output schema.

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

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

Schema coverage is 100% with a descriptive parameter. The description's 'Pass provider to check one provider's connections' essentially restates the schema's 'Optional provider to check connection health for', adding minimal extra meaning. Baseline 3 is appropriate.

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

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

The description clearly states the tool gets workspace health and includes connection state across providers, which is a specific verb+resource. It does not explicitly distinguish from siblings like workspace_usage, but the reference to connection state is specific enough to understand its purpose.

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

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

The description gives usage context by explaining the optional provider parameter, but does not mention when to use this tool versus alternatives. It implies usage for checking health but lacks explicit when/when-not guidance.

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

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

With no annotations, the description carries the full burden. It implies a read operation via 'Get' but does not disclose any behavioral traits such as authentication requirements, rate limits, data granularity, or whether the counts are real-time or cached. The description simply restates the tool's function without adding contextual depth.

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, well-structured sentence that conveys the core purpose without any filler. It is appropriately concise for a zero-parameter tool, with every word earning 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?

While the description states the essential purpose, it does not specify what the counters include (e.g., API calls, storage, active users) or how plan entitlement consumption is reported. Given that there is no output schema and no annotations, a bit more detail would help the agent understand what to expect from the response. Still, for a zero-parameter read-only tool, the description is minimally viable.

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 has zero parameters, so there is no parameter meaning to add. According to the baseline, a zero-parameter tool receives a 4 because the schema is complete and the description does not need to compensate.

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

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

The description uses a specific verb ('Get') and identifies the resource ('workspace usage counters and plan entitlement consumption'), which clearly distinguishes it from siblings like workspace_health or get_analytics. The tool's purpose is immediately actionable.

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 is provided about when to use this tool versus alternatives such as workspace_health, get_analytics, or account_capabilities. There are no usage criteria, exclusions, or alternative tool references.

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