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

With no annotations, the description conveys the key side effect: the post remains in the system but is not published. It does not mention whether the schedule is cleared or if it can be re-scheduled, but the primary behavior is clear.

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 packs the essential information without any filler. It is well-structured and front-loads 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?

The description is complete for the operation's primary purpose. It does not describe the return value, but for a cancel action, an explicit output is rarely needed. Given the simplicity and no output schema, this 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?

The sole parameter 'id' is described in the schema as 'Post id (uuid)', which is sufficient for a simple identifier. The tool description adds no further clarification, but given the 100% schema coverage, a baseline score 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 action (cancel a scheduled post) and the outcome (stays in system but not published), which distinguishes it from delete_post. The verb 'cancel' is specific and unambiguous.

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

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

The description implies when to use this tool (when you want to prevent publication without deletion) but does not explicitly contrast it with alternatives like delete_post or edit_post. It would benefit from a note like 'Use this instead of delete_post to keep the post record.'

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 does state the irreversible nature ('Cannot be undone'), which is critical, but it does not mention potential side effects (e.g., deleting associated comments, delivery history) or any authorization requirements. For a destructive operation, this is a moderate gap.

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

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

Two short sentences with zero redundant wording. The key action and irreversible consequence are front-loaded, making it easy to parse quickly.

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 delete operation with a single UUID parameter, the description covers the essential action and consequence. It does not mention return values, but no output schema exists to clarify that. It is adequate for most agents, though it could explicitly note that it is a hard delete with no confirmation dialog.

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 for the single parameter 'id', with a clear description and format. The tool description adds no additional meaning beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description states a specific verb ('delete'), a resource ('post'), and an important qualifier ('permanently') that distinguishes it from sibling tools like cancel_post, which likely implies a reversible action. The phrase 'Cannot be undone' further reinforces the tool's identity as a hard delete.

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 state when to use this tool versus alternatives. While it implies permanent deletion, it does not mention that cancel_post may be appropriate for reversible cancellations, nor does it provide any exclusions or prerequisites (e.g., 'use this only if the post is not scheduled'). This leaves the agent to infer the decision boundary.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It does disclose one meaningful trait: 'Only provided fields are changed' establishes partial-update (PATCH-like) semantics rather than full replacement. However, it omits required permissions, error behavior for a nonexistent id, and any indication of what a successful update returns.

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

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

Two short sentences, each earning its place: the first states the operation, the second scopes it. The verb is front-loaded with zero filler.

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

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

The tool is flat with only four scalar parameters, and the description states the two critical invariants: it targets an existing post and only provided fields change. But with no output schema, no annotations, and no guidance on schedule_at format or labels behavior, an agent still has meaningful gaps to resolve before invoking correctly.

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

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

Schema coverage is only 25% (only the id property is described), so the description must compensate but barely does. 'Only provided fields are changed' adds partial-update meaning to the optional parameters, yet it does not explain labels semantics (replace vs. append), any format constraints for schedule_at, or constraints on content.

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

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

The description states a specific verb ('Update') and resource ('an existing post'), and the second sentence scopes the operation to partial updates. This clearly differentiates it from the sibling tools (delete_post, get_post, schedule_post, cancel_post), whose verbs describe distinct operations.

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 — the agent can infer that edit_post is the right tool when altering an existing post's fields — but no explicit when-to-use, when-not-to-use, or alternative routing is given. The description does not address the overlap with schedule_post and cancel_post when the intended change concerns timing.

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?

Despite having no annotations, the description discloses an important behavioral detail: the tool costs 1 AI credit. It also sets expectations that output is tone-aware and produced by AI, which adds useful information beyond a generic tool name.

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 compact and front-loaded: it states the main function first, then optional inputs, then cost. There is no wasted phrasing or redundant 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?

The description is adequate for a simple generative tool with all optional parameters, and the credit cost is clearly noted. Gaps remain around char_limit and workspace_id semantics, expected output shape, and how it differs from the similar sibling rewrite_for_platforms.

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 maps current_caption to draft text and platforms to target platforms, which adds intent beyond the raw schema. However, it does not explain char_limit or workspace_id, and schema description coverage is 0%, so the description only partially compensates for undocumented parameters.

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

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

