Chirpie

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), so the bar is lower. The description still adds real behavioral value by disclosing the plan-limit failure mode and the quota mechanic that resolves it, which annotations do not express.

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

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

Three tight sentences: action and effect first, then when-to-use, then failure handling. Every sentence earns its place with no redundancy.

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

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

With one required parameter, full schema coverage, no output schema, and annotations covering the safety profile, the description supplies everything an agent needs: purpose, eligibility condition, and failure/remedy behavior. Nothing material is missing.

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

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

Schema description coverage is 100% for the single account_id parameter, so the schema already carries the syntax. The description adds only indirect context about which accounts are eligible (is_active: false), which is useful but not parameter-level detail, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Activate a connected account') plus the outcome ('so it can publish'), which clearly distinguishes it from the sibling chirpie_deactivate_account. An agent can tell what it does and on what entity without opening the schema.

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

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

Gives an explicit trigger condition ('accounts listed with is_active: false') and even a concrete example (extra Facebook Pages over plan limit). It also names the remedy when it fails (deactivating another account frees a slot), which routes the agent toward the sibling deactivate tool.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely new context: numbers come from a snapshot up to an hour old, frequent calls are free, Telegram exposes no analytics, and refresh is rate-limited (429 analytics_refresh_rate_limited with Retry-After). This is rich disclosure well beyond the annotations.

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

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

Front-loads the purpose and platform list, then packs the caching and refresh behavior into a single efficient sentence. Slightly dense but no filler; 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?

With no output schema, the description usefully names the returned metrics (likes, reposts, replies, etc.), covers platform support and the Telegram gap, and explains snapshot freshness and refresh. It does not describe the response shape in detail, but is otherwise complete for a two-parameter read tool.

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

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

Schema description coverage is 100%, and the schema already documents post_id and the full refresh rate-limit behavior. The description largely restates the snapshot/refresh tradeoff, adding little syntax or meaning the schema does not already carry, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get analytics (likes, reposts, replies, etc.) for a published post') and enumerates the supported platforms, so the agent knows exactly what is retrieved. It stops short of explicit sibling differentiation (e.g. vs chirpie_get_post), keeping it below a 5.

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

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

The description gives strong operational guidance for the refresh parameter ('calling this often costs nothing; set refresh to ask the platform now instead') and flags that Telegram is unsupported. However, it never states when to pick this over a sibling such as chirpie_get_post, so tool-selection guidance is only implied.

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

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

Annotations only declare the safety envelope (not read-only, open-world, not idempotent). The description adds genuinely non-obvious behavior: that the account password is refused, that anything other than the xxxx-xxxx-xxxx-xxxx format is refused, and the exact error code (bluesky_app_password_required) returned on failure. That is real additional transparency.

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

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

Front-loads the core action and the credential restriction, then supplies format and a creation link. Efficient, though the password format is repeated from the schema, which is minor redundancy.

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

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

For a connect tool with no output schema, the description covers everything an agent needs: required credential type, format, how to create it, and the failure mode. Nothing material is missing.

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

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

Schema coverage is 100%, so both parameters are already documented in the input schema, including the app-password format and the identifier flexibility. The description's restatement of the format is largely redundant; baseline 3 applies.

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

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

States a specific verb and resource ('Connect a Bluesky account') and distinguishes itself from the sibling connect_* family (facebook, instagram, x, etc.) by naming the platform in the tool name and title. An agent can route to it without opening a schema.

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

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

Gives clear context for how to obtain the required credential (app password created under Settings > Privacy and Security) and the exact URL, which is strong practical guidance. It does not explicitly name sibling alternatives or state when not to use this tool, so it stops short of a 5.

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

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

Annotations cover the safety profile (not read-only, open-world, non-idempotent), so the description correctly focuses on what they cannot convey: that this only starts the flow and returns an authorization_url the user must open in a browser. That workflow detail is genuinely additive, though it omits what happens if the flow is abandoned or that repeated calls yield fresh URLs.

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, both front-loaded and purposeful: the first defines the action, the second defines the return value and required user follow-up. No filler or restatement of the title.

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

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

For a zero-parameter tool with no output schema and full annotation coverage, the description supplies the essential missing piece — the authorization_url return value and the browser step. It stops short of describing post-authorization behavior or how to verify the connection succeeded, which would make it fully self-contained.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to disambiguate, and it correctly avoids inventing parameter detail.

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

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

The description states a specific verb and resource — 'Start the OAuth flow for a LinkedIn profile account' — which pins down both the action and the platform. Against siblings like chirpie_connect_bluesky or chirpie_connect_x, the platform-specific naming makes it unambiguous which tool to pick.

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

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

The description implies when to use it (to initiate a LinkedIn connection) and describes the follow-up step the user must take, but it names no alternative or exclusion — e.g., whether an existing connection should be checked via chirpie_list_accounts first or how this differs from chirpie_disconnect_account. Usage is inferable but not guided.

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

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

