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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the enumerated provider set returned, the four job categories each model is assigned to, and the privacy guarantee that keys are never shown — which matters because an agent might otherwise ask for credentials. It stops short of describing the response shape per provider.

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 the resource and scope front-loaded, plus one short clause on key privacy. The provider enumeration is long but earns its place by setting expectations for the return value. Nothing is redundant.

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 parameters, no output schema, and annotations already covering the read-only nature, the remaining burden is describing what the call reveals. The description covers providers, per-job model assignment, and the key-redaction guarantee, which is sufficient for an agent to call it and interpret the result, though it omits any hint about the response structure or how unconfigured jobs are reported.

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 parameterless tool applies. The description correctly does not fabricate options and instead spends its words on return content.

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

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

The description uses a concrete interrogative framing — reporting which AI providers are connected and which model each job (text, vision, image, transcribe) uses — and enumerates the providers, so the agent knows exactly what comes back. It does not name the sibling it complements, set_ai_models, so the read-vs-configure distinction is only implied by the word 'status'.

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

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

There is no explicit when-to-use sentence, no prerequisites, and no pointer to set_ai_models as the tool for changing the configuration. Usage is only implied: an agent can infer this is the read-only configuration inventory, but it must make that inference itself.

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 behavior: the comparison is scoped to same-format recent posts, and the returned payload changes shape depending on whether an AI provider is configured (diagnosis + next steps vs. a plain brief). That conditional output behavior is exactly what an agent needs and is not derivable from the annotations. It omits rate limits and the fact that account context/auth must be in place.

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 that leads with the comparison being made, then the metric list, then the AI-dependent output contract. The colon-and-list construction is dense but earns its words. Slightly long for one sentence; could be split for scanability.

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

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

With no output schema, the description usefully enumerates the return payload and its conditional AI branch, which is the main complexity here. Four params with only 50% coverage and no mention of account selection or the baseline_posts meaning leaves a small gap, but an agent could call this correctly from the description plus schema.

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

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

Schema coverage is 50%: account and diagnose are documented in-schema, while media_id and baseline_posts carry no description. The description partially compensates by explaining that comparison is against 'your own recent posts' (implying the baseline concept) and by tying the AI provider to the diagnose flag, but it never states what baseline_posts controls or what happens if media_id points to a different format. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: per-post (reel/story) performance measured against the account's own recent posts of the same format, and it enumerates the concrete metrics (outlier score, engagement rate, saves+shares per viewer, watch time, skip rate). That is far more than a restatement of the name. It stops short of naming the siblings it competes with (get_media_insights, find_outliers), so sibling differentiation is implied but not stated.

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 prescribed: the reader can infer this is for judging one specific post relative to the account's baseline. There is no explicit when-to-use, no 'use find_outliers instead for a set of posts' exclusion, and no mention that it requires a connected account. The AI-provider-vs-not sentence is behavioral, not a routing cue.

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 and closed-world, so safety is covered. The description adds real value beyond that by disclosing the scope of what is inspected: app configuration, per-account sign-in health, default account, login type, media host, AI providers, and Meta API usage. It does not describe the response shape, but as a read-only probe the behavioral picture is adequate.

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

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

One dense sentence enumerating report contents, followed by a short imperative directing first use. The enumeration is long but each item is a distinct diagnostic field, so it earns its place. The directive is front-loaded at the end where it is most visible.

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 explaining what comes back, and it does so by naming each reported facet. Nothing an agent needs in order to decide to call it first is missing; only the exact response structure remains unspecified, which is a minor gap for a status probe.

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 no parameters, so there is no parameter semantics to document; baseline 4 applies. The description correctly implies a no-argument, always-callable diagnostic.

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 ('Show whether the Meta app is configured, which Instagram accounts are connected') and enumerates the concrete states it reports. It is clearly distinguishable from siblings like ai_status, media_host_status, and list_accounts because it aggregates configuration/health rather than listing or mutating anything.

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

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

It gives an explicit sequencing rule: 'Call this first in a new conversation.' That is strong, actionable guidance for an agent at the start of a session. It does not state when-not-to-use it or name alternatives, which keeps it just below 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 readOnly/openWorld/idempotent, so the description needn't restate safety. It adds genuinely useful behavior: only PUBLIC stats are retrievable, the target must be a Business or Creator account, and the source is Meta's Business Discovery API (implying authorization requirements on the connecting account). It stops short of mentioning rate limits or failure modes for ineligible targets.

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 dense sentence front-loads the resource and metric list, followed by a short routing sentence and a constraint. No filler, though the metric enumeration is a packed run-on that is slightly harder to scan than a structured list.

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 well by naming the metric families returned. For a 3-parameter read tool this is close to complete; only the `posts` sampling parameter and error behavior on ineligible accounts are left to inference.

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

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

Schema coverage is 67%: `account` and `username` are documented in the schema, so the description earns no credit by repeating 'their @username'. The one undocumented parameter, `posts` (default 30, range 5–100), is never explained in the description — an agent gets no hint that this controls the sample window behind the medians. Baseline 3 for partial coverage.

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

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