The description clearly states the verb and resource: generate or improve a social media caption with AI. It is easy to identify the tool's main purpose, though it does not explicitly distinguish itself from the sibling tool rewrite_for_platforms.

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 clear usage context: use this when you need an AI caption generated or improved, optionally passing draft text and target platforms for tone-aware output. It does not mention exclusions or alternative tools, but the primary use case is clear.

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

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

No annotations are provided, so the description carries the burden of explaining behavior. It clearly frames the tool as a diagnostic, non-mutating check of token freshness and rate-limit headroom, and clarifies the kind of answer it provides. This is strong behavioral detail for a read-only health tool, though it never explicitly states that it performs no modifications.

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, front-loaded with the core action and followed by a practical use case. Every word earns its place with no filler, repetition, or unrelated 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?

For a simple, single-parameter diagnostic tool, the description gives the scenario, the purpose, and the key outcome. It doesn't specify the exact return structure, but no output schema exists and the description already conveys what the result should communicate ('token freshness', 'rate-limit headroom', 'OAuth token expired').

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 reported as 0%, and the only parameter is account_id. The phrase 'for a single account' partially compensates by indicating what account_id represents, but the description doesn't explain how to obtain the ID or that it must reference an existing account. The schema confirms it's a uuid string, so the core meaning is inferrable but not fully spelled out.

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 ('Check') and resource ('token freshness and rate-limit headroom') for a single account, going beyond the generic tool name. It also distinguishes itself from siblings by focusing on account health diagnostics rather than account listing, post mutations, or credits.

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 specific usage trigger: 'Useful when posts are failing — tells you if the OAuth token has expired.' This gives the agent a clear context in which to select the tool, although it does not explicitly mention when not to use it or name sibling alternatives.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states that the tool is read-only and reports specific information (balance, usage, reset date), which is sufficient for a simple tool with no side effects. It also implicitly signals that no mutation is performed, aligning with the read-only nature.

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 directly conveys the tool's purpose and key information. It is front-loaded and contains no redundant or irrelevant details, maximizing clarity in minimal words.

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

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

For a tool with no parameters and a straightforward read-only purpose, the description is complete enough. It does not detail return format or exact usage specifics, but given the simplicity and lack of an output schema, the description sufficiently covers what an agent needs to know to call it correctly.

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

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

The tool has zero parameters, and the schema is empty, so there is no parameter info to add. The description effectively communicates the output content (balance, usage, reset date), which is the core value. A baseline of 4 is appropriate for a parameterless tool where the description covers the tool's purpose.

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: showing the current AI credit balance, usage for the period, and the reset date. It uses a specific verb ('show') and clearly identifies the resource ('AI credit balance'), making it distinct from sibling tools that handle posts, accounts, or content generation.

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 a read-only information retrieval context, and with zero parameters, usage is straightforward. It provides clear context for what the tool reports but does not explicitly state when to prefer it over alternatives, which is acceptable given its unique scope among siblings.

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

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

The verb 'Fetch' implies a non-destructive read operation, and the description tells what data is returned. With no annotations, it does not say anything about permissions, errors, response envelopes, or lack of side effects, leaving some burden unmet.

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 clear sentence, front-loaded with the key information: what the tool does and what it returns. Not a single wasted phrase.

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

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

For a one-parameter read tool with no output schema, the description covers the core details: the exact parameter, the item type, and the return content. It could mention what happens for an invalid/missing id, but that is a minor gap.

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

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

The schema already documents the only parameter 'id' as a UUID with a description. The tool description merely says 'by id', which adds no semantic detail beyond the schema. Since schema coverage is 100%, the baseline of 3 is appropriate.

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

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

The description specifies a clear verb ('Fetch') and a concrete resource ('a single post by id') plus what it returns (full content, settings, delivery records). This is immediately distinct from list_posts and list_post_deliveries.

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 'single post by id' suggests the intended context of retrieving one specific post rather than listing posts. It does not explicitly mention alternatives or exclusions, but the usage intent is clear enough for a one-parameter lookup.

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

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