Annotations already cover the safety profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false), so the description only needs to add context. It does add two non-obvious facts: Chirpie retains only the server from the supplied value, and an unresolvable server is rejected with the specific error code mastodon_instance_invalid. It does not say what the call returns or that the user must complete an external redirect, but the annotation bar is met.

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

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

Two tight sentences: the action is front-loaded, then the accepted inputs and the failure mode. No filler and nothing important buried.

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

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

For a one-parameter OAuth initiation tool with annotations carrying the safety profile, the description covers action, input leniency, retention behavior, and the failure case. The main omission is the return value or next step (e.g. an auth URL the user must visit), which matters since there is no 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% and the single parameter is fully documented there, so the baseline is 3. The description's "keeps only the server" adds the useful nuance that a handle or profile URL is accepted and normalized rather than stored verbatim, but otherwise restates what the schema already says.

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

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

States a specific verb and resource ("Start the OAuth flow for a Mastodon account") and names the platform explicitly, which cleanly separates it from the sibling connect_* tools for Bluesky, X, Facebook, and the rest.

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 call it (a user wants to link a Mastodon account) and names the accepted input forms, but it never states when NOT to use it or routes the agent to an alternative, such as disconnecting or listing accounts. Usage is inferable rather than spelled out.

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

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

Annotations already disclose the safety profile (readOnly=false, destructive=false, openWorld=true, idempotent=false), so the description only needs to add context. It contributes the @BotFather prerequisite and the accepted chat target types, but never addresses the non-idempotent behavior — e.g., what happens if the same bot/chat is connected twice — which is the one trait the annotations flag as risky.

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

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

Two short sentences with the action front-loaded and the prerequisite sequence immediately after. No filler, no repetition of the title, 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 connect tool with no output schema and annotations covering safety, the description supplies the essential setup prerequisite and target scope. It is nearly complete; only post-connection behavior and duplicate-connect handling are unaddressed.

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

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

Schema description coverage is 100%, with chat_id formats and the bot_token source fully documented in the schema itself. The description restates 'pass the bot token and the chat ID (user, group, or channel)' without adding syntax or format detail beyond what the schema already carries, so the baseline 3 applies.

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

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

States a specific verb and resource (connect a Telegram bot) plus the required setup path, so the agent knows exactly what the call accomplishes. It does not explicitly differentiate itself from the connect_* siblings, but the platform-specific naming makes the distinction obvious without opening schemas.

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

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

Provides a prerequisite workflow (create the bot with @BotFather first, then pass token and chat ID), which is useful implied guidance for invoking it correctly. It offers no when-to-use vs. when-not guidance and does not mention chirpie_disconnect_account or reconnection scenarios as 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?

Annotations already declare readOnly=false, openWorld=true, idempotent=false, destructive=false, so the safety profile is covered. The description adds value beyond that by disclosing the return artifact (authorization_url) and the required human step, which is essential behavior for an OAuth initiation tool. It doesn't mention expiry or re-invocation behavior, keeping it at a 4.

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

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

Two sentences, zero filler, with the action stated first and the required user follow-up second. Nothing redundant with the title.

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

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

With no output schema, the description correctly carries the return-value burden by naming authorization_url and the browser step the user must perform. It leaves unspecified whether the URL expires, how the connection is confirmed, or whether a callback is involved, but the core invocation path is clear.

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

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

The tool takes zero parameters and the schema is empty, so there is nothing for the description to clarify. Baseline 4 applies for a no-parameter tool.

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

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

The description gives a specific verb and resource: 'Start the OAuth flow for a X/Twitter account.' Naming the platform separates it from the many connect_* siblings (bluesky, facebook, etc.) without needing the schema. It stops short of a 5 only because it doesn't explicitly frame itself against the X-specific key-management 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?

It states the follow-through ('the user must open in a browser to complete the connection'), which implies the context of use, but never says when to choose this over alternatives such as chirpie_set_x_keys or chirpie_get_x_keys_status, nor when not to use it. Adequate implicit guidance, no explicit routing.

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

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

Annotations already declare this is a non-readonly, non-idempotent, non-destructive write. The description adds critical non-obvious behavior: the key is returned exactly once, is prefixed 'chirpie_sk_', and is never shown again. That is exactly the kind of disclosure the description should carry.

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

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

Three focused sentences, front-loaded with the action and the one-time-return warning. The scope-inheritance sentence is dense but earns its place. Slightly heavy for a two-parameter tool, but not padded.

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 fills the gap by telling the agent the return value (the full key) is available only once. Combined with the scope rules and one-time visibility, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the schema already documents both parameters, setting a baseline of 3. The description goes beyond it by explaining scope inheritance: a key with no scopes mirrors the calling key, and a key can never grant a scope the caller does not hold — real semantic value the schema doesn't convey.

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: 'Create a new Chirpie API key.' This cleanly distinguishes it from sibling tools like chirpie_list_keys and chirpie_revoke_key without requiring schema inspection.

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 the semantics of scopes (what happens if you omit them, and the no-escalation rule), which implies when a scoped key is appropriate, but it never states explicit when-to-use/when-not-to-use conditions or names an alternative tool. Usage guidance is implied rather than stated.

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?

