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

Annotations only declare this is not read-only and not destructive, which is thin for a session/credential flow, and the description goes well beyond that: the token is entered on a local page and never passed through chat, cancel leaves saved accounts connected, and pending means the user has not yet finished. It stops short of stating failure/timeout behavior (e.g., what an expired URL returns) or any local-server prerequisite.

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?

Compact and mostly front-loaded, with the safety point (token never sent to chat) placed first where it matters. The action-by-action sentences read as a fragmented run-on with no visual separation between actions, so a scanning agent has to parse lines rather than bullets.

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?

An output schema exists, so return shape need not be described, yet the description still explains the meaningful states (connected includes the public profile, pending means waiting). What remains uncovered is the precondition for the whole flow — that a local page/server must be reachable — which an agent needs to interpret a failure.

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

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

Schema coverage is 0% and the enum values start/restart/cancel are bare in the schema, but the description defines each one: start opens a form or returns the current URL or result, restart opens a new form for another account or replacement token, cancel closes the form while preserving connected accounts. That is full compensation for the undocumented parameter.

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

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

The first sentence states a specific verb and resource (connect a Threads account) and adds the distinguishing mechanism (a local page, token never sent to chat). That immediately separates it from the entire sibling set of publish/list/insight tools, none of which touch account connection.

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 spelled out per action: show the URL to the user, call start again to poll, connected vs pending semantics, restart for another account or a replacement token, cancel to close the form. What is missing is any tie-in to the account-facing siblings such as threads_list_accounts, which an agent might otherwise reach for after connecting.

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=false, but the description goes well beyond: it discloses the permission requirement, the success criterion ('only after Meta acknowledges the exact deleted_id'), and the failure-mode protocol for timeout/cancellation/unknown outcomes. The warning that absence from one page of posts does not prove deletion is a non-obvious behavioral trait an agent could not infer.

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

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

Front-loaded with the action and its precondition, then layered constraints in short clauses. Every line conveys distinct operational information — permission, ID form, retry policy, verification protocol — with no restatement of the name or filler.

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

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

For a destructive two-parameter tool with an output schema, the description covers the risky parts an agent actually needs: authorization, identifier selection, success semantics, and post-failure verification. Return-value detail is correctly delegated to the output schema rather than duplicated.

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

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

Schema coverage is 0% and both parameters are bare $refs to a numeric ThreadsID pattern, so the description must carry the load. It does for post_id by ruling out container IDs, URLs and shortcodes, which is high-value disambiguation. It leaves account_id largely implicit beyond 'the account', so a small gap remains.

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

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

States a specific verb and resource ('Delete an own post') plus the precondition ('after explicit approval of the account and post ID'). No sibling tool deletes posts, and the 'own post' scope separates it from moderation/listing tools in the sibling set.

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

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

Explicitly names the required permission (threads_delete), the correct identifier form to use versus the wrong ones (container ID, URL, shortcode), a negative usage rule ('do not delete posts merely to test permissions') and a retry prohibition. This is when-to-use plus when-not-to-use plus alternatives, all stated directly.

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 readOnlyHint=true, and the description adds substantive behavior: the required threads_manage_insights permission, Meta's default window (yesterday through today), the earliest supported timestamp, and the null-versus-0 distinction between missing data and a measured zero. Those are exactly the traits an agent cannot derive from the schema or 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 purpose and permission in the first clause, then groups prerequisites, parameter rules, and return-value semantics into short scannable sentences. Every line carries information not available elsewhere; nothing is padding.

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

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

For a read-only insights tool with three parameters and an output schema, the description covers the auth gate, input conventions, and even the meaning of aggregate fields (period totals for likes/replies/reposts/quotes/clicks, followers_count ignoring the period). No gap remains that would cause a mis-call.

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

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