The description discloses return fields (platform, username, primary flag, connection status), which adds context beyond the input schema. However, without annotations, it omits details like authentication requirements, rate limits, and the meaning of 'connected' or 'primary flag'. It is helpful but not exhaustive.

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

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

A single, well-structured sentence that efficiently states the action and lists return fields. No redundant words; all information is presented clearly.

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 operation, the description is mostly sufficient, but it omits potential nuances like pagination, ordering, or error handling. The contrast with get_account_health is not clarified, which could lead to confusion in the absence of 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?

With schema_description_coverage at 0%, the description does not mention workspace_id or any parameter details. Although the parameter name is intuitive, the description fails to reinforce its requirement or clarify the expected format beyond what the schema provides.

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

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

The description uses a clear verb 'list' and specifies the resource 'connected social accounts in a workspace', distinguishing it from siblings like list_posts and list_workspaces. It immediately conveys what the tool does.

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 usage is implied through the purpose, but the description does not explicitly state when to use this tool over alternatives or mention any exclusions. No contrast with get_account_health or other account-related tools is provided, leaving selection inference to the agent.

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

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

No annotations are provided, so the description bears full responsibility for behavioral disclosure. It hints at a read-only operation via 'show' and lists the statuses, but it omits details on response structure, error conditions, permissions, or rate limits, leaving 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, tightly worded sentence that front-loads the core action and scope. It contains no filler and is appropriately sized for a simple tool, though it does not elaborate on output 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 clarify return structure. It states 'Show per-account delivery status' but does not explicitly mention that it returns a collection or list, nor does it cover pagination or error handling. For a one-parameter read tool, it is nearly complete but could specify the response format.

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

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

Schema description coverage is 100% with the sole parameter 'id' described as 'Post id (uuid)'. The description adds no extra parameter semantics beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the verb 'show' and the resource 'per-account delivery status' for a post, listing the status values (queued, publishing, published, failed). This distinguishes it from sibling tools like get_post or list_posts, though it does not explicitly name an alternative.

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

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

The description implies usage when delivery status is needed, but it does not provide explicit when-to-use or when-not-to-use guidance, nor does it contrast with siblings. Agents must infer the appropriate context from the purpose alone.

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

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

With no annotations, the description carries the burden of disclosing behavior. It clearly signals a read-only listing operation and describes filtering, pagination, and the returned data fields. It does not mention ordering, default pagination limits, or auth needs, but the core behavioral profile is transparent enough for a list endpoint.

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 convey purpose, filtering, pagination, and return contents without filler. The main action is front-loaded, and every clause adds information.

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

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

For a 4-parameter tool with no output schema and no annotations, the description is helpful but incomplete. It states return fields and filtering, yet it does not explain pagination behavior (defaults, max limit), total counts, ordering, or the complete status enum. An agent could call the tool correctly, but some operational details are left to inference.

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%; status and workspace_id are described, but limit and offset are not. The description adds the 'pagination' concept and names some status values, but it omits enum members like pending_approval and cancelled and does not explain limit/offset defaults or semantics. This is minimally adequate but not fully compensatory.

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 and resource: 'List posts in a workspace.' It also identifies key capabilities (filtering by status, pagination) and return fields, making the tool's purpose understandable. It does not explicitly differentiate from siblings like list_post_deliveries, but the resource is distinct enough.

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, nor does it mention exclusions or when a sibling like list_post_deliveries would be more appropriate. It implies a list/filter use case but leaves routing decisions to the agent.

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

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

No annotations are provided, so the description carries the full burden. It does communicate that results are filtered by the authenticated user's access, which is a useful behavioral trait, but it does not disclose pagination, result format, or potential empty-list 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, front-loaded sentence with no filler. Every word contributes to the tool's meaning and usage scope.

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 zero-parameter listing tool, this description is largely sufficient. The only missing context is what the returned workspace objects look like and whether listing is paginated, but the description enables correct 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?

There are zero parameters, so the baseline is 4. The description adds no parameter-specific details, but none are needed because the input schema already confirms no parameters exist.

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 action ('List') and the resource ('workspaces'), and specifies the scope ('the authenticated user has access to'). This distinguishes it from sibling tools like list_posts and list_accounts without needing to reference them explicitly.

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

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