Goes well beyond the annotations (destructiveHint, idempotentHint, openWorldHint=false) by disclosing the exact side effect: all scheduled posts are cancelled, quota is returned, reactivation does NOT restore them, and the count appears as canceled_posts in the response. This is precisely the destructive consequence an agent must surface before calling.

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

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

Front-loaded with the core action and its reversibility, then the cancellation consequence. Every sentence carries information, though the explanation of cancel semantics is repeated slightly ('CANCELS', 'cannot publish', 'cancelled', 'does NOT restore'), costing a bit of tightness.

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

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

With no output schema, the description compensates by naming the canceled_posts response field and the scheduled_posts pre-check field, so an agent knows both what it will get back and how to preview the impact. Complete for a one-parameter mutation 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?

There is a single required parameter and the schema documents it at 100% coverage ('Account ID to deactivate'), so the description need not explain it. The description adds nothing about the parameter itself; its useful detail is about response fields, not inputs. 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?

States a specific verb and resource ('Deactivate a connected account') and immediately contrasts it against the other obvious lifecycle action by noting it 'stays connected so it can be activated again without reauthorizing', which separates it from chirpie_disconnect_account and chirpie_delete_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?

Gives a clear use context — stop publishing and free a plan slot while preserving the authorization — and points to chirpie_list_accounts' scheduled_posts as a way to preview the cost. It does not explicitly name disconnect_account or delete_post as the alternative when the user wants a full removal, so the exclusion is implied rather than stated.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds substantial behavior beyond them: the platform-first-then-record ordering that prevents false deletion reports, cascade deletion of nested replies on Facebook/Instagram/Threads/LinkedIn, and the irreversibility note that a deleted comment cannot be restored. This is exactly the extra operational context an agent needs for a destructive call.

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

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

The core action is front-loaded in the first sentence, and each subsequent sentence carries distinct, non-redundant information (ordering guarantee, cascade behavior, permission check, irreversibility). It is dense but appropriately sized for a destructive, multi-platform operation.

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 fully covers what matters: preconditions (owning the post, delete_any capability), the safety semantics of the deletion, cross-platform cascade behavior, and irreversibility. Nothing an agent needs to call this destructive tool correctly is missing.

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

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

Schema coverage is 100% and both parameters are documented there (post_id, comment_id with its chirpie_list_comments origin). The description reinforces that comment_id comes from chirpie_list_comments and ties post_id to 'a post you published,' but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

The first sentence states a specific verb and resource with scope ("Delete a comment on a post you published"), which is more precise than the bare title. It does not, however, explicitly differentiate itself from the sibling chirpie_hide_comment, leaving the delete-vs-hide distinction to be inferred.

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 real context for when the call is legitimate: the comment must be on a post you published, and capabilities.delete_any from chirpie_list_comments determines whether deleting someone else's comment is permitted. It stops short of naming exclusions or the hide_comment alternative, so the guidance is clear but not complete.

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

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

Goes far beyond the annotations (destructiveHint/idempotentHint/openWorldHint): it explains upstream_error retry semantics, quota-return behavior via cancelled_ids/deleted_ids, delete_unsupported platform cases, thread-wide cancellation, and that the post persists in Chirpie with status 'deleted'. This is rich, non-redundant behavioral disclosure.

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

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

Long and dense, but every sentence carries a distinct behavioral fact rather than filler, and the core operation is front-loaded. It is justified by the tool's complexity, though the multi-clause sentences could be trimmed slightly.

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

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

For a destructive, open-world mutation tool with no output schema, the description supplies everything an agent needs: return signals (cancelled_ids, deleted_ids), error cases (upstream_error, delete_unsupported), reversibility, and post-deletion state. Nothing material is missing.

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

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

Only one parameter with 100% schema coverage, so the schema already documents 'Post ID to delete'. The description alludes to post identity (kept id, history, status 'deleted') but adds no syntax or format meaning for the parameter itself; 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?

States a specific verb+resource ('Delete a post') and immediately distinguishes itself from chirpie_hide_post by naming it as the reversible alternative. The description makes the tool's distinct behavior (platform-reaching, irreversible) unmistakable versus any sibling.

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?

Names alternatives explicitly: chirpie_hide_post is called out as the reversible alternative for published posts and for unsupported cases, and the platform's own app is noted. However, it never states a clean prescriptive 'use this when/not when' rule, leaving the routing inference partly to the reader.

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

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

Annotations supply destructiveHint=true and idempotentHint=true, but the description goes far beyond them: publishing stops immediately, a plan slot is freed, the account vanishes from chirpie_list_accounts, repeat calls return 404, scheduled posts are cancelled with quota returned, `canceled_posts` reports the count, and published posts keep history but return `account_id: null`. It also discloses irreversibility and pre-call inspection via `scheduled_posts`.

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

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