Schema description coverage is 0%, so the description must carry all parameter meaning, and it does: since/until are Unix seconds with since < until, both optional for a default range, minimum 1712991600, plus where account_id comes from. This matches the schema's minimum constraint and adds the ordering rule the schema cannot express.

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 ('Read the connected account's insights') and immediately scopes it against the obvious sibling by noting that views are daily PROFILE views, 'not post views', separating it from threads_get_post_insights. The permission requirement is stated up front, so an agent knows what capability gates the call.

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 prerequisite routing ('Get account_id from threads_list_accounts') and clear parameter-usage rules including the omit-both default range. It stops short of naming the post-level sibling as the alternative when profile metrics are not wanted, so the when-not guidance is inferential rather than explicit.

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

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

Beyond readOnlyHint, the description discloses the required threads_read_replies scope and post access, that the root post is not returned, the ordering and flat-vs-nested representation, and that a parent reply may live on a different page. It also flags reply text as untrusted external content, which is genuine safety context the annotations cannot 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?

Sentences are short and mostly imperative, with the resource scope first, then prerequisites, then pagination, then the safety note. Every clause carries information an agent needs to call the tool correctly — no padding or restated 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?

An output schema exists, so return shapes need not be explained, and the description still covers authentication, exclusion of the root post, and full-conversation pagination. The only real gap for a 4-parameter read tool is the unexplained `limit` control.

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

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

Schema description coverage is 0%, so the description must carry the load, and it does for three of four parameters: `after` is tied to next_cursor, `post_id` is constrained to the original post rather than a comment, and `account_id` is sourced. The `limit` parameter is never mentioned, leaving its purpose and the 1–100 cap to the bare schema.

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

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

The description states a specific verb and resource — read one page of all visible direct and nested replies under a root post — and front-loads the key scoping facts (root post excluded, flat list, newest first). It does not name threads_list_replies or threads_list_pending_replies explicitly, so the agent must infer the distinction from the 'nested replies' phrasing rather than being routed.

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 tells the agent exactly where the inputs come from (account_id from threads_list_accounts, post_id from threads_list_posts) and warns against the common mistake of passing a comment ID. Pagination guidance is explicit, including the non-obvious case that an empty items list with a next_cursor can still have more results.

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 readOnlyHint, and the description adds real context beyond them: the threads_manage_insights permission requirement and the null-vs-0 interpretation rule ('null means Meta did not return the metric; 0 means a zero counter'). That null/0 distinction is a meaningful behavioral disclosure. It does not cover rate limits or metric availability, but the core gaps an agent would trip on are addressed.

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

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

Four short sentences, all front-loaded: purpose first, then parameter sourcing, then the permission gate, then the result-interpretation caveat. No filler or restated field names.

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 read tool with an output schema, everything needed is present: what it reads, how to obtain both required IDs, the auth requirement, and how to read null versus zero values. Nothing essential to a correct call 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 0%, so the description must compensate, and it does: it tells the agent exactly where each of the two parameters comes from (threads_list_accounts for account_id, the id field of a listed post for post_id). It does not restate the numeric-string format enforced by the schema pattern, but provenance is the more valuable missing piece and it is 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?

The description opens with a specific verb+resource ('Read insights') scoped to 'one of the connected account's own Threads posts', which implicitly separates it from threads_get_account_insights. It does not name the sibling explicitly, so differentiation is clear but not spelled out.

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

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

It gives concrete provenance for both inputs ('Get account_id from threads_list_accounts', 'post_id from the id field of a post returned by threads_list_posts') and states the required permission threads_manage_insights. It stops short of explicit when-not guidance, such as directing the agent to threads_get_account_insights for account-level metrics.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds that the account must be a 'connected' one, which is useful context, but says nothing about what happens with an unconnected or invalid account ID.

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

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

A single front-loaded sentence with no filler. It earns its place, though it is arguably too sparse for a tool whose parameter is undocumented in the schema.

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

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

An output schema exists, so return values need not be described, and the tool is a simple one-parameter read. Still, the description leaves the sourcing of account_id and the failure mode for a non-connected account 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 0%, and the only parameter is an opaque numeric string reference. The description compensates slightly by calling it a 'connected account ID', implying the value comes from the connection flow, but adds no format or sourcing detail beyond that.

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

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

States a specific verb and resource ('Read your Threads profile'), which cleanly separates it from the sibling tools that publish, delete, list, or read insights. It does not name a sibling to distinguish against, but the operation is unambiguous.

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

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

Usage is only implied: an agent infers this is the way to fetch the authenticated user's profile. There is no explicit guidance on when to prefer it, or on prerequisites such as the account needing to have been connected first via threads_connect.

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

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

The readOnlyHint annotation already establishes safety. The description adds behavior-specific context by saying secrets are excluded and by explaining that expires_at is a Unix timestamp where null means unknown; that is meaningful beyond the annotation, though it does not discuss auth or pagination.

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

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

Three short sentences are front-loaded with the core output, then usage, then a field clarification. Every sentence earns its place and there is no redundant wording.

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

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

The tool has no inputs, an output schema, and a readOnlyHint annotation. The description supplies the essential purpose, routing context, and expiry-field meaning, which is sufficient for an agent to invoke it correctly.

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

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

The tool has zero parameters, so there are no parameter semantics to clarify. The baseline for a no-parameter tool is 4, and the description does not need to add anything about 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 description states a specific verb and resource: list connected Threads accounts with IDs and token expiry, excluding secrets. It also names the sibling threads_get_profile as the downstream consumer of account_id, so an agent can distinguish this discovery tool from profile retrieval.

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

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

It gives a clear usage context: use after startup to find account_id for threads_get_profile. It does not state explicit exclusions or when to avoid it, which keeps it short of a 5, but the routing guidance is concrete.

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?

readOnlyHint=true already establishes the safety profile, and the description still adds genuine context: an auth scope requirement (threads_read_replies), the approvals-enabled precondition, the pagination loop ('pass next_cursor as after until it is null'), the empty-page-with-cursor edge case, and an explicit prompt-injection warning about reply text.

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 purpose then preconditions, prerequisites, and pagination in a logical order; nearly every sentence earns its place. Minor cost: the enable_reply_approvals reference names a parameter belonging to a publish sibling, which briefly muddies an otherwise tight read.

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 an output schema present, return-value documentation is unnecessary, and the description instead covers the things the schema cannot: auth scope, the approvals precondition, the pagination termination rule, and injection safety. 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 0%, so the description carries the burden, and it does for post_id (numeric parent post ID), approval_status (omit for both states, or pending/ignored), and after (next_cursor until null). account_id and limit are left unexplained, which prevents a 5 given the complete absence of schema documentation.

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

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

Opens with a specific verb and resource: 'Read one page of pending/ignored replies under an own post with reply approvals.' The scope qualifiers (own post, reply approvals) plus the cited sibling threads_moderate_reply make it distinguishable from threads_list_replies without opening either schema.

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

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

Gives explicit preconditions ('The parent must have reply approvals enabled; an ordinary post is not an empty approval queue'), explicit fallbacks ('choose another post or use enable_reply_approvals=true'), the value-fork for approval_status, and a hard rule that the sibling threads_moderate_reply is only used after user approval.

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 readOnlyHint=true; the description adds real behavioral context beyond that, notably that an empty items array is not proof of the end of the list, and that reposts surface with media_type=REPOST_FACADE. It does not cover rate limits, ordering, or per-post visibility filtering, which keeps it below 5.

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

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

Front-loaded with the core action, then ordered as prerequisites, pagination, exclusions, and return-field quirks. Every sentence carries operational information; nothing is 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?

An output schema exists, so the description need not explain full return shapes, yet it still flags the tricky fields and the paging termination rule that an agent would otherwise get wrong. Gaps are minor: no limit-tuning advice and no statement about ordering or date filtering.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning and it largely does: account_id's source is given, and after is tied to next_cursor with its null-termination semantics explained. limit is never discussed in prose, though its bounds and default are still structurally visible 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?

A specific verb and resource with scope stated: reading one page of the connected account's *own* posts, plus an explicit exclusion ('Replies to other people's posts are not included'). It distinguishes the tool from the reply-listing siblings by scope, but never names the sibling to use instead, so it stops just 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?