The context is clear: use this tool when the agent needs to see which workspaces the current user can access. There are no explicit when-not-to-use instructions or named alternatives, so it stops just short of a 5.

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

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

With no annotations, the description carries the disclosure burden. It does disclose a meaningful behavioral trait: the call is batched, generates one post per platform, and costs 6 AI credits regardless of platform count. It omits response format, error behavior, and auth or rate-limit caveats, but the credit-cost disclosure is valuable.

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

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

Three sentences carry the core action, scope, and cost without rambling. The flagship/"write once, get 16 versions" phrase is slightly promotional, but it is short and reinforces the batch behavior.

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

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

The definition is enough to know what the tool does and roughly how to call it, but with no output schema it should describe the response shape, and it never explains workspace_id or when to prefer this over rewrite_for_platforms. These are clear gaps given the tool's moderate complexity.

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

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

Schema description coverage is 0%, so the description must compensate. It explains url (the page to fetch) and platforms (the list for which optimized posts are generated), but says nothing about workspace_id. The enum on platforms also helps, but the required workspace context is unidentified.

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

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

The description names a specific action (fetch a blog/article URL) and a concrete outcome (generate one optimized post per requested platform in a single call). The URL-to-multiple-platforms behavior separates it from sibling tools like rewrite_for_platforms, even without naming them.

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

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

The use case is implied: use this when you have a blog/article URL and want platform-specific posts in one call. However, it never explicitly contrasts the tool with rewrite_for_platforms or other siblings, nor gives when-not-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 provided, the description carries the full burden of behavioral disclosure. It does disclose the cost ('Costs 1 AI credit per platform'), which is useful, and hints at platform-specific adjustments. However, it does not mention permission requirements, reversibility, what happens with multiple platforms (e.g., returns multiple rewrites), or any other side effects. The cost disclosure is a positive but incomplete.

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 terse sentences that front-load the core purpose and immediately state the cost. Every word earns its place; no filler or repetition. Efficiency is excellent.

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 complexity (4 params, 20 platform options, multi-platform support) and the lack of an output schema, the description is too sparse. It does not explain return values, error behavior, how the 'tone' override interacts with platform defaults, or how costs accumulate for multiple platforms beyond the per-platform statement. An agent would likely need to probe the tool or rely on external knowledge to use it confidently.

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

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

Schema description coverage is only 25%, so the description needs to compensate. It does not explain 'tone' beyond the schema's minimal 'Optional user-defined tone override', nor does it clarify the expected format of 'content' or the role of 'workspace_id'. The description only indirectly references the 'platforms' parameter without adding meaningful detail beyond the schema.

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

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

The description clearly states the specific action ('Rewrite a piece of content'), the target resource ('one or more target platforms'), and the distinguishing behavior ('applying platform-specific tone and length constraints'). This makes it easy to differentiate from siblings like generate_caption or repurpose_url, which have different purposes.

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, exclusions, or scenarios where another tool (e.g., generate_caption, repurpose_url) would be more appropriate. The usage context is only implied by the purpose.

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 mutation (create/schedule) and the two behavior branches (draft vs immediate publish), but does not mention side effects, return values, or error handling. It adds useful context but lacks depth for a mutation tool with no annotations.

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

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

Three sentences with front-loaded main action and clear variations. Each sentence earns its place; no waste 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 7-parameter creation tool with no output schema, the description covers the essential actions and branches. It omits explicit mention of required workspace_id and doesn't describe the response, but the schema provides required fields and the variations are clear. Slightly incomplete but adequate for typical use.

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 71%; description clarifies content, account_ids, and schedule_at format (ISO 8601), and adds behavior for publish_now. However, it says nothing about workspace_id, labels, or media_urls, which are only partially covered by schema descriptions. The description adds value but does not fully compensate for the uncovered parameters.

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

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

The description states a specific verb ('Create and schedule') and resource ('a post'), with clear scope. It distinguishes from siblings like delete_post and edit_post by naming the creation/scheduling action and its variations.

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 usage conditions: omit schedule_at to save as draft, use publish_now=true for immediate publication. Gives clear context on when to use the tool, though it does not explicitly name alternatives or exclusions—but the primary use case is well-defined.

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