Front-loaded with the core action and consequence, and nearly every clause carries distinct information (slot freeing, 404, cancellation, quota return, history behavior). It is dense rather than wasteful, though the run of chained clauses is longer than strictly needed for a single-parameter tool.

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

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

No output schema exists, and the description compensates by naming the response field (`canceled_posts`) and the account-state fields (`account_id: null`) an agent will see. It also documents the pre-flight signal (`scheduled_posts`) and the irreversibility, so nothing needed to call this correctly is missing.

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

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

Schema description coverage is 100% and the tool has only one parameter (account_id), so the schema already carries the parameter semantics. The description adds only the incidental note that a repeat call with 'the same id' 404s, which is behavioral rather than parameter meaning. Baseline 3 applies.

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

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

Specific verb (disconnect) plus resource (connected account), and it explicitly differentiates from the closest sibling chirpie_deactivate_account, stating that deactivate keeps the connection while this removes it. An agent can pick between the two without opening either schema.

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

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

States the when-to-use condition (permanent removal vs. temporary deactivation), names the alternative tool explicitly, and adds the recovery cost: 'Reconnecting it means the user authorizing Chirpie on that platform again.' Exclusions and alternatives are both spelled out.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), but the description adds real behavioral value beyond them: it documents what a failed post returns (error_message, retry_count), that the reason connection_lost requires reconnecting the account before anything else publishes, and it routes to chirpie_list_accounts for identifying the account. It stops short of describing the success-path payload shape.

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

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

The core action is front-loaded in the first sentence, and the following clauses are dense with operational detail rather than filler. The last two clauses run long and pack several ideas (error fields, connection_lost, list_accounts) into one sentence, but each idea 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?

There is no output schema, so the description carries the burden of explaining returns, and it does cover the important failure-state fields and the platform_post_url link for a single-post fetch. Missing coverage of the general success payload keeps it from being fully complete for a lookup 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?

With one parameter at 100% schema description coverage, the schema already documents id as the post ID. The description restates 'by ID' without adding format, sourcing, or ambiguity guidance, so it contributes no meaning beyond 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?