Gives a clear precondition ('Get account_id from threads_list_accounts') and a concrete paging loop: pass the previous response's next_cursor as after, with null marking the end. It does not name alternative tools for conversation or replies, so the when-not side is implied by the exclusion 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 past readOnlyHint=true by disclosing the required scope (threads_read_replies plus access to the post), the pagination invariant ('null means no more pages', plus the edge case where an empty items list still carries a next_cursor), and an explicit prompt-injection warning about reply text. That is substantive behavioral context the annotations cannot 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 with the core action, then prerequisites, then the two non-obvious behaviors (recursion and pagination), then the safety note. Multi-line but every sentence carries distinct information with no restatement of the name or schema.

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

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

For a read-only listing tool with an output schema, the description covers everything an agent needs: auth requirements, ID sourcing, recursion strategy, pagination termination rule, and content-trust handling. The only omission, the limit bound, is available in the schema itself.

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

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

Schema description coverage is 0%, so the description must carry the load; it explains the provenance and format of account_id and post_id and clarifies that next_cursor is passed as 'after'. The 'limit' parameter (default 20, max 100) is never mentioned, leaving one of four parameters undocumented in both schema and description.

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

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

States a specific verb and resource with explicit scope: 'Read one page of direct replies under a Threads post or reply.' The qualifiers 'one page' and 'direct replies' pre-empt confusion with conversation/thread traversal and with pending-reply moderation 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?