The description names the exact mechanism (Meta's Business Discovery) and enumerates the returned metrics — followers, posting frequency, format mix, median likes/comments/views, engagement per follower, top hashtags, top posts — so an agent knows precisely what 'benchmark' means here. It also distinguishes itself from get_account_insights by framing this as competitor/public data versus 'your own'.

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 explicitly routes the complementary action to get_account_insights and states a hard eligibility constraint ('Facebook Login accounts only'), plus the target restriction to Business or Creator accounts. It lacks explicit when-not guidance (e.g. what happens for personal accounts) but the context is clear enough to select the 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 read-only, idempotent, non-destructive, so the bar is lower. The description still earns credit for disclosing methodology ('each post scored against your median, so one viral post does not decide') and for warning that follower-online data is conditional on Meta providing it. It does not state the lookback window or what happens with sparse data.

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

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

One front-loaded sentence with no filler; the qualifying parenthetical is the most useful part. The nested clause about follower data makes it slightly dense but nothing 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 and 40% parameter coverage, the description should explain the result shape more explicitly, e.g., a ranked list of weekday/time blocks with scores. It conveys the grain but not the return structure or how metric choice affects results, leaving gaps for a 5-param analytic 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 coverage is 40%, so the description must carry weight. It clarifies the time zone meaning ('in your time zone') and the output granularity, but adds nothing about the three undocumented parameters: the FEED/REELS type, the posts count window, or the metric enum 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?

States a specific verb/resource pairing: it reports when your own posts performed best, broken down by weekday and 3-hour block. The parenthetical about median-scoring makes the output unit concrete. It does not name the sibling insight tools it differs from (get_account_insights, get_audience), 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 only implied: the 'your own posts' framing hints this is a self-performance tool rather than a follower-activity tool, but there is no explicit when-to-use, when-not-to-use, or named alternative. An agent must infer that this is the scheduling/optimization tool rather than a general insights 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 destructiveHint=true, and the description goes beyond that by qualifying the destruction (hosted copies are removed) and stating reversibility via resume_publish, plus a user-confirmation requirement. It does not cover authorization scope or what the response contains, keeping it short of a 5.

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

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

Three short sentences, front-loaded with the core action and scope, followed by consequence, reversibility, and prerequisite. No sentence is redundant or restates 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 two-parameter mutation with annotations already covering the destructive profile, the description supplies the missing pieces an agent needs: what state qualifies, what is removed, and how to undo it. The only omission is the return behavior, which is minor for a cancel operation and there is no output schema to lean on.

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 50%: confirmation_token is documented in the schema, and the description reinforces its purpose by saying the user's confirmation is required. However, job_id is undocumented in both places, and the description never clarifies that it is the publish job identifier rather than a media id.

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

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

The description opens with a specific verb+resource ("Stop a post") and immediately narrows the scope to unpublished states (scheduled, waiting, in progress). That scope statement distinguishes it from siblings like delete_media or reschedule without the agent needing to open any schema.

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

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

It states the applicable condition (post not yet published) and names the recovery path (resume_publish) plus a prerequisite (user confirmation). It stops short of explicitly contrasting with reschedule or delete_media, so the agent must infer those exclusions from the scope wording.

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 and openWorldHint=false, and the description is consistent with them. It adds genuinely useful behavior detail beyond the annotations: the concrete thresholds enforced (2,200 chars, 30 hashtags, 20 mentions) and that the preview applies the template with publish-time fidelity, though it says nothing about what the check returns on failure.

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

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

A single dense sentence that front-loads the validation behavior before the preview behavior, with no filler. The parenthetical limit list is efficient, though the sentence is long enough that the preview capability could be separated for scannability.

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

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

For a simple read-only two-parameter tool the inputs are adequately framed, but with no output schema the description should say what a check yields (violation list? pass/fail? rendered preview string) and what happens if template is absent. Those gaps matter because the tool's whole value is in its result.

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% for two parameters, so the description must carry the load. It clarifies the optional template parameter's effect ('applied exactly as it will be published') but never states what happens when template is omitted, nor any caption format/length expectations beyond the limit itself.

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 ('Checks') plus a specific resource ('a caption') and enumerates the exact rule sets applied (Instagram limits, craft rules) and the preview behavior. An agent can distinguish it from generate_caption or critique_cover 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?

Usage is only implied: 'previews it ... exactly as it will be published' suggests a pre-publish validation step, but the description never says when to call this versus generate_caption or critique_cover, nor any preconditions (e.g. must a template exist first).

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false and destructiveHint=false, and 'Public' merely restates openWorldHint. The genuinely additive piece is 'the user confirms first', which explains the confirmation_token gate and that the action is user-approved. Missing: what happens if the confirmation is omitted, whether comments can be edited or removed afterward, and any rate-limit behavior.

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

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

A single short sentence with the action front-loaded and no redundant restatement of the name. The trailing parenthetical is the one low-value element and could be dropped without loss.

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

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

For a public, non-idempotent write operation with no output schema and two undocumented parameters, the description covers the core action and the confirmation requirement but leaves error handling, the full confirmation handshake, and the meaning of media_id/message to be inferred. Adequate but with clear gaps.

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

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

Schema coverage is 50%: 'account' and 'confirmation_token' are documented in the schema, while 'media_id' and 'message' are bare. The description partially compensates by framing 'on one of your posts' (scoping media_id to the user's own media) and 'the user confirms first' (explaining the token), but adds nothing about the message content limits or formatting.

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 ('Add a new top-level comment'), and the word 'top-level' implicitly distinguishes it from the reply_to_comment sibling. The parenthetical '(e.g. a pinned-style note or first comment)' is vague and adds ambiguity rather than precision, and no sibling is named outright.

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?

'Public; the user confirms first.' conveys an important precondition for invoking the tool, which is real usage guidance. However, it never states when to use this versus reply_to_comment or private_reply, and it doesn't explain the two-step confirmation flow (call, then re-call with the token) beyond what the parameter description hints at.

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 that this writes state (readOnlyHint=false) and reaches an external service (openWorldHint=true), so the safety profile is covered. The description usefully frames the tool as an OAuth recovery path rather than a primary sign-in, but says nothing about code/state expiry, failure modes, or what happens to an already-connected account.

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 action, followed by the disambiguating usage condition. No restated boilerplate and nothing extraneous to trim.

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

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

For a one-parameter tool with annotations and no output schema, the definition covers what to supply and when. It stops short of describing the outcome (e.g. account now listed by list_accounts) or what an invalid/expired callback URL produces, which would fully close the loop.

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 by noting the URL 'contains ?code=...&state=...', signalling that the query string must be preserved intact and not truncated. That goes beyond the schema's 'full address-bar URL after approving, starting with http'.

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 ('Finish a connect_account sign-in') and ties it to a concrete input ('the full URL the browser landed on after approving'), naming the sibling connect_account whose flow it completes. An agent can distinguish it from connect_account and auth_status 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 trigger conditions: the callback page did not load, or sign-in happened on another device. That is a clear when-to-use, though it does not explicitly state that a normal flow should just use connect_account's own callback, leaving the alternative implied by naming connect_account.

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 mark this as a non-read-only, open-world, non-destructive operation. The description adds substantial context beyond that: it opens a browser on the local machine, returns a sign-in link, connects every Facebook Page-linked Instagram account the user selects, waits up to wait_seconds, and describes the manual fallback when a page fails to load.

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

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

The description is front-loaded with the main action and then layers in the Facebook Login behavior, waiting, and fallback. Every sentence carries useful information, though the final sentence is longer and could be split for easier parsing.

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

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

For a two-parameter tool with no output schema, the description covers the important behavioral facts an agent needs: what starts, what the user sees, what gets connected, how long it waits, and what to do if the browser page fails. Nothing essential to invoking it correctly appears to be 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 50%: wait_seconds is documented in the schema, while open_browser is not. The description adds meaning to wait_seconds by explaining that the tool waits for the user to finish signing in, and it implies browser opening, but it never states what open_browser=false does, leaving part of the parameter semantics unaddressed.

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: starts the Meta sign-in to connect (or reconnect) Instagram professional accounts. It distinguishes the operation from sibling complete_connect by describing the fallback path, making it clear this tool begins the flow rather than completes it.

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

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

Explicitly says when to use it (connecting or reconnecting professional accounts) and gives the exact condition for switching to complete_connect: when the browser lands on a page that does not load. It does not state prerequisites such as checking auth_status first or when not to reconnect, which keeps it below 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 only declare readOnlyHint and openWorldHint, so the description carries the interesting part: behavior branches on whether an AI model is configured, yielding either structured ideas with format/hook/angle/evidence/confidence or raw data to reason from. That two-mode disclosure is genuinely useful and not present in structured fields. It stops short of noting pagination, volume limits, or what happens with sparse account history.

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

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

Roughly one dense sentence, front-loaded with the purpose before the AI/non-AI branch. Nearly every clause earns its place, though the AI-vs-raw-data clause runs long and could be split for scanability.

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 does the right work by sketching the return shape (format, hook, angle, evidence, confidence) and flagging the degraded non-AI mode. The remaining gap is the undocumented 'template' parameter and the size of the performance lookback, which an agent would want 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 coverage is only 40%, so the description needs to compensate and largely does not. It explains 'focus' as an optional topic and hints that performance is drawn from recent posts, but leaves 'count', 'posts' (the lookback window size) and especially 'template' entirely undefined 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?

The description names a specific output (next post ideas), the grounding signal (this account's recent performance, formats and topics scored against the account's median), and an optional narrowing (a topic). This is clearly separable from siblings like analyze_post or find_outliers, which diagnose past performance rather than propose future posts.

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

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

Usage is implied by 'next post ideas' and by the optional focus parameter, so an agent can infer when to reach for it. However, it never states when not to use it or names a sibling alternative (e.g. hashtag_research, generate_caption) for adjacent needs, leaving routing to inference.

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

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

Substantially exceeds the annotations: it discloses that each version consumes the publishing limit, that trial reels are shown to non-followers first, that a background service evaluates after decide_after_hours, and that a winning version may be auto-republished. It also states a hard platform limitation (Meta's API cannot graduate trial reels) and the confirmation_token prerequisite, which are exactly the behavioral facts an agent needs before calling a write 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?

Front-loaded with the core purpose, then layered with behavior, lifecycle, and constraints in a logical order. Every sentence carries information, though the trailing fragment "Asks the user first" is tersely attached rather than integrated.

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 an 11-parameter publishing tool with no output schema, the description covers the preconditions, side effects, post-publish lifecycle, and the result (winner or "inconclusive"). Minor gaps remain around staggered publishing and what the immediate call returns, but nothing critical to a correct invocation 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?

With 64% schema coverage, the description fills key gaps: it gives the decide_after_hours default and range (48, 12-168), explains the practical consequence of share_winner "republish", and clarifies what a variant represents (hook, cut, caption, cover). It does not touch stagger_minutes, template, publish_at, hypothesis, or account, leaving those to 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 and resource (publishes reel variants as trial reels) and constrains the count (2-4 versions). It is distinguishable from the sibling publish_reel, publish_trial_reel, and get_ab_test without opening any schema.

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

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

It explains the situation the tool is for (testing hook/cut/caption/cover differences without spamming followers) and constrains the setup ("Versions should differ in one thing"). It also flags the approval gate ("Asks the user first"). It stops short of naming an explicit alternative such as publish_trial_reel for a single trial or list_ab_tests for monitoring.

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 openWorldHint; the description adds real behavioral context: the 1-4 scoring scale, dual evaluation contexts (full-screen reels feed vs. small grid tile), that output is ranked with concrete fixes, and that an external vision model is required. It stops short of noting model-dependent cost, latency, or failure behavior when no model is configured.

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

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

Two sentences, no filler, with the core action and evaluation criteria front-loaded and the prerequisite model requirement trailing as a constraint. Every clause carries information an agent needs.

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

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

With no output schema, the description usefully sketches the return shape (per-item 1-4 scores, a ranking, and a list of fixes). Only the input-mode interaction between image_paths and video_path is left unspecified for a tool whose whole value depends on which candidates get scored.

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

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

Schema coverage is 67% and image_paths has no schema description at all; the description compensates partly by explaining the '1-4 images or 4 video frames' candidate concept. It does not clarify the relationship between image_paths and video_path (mutually exclusive alternatives?) or what happens if both are 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?

States a specific verb and resource ('Scores ... cover images', or 4 frames from a video), plus the outcome ('Ranks them and lists fixes'). No sibling tool in the list does cover judging, so it is distinguishable at a glance.

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 can infer this is a pre-publish candidate-selection step, but the description never says when to call it or what to use instead (e.g., analyze_post for post-hoc analysis). The one genuinely useful constraint, 'Needs a vision model (Claude, OpenAI, Gemini, Azure)', is a prerequisite rather than a routing rule.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description still adds real value by stating irreversibility ('Cannot be undone') and the two-step confirmation requirement ('the user confirms first'), which explains why confirmation_token exists. It stops short of describing failure modes or what happens if the token is stale.

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

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

Two short sentences, front-loaded with the action and scope, then the alternative, then the risk. No filler and nothing 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 destructive, no-output-schema tool the description covers action, alternative, irreversibility, and the confirmation gate. The only gap is the undocumented comment_id format, which matters for correct invocation.

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

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

Schema coverage is 67% and comment_id carries no schema description, yet the description adds nothing about its expected format or where to obtain it. The confirmation flow is implied but the token's semantics are already spelled out in the schema, so this is baseline territory.

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 ('Permanently delete a comment') plus the scope ('on your post, yours or someone else's'), which immediately separates it from hide_comment and delete_media in the sibling list.

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

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

Explicitly routes the agent: 'Prefer hide_comment unless it must go' names the alternative and the condition that selects it, which is exactly the when/when-not guidance needed for a destructive 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 flag destructiveHint and idempotentHint, and the description adds what they don't: irreversibility ('Cannot be undone'), a platform-level auth constraint (Facebook Login requirement, attributed to Meta), and a confirmation-gating flow. These are exactly the behavioral facts an agent needs before firing 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?

Three compact sentences, front-loaded with the core action and scope, then eligibility, then safety. 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 3-parameter destructive tool with no output schema, the description covers scope limits, auth eligibility, irreversibility, and the confirmation gate. Only minor gaps remain, such as what the call returns on an already-deleted target despite the idempotent hint.

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

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

Schema coverage is 67% and media_id has no description at all; the description compensates by clarifying that the ID may refer to a post, reel, story, or carousel, and that individual carousel children are not valid targets. 'The user confirms first' also implicitly explains when confirmation_token becomes usable, though it doesn't spell out the two-call handshake explicitly.

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?

Names a specific verb ('Permanently delete') and enumerates the exact resources it acts on: post, reel, story, whole carousel. It also carves out a scope boundary ('single carousel items cannot be deleted') that no sibling tool covers, so an agent can distinguish it from delete_comment and delete_template immediately.

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

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

Gives a hard eligibility rule ('Only for accounts connected with Facebook Login') that determines whether the tool can be called at all, plus the precondition that the user confirms first. It doesn't point at alternative tools, but there is no competing deletion path among the siblings, so the missing explicit 'use X instead' is minor.

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 annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds that user confirmation happens first, which is useful context above the annotations. However, it does not say whether deletion is permanent or recoverable, nor what happens if the name is not found.

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, action first, caveat second. Every word is doing work and nothing is redundant, which is exactly right for a two-parameter destructive 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?

For a destructive tool with no output schema, the definition covers the essential action and the confirmation requirement, and the schema documents the token flow. It stops short of describing failure behavior, irreversibility, or the meaning of the required name parameter, which an agent would need for confident invocation.

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

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

Schema coverage is 50%: confirmation_token is well documented in the schema, but the required 'name' parameter has no description in either place. The description's word 'file' hints that name may be a filename, yet it never clarifies whether it is a template name, slug, or path, and it does not explain the round-trip of re-calling with identical arguments. Baseline 3 is appropriate given partial schema coverage.

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

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

The description states a specific verb and resource: 'Deletes a saved template file.' This is clearly distinguishable from the sibling tools list_templates and save_template, though it does not name those siblings explicitly. The agent can tell what the tool does without needing to consult 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?

'Asks the user first' implies a two-step confirmation flow, which is the closest thing to usage guidance here. It does not say when to choose deletion versus, for example, overwriting a template via save_template, nor does it state prerequisites such as the template having to exist.

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 destructiveHint=true, but the description goes further by specifying exactly what is destroyed (stored token), the additional side effect of revoke=true (removing the app's permissions from the Facebook user), and the downstream impact that scheduled posts stop.

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, front-loaded with the core action, then the conditional behavior, the side effect, and the confirmation requirement — no filler or redundancy.

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

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

For a destructive, zero-required-parameter tool with no output schema, the description covers consequences, conditional behavior, and the confirmation gate. It stops short of stating whether the action is reversible or what must be done to reconnect, which would complete the picture.

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

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

Schema coverage is 67% and the undocumented parameter is exactly the one the description explains: revoke=true is tied to Facebook Login permission removal. It adds real meaning beyond the schema, though it does not elaborate on revoke=false beyond the default 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?

States a specific verb and resource ('Remove a connected account from this server') plus the concrete consequence ('delete its stored token'), which distinguishes it cleanly from siblings like connect_account, complete_connect, and list_accounts.

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

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

Gives a clear precondition ('Needs the user's confirmation') and clarifies the conditional revoke path, but does not explicitly name the alternative tool (e.g., connect_account) or state when not to use this.

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

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

Annotations declare a non-destructive write, and the description adds genuinely useful behavior beyond them: output location (data folder's exports/), that bare filenames land there too, that other paths require user approval, and that existing files are never clobbered thanks to a -1, -2 suffix. The one gap is what the tool returns (presumably the written path), which matters for a write operation. Minor tension worth noting: the collision-suffix behavior means repeat calls create additional files, which sits awkwardly with idempotentHint=true, though it is consistent with destructiveHint=false.

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 artifact, then constraints in descending order of importance. The long parenthetical column list is bulky but pays for itself by telling the agent what fields the export contains. Sentence structure is dense 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 should say what a successful call returns (file path? row count?), and it does not. The confirmation_token flow is left entirely to the schema. For a 6-parameter write tool whose primary result is an unseen file, that leaves the agent guessing about the response.

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

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

Schema coverage is 67%, and the description usefully reinforces path semantics (bare name vs. absolute/~ path needing approval) and enumerates the CSV columns, telling the agent what data the export carries. But since and until have no schema description and get no explanation in the description either, so date format and defaults remain unknown. Baseline 3 fits.

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

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

Opens with a specific verb and artifact: 'Writes a CSV (one row per post: date, type, link, ... views, reach, likes...)'. An agent immediately knows this produces a per-post metrics export rather than returning data inline. It stops short of naming a sibling, so an agent must still infer that this is the file-export counterpart to get_media_insights or analyze_post.

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

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

The phrase 'for spreadsheets' signals the intended consumption scenario, and the description explains where the file goes and when approval is needed. However, it never states when to choose this over get_media_insights or analyze_post, nor what happens if limit exceeds available posts. Usage is implied rather than directed.

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 and openWorldHint, so the safety profile is covered. The description adds real value beyond them by naming the account-type and permission prerequisites for each input mode. It does not say what is returned on success or what happens when the page cannot be resolved, which matters for an open-world lookup.

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 key fact is front-loaded and the total length is small. The nested parenthetical in the second sentence is dense and slightly harder to parse than a two-bullet structure would be, but nothing 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?

For a three-optional-parameter lookup with no output schema, the description covers the prerequisite conditions well. It leaves implied rather than stated whether 'page' and 'query' are mutually exclusive and what the successful result actually contains, which is the main remaining gap.

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

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

Schema coverage is 100%, so all three parameters are already documented, making 3 the baseline. The description does add meaning the schema lacks, namely that 'query' is gated behind Page Public Metadata Access and that 'page' depends on a Facebook Login account, which isn't visible from 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?

The first sentence states the specific domain fact ('Instagram location tags use the Facebook Page ID of a place') and the second states the action: pass a page or a query to resolve it. That is a concrete verb+resource and it is unlike any sibling in the list, which are all publishing, commenting, or analytics tools.

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

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

It clearly routes the agent between the two input modes: 'page' works for Facebook Login accounts, while 'query' requires Meta's Page Public Metadata Access, 'which most apps don't have.' It even supplies a fallback for apps lacking that permission (look the place up on facebook.com and pass its Page URL). It stops short of tying the call to a downstream use such as tagging in publish_photo.

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, openWorld and non-destructive, so safety is covered. The description adds the meaningful behavioral detail that results are relative to the caller's own median rather than absolute thresholds, but says nothing about the default lookback window, sorting, or the shape of the two returned groups.

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

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

Two short sentences with the core definition front-loaded and no redundancy. The closing clause is partly motivational rather than informational, but it is brief enough to earn 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 five-parameter analytical tool with no output schema and no annotations explaining semantics, the description should clarify the lookback window (posts) and how many results per side (top) are returned. It covers the comparison concept well but leaves the result shape and windowing behavior to inference.

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

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

Schema description coverage is only 40%, but the description usefully expands the metric parameter far beyond the schema by listing eight named metrics, which the schema leaves as an undocumented plain string. It does not explain top (how many best/worst per side) or posts (the lookback window size), so coverage remains partial.

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 analysis operation on a specific resource: best and worst recent posts measured against the account's own median on a single metric, with the metric set enumerated. The median-baseline framing implicitly separates it from per-post tools like analyze_post and get_media_insights, though no sibling is named directly.

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?

'Shows what to repeat and what to drop' implies the strategic use case, and the schema's type field nudges toward comparing within one format. There is no explicit when-to-use/when-not guidance or pointer to an alternative tool for related analysis.

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 readOnlyHint/openWorldHint annotations it discloses the important behaviors: it drafts only and nothing is published, images are actually inspected, videos are transcribed only when a transcription model is connected, and without an AI model it degrades to returning a brief. It also notes that Instagram limits are checked, which explains why the output may be constrained.

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 with the output shape in parentheses, followed by constraints and the no-model fallback. Dense but each sentence carries information; the long parenthetical in sentence one is the only slightly awkward element.

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 and no required parameters, the description compensates by describing the caption structure produced and the fallback when no model is configured. Gaps remain around the purpose of notes, allowed language values, and where templates come from (list_templates), but the core call contract 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?

Schema coverage is only 25%, so the description has to carry meaning, and it covers three of the eight inputs well: description, transcript_path, and file_path are all implied by the listed sources. The remaining parameters (count, notes, language, format, template beyond "applies the template") receive no explanation of what values to supply or how they affect output.

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?

"Drafts caption options (hook first line, short body, call to action, hashtags, and on-screen hook text for reels)" is a specific verb plus resource and even enumerates the output components. The input sources (description, transcript file, media file) further pin the scope, making it distinguishable from publish_* (this never publishes) and from caption_check or translate_caption.

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 which input sources are acceptable (a description, a transcript file, or the media file itself), which is real when-to-use context. It stops short of naming alternatives or exclusions, e.g. when to prefer caption_check, translate_caption, or generate_hashtags instead of or alongside this tool.

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

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

Annotations only declare readOnlyHint and openWorldHint, so the valuable addition here is "AI-based" — telling the agent the output is generated rather than measured, which is the key behavioral distinction from hashtag_research's live data. It also discloses a sibling's auth and rate constraints. It stops short of describing cost, latency, or determinism of the generation itself.

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 output shape comes first, then the disambiguation and its constraint. Dense but front-loaded exactly where an agent needs 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?

With no output schema, the description usefully sketches the return value (categorized tags with reasons, a recommended 5-10, and an avoid list), which covers the return side well. However, for a four-parameter generative tool it leaves every input unexplained, including the non-obvious `template` parameter, so an agent still has to guess at call construction.

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 full burden, yet it explains none of the four parameters. It never says what `topic` should contain, how `caption` influences suggestions, what `template` refers to (presumably a saved template from list_templates), or that `count` (5-30, default 20) is the number of candidate tags produced rather than the 5-10 recommended ones.

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?

"Suggests a hashtag set for a post" gives a specific verb+resource, and the description goes further by enumerating what the set contains (broad, niche, community, branded, location tags with reasons, plus tags to avoid). It also names the sibling it is not (hashtag_research) and implies its relation to hashtag_budget, so the agent can distinguish it 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 the agent away to hashtag_research when live activity data is needed, and states the concrete constraint on that sibling (Facebook Login only, 30 hashtags per 7 days). It does not mention hashtag_budget or set explicit preconditions for this tool, so the guidance is clear but not exhaustive.

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 and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavior beyond that: it discloses that refresh=true triggers a live fetch from Instagram before the decision, which is a real network/latency implication an agent should know about. It doesn't cover failure behavior for an unknown test_id, 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?

Two tight sentences with no filler. The return contents are front-loaded and the refresh behavior is appended as a second, self-contained clause. Every phrase carries information.

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

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

With no output schema, the description correctly takes on the job of describing what comes back, and it does so at the right level of detail for a read-only inspection tool. The main residual gap is error/not-found behavior and whether refresh incurs added latency or rate limits, which would matter for an open-world 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 0%, so the description must carry the parameter burden. It fully explains the non-obvious parameter, refresh, including its default-off implication and its side effect of pulling current numbers from Instagram. test_id is left unelaborated, but its meaning is unambiguous from the tool's purpose.

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

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

The description uses a specific verb ("Shows") with a specific resource ("an A/B test") and enumerates the returned fields: per-version publishing status, link, latest metrics, decision time, and the verdict with confidence and next step. That makes it distinguishable from siblings like list_ab_tests or stop_ab_test. It stops short of explicitly naming the sibling it is not, which keeps it at 4 rather than 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: an agent can infer this is the single-test inspection tool versus list_ab_tests for enumeration, and "refresh: true pulls current numbers from Instagram before the decision" gives one concrete conditional behavior. However, there is no explicit when-to-use/when-not guidance and no mention of when to prefer it over list_ab_tests or stop_ab_test.

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, open-world behavior, so the safety profile is covered. The description adds real behavioral context beyond that: a 30-day ceiling on the since/until window and preset-over-metrics precedence. It still says nothing about rate limits, pagination, or what the response looks like for each mode.

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 carry a lot of information with no filler, but the leading "Account-level numbers." is weak and the long parenthetical enumerations are hard to scan. Structure is flat prose rather than grouped by preset mode vs. custom mode, which would read better for a 9-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?

With no output schema, the description needs to carry return-shape information; it partially does by naming the fields each preset yields, but not the response envelope or how time_series differs from total_value. It also omits how this tool relates to nearby insight tools, leaving an agent to guess at boundaries.

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

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

Schema coverage is 67%, and the description fills the biggest hole: the metrics array items are untyped strings in the schema, but the description enumerates every valid metric name. The preset-to-output mapping (overview, daily, reach_breakdown, follows) also adds meaning the enum list alone does not convey, though period and metric_type receive no elaboration.

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?

"Account-level numbers" plus an explicit inventory of the four presets and the customizable metric list makes clear this tool retrieves account-level insights rather than media-level ones. It implicitly separates itself from siblings like get_media_insights and get_audience by scope, though it never names them, and it lacks a real verb in the opening sentence.

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

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

The description does lay out two modes of use (pick a preset vs. supply your own metrics) and states that metrics is ignored when a preset is set, which is genuine routing guidance within the tool. It never says when to prefer this over get_media_insights, get_audience, or export_insights, nor does it state prerequisites such as a connected account or required scopes.

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

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

Annotations already declare this a read-only, idempotent, non-destructive open-world call, so the safety profile is covered. Beyond that, the description adds genuinely new behavior: a 100-follower eligibility threshold and a hard cap of the top 45 values per breakdown returned by Meta, both of which affect how the agent interprets results. It does not say what an empty or under-threshold response looks like, which keeps it below a 5.

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

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

Two tight sentences with the substantive content front-loaded: what the data is, then the constraints. There is no filler, though the parenthetical '(or the people who engaged)' slightly interrupts the opening clause.

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

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

With five optional parameters, no output schema, and low schema coverage, the description is only partially sufficient. It handles eligibility, dimensions, and the 45-value cap well, but omits the timeframe window semantics and gives no hint of the response shape (per-breakdown lists of values with shares), which the agent must infer.

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

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

Schema description coverage is only 20% (only 'account' is documented in the schema), so the description must carry weight. It does add meaning for 'who' (followers vs. people who engaged), 'breakdowns' (the four named dimensions), and 'top' (implied by the 45-value cap), but it never mentions the 'timeframe' parameter or its this_week/this_month options, leaving one of five parameters unaddressed in both places.

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 the specific resource (follower/engaged-audience demographics) and enumerates the dimensions returned: age, gender, country, city, expressed as percentage shares. This is far more concrete than the title alone and lets an agent distinguish it from the broader insight tools. It stops short of explicitly naming the sibling tools it is not (e.g., get_account_insights).

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

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

It supplies a real precondition — 'Needs at least 100 followers' — which tells the agent when the call will fail, and implies usage for audience analysis. However, there is no explicit when-to-use-vs-alternative guidance against get_account_insights or get_media_insights, and no statement of when to prefer 'engaged' over 'followers'.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuinely new behavioral facts beyond those: results are newest-first and Meta caps at the 20 most recent. It does not disclose whether older messages are reachable by any means, which is the one trait an agent most needs to know.

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

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

A single front-loaded sentence with no filler; the ordering and cap are stated up front. It is slightly telegram-style rather than a complete clause, but nothing 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, no annotations gap, and only 33% parameter coverage, the description should say more about what a returned message contains and how to obtain a conversation_id. The 20-message ceiling is the key constraint and it is present, so the definition is adequate but not complete for a 3-parameter 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 only 33% — only the account parameter is documented. The description partially compensates for limit by explaining the 20-most-recent ceiling, but the required conversation_id has no format or provenance guidance in either the schema or the description, leaving the most important parameter underspecified.

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 the resource precisely ('Messages in one Direct conversation') and its ordering, and the title supplies the verb ('Read'). It is clear what the tool returns, but it never distinguishes itself from the adjacent siblings list_conversations and send_dm, so the agent must infer the boundary between listing conversations and reading one.

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 phrase 'one Direct conversation' suggests a single-thread fetch versus list_conversations, but there is no explicit when-to-use, no note that a conversation_id must first come from list_conversations, and no mention of send_dm as the write counterpart. An agent can guess correctly, but the description does not route it.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description adds the returned detail fields, which is useful without an output schema, but it omits account scoping behavior, missing-media errors, and any rate-limit or permission context.

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

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

A single front-loaded sentence with no filler. The field list is dense but every item is relevant to what the tool returns.

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

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

For a simple read tool, the annotations cover the safety profile and the description usefully lists return contents in the absence of an output schema. It still lacks sibling routing guidance and leaves media_id and account semantics largely to 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 coverage is only 50%: the account parameter is documented in the schema, but the required media_id has no schema description. The description implies that media_id identifies a post, reel, or carousel, but adds no format or account-selection semantics, so it does not compensate for the gap.

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

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

The description opens with 'Full details of one post, reel or carousel' and enumerates the returned fields, so the agent can tell this retrieves a single media item. It does not explicitly distinguish itself from siblings such as list_media or get_media_insights.

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

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

There is no explicit when-to-use, when-not-to-use, or named alternative. 'One post' only implicitly suggests fetching details for a known media_id after enumeration, leaving the agent to infer the contrast with list_media and get_media_insights.

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 read-only, idempotent, non-destructive, and open-world, so the safety profile is covered. The description adds genuinely new behavioral context: these are lifetime (not windowed) numbers, story insights expire after 24 hours, and a 5-viewer threshold applies. It does not describe response shape or any rate limiting, keeping it short of a 5.

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

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

Two sentences, front-loaded with the returned metrics and followed by the invocation rule and the story caveat. The long metric enumeration is dense but each item is informative, and nothing is repeated from 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?

With no output schema, the description carries the burden of describing returns, and it does so thoroughly by listing the metric set and the per-type additions. Remaining gaps — account scoping (covered by schema) and any pagination or truncation behavior — are minor for a read-only metrics 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 coverage is 67%, with media_ids carrying no schema description at all; the description compensates by explaining that media_ids targets specific posts and that omitting them falls back to recent posts. It also clarifies that the metrics differ by media type, which affects what the agent can expect per ID. It does not explain the media_ids array cap or the latest/account interplay beyond defaults.

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 the resource (media insights) and enumerates exactly which metrics come back for posts, reels, and stories, so the agent knows precisely what this returns. It does not, however, differentiate itself from close siblings such as analyze_post, get_account_insights, or export_insights, leaving some ambiguity about which insight 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?

"Give media_ids, or omit them for the latest posts" gives a clear selection rule for the optional parameter, and the 24-hour/5-viewer note tells the agent when story data will be unavailable. There is no explicit guidance on when to use this instead of analyze_post or get_account_insights, 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?

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The word 'Live' usefully signals a fresh upstream fetch rather than cached data, but nothing is said about rate limits, latency, or what happens when the default account is unauthenticated or missing.

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

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

One front-loaded sentence with no filler, and the field list is informative rather than redundant. It reads slightly like a return-value inventory, which makes the core action ('fetch this account's profile') implicit, but nothing 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 enumerated fields (username, biography, followers, media count, picture) usefully describe the returned shape, and annotations cover the read-only, open-world nature. For a one-optional-parameter read tool this is nearly sufficient; only guidance on default-account errors and sibling selection 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 single 'account' parameter is fully documented in the schema (100% coverage), including the omit-for-default behavior, so the description owes nothing extra. It adds no meaning beyond the schema, which matches the baseline 3 when schema coverage is complete.

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 the resource (a connected account's profile) and enumerates exactly what it returns, so an agent can tell it fetches profile data rather than metrics or account lists. It never explicitly differentiates from siblings such as get_account_insights or list_accounts, and the verb is only implied by 'Live profile', 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?

There is no statement of when to call this versus alternatives like list_accounts (to enumerate accounts) or get_account_insights (for metrics). The only implicit hint is that it applies to a single connected account, leaving routing between siblings entirely to the agent.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, and the description goes beyond them by disclosing the shape of the result: staged progress states (preparing, uploading %, processing), error entries that include fixes, and the permalink appearing only after publication. It does not say what happens when a wait exceeds the timeout (partial status vs. error), which is the main remaining behavioral 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?

Front-loaded with the resource and its return contents in a single tight sentence, followed by a short fragment on waiting. Nothing is wasted, though the telegraphic 'Can wait for changes' could be slightly clearer about the wait_seconds mechanism.

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 explaining return values and does so well (progress states, errors with fixes, permalink). For a two-parameter read tool this is nearly complete; only timeout/failure behavior on the wait path is unaddressed.

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

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

Schema coverage is 50%: wait_seconds is documented in the schema, while job_id is undocumented anywhere but is self-evident from the phrase 'status of a publishing job'. The phrase 'can wait for changes' adds the semantic that wait_seconds enables a blocking/long-poll style call rather than being a plain delay, which is a useful but modest addition.

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?

Names the specific resource (status of a publishing job) and enumerates what it reports: per-item progress states, errors with fixes, and the permalink once published. That is enough to separate it from publish_photo/publish_carousel (which start jobs) and media_host_status (which covers media hosting), though no sibling is named explicitly.

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

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

Usage is only implied: an agent can infer this is the polling/observation step after starting a publish job via publish_photo or similar. There is no explicit when-to-use statement, no guidance on preferring polling over the wait option, and no mention of what to do if the job ID is unknown.

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 read-only, idempotent, non-destructive profile, and the description adds real domain behavior on top: the exact quota (30 searches), the rolling 7-day window semantics, and the existence of a free-repeat set. It does not say whether the count resets on a fixed or sliding schedule per hashtag, but the added context is substantive.

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

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

One sentence, front-loaded with the quota number, with no filler. Every clause contributes a distinct fact an agent needs.

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

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

For a zero-required-parameter read tool with full schema coverage and no output schema, the description conveys both returned facts adequately. It stops short of describing the shape of the response (e.g. how free-repeat hashtags are listed), which is a minor gap rather than a blocking one.

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 optional 'account' parameter fully documented in the schema (100% coverage), so the schema carries the meaning. The description adds nothing about the account parameter or which account's budget is reported when it is omitted — a question an agent with multiple connected accounts would legitimately have.

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 resource (remaining hashtag searches within a 30-per-rolling-7-days allowance) and a second output (hashtags repeatable for free), which is concrete enough to separate it from publish_budget and hashtag_research. It never explicitly names those siblings, though, so an agent must infer the distinction from the wording.

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 — check this before spending a search via hashtag_research — but the description never states when to call it, when not to, or what to do if the budget is exhausted. No alternative tool is named.

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), and the description adds real operational context beyond them: the 30-distinct-hashtags-per-7-days Instagram limit, that repeats are free, that remaining budget is surfaced, and the Facebook Login account restriction. It does not state whether this call itself consumes budget or what happens when the budget is exhausted.

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?

Dense and front-loaded — the output inventory comes first, then the budget constraint, then the account restriction. The parenthetical 'top (or most recent)' is slightly awkward but earns its place by explaining the edge choice; otherwise there is 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?

There is no output schema, so the description carries the return-value burden, and it does describe the shape of results per hashtag. Combined with the budget and account-type constraints, an agent has enough to call it correctly; only per-call cost/limit interactions are underspecified.

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 50% schema coverage, the description partially compensates: 'top (or most recent)' maps directly onto the undocumented `edge` enum values. However, it adds nothing about the `account` selector, the sample-size behavior of `limit`, or that `hashtags` accepts at most 10 entries, leaving the multi-hashtag batching 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?

The description names the resource (hashtags) and enumerates the concrete outputs: top/recent public posts, median likes and comments, format mix, related hashtags, and example posts. That is far more specific than the title, though it never explicitly contrasts itself with siblings like hashtag_budget or generate_hashtags.

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 budget and 'Facebook Login accounts only' notes tell the agent the preconditions, but there is no explicit 'use this instead of X when Y'. Given the presence of hashtag_budget and generate_hashtags in the sibling list, a routing sentence would have been valuable.

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 (non-read-only, non-destructive, idempotent), and the description adds genuinely new context: the visibility scope (author still sees the comment) and the two-step confirmation requirement that gates the call. Remaining gaps are error/permission behavior, which is a lesser omission given the annotation coverage.

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, the primary effect front-loaded and the reversal case plus confirmation requirement follow immediately. No filler, no restatement of the tool name.

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

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

For a mutation tool with a confirmation flow and no output schema, the description supplies the essential effect, reversibility, and the confirmation prerequisite. It stops short of describing failure modes or what the confirmation_token lifecycle looks like on retry, which would complete the picture.

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 50%: only account and confirmation_token are documented in the schema. The description compensates for the undocumented 'hide' boolean by explaining that hide: false reverses the operation, but comment_id and the interaction between confirmation_token and the prior identical call are left to the schema or inference.

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 ('Hide') and resource ('a comment') and defines the exact effect: hidden from everyone except its author, reversible with hide: false. It does not name the adjacent siblings (delete_comment, toggle_comments) it might be confused with, 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?

Use is implied by the effect statement and the '(or show it again with hide: false)' parenthetical, which signals the reverse case. However, there is no explicit guidance on choosing this over delete_comment or toggle_comments, and no stated prerequisites beyond the confirmation flow.

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 annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral detail — result ordering ('newest first') and the fact that filtering is optional — but says nothing about result volume, pagination, or what fields each test contains.

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 telegraphic sentence with zero padding; ordering and filtering are both front-loaded. It is a noun phrase rather than a verb phrase, which slightly weakens readability but costs nothing in length.

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-optional-enum read tool with annotations covering safety and no output schema to explain, the description supplies what an agent needs: what is returned, in what order, and that the filter is optional. Only the absence of any statement about result set size or truncation keeps it below a 5.

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%, but the single parameter is a self-describing enum whose allowed values live in the schema. The description adds only that the filter is optional and keyed on status, which is a small but real increment over 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 names the resource ('All A/B tests') and its scope, making clear this is the collection-listing counterpart to get_ab_test, create_ab_test, and stop_ab_test. It stops short of explicitly naming those siblings, so the differentiation is inferred from the plural 'All' rather than stated.

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?

'Optionally filtered by status' implies the filter is opt-in and that omitting it returns everything, which is useful invocation guidance. However, there is no explicit statement of when to prefer this over get_ab_test or create_ab_test, and no exclusions or prerequisites are given.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety and locality are covered structurally. The description adds the meaningful scope constraint that results are limited to accounts connected to this server, but says nothing about ordering, empty-state behavior, or what identifying fields each account entry carries.

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 ten-word sentence that front-loads the verb and resource with zero filler. Nothing could be removed 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 zero-parameter read tool with annotations covering safety and locality, this is nearly complete. The only residual gap is that no output schema exists, so the description could have hinted at what an account record contains (ID, username) to help the agent chain into account-scoped tools.

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

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

The tool takes zero parameters, which is the baseline-4 case; there is no parameter semantics to explain. The description correctly signals that no filtering arguments are accepted, matching the empty input 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 gives a specific verb and resource ('List the Instagram accounts') and scopes it to 'connected to this server', which distinguishes it from global lookups. It does not explicitly contrast with nearby siblings such as get_profile, auth_status, or set_default_account, so an agent must infer that this is the enumeration primitive.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no named alternative. Usage is only implied: an agent would reasonably call this to discover which accounts exist before calling account-scoped tools like publish_photo or get_account_insights, but that must be inferred.

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

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

Annotations already declare the read-only, idempotent, non-destructive profile, so the description only needs to add context. It does: replies are nested under each comment, each comment carries an answered/unanswered flag, and scanning spans recent posts by default. It omits pagination behavior and how deep the 'post scan' goes, which is a minor gap against a 7-param tool with no output schema.

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

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

Three short sentences, front-loaded with what is returned and the two scoping modes, followed by the filtering tip and the sibling handoff. No redundant restatement of the title 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 filtered list tool with no output schema and a well-documented schema (86% coverage), the description supplies the key missing pieces: return shape (comments plus replies, answered status), default cross-post scanning, and the triage_comments handoff. Nothing an agent needs to call it correctly is absent.

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 86%, so the baseline is 3. The description reinforces media_id scoping and reframes unanswered as a reply-queue filter, which adds a little intent beyond the schema's literal 'Only comments you have not replied to', but it says nothing about since, hidden, posts, per_post, or account, leaving those entirely to 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 the resource (comments, with their replies) and two distinct scopes: a single post via media_id or the most recent posts. An agent can distinguish it from reply_to_comment or hide_comment, though the description never uses an explicit verb like 'list' or 'fetch' and instead relies on the name/title to convey 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?

Gives actionable routing: 'Use unanswered: true to build a reply queue' and 'triage_comments sorts them by priority', which tells the agent when this tool is the right first step and when to hand off. It stops short of explicit exclusions (e.g., when to prefer list_mentions or how it relates to the comment-management siblings), so it stops at 4.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context about the 24-hour reply window and what each conversation includes, but it omits pagination behavior, account defaulting, and rate-limit considerations.

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

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

The description is a single front-loaded sentence with no wasted wording. The parenthetical explanation of the 24-hour reply window is directly useful and appropriately placed.

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 list tool with no output schema, the description does a fair job explaining the returned fields and reply eligibility. However, it omits pagination/limit behavior and account selection context, which are important for correct invocation.

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

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

Schema coverage is 67%: account and user_id are documented in the schema, while limit has no description. The tool description adds no parameter meaning at all, so it does not compensate for the undocumented limit parameter or clarify filtering behavior.

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

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

The description clearly identifies the resource as recent Instagram Direct conversations and specifies the returned information: who, last message, and reply eligibility. It distinguishes itself from a single-conversation tool like get_conversation by emphasizing recent conversations, though it does not explicitly name that 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?

The description implies usage by saying 'Recent Instagram Direct conversations' and explaining the 24-hour reply window, but it gives no explicit when-to-use guidance or alternatives. It does not tell the agent when to choose this over get_conversation or send_dm.

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 genuine context beyond them: result ordering (newest first) and that captions are shortened, which matters for downstream use. It says nothing about pagination or how to walk past the limit, which is the remaining behavioral gap.

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

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

Two tight sentences with zero filler, front-loading the resource and return fields before the alternative routing. The field list is slightly dense but each item earns its place by previewing the return shape.

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 compensates by enumerating returned fields, and it covers the main alternatives among 60+ siblings. Slight incompleteness on result-walking behavior (pagination or how to fetch more than the limit), but nothing required to call it correctly is missing.

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

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

Schema description coverage is 80%, so the schema already documents type, since, until and account. The description's reference to 'published posts, reels and carousels' loosely maps to the type enum but adds no new syntax or filtering semantics. Baseline 3 is appropriate when the schema carries the parameter burden.

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 resource set (published posts, reels, carousels) with ordering (newest first) and enumerates the fields returned, so an agent knows exactly what it gets. It also names the two sibling tools that serve different needs, making it distinguishable 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 the agent: use get_media for one post in full, get_media_insights for its numbers. This is a when-to-use-this-vs-alternatives statement with the selecting condition attached, not just implied context.

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

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

The annotations already declare read-only, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds the newest-first ordering and the provenance constraint on the ids, but says nothing about pagination or whether limit interacts with the single-item lookup mode.

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 with the primary scope first and the conditional lookup mode second. No filler, no restatement of the tool name.

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

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

With no output schema, the description should say more about the returned shape, since a mention record and a single @mention lookup likely return different things. Pagination behavior and the id-precedence rule remain gaps for a four-parameter, dual-mode 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 coverage is 75%, so the schema documents account, media_id, and comment_id; the description only reinforces where those ids come from. The limit parameter is undocumented in both text and schema, and the mutual exclusivity of the two id parameters is left unstated.

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 ('posts that tagged it'), the ordering ('newest first'), and a second lookup mode. It never distinguishes itself from the sibling list_tagged, which on its face covers similar ground, so an agent must guess which one 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?

Gives an explicit condition for the single-mention mode: pass comment_id or media_id taken from a mention notification. It offers no when-not guidance, no statement about which of the two ids wins if both are supplied, and no pointer to list_tagged as an alternative.

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 and openWorldHint=false, so the safety profile is covered. The description adds two genuinely useful facts beyond that: ordering (soonest first) and scope (local machine state). It does not say what the result set looks like per category, whether empty categories are omitted, or how the account parameter interacts with the 'this computer' scope.

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 no filler, and the primary content (upcoming scheduled posts) is front-loaded. The middle clause 'posts being published or waiting' is compressed to the point of slight ambiguity, but nothing 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?

For a two-optional-parameter read-only listing with no output schema, the description covers what the tool returns at a category level, which is the minimum an agent needs. It stops short of describing the shape of each entry or whether the categories are interleaved, and the 'this computer' scoping versus the account parameter is left unresolved.

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

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

Schema description coverage is 100%, so both parameters (recent, account) are already documented with defaults and bounds. The phrase 'recent results' loosely maps to the recent parameter but adds no semantics beyond the schema, and the account parameter is not mentioned in the description at all. Baseline 3 is appropriate.

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

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

The description names the resource concretely: upcoming scheduled posts in chronological order, in-flight publishes, and recent finished results from this machine. That is more specific than a bare 'list', but no explicit verb appears and it does not distinguish itself from siblings like get_publish_status or list_media, which an agent could plausibly confuse it with.

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 mix of upcoming, in-flight and finished items signals a queue/dashboard overview, and 'from this computer' hints at local-scope state. There is no explicit statement of when to pick this over get_publish_status or list_media, and no prerequisites (e.g. an authenticated account) are mentioned.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is fully covered structurally. The description adds the meaningful behavioral fact that results are scoped to the last 24 hours and that story insights also expire, but says nothing about ordering, pagination, or how expired/archived stories are handled.

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

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

Two short sentences with the core scope front-loaded and no filler. The second sentence about insight expiry is slightly tangential but justifies itself by explaining the time-sensitivity of the data.

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-required-parameter, read-only list tool with full schema coverage and rich annotations, the description supplies the key scope boundary. What is missing is a hint about what each returned story contains, which matters somewhat given 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?

There is a single optional 'account' parameter with 100% schema description coverage, so the schema already carries the semantics of @username/ID/default fallback. The description adds no parameter-level information, which is acceptable here but earns only the baseline.

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

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

The description states the specific resource (stories) and a precise temporal scope (currently live, last 24 hours), which is a clear verb-implied list operation. It does not explicitly differentiate from siblings such as list_media or list_scheduled, but the 24-hour live constraint is distinctive enough that an agent can 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 implied rather than stated: an agent can infer this is the tool for currently live stories, and the note about insights expiring hints at the time-sensitive reason to call it. There are no explicit when-not conditions or named alternatives (e.g., list_media for non-expiring content).

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and non-destructive, so safety is covered. The description adds the one useful trait beyond that: results are ordered newest first. It says nothing about pagination, result volume, rate limits, or what happens when the account has no tags.

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

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

A single front-loaded sentence with no filler; the resource, scope, and ordering each earn their words. Nothing is buried or redundant.

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

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

For a simple two-parameter read with no output schema, the description covers what the tool returns conceptually but not the shape of each item, how the limit behaves, or whether more pages exist. Adequate to call correctly, thin for interpreting results.

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

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

The schema documents only the account parameter (coverage 50%); limit has no description in either place, including its default of 25 and max of 100. The description adds no parameter meaning at all, so it does not compensate for the coverage gap.

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

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

"Media where other accounts tagged this account (photo tags), newest first" names the resource (media with photo tags) and the scope (tags by others of this account). The parenthetical "(photo tags)" separates it from caption-based mentions in sibling tools like list_mentions, though without naming that sibling explicitly.

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

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

Usage is only implied: an agent can infer this is the tool for photo tags rather than caption mentions. There is no explicit when-to-use statement, no mention of how it differs from list_mentions or list_media, and no prerequisites such as needing a connected account first.

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 and openWorldHint=false; the description adds useful context that templates live as JSON files in a local 'templates folder', which is consistent with the closed-world hint. It does not say how many templates are returned, whether the result is empty by default, or how the list is ordered.

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 compact sentence, structured as a topic label followed by a field list, with no filler. Its only structural weakness is that it front-loads the noun 'Caption templates' instead of the action the tool performs.

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 parameters, no output schema, and annotations covering the safety profile, the description is nearly sufficient. Still missing are the fact that it returns a collection (and its shape/emptiness behavior), which an agent needs before deciding to call it as a discovery step.

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's enumeration of template fields is informational rather than a parameter explanation, but nothing is lost 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?

The description never uses a verb; it is a noun-phrase inventory of what a caption template contains ('header/footer, hashtags, mentions, first comment, collaborators, location and the account voice'). The listing action is only recoverable from the tool name/title, and the description does not distinguish this from save_template or delete_template beyond the fact that it describes stored templates.

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

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

There is no guidance on when to call this versus siblings such as save_template, delete_template, or generate_caption. It also omits the obvious workflow hint (e.g. use before generating a caption to reuse a saved voice).

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 and openWorldHint. The description adds useful routing behavior: Facebook-Login accounts upload videos directly to Meta while images always use the host, which is context beyond the annotations. It does not cover return shape or failure modes, so not 5.

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

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

Two sentences, no filler, and the host options are compactly enumerated. The opening is slightly indirect for a status tool, but overall well-structured.

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

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

For a one-optional-parameter read-only status tool with no output schema, the description gives enough context about host modes and routing exceptions. It could state what the status result contains, but the core selection and invocation context is present.

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 host parameter is documented, but the description adds meaning to each enum value (Cloudflare quick tunnel, S3/R2/B2 bucket, Azure Blob Storage) beyond the schema's bare enum. That is valuable semantic enrichment.

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 identifies the resource (media hosting for local files reaching Instagram) and the three host modes, while the name/title supply the status verb. It does not explicitly contrast with prepare_media or publish_* siblings, so it stops short of 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?

No explicit when-to-use or when-not-to-use guidance is given; it explains host types but not when an agent should call this status tool versus prepare_media or publish_* tools. Usage is only implied by 'whether it works'.

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 readOnlyHint=false already flagging that a write can occur, the description adds genuine context: the write only happens when convert=true, what the output container/codec will be, and that a path is returned. The "Needs ffmpeg" prerequisite is a real environmental dependency worth disclosing. It doesn't say where the copy is written, whether it overwrites, or cleanup expectations.

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 inspection purpose, then the mutation mode, then the redundancy note and dependency. No filler and nothing repeated from 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?

There is no output schema, and the description covers both return shapes at a high level: a list of rejections in inspect mode and a file path in convert mode. The ffmpeg requirement and the note about automatic handling in publishing tools round it out. Minor gap: the structure of the rejection list and the destination of the converted copy are unstated.

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 75%, so kind, file_path and convert are already documented in the schema. The description adds the output target format for convert (JPEG / H.264+AAC MP4) and that reframing uses fit, but the fit enum values keep/crop/blur are never explained in either place. 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?

Specific verb+resource with explicit scope: "Inspect an image or video and list what Instagram would reject for a placement (format, codec, aspect ratio, length, size)". It also names the second mode (convert=true writes a fixed copy) and distinguishes itself from the publish_* siblings by noting they do this automatically.

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?

"Publishing tools do this automatically" tells the agent this is a pre-flight check, not a mandatory step, which is real routing guidance against publish_photo/publish_reel. It also implies the convert=false vs convert=true decision (inspect vs fix). It stops short of explicit when-not-to-use or when to prefer convert over letting the publisher handle it.

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

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

Annotations already declare this as a non-read-only, non-idempotent, open-world mutation, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond that: a hard one-message-per-comment limit, a 7-day eligibility window, and a mandatory user-confirmation step before sending. It does not describe what happens when the window has expired or when a duplicate is attempted, which is the 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 short sentences, none wasted: purpose first, then constraints, then the confirmation prerequisite. The most important scoping rule (one message per comment) is front-loaded.

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

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

For a four-parameter mutation with no output schema, the description covers the essential decision inputs: recipient derivation, rate limit, time window, and the approval gate. Missing only edge-case behavior and error outcomes, which is a modest gap rather than a blocker for correct invocation.

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

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

Schema coverage is 50%, so the description must carry weight, and it does: it explains that the recipient is derived from the comment (clarifying comment_id's role beyond a bare string) and that confirmation must occur before the call, giving the confirmation_token lifecycle context the schema only hints at. The account parameter is left entirely to the schema, which does document it adequately.

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 ("Send one private Direct message to the person who wrote a comment") and adds a concrete example of the intended content ("the link they asked for"). This clearly separates it from the public-facing reply_to_comment and the general send_dm 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 gives explicit qualifying conditions — one message per comment, within 7 days — and notes the user must confirm first, which tells the agent when this call is appropriate. It stops short of naming the sibling alternatives (reply_to_comment for public replies, send_dm for arbitrary recipients), leaving that routing 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 declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: the window is rolling 24 hours, it reflects Meta's platform limit, and carousels count as a single post — counting rules an agent could not infer otherwise. It stops short of describing the response fields or what happens when the count reaches zero.

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

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

One sentence, front-loaded with the primary answer (remaining posts) and the secondary one (scheduled posts). The parenthetical about carousels earns its place; there is 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 one optional parameter, no output schema, and annotations covering safety, the description is nearly complete — it explains the units and rules of the count. A small gap is the lack of any pointer to how the returned numbers map to publish decisions or to the sibling used for editing the schedule.

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 optional 'account' parameter, including the default-account behavior, so the schema does the work. The description adds nothing about account scoping, which is the baseline-3 outcome.

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 precisely what the tool returns: remaining API posts in Instagram's rolling 24-hour window plus posts scheduled for the next 24 hours. That is specific enough to separate it from siblings like list_scheduled or get_publish_status, though it never names those alternatives to reinforce 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 — an agent can infer it is a pre-publish quota check, but the description never says when to call it or when another sibling (e.g. list_scheduled for full schedules, get_publish_status for a specific post) would be the better choice. No exclusions or prerequisites 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?

Goes well beyond the annotations: discloses that the user's confirmation is required, that execution runs in the background, that Instagram crops every item to the first item's shape, and the scheduling caveat that a missed window more than 2 hours late is not published (reschedule or resume_publish). These are exactly the operational traits an agent needs before invoking a non-idempotent, open-world write.

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, front-loaded with the action and limits, then the cropping behavior, then the per-item extras, then the confirmation/background caveat. 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?

For a 13-parameter mutation with no output schema, the description covers the risky parts (confirmation, background execution, scheduling failure mode, immutability of captions after publish). Minor gaps remain around the return value and the wait_seconds/get_publish_status handoff, though the schema documents those.

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: it explains why 'fit' matters (Instagram crops to the first item's shape) and that alt text and user tags are per image, which the schema alone does not motivate.

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 (or schedule) a carousel') plus the cardinality constraint (2 to 20 images/videos, videos 3-60 s), which cleanly separates it from publish_photo, publish_reel and publish_story in the sibling list.

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?

Makes clear this is the multi-item path and that it can either publish now or schedule, and flags the confirmation prerequisite. It does not explicitly name the sibling tools to use instead for single photos or reels, so routing is inferred from the carousel scope 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 only give the generic write/open-world/non-idempotent profile; the description adds real substance on top: automatic JPEG conversion and aspect-ratio fitting into 4:5 to 1.91:1, the mandatory user confirmation gate, and asynchronous background execution that must be polled with get_publish_status. It stops short of describing failure modes after the confirmation_token call or what a partial publish looks like.

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

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

Three sentences, each carrying distinct information: the verb and scope first, the media-transformation guarantee second, the confirmation requirement and async handoff last. No filler and no repetition of schema content.

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

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

For a 16-parameter mutation with no output schema, the description supplies the two things an agent most needs and the schema cannot convey: the human-approval gate and the asynchronous poll-with-get_publish_status workflow. It leaves the return payload shape unstated, though the wait_seconds and status-tool handoff largely imply it.

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

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

Schema description coverage is 100%, so every one of the 16 parameters is already documented in the schema, including the fit enum, the scheduling window, and the confirmation_token protocol. The description adds only indirect meaning ('Images are converted to JPEG and fitted...' which contextualises fit/prepare) and does not touch caption, tagging, location or collaborator parameters. 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 description opens with a specific verb and scope: 'Publish (or schedule) a single-image feed post.' That phrase cleanly separates this tool from publish_reel, publish_carousel and publish_story without the agent needing to open any schema.

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

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

It states the confirmation prerequisite ('Needs the user's confirmation') and names the follow-up tool get_publish_status, plus the recovery path via reschedule or resume_publish when a scheduled time is missed. It never explicitly says 'use publish_reel for video' or 'use publish_carousel for multiple images', so routing to siblings rests on the self-descriptive names rather than on stated exclusions.

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

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

The annotations already declare non-read-only, open-world, non-idempotent, and non-destructive behavior. The description adds meaningful operational context beyond those annotations: duration and size limits, automatic H.264/AAC MP4 conversion, the inability to add licensed music via API, required user confirmation, and background execution.

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

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

The description is compact and front-loaded, moving from the core action to key constraints, conversion behavior, licensing limitation, and confirmation/background behavior. Every sentence carries useful information 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?

For a complex 20-parameter publishing mutation with no output schema, the description covers the most important operational constraints and the confirmation/background model. It stops short of explaining return behavior or status polling, though the wait_seconds schema and get_publish_status sibling tool provide related guidance.

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

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

Schema description coverage is 100%, so the schema already documents all 20 parameters in detail. The description adds some useful media context around fit and 9:16 reframing, but most of that meaning is already present in the schema, making a 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?

The description states a specific verb and resource: publish or schedule a reel. It adds concrete scope constraints (3 seconds to 15 minutes, up to 300 MB, 9:16 targeting) that distinguish this from generic media publishing and make the reel-specific purpose clear.

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 indicates that the tool can publish or schedule and that user confirmation is required, which gives useful context. However, it does not explicitly explain when to use this versus sibling tools such as publish_trial_reel, publish_story, publish_photo, or publish_carousel, so the agent must infer selection 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 write, open-world, non-idempotent, non-destructive, so the bar is lower; the description still adds real behavior: the 24-hour ephemerality, the API-surface limitations (no stickers, links, polls, music), and the human-approval requirement. Scheduling side effects and the 'computer must be on' caveat live only in the schema, which is acceptable given full coverage.

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, front-loaded with the action, then limits, then lifetime, then API restrictions, then the confirmation gate. No filler and nothing repeated from 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?

Given 10 optional parameters, a two-step confirmation flow, scheduling and a status-polling follow-up, the description covers the essentials an agent needs before the first call. It could have mentioned the confirmation round-trip and the get_publish_status follow-up, but the schema documents both, so the gap is minor.

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 explains fit, prepare, publish_at, wait_seconds and confirmation_token in detail. The description adds the media envelope (3-60 s, 100 MB) that constrains which file_path/url values are valid, which is a modest but genuine value-add over the schema rather than a rephrasing of it.

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

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

States a specific verb+resource (publish a story) plus the accepted media types and limits (image or 3-60 s video, up to 100 MB), and 'Stories last 24 hours' distinguishes it from the persistent publish_photo/publish_reel siblings. It stops short of naming those siblings explicitly, so the differentiation is inferential rather than 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?

Clear context: use it to publish now or to schedule, and it flags the user-confirmation prerequisite, which is the key gate before calling. It gives no exclusions, though — nothing says when to prefer publish_reel over publish_story, or that prepare_media can be used first rather than relying on the prepare flag.

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