Mellow Hub

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context beyond annotations: it notes the metrics:read requirement and that "Hosts that draw MCP Apps show it as a card," which tells the agent to expect app-style rendering. It does not cover rate limits or pagination, so it is strong but not exhaustive.

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

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

The description is compact: one long sentence lists the returned contents, followed by a short usage cue and a rendering note. It is front-loaded with the substantive inventory, though the list is dense and a couple of terms ("honours," "publications left") could be tighter.

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 is returned, and it does so by enumerating the main data points (networks, posts, quotas, per-network views, best post, honours). Some terms remain vague, but for a no-parameter dashboard tool whose annotations already cover safety, this is adequately complete.

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

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

There are zero input parameters, so the baseline is 4. The description does not need to document parameter semantics, and the empty schema has 100% coverage for the absence of parameters. The parenthetical "(with metrics:read)" adds a permission-scope hint rather than parameter guidance.

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 (the account profile) and enumerates the concrete contents it returns: connected networks, published and scheduled posts, publications left, 30-day views per network, best post, and honours. It is clear what the tool does without opening a schema, though it does not explicitly contrast itself with siblings like whoami or get_metrics.

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 phrase "The answer to 'how is my account doing?'" signals the question it addresses, but there is no explicit when-to-use guidance, no when-not to use it, and no named alternative such as whoami or get_metrics for narrower questions.

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, idempotentHint=true, openWorldHint=true, and readOnlyHint=false. The description adds useful behavioral context beyond those annotations by explaining the API-level limitation around already-published posts and the out-of-band resolution path.

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, and the core operation is front-loaded. The important limitation follows immediately as supporting context.

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 mutation with no output schema, the description covers scope and the key API limitation, while annotations cover safety traits. It could say more about the confirm requirement or expected outcome, but the structured fields already carry most of that burden.

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

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

Schema description coverage is 50%: confirm is documented in the schema, while postId is not. The description indirectly constrains postId to posts that have not gone out yet, adding some meaning, but it does not explain the confirm parameter or add syntax/details beyond the schema.

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

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

States a specific verb and resource: 'Withdraws a post that has not gone out yet.' This clearly distinguishes cancel_post from siblings like create_post, reschedule_post, and get_post without ambiguity.

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 the tool cannot be used (already-published posts) and where that action must instead happen (in the network itself, by a person). It gives strong context, though it does not explicitly compare against in-API alternatives such as reschedule_post.

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 openWorldHint/readOnlyHint=false; the description goes well beyond that by explaining the human-in-the-loop handoff, the per-network connection mechanics for Bluesky and Telegram, the prohibition on collecting passwords in chat, and the one-Instagram-per-profile constraint with its workaround.

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 critical fact (a link for a person, agent cannot complete it) is front-loaded in sentence one, and each subsequent sentence carries actionable behavior rather than filler. It is a single dense block of six sentences, so scanning is slightly harder than it needs to 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?

With no output schema, the description correctly explains what is returned (a link plus instructions), what the agent must do next, and the platform-specific exceptions and limitations. Nothing an agent needs to invoke this tool correctly and hand off to the human is missing.

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

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

Schema coverage is only 50%, so the description must compensate: it adds real semantic weight to the platform parameter by describing distinct flows for bluesky, telegram and instagram and the one-instagram-per-profile rule. It does not, however, explain connectionType values (instagram/facebook, oauth2/oauth1, organization/personal) at all, which is left 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?

The first sentence states a specific verb, resource and output: it returns a link that a human must open to connect a network. It also makes the crucial distinction that the agent cannot complete the task itself, which separates it from sibling tools like list_channels that merely report state.

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

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

It gives clear operating context (the person must sign in, never ask for a password in chat) and an explicit follow-up step: call list_channels with refresh once the user is done. It does not name a competing tool or a when-not-to-use condition, so it is strong context rather than full alternative routing.

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

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

Annotations only mark this as a non-readonly, open-world, non-idempotent mutation. The description goes well beyond them: it discloses the autopilot-vs-review-mode split ('live at once and answers real people in public' vs 'saved off and a person turns it on in Hub'), per-person throttling ('at most once per person an hour'), Instagram's one-DM-per-comment limit, and the required posts:write / posts:publish 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?