Gives prerequisite sourcing for both required IDs ('Get account_id from threads_list_accounts and post_id from threads_list_posts'), states the permission needed, and explains exactly how to descend into nested replies via has_replies and how to continue paging via next_cursor.

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 flag this as destructive, non-idempotent and not read-only; the description goes further by disclosing that hide/unhide cascades to nested replies, that ignored replies remain approvable, and that it returns only a confirmed acknowledgement. The recovery guidance for timeout/cancellation/unknown outcome and the warning that absence from one page is not proof of approval are exactly the behavioral context an agent needs before retrying.

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 single most important constraint — explicit approval — is front-loaded in the first sentence, and each following sentence carries operational weight rather than filler. It is dense and slightly run-on across many short clauses, but nothing is clearly expendable.

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, non-idempotent moderation tool the description covers prerequisites, permission requirements (threads_manage_replies), scope of effect, where to obtain inputs, failure/retry policy, and confirmation semantics. With an output schema present, the brief acknowledgement note is sufficient return-value coverage.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning; it does explain the behavior of each operation value (hide/unhide cascade scope, approve/ignore lifecycle), which the bare enum does not. However, it never names or characterizes account_id or reply_id beyond the precondition phrasing, so two of three required parameters gain only indirect meaning.

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 (moderate) and resource (a reply) plus the hard precondition of explicit approval of account, reply and operation. The operation set (hide/unhide/approve/ignore) is spelled out, which cleanly separates it from the read-only siblings threads_list_replies and threads_list_pending_replies.

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

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

Explicit routing: get the target from threads_list_replies, and use approve/ignore only for items surfaced by threads_list_pending_replies. It also names exclusions — do not use this tool to test permissions, do not retry automatically — and states that nested replies cannot be hidden individually.

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 it discloses the required scope (threads_content_publish), the two-phase child/parent upload model, minimum ~60s processing time, that URLs and caption are transmitted unchanged, and that the result is non-idempotent with explicit duplicate-avoidance guidance after ambiguous failures. This is materially more than readOnlyHint/idempotentHint provide.

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

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

Front-loaded with the action and constraints, then prerequisites, then failure recovery. Every sentence carries operational weight, though 'This action is not idempotent' restates idempotentHint=false and the timeout sentence partially overlaps it.

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

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

For a mutating, non-idempotent publish tool with 3 parameters, the definition covers authorization scope, input validation, latency, return value, and failure recovery. The output schema handles the return shape, so nothing an agent needs before calling 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 0%, so the description must compensate and largely does: it explains image_url must be publicly reachable HTTP(S), alt_text caps at 1000 characters, and text is a single optional caption passed through verbatim. Only account_id is left unexplained, and the image ordering semantics (user-approved order maps to array order) are implied rather than stated.

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

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

States a specific verb and resource with hard constraints: 'Publish 2 to 20 images ... with one optional caption.' The 2-20 range implicitly distinguishes it from threads_publish_image (single image) and the carousel children/parent mechanics make the multi-image scope unambiguous.

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

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

Gives an explicit precondition ('Use only after explicit approval of the account, images, order and caption'), names an exclusion set (videos, local files), and routes the agent to threads_list_posts after a timeout or unknown outcome. That is when-to-use, when-not-to-use, and an alternative, all present.

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: discloses the required OAuth scope, the hard constraint that Meta fetches image_url from a public HTTP(S) server, ~30 seconds of processing latency, pass-through of URL/caption/alt_text without transformation, and post_id as the confirmed return. The non-idempotency note reinforces idempotentHint=false with actionable recovery guidance (check threads_list_posts after timeout/cancel/unknown outcome).

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 the approval precondition, then moves through constraints, side effects and recovery in a logical order. Every sentence carries operational information; nothing is padding, and the short 'Processing takes about 30 seconds' / 'This action is not idempotent' lines are deliberately scannable.

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-shot publishing mutation with an output schema, the description covers the gaps structured fields cannot: auth scope, external URL fetchability, latency, non-idempotency and duplicate-avoidance workflow. An agent has everything needed to decide, call, and safely recover.

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 0% schema description coverage the description must carry the load, and it does add real meaning: image_url must point at a public server fetched by Meta, and caption/alt_text are optional and sent unchanged. It does not explain account_id (the ThreadsID pattern reference) or note the 500/1000 character caps, and it calls the 'text' parameter 'caption', leaving a small naming mismatch for the agent to resolve.

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 ('Publish one image') plus an explicit cardinality constraint ('one image only'), which separates it cleanly from threads_publish_carousel, threads_publish_text and threads_quote_post. The precondition clause ('only after the user approves the account, image and caption') further pins down the exact 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?