States a specific verb and resource: 'Get a single post by ID.' It is clearly distinguishable from bulk siblings like chirpie_list_posts and mutation siblings like chirpie_update_post. It does not, however, explicitly name a sibling to differentiate itself.

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 (fetch one post's details, especially when diagnosing a failed publish) rather than stated. The description notes that a Threads/Instagram post without a platform_post_url will have it 'asked for again here', which hints at a lookup use case, but it never contrasts this with chirpie_list_posts or other retrieval paths.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: it returns configuration status plus the callback URI, and explicitly states it never returns the client secret — a meaningful disclosure for a credentials-adjacent 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?

Two sentences, zero waste. The purpose is front-loaded and the security-relevant caveat (no client secret) is stated compactly rather than padded out.

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

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

With no output schema, the description carries the return-value burden and does so partially — it names configuration status and the callback URI but not the concrete shape of the status response. For a zero-param read tool whose annotations cover safety, this is nearly 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?

The tool takes zero parameters, so the baseline is 4. The description correctly implies no input is needed and instead spends its words on what comes back, which is the right trade-off here.

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

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

States a specific verb+resource: checking whether the user has registered their own X developer app, and clarifies it is a status/configuration read. It implicitly contrasts with the set/remove x-keys siblings but never names them, so an agent must infer the distinction.

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

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

Usage is only implied: the mention of returning a callback URI signals this is how you learn what to register on the X app, but there is no explicit 'use this before set_x_keys' or 'use this instead of list_keys' 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 annotations already covering safety (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description adds real behavioral context: unsupported platforms return comment_action_unsupported instead of a false success, and a hidden comment remains in the Chirpie listing behind include_hidden so moderation history is preserved. That is exactly the extra layer annotations cannot express.

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

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

Three tight sentences, no filler, and the core capability is front-loaded ahead of the platform caveat and the persistence note. Every sentence carries distinct information.

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

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

For a three-parameter mutation with no output schema, the description covers the operation, platform support, failure token and post-hide state, so an agent has what it needs. Minor gap: it does not state reversal/permission requirements beyond what the idempotent annotation implies.

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

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

Schema description coverage is 100% and every parameter (hidden, post_id, comment_id) is already documented in the schema, so the baseline is 3. The description adds no syntax or format detail beyond what the schema provides; include_hidden refers to a listing tool, not this tool's inputs.

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

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

States a specific verb and resource (hide/unhide a comment) plus a scope constraint ('on a post you published'), which cleanly distinguishes it from chirpie_delete_comment and chirpie_hide_post. An agent can route to it without opening the schema.

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

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

Explicitly scopes availability (Facebook, Instagram and Threads support hiding) and tells the agent what happens elsewhere, which is strong when-to-use guidance. It stops short of naming sibling alternatives such as chirpie_delete_comment for outright removal, so it is not a full when/when-not treatment.

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

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

Annotations only say readOnly=false, idempotent=true, destructive=false. The description adds the non-obvious behavior: nothing reaches the platform, analytics/comments are preserved, no quota or billing impact, hidden posts are excluded from chirpie_list_posts unless include_hidden is true, and a hidden queued post still publishes. It also discloses the surprising return dimension that hidden_ids can list more posts than the id passed.

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

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

Front-loaded with the core action, then layered with caveats in rough order of importance. The all-caps emphasis and repeated contrast with chirpie_delete_post is slightly verbose, but nearly every clause carries a distinct routing or behavioral fact.

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

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

For a single-parameter, non-destructive state toggle there is no output schema, yet the description still covers restore path, listing visibility, queued-post edge case, and the hidden_ids return shape. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100% for the single id parameter, so the baseline is already satisfied. The description goes beyond the schema by explaining that a thread or fan-out moves as one unit and that this is why the answer (hidden_ids) can name more posts than the id supplied.

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

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

Opens with a specific verb+resource ("Hide a post from the user's Chirpie listings") and immediately scopes what it does not do. It names the sibling that actually removes content (chirpie_delete_post) and the inverse (chirpie_unhide_post), so an agent can separate it from the {delete, unhide, update}_post cluster without opening any schema.

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

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

Gives explicit when-to-use vs alternatives: use this to stop Chirpie showing a post, use chirpie_delete_post to take it off the platform, use chirpie_unhide_post to restore, and for a queued post use chirpie_delete_post because hiding won't stop publishing. Both the alternative and the condition that selects it are stated.

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 output schema, the description carries the full semantics of the returned data: what `is_active: false` means, the exact vocabulary of `inactive_reason`, the consequence that a revoked token cancels scheduled posts with quota returned, and that reconnecting never needs a free slot. This is materially more than the readOnly/idempotent annotations convey.

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

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

Front-loaded and each clause carries real information, but it is delivered as one dense, over-parenthesized block that mixes this tool's return semantics with sibling-tool behavior (what deactivate cancels, what reconnect requires). Structure would benefit from separating what this call returns from cross-tool guidance.

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

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

For a parameterless listing tool with no output schema, the description covers the fields an agent must interpret to act correctly and explains the LinkedIn `account_type` distinction. Nothing essential for correct use or follow-up action is missing.

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

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

Zero parameters, so the baseline of 4 applies; the schema is empty and there is nothing for the description to clarify. The mentions of `accounts_limit` and `accounts_active` describe returned fields, not inputs.

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

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

The first clause states a precise verb+resource ('List connected social accounts') and enumerates every platform covered. An agent immediately knows this is the enumeration tool for connection state, distinct from the many chirpie_connect_* 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 description routes follow-up actions clearly: `inactive_reason` of `plan_limit` points to chirpie_activate_account, while `token_revoked`/`token_expired`/`reauth_required` require a fresh connect, and it notes retrying a post will not reactivate an account. It never explicitly frames when to call this lister itself versus checking state elsewhere, but the context is unambiguous.

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

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

Annotations already declare readOnlyHint/idempotentHint, and the description adds substantial context beyond them: snapshot freshness semantics via `sync` and `sync.reason`, per-platform capability flags including `delete_any`, cursor pagination, and the quota cost of the related reply action. This is rich behavioral disclosure.

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

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

Purpose is front-loaded in the first sentence and the rest is dense, useful signal. The later sentences are run-on with stacked parentheticals, which slightly hurts scannability but no sentence is wasted.

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

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

With no output schema, the description carries the burden of describing the return shape — `sync`, `sync.reason`, `capabilities`, and `next_cursor` — and it does so. An agent has everything needed to call and interpret the result correctly.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema (including the `sync` enum values and their refresh windows). The description's 'Page with `next_cursor`' mostly restates schema content, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the comments on a post you published') plus the ordering ('newest first'). The scope constraint 'you published' and the capability enumeration implicitly separate it from the mutation siblings (chirpie_reply_to_comment, chirpie_hide_comment, chirpie_delete_comment).

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

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

Gives clear context for use — read a post's comments from the stored snapshot — and contrasts the free listing with quota-consuming replying, steering the agent away from mutation tools. It stops short of explicitly naming alternative tools or stating when not to use this one.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered by structured data. The description adds genuinely useful behavioral context beyond that: the return shape (prefix + metadata) and the security-relevant fact that the full secret is only shown at creation, which prevents an agent from attempting to re-fetch a key.

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 with a front-loaded verb and resource, plus one parenthetical that earns its place by disclosing the key-visibility limitation. No filler.

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

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

With no input parameters and no output schema, the description carries the burden of describing the return value, and it does so ('prefix + metadata'). Nothing an agent needs in order to call this correctly is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameter-free tool is 4. No misleading parameter hints are present.

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

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

The description names a specific verb and resource ('List the user's Chirpie API keys') and is naturally distinguishable from the create/revoke siblings in the same namespace. An agent can immediately tell this is a read-only inventory operation rather than a mutation.

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 rather than stated: it lists keys, so you'd call it to inspect existing key prefixes/metadata. The parenthetical hints at when you cannot use it for retrieval (full key only visible at creation), but no alternative tool or explicit condition is named, so guidance is only implicit.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, non-open-world), yet the description adds substantial behavior beyond them: the meaning of error_message and retry_count on failed posts, the enumerated cancel reasons on deleted posts (account_disconnected, account_deactivated, connection_lost), and the retention rule that Chirpie never removes post history. That is real disclosure an agent could not get from the structured fields.

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

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

The core purpose and filters are front-loaded in the first sentence, and the return-field detail follows. The middle sentences on error_message/retry_count are dense but relevant for a tool with no output schema; a tighter edit could trim redundancy around the hidden/deleted cases.

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

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

With no output schema, the description usefully explains the returned fields (platform_post_url, hidden, error_message, retry_count) and the delete/hide behaviors. Gaps remain around pagination/limit behavior and the group_id fan-out semantics, which are only covered parenthetically in the schema.

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

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

Schema description coverage is 100%, so the schema already documents limit, status, group_id, account_id and include_hidden, making 3 the baseline. The description reinforces the include_hidden/hidden relationship but says nothing about limit, group_id, or account_id beyond what the schema provides, so it adds no meaningful parameter 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 opening two sentences state a specific verb and resource (list recent posts) plus the supported filters (status, account). It clearly differs from non-list siblings like chirpie_get_post or chirpie_post, but it never names a sibling or explicitly contrasts with get_post, so it stops short of a 5.

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

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

Usage is implied rather than stated: the reader learns that hidden posts are excluded unless include_hidden is true and that drafts are only returned with an explicit status filter (the latter lives in the schema, not the description). There is no explicit when-to-use-this-vs-alternative guidance, such as chirpie_get_post for a single post or chirpie_list_comments for comments.

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

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

Annotations only declare write/openWorld/non-idempotent/non-destructive. The description adds substantially beyond that: quota semantics and the two distinct 429 codes, X link-post billing and Free-plan rejection, the Instagram media requirement, draft-mode behavior plus the `warnings` array, and first_comment never failing the post. This is unusually rich behavioral disclosure.

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

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

Long, but front-loaded with the core action and immediate-vs-scheduled branch first, then progressively deeper caveats. For a 13-parameter tool with nested objects, nearly every sentence (quota, media rules, draft warnings) 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?

No output schema, yet the description covers the failure modes (429 usage_limit_exceeded vs rate_limited, 400 unsupported_media/configuration_unsupported), the group_id per-account result shape, and draft warnings. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100% and the nested objects are exhaustively documented, so the baseline is 3. The description restates the account_ids/account_configurations semantics that the schema already carries, adding little that isn't already in structured fields.

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

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

Opens with a specific verb and resource ('Create a post') and enumerates the platforms, then distinguishes itself from chirpie_update_post (drafts) and the fan-out behavior. An agent can tell it apart from chirpie_thread and chirpie_update_post without opening any schema.

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

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

Explicitly routes to account_ids for fan-out vs account_id, names schedule_at vs immediate publishing, points to draft:true for saving without sending, and directs editing/promotion to chirpie_update_post. When-to-use and the alternative are both stated.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely useful downstream context: connected X accounts stop refreshing until keys are re-added or reconnected, which tells the agent the blast radius of the action.

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

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

Two tight sentences with the destructive action front-loaded and the consequence following. No filler, no repetition of the title.

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

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

For a zero-parameter destructive tool, the description covers the action, the ownership scope, and the recovery path (re-adding keys). Combined with annotations covering reversibility and destructiveness, an agent has enough to call it correctly.

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

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

The tool takes zero parameters and the schema is empty, so there is nothing for the description to disambiguate. Baseline of 4 applies for a parameterless tool.

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

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

The description states a specific verb and resource: 'Remove the user's own X developer app'. The possessive scope ('user's own') clarifies ownership. It doesn't distinguish from the sibling chirpie_revoke_key, which could plausibly be confused with this operation.

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 through the stated consequence (accounts stop refreshing), which hints at when an agent would invoke it. However, no explicit when-to-use guidance or comparison against alternatives like chirpie_revoke_key or chirpie_set_x_keys 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?

Annotations only declare the generic safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false). The description adds substantive behavior the annotations cannot: the reply becomes a public post, consumes monthly quota, triggers per-platform billing on X, and is rejected on the Free plan. That is exactly the side-effect disclosure a mutation tool needs.

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

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