It is front-loaded with the core purpose and every sentence carries information, but the mode/rate-limit sentence is long and em-dash-heavy, which slightly slows parsing of two important operational facts.

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 6-parameter mutation tool with no output schema, the description covers prerequisites, permissions, mode-dependent side effects, throttling, and matching rules. There is no output schema to explain, and nothing an agent needs in order to invoke it safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description earns above that by adding matching semantics the schema lacks ('Whole words match, in any case'), the default for source, and the reply-selection behavior for comment vs message rules.

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

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

The description names a specific verb and resource ('Creates a rule that answers Instagram comments or direct messages containing one of its keywords') and immediately scopes it to the account's own name. An agent can distinguish it from list_autoreplies, update_autoreply, and delete_autoreply 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 gives an explicit prerequisite ('Read the account and its posts with list_autoreplies first') and clarifies the two operational modes via source comment vs source message. It does not, however, say when to reach for update_autoreply instead of creating a new rule, so the sibling boundary is only partly drawn.

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

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

Goes well beyond the annotations: destructiveHint=false could mislead an agent into thinking this is recoverable, so the description explicitly states the post is PUBLIC and CANNOT BE UNDONE once a network publishes, and explains the review-mode credential path. It also explains why idempotencyKey must be derived from content rather than randomly, which is exactly the retry semantics an agent needs.

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

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

Four sentences, each load-bearing, with purpose first, the irreversibility warning second, and the two operational rules (idempotency key, review mode) after. No filler and no repetition of schema text.

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 8-parameter tool with nested objects, it covers the safety profile, idempotency, scheduling and review mode well, and hints at the retry return value. With no output schema it could say more about what a successful or partial publish returns, but nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning the schema lacks: the derivation rule and stability requirement for idempotencyKey ('derive it from the content or the task, not at random'), the all-channels scope of channels, and the draft-vs-publish distinction tied to options.

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 — 'Publishes to every named channel, or schedules it with scheduledAt' — and distinguishes the two modes in one sentence. Against siblings like update_post, reschedule_post and cancel_post, the action and scope are unambiguous without opening the schema.

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

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

It gives clear routing between publish-now and schedule (omit scheduledAt), and flags that a review-mode credential turns the call into a prepare-and-stop step. It does not point at adjacent tools an agent might want first (preview_post, validate_post), so it stops short of full when/when-not/alternatives guidance.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, and the description adds two useful facts: previously answered comments/messages are retained (scoping the destruction), and the required scopes posts:write and posts:publish. Return format and error behavior are not described, 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 tight sentences with the core action front-loaded, then the retention caveat, then the permission 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 two-param destructive tool with no output schema, the description covers action, side-effect scope, and auth requirements. It could mention the confirm=true guard, but the schema handles that.

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%: ruleId is bare and confirm is fully documented in the schema. The description adds nothing about either parameter, but ruleId is self-explanatory and confirm is covered by the schema, so the baseline 3 holds.

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?

"Deletes a rule" gives a clear verb+resource, and the title plus sibling set (create_autoreply, update_autoreply, list_autoreplies) makes the auto-reply domain obvious. However, the description itself never says "auto-reply," relying on the title for that specificity.

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 delete versus update an existing rule, no prerequisites stated beyond permissions, and no mention of alternatives. The agent must infer usage entirely from the name and sibling list.

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 destructiveHint=false, so safety needs no restating. The description goes further by disclosing result semantics the agent would otherwise have to discover: missing readings stay missing, and reporting statuses are ok/empty/unsupported/failed. It also names the required scope metrics:read, which annotations do not cover.

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 tight sentences, front-loaded with scope, then the param modifier, then result semantics, then auth. No filler, no repetition of the title or annotations.

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 by explaining the status vocabulary and how absent readings behave. Combined with the schema's limit bounds and the read-only annotations, an agent has enough to invoke it correctly. Pagination or per-status actionability is not addressed, keeping it out of 5 territory.

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%: limit is documented in the schema, but channelId is bare. The description compensates by explaining that channelId narrows the result set, which is the missing semantic. It does not add format or syntax detail, but the coverage gap is addressed.

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: reading recent published posts plus network-reported metrics, scoped to channels the credential can reach. That is materially clearer than the name alone and separates it from list_posts or post_results. It stops short of naming the sibling it should be chosen over, so it is not 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?

It states the scope precondition ('channels this credential can reach'), the auth requirement ('Requires metrics:read'), and that channelId is optional and narrowing. However, it never says when to pick this over account_overview or post_results, so 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 this a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description earns credit by disclosing a non-obvious behavioral trait: a 'partial' outcome means some channels succeeded, and republishing would duplicate them. That is decision-relevant context beyond the annotations.

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

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