Gives when-to-use (after user approval of account, image and caption), an explicit when-not ('Do not use this tool to test access'), and a named fallback for the ambiguous-outcome case: check threads_list_posts before retrying. The external prerequisite (threads_content_publish scope) is also 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?

Well beyond what the annotations declare: permission requirements (threads_content_publish, plus threads_manage_replies and reply_to_id access for replies), external platform limits (five unique links, no attachment link when the main post already links), ~30 second processing time, and explicit post-timeout recovery via threads_list_posts/threads_list_replies with a no-auto-retry rule. The non-idempotency is already in annotations but is reinforced with concrete recovery steps rather than merely repeated.

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

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

Front-loaded with the action, then constraints, permissions, approval gate and retry policy in a scannable order; nearly every line carries operational value. Minor redundancy in restating the link limits then adding 'Meta enforces these limits.'

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

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

For a non-idempotent, permission-gated publishing action with seven parameters and no schema descriptions, the definition covers inputs, platform limits, auth, approval gate, latency and failure recovery. Return values are not needed since an output schema exists.

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

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

Schema coverage is 0%, so the description must carry the load: it documents character bounds for text and attachment_text, that link_url must be HTTP(S) and is sent unchanged, that only plain text is supported, and the semantics of reply_to_id and the reply settings. It leaves account_id and the allowed reply_control enum values unexplained, which the schema's enum does supply for the latter but not the former.

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: publishing a short approved text preview paired with a long-text attachment, which implicitly separates it from the plain threads_publish_text and the media publishers. It never names the sibling it differs from, so the differentiation is inferred rather than explicit.

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

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

Gives explicit when-to-use conditions for each optional behavior: omit reply_to_id for a new post, use reply_control/enable_reply_approvals only when the user requests them, and publish only after explicit approval of account, texts, link and reply target. It also names when not to use it ('Do not use this tool to test access') and what to do after an uncertain outcome.

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: discloses the required permission (threads_content_publish), the ~30 second container processing latency, that text is transmitted unchanged with possible Meta emoji/link limits, and that post_id is returned only after confirmed publication. It also reinforces non-idempotency declared in annotations with concrete failure handling for timeout/cancellation/unknown outcomes.

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 purpose, then ordered into permission, constraints, timing, return, and recovery guidance — an agent can scan it quickly. A few lines restate schema facts (non-blank, 500 characters) and the emoji/link caveat could be folded into the length sentence, so it is slightly longer than strictly necessary.

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

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

For a non-idempotent mutation with an output schema, the definition covers permissions, latency, cost of duplicates, retry protocol, and prerequisite tooling. Nothing an agent needs to call it safely is missing, and return values are appropriately left to the 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 0%, so the description must carry parameter meaning and it largely does: account_id's source, text's non-blank/500-char limits and unchanged transmission, and a conditional-use rule for reply_control and enable_reply_approvals. It stops short of explaining what each reply_control value means or how reply approvals interact with reply_control, leaving the enum semantics to the schema alone.

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

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

States a specific verb and resource ('Publish a text-only Threads post') plus the scope qualifier 'for the selected connected account'. The 'text-only' qualifier cleanly separates it from siblings like threads_publish_long_text, threads_publish_image, and threads_publish_carousel.

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

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

Explicitly states when to use it ('only when the user explicitly requested publication on Threads and approved the exact text and account') and when not to ('Never publish to test permissions'). It also names the prerequisite tool for account_id (threads_list_accounts) and the recovery path after an ambiguous outcome (threads_list_posts).

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

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