Two sentences, front-loaded with the core action and then the operational consequences; nothing is padding. The second sentence is dense with billing/quota clauses but each clause is decision-relevant, so it stays efficient rather than bloated.

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

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

No output schema exists, but the description covers the publish side effects, quota consumption, billing and rejection rules, and character-limit inheritance. It omits what is returned on success and error surfaces beyond those in the schema, which is a minor gap for a write tool with no 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 adds only one marginal detail beyond the schema – that the same per-platform character limits as a post apply to text – while the idempotency_key semantics are richer in the schema itself. It neither compensates for nor detracts from the schema.

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

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

States a precise verb+resource ('Reply to a comment on a post you published') and implicitly scopes the target, distinguishing it from chirpie_post (new posts), chirpie_thread (threads), and the hide/delete comment siblings. An agent can identify the operation without opening the schema.

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

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

Gives useful situational context (reply is published publicly, counts against the monthly quota, link-containing X replies cost $0.25 and are rejected on Free), which helps decide whether to call it. However, it names no alternative tool and gives no explicit when-not-to-use guidance, so usage is only implied.

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

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

Beyond the annotations (which only say this is a non-readonly, non-destructive write), the description discloses the monthly-quota cost of a successful retry, the exact refusal codes (404 first_comment_not_found, 409 first_comment_not_retryable) and the propagation of the platform's own failure. That is genuine operational context an agent cannot get from structured fields.

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

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