Two compact sentences, no filler, with the data description front-loaded before the operational caution. The opening noun fragment is slightly awkward 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 description carries the return-value burden and does describe the shape (post, per-channel outcome, public link) plus a downstream warning. For a single-resource read tool this is essentially complete; only the input parameter is left undocumented.

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

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

Schema description coverage is 0% and the description never mentions the sole parameter. The parameter (postId) is self-evident and required, so the cost is low, but the description does nothing to 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?

The description names the resource and the payload precisely ('The post and its per-channel outcome, with the public link'), so an agent knows what comes back. It is a noun-phrase fragment with no explicit verb and does not distinguish itself from lookalike siblings such as post_results or list_posts, 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?

The caution 'Read targets, not just status: partial means some channels succeeded and republishing everything would duplicate them' implies a when-to-use context (before republishing), but no alternative tool is named and no explicit when-not is given. Usage is inferred rather than stated.

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

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

Annotations already cover the safety profile (readOnlyHint, openWorldHint, destructiveHint false). The description adds real value beyond them: the required posts:read scope, the human-in-the-loop constraint that an agent cannot connect an account because consent belongs to Instagram, and a sketch of the returned rule structure. It does not mention pagination, result limits, or empty-result 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?

Three tight sentences, front-loaded with what is read, then the posts: true behavior, then the caveat about connecting accounts. Every sentence is useful, though the Hub-connection aside is slightly tangential to invoking the 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 carries the return-shape burden and does a fair job (accounts, rules with keywords/reply variants/private message, recent answers). Missing pagination and result-volume details keep it from being fully complete for a potentially multi-account listing tool.

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

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

Schema description coverage is 100%, so both parameters are already documented inline. The description restates them ('Set posts: true to also list...', 'needed with posts when several are connected') with only marginal additions such as 'the ids a rule can listen on'. Baseline 3 applies when the schema carries the parameter semantics.

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

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

States a specific verb (Reads) and a precisely scoped resource: the connected Instagram accounts for auto-replies, their rules, and recent answers. It goes further than a label by outlining what a rule contains (keywords, public reply variants, optional private message), so an agent knows exactly what this tool surfaces versus the create/update/delete_autoreply siblings.

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

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

Gives concrete usage guidance: set posts: true to include recent posts and the ids a rule can listen on. It also states a permission prerequisite (requires posts:read) and explains the fallback when nothing is returned (a human connects the account in Hub). No sibling alternative is named, and there are no explicit when-not-to-use conditions, so it stops short of a 5.

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

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

Annotations cover the safety profile (readOnlyHint=true, openWorldHint=true, destructiveHint=false), leaving the description to add operational context, which it does: it explains that needsReconnect means the network refused the sign-in and that signIn.endsSoon flags a sign-in expiring within a week. It goes beyond repetition by telling the agent what to do with those flags, though it doesn't describe the full response shape.

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

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