Annotations already declare readOnlyHint=false and idempotentHint=false, but the description goes further: ~30 second processing latency, text sent unchanged, permission scope required, and a duplicate-publication hazard with a named inspection step on timeout or unknown outcome. The only minor gap is that the 'approval' gate is not explained operationally, leaving the agent unsure how approval is signalled.

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

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

Every sentence carries a distinct constraint or hazard, and the most important gate (approval/prerequisites) is front-loaded ahead of formatting limits and retry procedure. No filler or restatement of the schema.

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

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

An output schema exists, so return values need no prose. Prerequisites, latency, non-idempotency and retry safety are all covered; the residual ambiguity is what 'approval of the account, original post and text' means and how an agent verifies it before calling.

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

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

Schema description coverage is 0%, so the description carries the load, and it does: post_id is constrained to the numeric media ID and explicitly not a URL or shortcode, and text must be non-blank and at most 500 characters. account_id is only indirectly characterized via the approval/permission sentence, so it is not fully covered.

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: 'Publish a text quote', and the qualifier 'after approval of the account, original post and text' narrows the case. It is reasonably distinguishable from threads_publish_text and threads_repost, though it never explicitly contrasts itself with those two closest 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 prerequisites ('Requires threads_content_publish and access to the original'), an explicit prohibition ('Do not use this tool to test permissions'), and a concrete recovery path naming the sibling threads_list_posts and the field quoted_post.id before retrying. That is when/when-not/alternative coverage in one paragraph.

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, but the description adds substantial context beyond them: required scopes, permission differences between own and others' root posts, ~30s processing latency, non-idempotency with a concrete recovery procedure, and a prompt-injection caution about other users' comments.

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

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

Front-loaded with the action, then preconditions, ID sourcing, permissions, constraints, and retry guidance in a logical order. Slightly long and restates the character limit already in the schema, but nearly 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 non-idempotent publish tool with three required parameters and no schema descriptions, the description covers authorization, ID provenance, constraints, latency, return value (post_id), and failure recovery. An output schema exists, yet the return mention is brief and not redundant.

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

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

Schema description coverage is 0%, so the description must carry the burden, and it does: it explains where account_id and reply_to_id come from, the semantic distinction between a comment id and a root post id, and that text is sent unchanged. The 500-char and non-blank constraints duplicate the schema slightly but add the 'sent unchanged' nuance.

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 ('Publish a text reply to a specific Threads post or comment') and is immediately distinguishable from siblings like threads_publish_text, threads_quote_post, and threads_repost by naming the reply target.

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

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

Explicit preconditions ('only after the user explicitly approved the exact reply text, target, and account'), explicit ID sourcing (threads_list_accounts, threads_list_posts, threads_list_replies), and an explicit disambiguation rule: use the comment's id, not its root post's id.

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

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

Beyond the annotations it discloses the required permission scope (threads_content_publish), that publishing is immediate with no container step, and a full failure-recovery procedure for a non-idempotent write. It restates non-idempotency already flagged by idempotentHint, but the added auth and recovery detail is substantial context the annotations do not 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?

Front-loaded with purpose, then preconditions, parameter note, return value, and recovery guidance in a logical sequence with no filler. The recovery sentence is long and mentions an internal artifact name ('container', 'REPOST_FACADE') that is dense but functional rather than wasteful.

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

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

An output schema exists, so return detail is largely free, yet the description still names the returned repost ID. For a non-idempotent mutation with two required IDs, it supplies the permission requirement, the ID format, and the retry-safety procedure — everything an agent needs to call it without causing duplicates.

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

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

Schema coverage is 0%, so the description must compensate. It fully pins down post_id ('numeric media ID, not a URL or shortcode'), which is exactly the ambiguity the bare string pattern leaves open, and hints at account_id via 'explicit approval of the account', though it never states what account_id identifies or whether it must match the authenticated account.

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 (repost a post) and immediately scopes it with 'accessible post' and the approval precondition. The clause distinguishing post_id from a URL or shortcode plus the contrast with quote/reply siblings makes the operation unambiguous.

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

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

Gives explicit preconditions ('after explicit approval of the account and original'), a stated exclusion ('Do not use it to test access'), and a concrete recovery path after an unknown outcome (check threads_list_posts for REPOST_FACADE or the Reposts tab before retrying). That is when-to-use, when-not, and what-to-do-on-failure in one place.

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