The purpose is front-loaded in the first sentence and every subsequent clause carries real information (quota, preconditions, refusal codes). It is a single dense block of long sentences, which is slightly heavy, but there is little filler to cut.

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 fully carries the burden: it covers the trigger condition, quota implications, sibling-tool escape hatch, and every documented failure mode. An agent has enough to call this correctly without further reading.

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 both params (id, idempotency_key) are already documented, including the idempotency replay semantics. The description adds the conceptual point that the comment text is carried by the post rather than passed in, but no syntax or format details beyond the schema, so the baseline 3 applies.

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

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

The first sentence gives a specific verb, resource and click-scope: 'Post a first comment that failed, again.' It is immediately distinguishable from siblings like chirpie_update_post and chirpie_reply_to_comment, and it further pins down that the text is the one the post already holds rather than a new body.

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 the precondition for use (a first comment left in status 'failed' on a published post) and routes the agent elsewhere when the text must change, citing chirpie_update_post and its 409 post_not_editable refusal. Explicit 'when not to use' is only implied via the refusal list, so it falls 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?

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered structurally. The description adds real value beyond that by stating the effect is 'permanent and immediate', clarifying that the action is irreversible rather than a soft disable (contrast with chirpie_deactivate_account). No contradiction with annotations.

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

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

Two short sentences, zero waste, with the action front-loaded before the permanence warning. Every sentence earns its place.

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

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

For a one-parameter destructive tool with full annotation coverage and no output schema, the description supplies what structured fields cannot: permanence and immediacy. It omits any return/confirmation behavior and routing to sibling key tools, which keeps it just under 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 coverage is 100% and the single 'id' parameter is fully described in the schema. The description's 'by its ID' merely restates that, adding no format, source, or validation detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb (revoke) and resource (Chirpie API key) plus the lookup key (ID), which is unambiguous. It does not explicitly differentiate itself from the similarly named sibling chirpie_remove_x_keys, so it falls short of a 5.

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

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

The description says nothing about when to revoke versus using chirpie_remove_x_keys, chirpie_delete_comment, or other destructive siblings, and gives no preconditions (e.g., ownership or confirmation). Usage must be inferred entirely from the tool name.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description adds valuable workflow behavior: a redirect_uri is returned, it must be registered as a callback URI, and each account must be reconnected. It does not disclose what the destructive hint actually destroys (e.g. overwriting previously stored keys), which is a remaining 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?

Three tight sentences, front-loaded with the core action, followed by the billing benefit and the required post-steps. Every sentence earns its place with no filler.

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

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

With no output schema, the description compensates by explaining the returned redirect_uri and the exact next steps the user must take. An agent has everything needed to invoke the tool and instruct the user correctly.

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

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

Schema coverage is 100%, so client_id, client_secret and label are already documented in the schema. The description adds context about where the credentials come from and their effect on billing, but no additional per-parameter syntax or format detail.

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

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

States a precise verb+resource: registering the user's OWN X developer app so their accounts post against their own API credits. This clearly differentiates it from siblings like chirpie_connect_x (account connection) and chirpie_get_x_keys_status (status check).

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

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