Every sentence carries actionable information and the refresh guidance is front-loaded. The opening noun phrase ('The owner's connected accounts, with the channel IDs...') is a fragment that reads awkwardly, but overall 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 must carry the return-value burden. It explains three response signals (channel IDs, needsReconnect, signIn.endsSoon/endsAt) but omits other likely fields, ordering, and pagination, so an agent still cannot predict the full 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 100%, so the baseline is 3. The description earns above baseline by adding timing semantics the schema lacks — the exact moment to use refresh: true (just after a person connects an account) and what it changes (re-read from provider vs. local copy).

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 precisely — the owner's connected accounts and the channel IDs used in a post — so an agent can infer it returns connected accounts. It never uses an explicit verb like 'list' and offers no direct comparison to the nearby list_platforms, which an agent could easily confuse with it, 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 guidance is present but only for the refresh parameter ('pass refresh: true after a person has just connected something'), not for tool selection. It never states when to call this versus list_platforms or whoami, so the when-to-use layer is left 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?

Annotations already establish readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds substantive behavioral context beyond that: it details exactly what data surfaces back (per-network video file constraints, posting cadence, sourced 'from the network's own pages'), which an agent cannot infer from annotations alone.

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

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

Two sentences with no filler. The primary scope is front-loaded, the returned detail follows, and the closing directive 'Read this instead of guessing a limit' is a compact, high-value call to action.

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

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

With no input schema, no output schema, and zero parameters, the description carries the full burden of explaining the return content — and it does so in detail (limits, media kinds, required fields, placements, video specs, cadence). Nothing an agent needs to decide to call it is missing.

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

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

The tool takes zero parameters, so no parameter semantics are required and the baseline is 4. The description correctly spends no words on arguments and instead describes the returned payload.

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 and scope: 'every network Mellow publishes to and the rules it enforces,' with a concrete enumeration of the rule families (caption limits, media counts, required fields, placements). It is clearly distinct from siblings like list_channels (the user's connected accounts) or validate_post, though it never explicitly names a sibling to contrast against.

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?

'Read this instead of guessing a limit' gives a clear condition for use: consult it before encoding platform constraints. It stops short of naming named alternatives (e.g. validate_post) or stating when not to use it, so it lacks true when/when-not routing.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds the 'newest first' ordering trait, which is useful, but says nothing about pagination, caps, or return format.

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 resource and ordering and no wasted phrasing. The trailing 'after a timeout' clause is slightly cryptic but does not bloat the text.

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 list tool with annotations already covering safety and no output schema to explain, the definition is nearly sufficient. It still omits how results are paginated and how it relates to the get_post sibling, leaving minor gaps.

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

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

Schema coverage is 50%: limit is documented in the schema but status only exposes an enum without prose. The description partially compensates by mentioning a status filter, but adds no syntax or default details for limit beyond the schema.

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

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

The description names the resource (posts), the ordering (newest first), and the optional filter (status), so the agent knows what the tool returns. It does not, however, distinguish itself from the sibling get_post, which an agent might reasonably confuse for post 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?

'Use it to find a post after a timeout' gives one concrete when-to-use scenario, but it is narrow and offers no guidance against alternatives like get_post or list_channels. Usage is implied for listing scenarios but not framed as a choice.

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, non-destructive, openWorld), so the description's job is to add context — and it does: the TikTok 'sent' status until the video is named, and that MCP Apps hosts render the result as a card. That is genuinely useful behavior an agent could not infer from structured fields.

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

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

Front-loads what is returned before the routing hint and the optional-parameter note; almost every sentence carries information. Slightly dense with the TikTok and MCP Apps asides, but none is filler.

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

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

With no output schema, the description must convey the return shape, and it does — per-network lines with location, status, views, likes and link. Combined with the optional-param rule and the status caveat, an agent has enough to call and interpret it.

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

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

Schema coverage is 100% and the single postId description already says 'Omit for the most recent published post.' The description restates that same fact without adding format, ID source, or error semantics, so this is the baseline 3.

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: one post's results, itemized one line per network with named fields (where it went, status, views, likes, link). It explicitly distinguishes itself from get_metrics, so an agent can route without opening either schema.

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

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

Explicitly frames the selecting question ('how did my post do?') and names get_metrics as the wrong tool for it, which is clear when-to-use guidance. It does not, however, differentiate against get_post or list_posts, so a sibling ambiguity remains.

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, destructiveHint=false, so the description's 'without publishing' largely restates the structured safety profile. It adds the fact that rendering is per-network, but says nothing about the shape of the preview output, latency, or limits. With annotations carrying the safety burden, this is adequate but thin.

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 earning their place: the first defines the action, the second routes to the alternative. The scoping statement is front-loaded with no preamble or filler.

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

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

For a read-only renderer with full schema coverage and no output schema, the description supplies what an agent needs to choose and call it. The only gap is that it does not characterize the returned preview (what fields/structure come back), which the missing output schema leaves 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 100% with 7 richly documented parameters (channels, perChannel, options, media, etc.), so the schema does the heavy lifting and baseline is 3. The description names no parameter and adds no syntax or format detail beyond what the schema already provides.

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

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

States a specific verb and resource — 'Renders what the post will look like on each network, without publishing' — and immediately contrasts itself with the sibling validate_post. An agent can tell preview_post apart from validate_post and create_post without opening any schema.

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

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

Gives an explicit selection rule: use it 'when the question is how something will read rather than whether it is allowed', naming validate_post as the tool that answers the other question. The when-to-use condition and the alternative are both spelled out.

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

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

Annotations already cover safety (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower. The description adds real behavioral context: 'Nothing is copied — the network fetches the URL when it publishes,' which clarifies that this is deferred fetching rather than a transfer. It does not describe the shape of the reported result, keeping 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?

Three short sentences, front-loaded with the core action, then the no-copy clarification, then the alternative routing. No wasted words.

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

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

For a one-parameter validation tool with no output schema and full annotation coverage, this description covers what happens, what does not happen (no copy), and the correct alternative. Only the nature of the returned report is left vague, which is acceptable given the tool's simplicity.

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

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

With a single parameter and 100% schema description coverage, the schema already documents the url field fully ('A public https URL to an image or video'). The description restates the public-https constraint but adds no syntax, format, or edge-case detail beyond it, so 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 gives a concrete verb and resource: it validates that a public https URL is fetchable and reports what it is. It also implicitly differentiates itself from request_upload_url, though the name 'register_media' is slightly broader than the 'check and report' behavior described.

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 exact condition that selects the alternative: 'If you hold bytes rather than a URL, call request_upload_url instead.' This is an explicit when-to-use / when-to-use-something-else routing rule, leaving nothing to inference.

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

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

Annotations declare mutating (readOnlyHint=false) and non-idempotent, and the description adds genuinely useful behavior beyond them: bytes go straight to storage and never through Mellow, and the call yields both a PUT target and a media URL for the follow-up post. It omits how long the signed URL lives or whether it is single-use, which matters for a non-idempotent operation.

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

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

Two tight sentences with no filler; the primary output (signed PUT URL) is front-loaded and the usage qualifier follows immediately.

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 the return value, and it does so well (PUT URL + media URL for the post). The main gap is operational detail about URL lifetime and whether a new call is needed per upload, which a non-idempotent upload flow would benefit from.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly implies the caller supplies nothing up front and instead receives the destination URL, which matches the empty 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 makes clear this returns a signed PUT URL plus a media URL for later use in a post, which is a specific and actionable purpose. It does not name the sibling it replaces (register_media) explicitly, so it is clear but not fully differentiated from alternatives in the toolset.

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 this for anything you hold as bytes, and for any video" states the condition for choosing this tool over an alternative path. It implies but never names the URL-based alternative (likely register_media), so the routing guidance is clear but not fully explicit.

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

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

Beyond the annotations' safety profile, it discloses exactly what is preserved (caption, media, destinations), two hard exclusions (drafts, published), a credential-mode edge case, and two authorization prerequisites (access to every destination, owner's subscription allowance). This is rich behavioral context an agent cannot get from the schema or hints.

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, each carrying distinct information (action, preservation, exclusions, prerequisites), with the core action front-loaded and no redundant 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 2-parameter mutation with no output schema, the description covers what changes, what stays the same, what is blocked, and what authorization is needed. Nothing an agent needs to decide whether and how to call it is missing.

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

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

Schema coverage is 50%: scheduledAt is documented in the schema, postId is not documented anywhere, and the description's 'future ISO 8601 time' requirement simply restates the schema text. Baseline 3 is appropriate since the schema carries the parameter detail and the description adds no new syntax or constraint.

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+scope: 'Moves an existing scheduled post to a future ISO 8601 time.' This clearly separates it from siblings like update_post (edits content), cancel_post (removes), and create_post (creates new).

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 clear eligibility conditions: drafts and published posts cannot be rescheduled, and review-mode credentials block the move. It stops short of naming an alternative path (e.g., cancel_post + create_post) for when the tool cannot be used, so it is strong context without explicit routing.

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

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

Goes well beyond the annotations (idempotentHint, destructiveHint=false) by disclosing automatic-retry precedence, the seven-day/oldest-first/ten-minutes-apart batching for the no-postId case, the refusal conditions (expired sign-in, disconnected account), review-mode restrictions, and a per-network retry cap of three. This is exactly the operational context an agent needs.

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

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

Purpose and the auto-retry caveat are front-loaded, and each subsequent sentence adds distinct operational detail (batching, refusals, rate limit). Density is high but phrasing is convoluted in places (e.g. 'sends a busy network, an unprocessed file and a network's limit again by itself first'), which costs a little readability.

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

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

For a mutating tool with no output schema, the description covers the failure semantics, refusal paths, credential restrictions and retry limits an agent needs to call it correctly, and defers nothing important. No output-schema-dependent gaps remain.

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

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

Schema coverage is 100%, so the schema already documents both params; the description still adds value by spelling out the batch semantics of omitting postId (all profile posts with a failed channel in the last seven days, oldest first, spaced ten minutes) and the narrowing behavior of channels. Slightly above the baseline because it adds format/timing meaning not 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+resource (re-send a post) and precisely scopes it to 'the networks that did not take it; where it is already out, nothing changes'. It also distinguishes the two modes (with vs. without postId) and routes the agent to get_post to confirm failure, so it is separable from siblings like cancel_post and update_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?

Explicitly says to use this 'for a channel that still reads failed in get_post', and explains that Mellow Hub already re-sends busy-network, unprocessed-file and rate-limit cases automatically — a clear when-to-use vs. when-not-to. It also names the conditions under which the call is refused.

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?

Adds real value beyond the annotations: returned artifacts (stable image URLs, caption, thumbnailUrl), the cost ('free'), and the critical scope limit that it does not publish. This complements idempotentHint=true and destructiveHint=false without contradicting readOnlyHint=false (it produces a render artifact). Auth requirements and the meaning of an unsupported revision remain unstated.

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 sentences, front-loaded with the core action and return payload, then downstream wiring, then scope limits. Dense but each sentence carries actionable information; the compression of the media-attachment guidance makes it slightly hard to parse 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 description correctly explains the return shape (image URLs, caption, thumbnailUrl) and adds publishing/downstream context. Given only two required params and annotation coverage of safety traits, this is nearly complete; the main gap is that projectId semantics and how a valid revision is identified are left to inference.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, but it only indirectly implies that 'revision' refers to a saved revision. projectId is never mentioned, and neither parameter's format, source, or valid range is explained beyond the schema's integer minimum of 1.

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

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

States a specific verb and resource with output format: 'Render the saved revision to ordered JPEG slides.' The agent immediately learns the artifact type (JPEG slides) and that it is free, though the description never explicitly contrasts itself with studio_generate or studio_save, so differentiation is by output rather than by direct sibling comparison.

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 concrete downstream routing: use the wider carousel media in validate_post/create_post, and attach a cover as thumbnailUrl on the VIDEO media item rather than replacing the video. It also draws a boundary ('Does not publish') and defers unsupported thumbnail formats to list_platforms, though it never says when to prefer a different export path.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds valuable state-machine semantics: queued/planning/generating/saving are in-progress, ready returns the saved result, failed means credits were returned. This tells the agent how to interpret outcomes, beyond what annotations provide. It doesn't cover polling frequency or timeouts, keeping it from 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, front-loaded sentences with zero waste: the action, the status meanings, and the explicit exclusion. Each sentence earns its place.

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

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

No output schema, so the description must explain return semantics, which it does via the status list. Combined with readOnly annotations, an agent knows it's a safe read that returns either progress or a result. It's missing where a jobId comes from and whether polling is needed, which keeps it from complete.

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

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

Schema description coverage is 0% with a single required parameter jobId, so the schema gives no meaning. The description implies jobId refers to a saved generation (the thing being read), which adds context. However it doesn't specify the format/origin of jobId (where to get it). With only one param, baseline is 4, and this provides some semantic framing.

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 read operation on a saved generation job, and explicitly distinguishes it from starting a generation with 'This does not start another generation.' The 'saved' qualifier and jobId scope separate it from siblings like studio_save or create_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?

Clearly implies usage: use this to poll/check status of an existing generation, and the final sentence explicitly rules out the alternative of starting a new generation. It lacks explicit sibling naming (e.g., 'use request_upload_url first'), but the when/when-not is clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds the access-scoping constraint (results belong only to this credential's profile), which is useful context beyond annotations. It does not describe pagination, rate limits, or return format, and with annotations carrying the behavioral burden, a 3 is appropriate.

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 resource list, and the scoping constraint is placed second. Every clause adds information without waste.

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

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

Given the simplicity (no parameters, no output schema, annotations cover safety), the description is nearly complete: it says what is read, who sees it, and the access boundary. The only missing piece is explicit guidance on when to choose this over sibling read tools like account_overview, but that is a minor gap in this context.

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

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

The tool has zero parameters, so there is nothing to document beyond what the schema already shows. The baseline for zero parameters is 4, as no additional parameter semantics are needed.

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 read verb and a concrete resource set: carousels, video covers, generation progress, and shared AI credit balance. It clearly states what is returned, distinguishing it from write siblings like studio_save or studio_export. It does not explicitly contrast with siblings such as studio_project or account_overview, but the scope is clear enough for an agent to identify the resource.

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 stating the results belong only to this credential's profile, which hints at the scoping condition. However, it does not say when to use this tool versus alternatives like account_overview or studio_project, leaving the agent to infer from the resource list.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds one genuinely non-obvious constraint — Panorama art cannot be redrawn one slide at a time — but says nothing about auth, errors, or how revisions relate to the current document. Adequate, not rich.

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 paragraph enumerating block types (note, pills, stat, board, steps, prompt, buttons) with their field shapes. Most of that detail is return-shape trivia, not invocation guidance, and it swamps the one sentence that matters. Poorly front-loaded relative to its size.

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, describing the document/revision shape and Panorama structure does add return-value context that would otherwise be absent. However, the sole required input, projectId, is left unexplained, so an agent knows what comes back but not what to pass in.

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

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

Schema description coverage is 0% and there is one parameter, projectId, which the description never mentions or explains (no format, no source, no example). The description must compensate for the schema gap and instead spends its words on Panorama block shapes that are not inputs to this call.

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

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

The opening sentence states a specific verb and resource: read a carousel or cover's document and revision. It also implicitly distinguishes itself from studio_save by naming that sibling as the editing path. It stops short of 5 because the purpose is buried under a large amount of data-model exposition rather than leading cleanly.

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

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

The description says the retrieved fields are editable with studio_save, which implies a read-then-save workflow, but never states when to choose this tool versus studio_list, studio_job or studio_export. Usage is implied rather than instructed.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds behavior the annotations cannot express: it refuses stale revisions (optimistic-concurrency guard), rejects image IDs belonging to another profile (ownership constraint), and states that saving is free and performs no publishing or AI generation. It stops short of stating that the prior document is overwritten or what the failure response 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?

It is front-loaded — the act and its rejection rules come before the document-format detail — and nearly every sentence carries information that the opaque schema does not. The Panorama spec is delivered as one dense run-on paragraph with no structure, which makes it harder to scan than it needed to be.

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 nested free-form document, no output schema, and 0% schema coverage, the description covers Panorama documents well but says nothing about the default document shape, what happens to prior content on save, or what a successful save returns. An agent calling this for a non-Panorama document is still guessing at the payload.

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

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

Schema description coverage is 0% and 'document' is an untyped free-form object, so the description carries the burden. It compensates substantively for the Panorama case (slide label/heading/emphasis, the seven allowed block types with their fields, and 'zone' as pixels from the top of 1080x1350), and 'Refuses stale revisions' explains revision semantics. However projectId is never explained and the non-Panorama document shape is completely undocumented, leaving a real 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 first sentence gives a specific verb and resource ('Save an edited Studio document at its current revision') and the save/revision scope immediately separates it from read-only siblings like studio_project or studio_list. It also names the downstream sibling studio_export, so an agent can place this tool in the studio workflow without opening either schema.

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

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

It gives real routing context: 'Manual editing is free. No publishing or AI generation occurs' steers the agent away from create_post and generation tools, and 'studio_export then sets the saved words exactly' establishes the follow-on call. There is no explicit when-not or prerequisite list (e.g. whether the project must already exist), so it falls short of full alternative coverage.

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 beyond the annotations (destructiveHint, idempotentHint, openWorldHint) by disclosing partial-update semantics, credential/permission behavior for review-mode tokens, and the required scopes posts:write and posts:publish. It does not clarify whether omitted fields are left intact versus cleared, which is the key ambiguity for a destructive partial update.

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 tightly-packed sentences with zero filler; the patch instruction and the permission caveat are both front-loaded and each sentence carries distinct information.

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

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

For a mutation tool with no output schema and only 1 required parameter, the description covers authorization, patch semantics, and credential-mode limitations well. The remaining gaps are the return shape and whether field omission preserves or clears existing values.

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% (postId, ruleId, message are documented; enabled, replies, keywords are not). The description compensates by mapping prose to parameters and clarifying that 'enabled' toggles the rule on/off, but it adds no format, constraint, or null-handling detail for the replies/keywords arrays. Roughly baseline for half-covered 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 ('Changes') on a specific resource ('a rule') and enumerates the mutable fields (keywords, replies, private message/post, enabled). The verb 'changes' cleanly separates it from create_autoreply and delete_autoreply without needing to name them.

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

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

Gives real when-to/when-not guidance: 'Send only what changes' establishes patch semantics, and the review-mode paragraph spells out exactly which operations a restricted credential may and may not perform ('may turn a rule off... may not turn one on or change one that is live'). It also names the required scopes. It stops short of naming sibling alternatives like create_autoreply/delete_autoreply explicitly.

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 destructiveHint and idempotentHint but the description adds the crucial replacement semantics ('Send the whole post as for create_post — what is left out is removed'), the refusal conditions, review-mode approval behavior, and the draft rollback behavior of draft:true. This is real behavioral context beyond the structured hints.

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 behavior, then constraints, then routing to sibling tools in a logical order. Dense but each sentence carries weight; slightly packed with special cases, 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 an 8-parameter, nested-object mutation tool with no output schema, the description covers replacement semantics, refusals, review-mode and draft behavior, and prerequisites. The only gap is return/response behavior, which the absence of an output schema makes less critical.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: the whole-post replacement rule that makes omissions destructive, and the effect of draft:true on an already-scheduled post. It does not elaborate scheduledAt or perChannel beyond the schema, keeping it at a strong 4.

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 (changes) and resource (a saved post) with precise scope: it edits in place and keeps the id, covering caption, media, channels, per-network settings and time. It explicitly differentiates itself from reschedule_post ('Moving a post without changing it is reschedule_post') and create_post, so an agent can route correctly without opening schemas.

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

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

Gives explicit eligibility (drafts, awaiting approval, scheduled) and explicit refusals (already published, going out now, handed over in parts), plus special cases for draft:true and review-mode credentials. It names prerequisites and alternatives (validate_post, reschedule_post) with the condition that selects each.

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 carry readOnlyHint=true, destructiveHint=false and openWorldHint=false, and 'publishes NOTHING' reinforces that without contradicting it. It adds genuinely useful behavior the annotations cannot express — the return shape ('every problem at once, each naming the channel and the field') despite there being 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 sentences, front-loaded with the effect-free nature of the call, and sized well for a simple tool. The motivational tail ('the difference between fixing a post once and learning the rules by publishing badly') is persuasive rather than informational, which is the only mild padding.

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

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

For a no-side-effect validator that takes the same rich, nested post payload as create_post, the description covers the essential facts an agent needs: it changes nothing, it accepts the post it names channels for, and it returns all problems with channel and field. With no output schema, explaining the error shape in-description was the right call.

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

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

Schema description coverage is 100% across 7 parameters, so the schema already documents draft, media, caption, options, channels, perChannel and scheduledAt in detail. The description only implies that a normal post payload is passed in ('checks a post') and adds no field-level meaning, so baseline 3 applies.

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

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

States a specific verb+resource+scope: it checks a post against every channel it names and produces no side effects ('publishes NOTHING'). The closer 'Returns every problem at once, each naming the channel and the field' distinguishes it from create_post and from a plain preview.

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, directive when-to-use ('Call this before create_post every time') and names the alternative it precedes. It does not distinguish itself from the sibling preview_post, nor state any when-not condition, so the routing guidance is clear but incomplete.

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, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds useful behavioral context — that mode determines whether publishing happens (autopilot) or only preparation occurs (review) — which goes beyond the annotations. However, it does not disclose rate-limit behavior, auth failure modes, or response shape, so it is solid but not rich.

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 what is returned and ending with the directive to call it first. Every clause adds information: the returned fields, the mode semantics, and the usage imperative. No waste.

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

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

For a no-input, no-output-schema introspection tool, the description supplies everything an agent needs: what it returns, why it matters, and when to call it. The only minor gap is that return format is not described, but with no output schema and a simple profile object, this is acceptable.

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

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

Zero parameters, so the baseline is 4. The description correctly does not invent parameter semantics and instead uses the space to explain what the credential-scoped response contains, which is the right use of a no-param tool's description.

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

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

States a specific resource (the current profile/credential) and enumerates exactly what is returned: ID, name, mode, scopes, reachable channels, remaining post quota, and subscription publishing eligibility. This is far more specific than any sibling (account_overview, list_channels) and lets an agent distinguish it without opening the schema.

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

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

Provides explicit, directive usage guidance: 'Call this before anything else'. It also frames when the information matters ('answers the questions you would otherwise discover by being refused'), which tells the agent both the timing and the cost of not calling it. No exclusions are stated, but the 'before anything else' instruction is a strong, unambiguous rule.

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