Explains the context for using it (own app, own credits, no surcharge) and names the follow-up alternative chirpie_connect_x that must be called afterward. It does not explicitly state when NOT to use it (e.g. if the user is happy with Chirpie's credits), but the selection context is clear.

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

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

Annotations only declare readOnly=false, openWorld=true, idempotent=false, destructive=false; the description adds far more: the atomic thread contract, what a rollback deletes, the thread_rollback payload, the difference between upstream_error (safe to retry) and thread_rollback_incomplete (retry would double-publish), the Instagram delete limitation, X link billing, and the 429 quota vs burst-limit distinction. This is exactly the behavioral context annotations cannot carry.

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

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

Purpose and the atomicity contract are front-loaded, and almost every clause carries operational weight (rollback codes, quotas, platform threading support). It is nonetheless very dense and long, with several multi-clause sentences that could be split or trimmed without losing meaning.

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

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

For a 10-parameter, nested-schema, no-output-schema mutation tool, the description covers the failure modes, retry safety, quota and rate-limit behavior, draft semantics, and enough of the response shape (group_id, per-account success, warnings, thread_rollback) that an agent can act and recover correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: what naming account_ids changes in the response, that a draft may be a single part, that a thread needs two parts to publish, and the interaction between schedule_at and timezone. It does not explain idempotency_key, which lives only 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 first sentence names a specific verb (create/publish a thread) and the resource (multiple posts on named platforms), and the definition is clearly distinct from the single-post sibling chirpie_post. It also disambiguates the multi-account variant (account_ids vs account_id) within the opening sentences.

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

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

It gives clear context for when to use it (multi-part threads, multi-account fan-out, scheduling, drafts) and states the condition that selects account_ids over account_id. It never explicitly names chirpie_post as the alternative for single posts or says when not to use this tool, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds value beyond them by disclosing that 'nothing reaches the platform' (no external side effect) and that unhiding a never-hidden post succeeds and changes nothing, giving concrete idempotency semantics. It stops short of describing the return payload, but no output schema exists to lean on.

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 core action, followed by the undo relationship and a discovery hint. Every sentence carries distinct information with no repetition or padding.

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

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

For a single-parameter, non-destructive, idempotent local operation with full schema coverage and existing annotations, the description covers purpose, inverse relationship, side-effect scope, and idempotency edge case. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100% and the single id parameter is fully documented in the schema, including the 'thread or fan-out moves whole' note. The description adds no parameter-level detail 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?

States a specific verb and resource ('Put a hidden post back in the user's Chirpie listings') and explicitly identifies itself as the inverse of the sibling chirpie_hide_post. An agent can distinguish it from hide_post, delete_post, and list_posts without opening any schema.

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

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

Names the operation it undoes (chirpie_hide_post) and points to chirpie_list_posts with include_hidden true as the way to find hidden posts, which is real routing guidance. It does not state an explicit when-not-to-use case, but the context is clear for such a narrow tool.

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

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

Annotations only flag the mutation profile (destructiveHint=true, idempotentHint=false, openWorldHint=true). The description goes well beyond them by disclosing the 409 error code, the quota semantics ('costs nothing, since it spent its quota when it was created'), thread-wide rescheduling via rescheduled_post_ids, draft warnings behavior, and the create-equivalent validation on promotion.

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

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

The opening sentence is correctly front-loaded with the core action and scope. The remainder is information-dense with little waste, but it is delivered as one long unbroken paragraph, which hurts scannability for a tool with this many conditional behaviors.

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 correctly takes on return-value disclosure: it names rescheduled_post_ids, the warnings array, and promoted_from_draft_id. Combined with the error code and quota/thread behavior, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100% and each parameter is richly documented, so the baseline is 3. The description still adds cross-parameter semantics the schema states only piecemeal: omitting schedule_at preserves the existing time and never publishes, publish and schedule_at are mutually exclusive, and draft:true alongside schedule_at changes only the remembered time.

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 plus a hard scope constraint: 'Edit a post that has not published yet, or finish a draft.' It clearly distinguishes the two modes (editing a queued post vs. finishing/promoting a draft) and reads differently from siblings like chirpie_post, chirpie_delete_post, or chirpie_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?

It gives explicit when-to-use and when-not-to-use conditions: a post can only be edited while still waiting to publish, and 'publishing, published, failed or deleted is refused with 409 post_not_editable.' It further spells out the mode-selecting conditions for schedule_at, draft:true, and publish:true, so the agent knows which parameters apply to which state.

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

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

Annotations only cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the description carries real weight here and delivers: type detection from the file's own bytes rather than name/declared type, a 7-day id lifetime, the fact that a post keeps its own byte copy so expiry is harmless, and the 3 MB data limit. These are exactly the non-obvious traits an agent needs before calling.

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

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

Purpose is front-loaded in the first sentence, followed by input modes, safety behavior, attachment guidance, and limits in a logical order. Every sentence carries distinct information and none repeats the structured fields verbatim.

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 must explain the return value, and it does (the id, its 7-day validity, how to attach it). Combined with lifetime, size limits, and the byte-copy guarantee, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description nevertheless adds meaning the schema lacks, notably the 3 MB ceiling on `data` and the rationale that the bound applies to the request, not the post. The `url`/`data` exclusivity and byte-sniffing behavior largely restate schema descriptions, so it sits above baseline but not at the top.

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 ('Upload an image or a video') and states the concrete outcome ('get back the id a post can attach'), which distinguishes it from the sibling post-creation tools it feeds. An agent can tell exactly what this tool produces without opening the schema.

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

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

It gives explicit when-to-use routing: supply either `url` or `data`, and it names the alternative path for large files ('attach a larger file with media_urls instead, which has no such limit'). It also names the three sibling tools (chirpie_post, chirpie_thread, chirpie_update_post) that consume the returned id, leaving nothing to inference.

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