Mellow Hub

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 already disclose openWorldHint=true and readOnlyHint=false, but the description adds critical non-obvious behavior: the tool does not itself connect the channel; it returns a link that a human must open. It also notes Bluesky credential requirements and the required follow-up call. No contradiction with annotations.

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

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

Front-loads the core behavior ('Returns a link a PERSON must open') and then adds only necessary operational context. Every sentence carries unique information: human-in-the-loop constraint, credential requirement, follow-up action, and profile limit. 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?

With no output schema, the description adequately explains that the return value is a link and what the agent must do with it. It covers the human-interaction model, platform-specific credential needs, follow-up verification, and an edge case, leaving no critical gap for an agent to invoke it correctly.

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

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

Schema coverage is 75%, with handle, appPassword, and connectionType already described in the schema. The description reinforces Bluesky's handle/appPassword need and mentions Instagram's limit, but adds no parameter-level detail beyond what the schema already states. Baseline 3 is appropriate.

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

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

States a specific verb and resource: returns a link a person must open to connect a network. Clearly distinguishes this from sibling list_channels by framing this as the initiation step, with list_channels as the follow-up verification. An agent can tell this is not a direct connection tool.

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 (to get a connection link for a person) and when not to attempt it alone ('You cannot complete this yourself: every network asks a human to sign in'). It also names the follow-up action (call list_channels with refresh) and handles the Instagram one-per-profile edge case.

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: it warns the post is public, cannot be undone once a network publishes, explains the review-mode credential path, and tells the agent how to derive idempotencyKey rather than just that the call is idempotent. It omits things like rate limits or partial-failure behavior across channels, so not 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 tightly packed sentences, no filler, and the highest-stakes fact (public, irreversible) is front-loaded before the idempotency and review-mode details.

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

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

For a mutating, open-world publishing tool it covers the critical risks: public exposure, irreversibility, idempotency, and approval mode. With no output schema, it does not say what a successful call returns (e.g., post identifiers the caller would need for get_post/post_results), 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 already 100%, so the baseline is 3, but the description adds real meaning on idempotencyKey ('derive it from the content or the task, not at random') that the schema's 'stable for this post' does not convey. Other params (draft, media, perChannel) are 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?

States a specific verb and resource ('Publishes to every named channel, or schedules it with scheduledAt'), plus the scope that all named channels receive the post. It implicitly separates itself from preview_post/validate_post via the irreversibility warning, but never names a sibling, 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 publish-now vs schedule-with-scheduledAt fork is stated, and the review-mode note tells the agent what happens under certain credentials. However, it never directs the agent to validate_post or preview_post first, and gives no explicit when-not to call it, leaving the alternatives 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?

The description adds real behavioral context beyond the readOnlyHint/openWorldHint annotations: missing readings stay missing, results are classified as ok/empty/unsupported/failed, and the metrics:read scope is required. That partial-failure semantics disclosure is genuinely useful for an agent.

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 purpose and constraint, no filler. Slightly terse on the auth requirement placement, but every sentence 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 does the work of explaining the result shape (status categories, absent readings) and the permission prerequisite. Only pagination/ordering behavior for the limit parameter is left implicit.

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, channelId is not. The description partially compensates by explaining channelId narrows results, but adds nothing about limit beyond the schema's per-channel semantics. 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?

States a specific verb and resource: reads published posts plus network-reported metrics, scoped to channels the credential can reach. Clear enough to separate from list_posts/get_post, though it never names which sibling to prefer.

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?

'Optional channelId narrows the result' implies when to pass a filter, but there is no explicit guidance on when to call this versus post_results, get_post, or list_posts. Usage is inferable but not 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=true, openWorldHint=false), so the bar is lower; the description adds real context on the returned shape (per-channel outcome, public link) and on the meaning of a partial result. It does not mention pagination or missing-post/error behavior, keeping it out of 5 territory.

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, front-loaded with what is returned and followed by the operational caution. Slightly compressed phrasing ("Read targets, not just status") costs a little clarity but no sentence is wasted.

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

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

With no output schema, the description carries the return-value burden and does so reasonably: it identifies the post, its per-channel outcome, and the public link. What remains thin is the input side (postId provenance) and error behavior for a nonexistent post.

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 sole parameter postId is never described in the text — no format, no indication of where the ID comes from (create_post/list_posts). The parameter name is largely self-explanatory, but the description adds no meaning beyond 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?

The description names the resource ("The post") and its returned scope (per-channel outcome plus public link), which is more specific than a bare 'get a post'. It does not explicitly name a sibling (e.g., post_results or list_posts) to sharpen the boundary, 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?

"Read targets, not just status" implies when this tool is useful (diagnosing partial per-channel outcomes) and warns against republishing, but it never states when to prefer this over post_results or list_posts. Usage is inferable rather than explicit.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds a behavioral trait annotations cannot express: by default it answers from a local copy, and refresh re-reads from the provider. That caching distinction is exactly the kind of extra context worth having.

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 output stated first and the parameter caveat second. The phrase 'with the channel IDs you name in a post' is 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?

For a no-required-param read tool with full schema coverage and no output schema, the description covers what is returned and the one behavioral quirk (local copy vs provider re-read). Return shape details are minor given the tool's simplicity, though a hint about pagination or account fields would fully close the 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 the baseline is 3, and the schema already explains refresh as 're-read from the provider before answering.' The description goes further by naming the triggering scenario (a person has just connected something), which tells the agent when the flag is warranted rather than just what it does.

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 resource clearly ('the owner's connected accounts') and what it yields ('the channel IDs you name in a post'), which implicitly separates it from list_platforms (available platforms rather than connected accounts). It lacks an explicit verb, but the name plus the resource phrase make the purpose unambiguous.

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

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

It gives a real conditional for the refresh flag ('after a person has just connected something'), which is genuine usage guidance for the parameter. However, it never says when to call this tool versus siblings like list_platforms or whoami, so the routing guidance is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds substance beyond that by enumerating what the response contains (limits, media kinds, required fields, placements), which matters because there is no output schema. It omits nothing critical for a no-param read.

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. The resource and its returned rule categories come first, and the usage nudge is placed last as a takeaway.

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 saying what comes back, and it does so by listing the rule categories. Combined with annotations covering the read-only, non-open-world profile, an agent has everything needed to call it correctly.

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

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

The tool takes zero parameters, so there is nothing to disambiguate; the baseline for 0-param tools is 4. The description correctly implies no filtering or selection is 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 states a specific resource (every network Mellow publishes to) plus the payload of rules it returns (caption limits, media counts/kinds, required fields, placements). That is concrete enough to separate it from siblings like validate_post or create_post without opening a schema.

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

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

"Read this instead of guessing a limit" gives a clear condition for invocation: consult it before asserting any platform constraint. It does not name a sibling alternative or state exclusions (e.g. whether validate_post already enforces these), so it stops short of explicit 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 and openWorldHint=false, so the safety profile is covered. The description adds the meaningful 'newest first' ordering trait, but says nothing about pagination behavior or how many items come back by default.

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 return shape front-loaded and no filler. The 'after a timeout' clause is slightly informal but earns its place as usage guidance.

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

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

For a simple read-only list with no output schema, the essentials (contents, ordering, optional filter) are present. It omits default/max limits (only in the schema), pagination, and any pointer to get_post for single-record retrieval, so it is adequate rather than 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 50%: limit is documented in the schema, but status carries only an enum. The description confirms status is an optional filter, adding marginal value, but the enum values themselves are what convey the allowed statuses, so the description does not compensate much 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 states the resource (posts), the ordering (newest first), and the optional status filter, so an agent can tell it returns a collection rather than a single record. It lacks an explicit verb and does not name the get_post sibling it contrasts with, but the purpose is 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 provides one concrete scenario ('find a post after a timeout'), which is genuinely useful context for the create_post flow. However, it never states when NOT to use it or points to get_post when the ID is already known, leaving the sibling 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?

Annotations already declare readOnlyHint/openWorldHint, but the description adds non-obvious state semantics — a TikTok reads 'sent' until TikTok names the video — and a rendering note about MCP Apps hosts. These are behavioral details the annotations do not convey, though no auth or rate-limit context is given.

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 what is returned and the sibling exclusion. The MCP Apps card note is slightly niche but still earns its place as rendering behavior.

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

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

With no output schema, the description supplies the return shape (one line per network with the listed fields), the default-parameter behavior, and an edge case for TikTok status. Complete enough to call correctly.

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

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

Schema description coverage is 100% and the single parameter is already documented in the schema; the description's 'without it, the most recent published post' essentially repeats that. Baseline 3 applies since 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?

Names a concrete resource (one post's results) and enumerates the returned fields (where it went, status, views, likes, link), and explicitly distinguishes itself from get_metrics. An agent can pick this over the sibling without opening either schema.

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

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

States the exact question it answers ('how did my post do?') and names the alternative tool it is NOT (get_metrics), plus explains the optional postId default. Explicit when-to-use and when-not-to-use 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 and openWorldHint=true, so the safety profile is carried by structured data. The description adds the crucial reassurance that nothing is published, which matters because the schema's own fields (scheduledAt, media, caption) make this look like a mutating create_post call. It does not discuss rate limits, persistence of previews, or auth needs, so it stops short of full behavioral disclosure.

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

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

Two sentences, zero filler, and the non-publishing constraint is front-loaded before the sibling comparison. Every clause earns its place.

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

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

With no output schema, the description carries some burden for explaining what comes back, and 'renders what the post will look like on each network' reasonably implies a per-network preview payload. Given seven parameters and deep nesting, it leans heavily on the schema, but the routing and the no-publish guarantee are the pieces an agent most needs here.

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

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

Schema description coverage is 100% and the nested options/media fields are richly documented in the schema itself, so the baseline of 3 applies. The description names no parameters 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 (renders) and a specific resource (what the post will look like on each network), plus the key scoping constraint (without publishing). It explicitly names the sibling validate_post and what that tool covers instead, so an agent can separate the two without opening either schema.

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

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

Gives an explicit selection rule: use this when the question is how something will read, use validate_post when the question is whether it is allowed. The alternative is named and the condition that selects it is stated, 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 already declare readOnlyHint=true and openWorldHint=true, and the description adds real value beyond them: nothing is copied, the fetch happens at publish time, and the URL must be public https. It does not describe error behavior for unreachable URLs or any rate limits.

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 deferred-fetch caveat, then the alternative routing. 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?

Covers the mutation-free semantics and the alternate path well, but with no output schema the phrase 'reports what it is' leaves the return value under-specified. Otherwise adequate for a single-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?

Only one parameter and schema coverage is 100%, so the baseline is 3. The description reinforces the 'public https URL' constraint from the schema but adds no format, size, or content-type guidance beyond 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 action on a specific resource ('Checks that a public https URL can be fetched') and names the sibling it complements, request_upload_url. Slight ambiguity remains around what 'register' means as a side effect, though 'the network fetches the URL when it publishes' partly resolves 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?

Gives an explicit when-not condition and the alternative to use instead: 'If you hold bytes rather than a URL, call request_upload_url instead.' That is exactly the routing decision an agent needs.

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?

With destructiveHint=true, idempotentHint=true and openWorldHint=true already declared, the description adds real context: caption/media/destinations are preserved, and the call requires access to every destination plus subscription allowance. These permission and side-effect details go beyond the annotations. It stops short of describing what 'destructive' means here (e.g. whether the original time is lost) or the failure mode when allowance 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?

Three tight sentences, front-loaded with what the tool does, then the preservation guarantee and the eligibility/permission constraints. 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?

No output schema exists, but the tool is idempotent and returns little of interest, so the description need not explain return values. Safety is covered by annotations and preconditions and permission requirements by the description, leaving only minor gaps around failure behavior and postId.

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 as a future ISO 8601 time with timezone, and the description repeats the 'future ISO 8601' framing. postId carries no description in either the schema or the description, so half the parameters remain undocumented and the description does not compensate.

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 (moves/reschedules), resource (existing scheduled post), and target (future ISO 8601 time), which cleanly separates it from create_post and cancel_post. The added preconditions on drafts and published posts further pin down exactly what the tool operates on.

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 when-not rule ('Drafts and published posts cannot be rescheduled') and implicitly scopes usage to already-scheduled posts. It does not name a sibling alternative (e.g. cancel_post or create_post) for the cases it excludes, 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?

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 cover idempotency and safety, but the description adds far more: required scopes (ai:generate, posts:write), credit costs per kind, the refund-once-failure policy, and that applied=false results are retained separately because user edits won. This is exactly the behavioral context structured fields can't carry.

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

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

Front-loaded with purpose and prerequisites, and nearly every sentence carries operational information. The telegraphic, run-on style ('for 2+10*count credits') is dense and occasionally cryptic, but length is justified by the four-kind complexity.

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, costly, mutating generation tool with no output schema, the description covers cost, prerequisites, idempotency, failure/refund behavior, follow-up polling, and result-state handling. An agent has everything needed to call it safely.

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

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

With 0% schema description coverage, the description must carry the load and does: kind semantics, that maxCredits is a spend cap, that idempotencyKey must be stable and never charges twice, that references must belong to the profile, and that illustration needs projectId and slideId. This meaningfully exceeds what the raw schema exposes.

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 states a specific verb and resource ('Starts durable AI generation') and immediately enumerates the four kinds it produces. It clearly differentiates itself from siblings by routing to studio_quote for quoting, studio_job for polling, and studio_export for export.

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 sequencing ('Quote first', 'Poll studio_job') and a spending policy ('Ask before spending unless already delegated'). It also names the alternative actions for export and publishing, so the agent knows what this tool does NOT cover.

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 genuinely non-obvious behavior: the state machine's semantics and the fact that a failed job means credits were returned. It still doesn't say whether repeated polling is expected or whether results persist, so it's not 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: the action first, then the state semantics, then the exclusion. 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?

With no output schema, the description usefully enumerates the possible status outcomes, which is the key return-value information an agent needs. The remaining gap is the provenance/format of jobId, which leaves a small but real hole for a required parameter.

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 parameter jobId has 0% schema description coverage and the description says nothing about it — not where the ID comes from (presumably studio_generate/studio_quote/studio_save) nor its format. With only one param, the description could easily have closed this gap and didn't.

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 (Read) and resource (a saved generation), and explicitly fences itself off from the sibling studio_generate with 'This does not start another generation.' An agent can distinguish it from studio_generate/studio_save without opening a schema.

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

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

The status enumeration (queued/planning/generating/saving = in progress, ready = result, failed = credits returned) tells the agent when this tool is the right call and what outcome to expect. It never names an alternative tool explicitly, so it falls short of a full when/when-not routing statement, but the negative clause covers the main confusion.

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 supply readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful scope context with 'Results belong only to this credential's profile', but says nothing about volume limits, pagination, or what happens if no studio content exists yet.

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

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

Two tight sentences, the resource list front-loaded in sentence one and the scoping caveat second. No filler and nothing redundant with the title.

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

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

With no output schema, the description carries the return-value burden and does so reasonably by naming the four categories of content returned. It stops short of describing shape or limits, but a read-only zero-arg listing tool is nearly covered.

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

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

The tool takes zero parameters and the schema is empty, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter claims are made or 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?

Names a specific verb (Read) and enumerates the resources returned: saved carousels, video covers, generation progress, and the shared AI credit balance. That is enough to distinguish it from studio_generate or studio_export, though it never names or contrasts with the closest sibling, studio_job.

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 when-to-use guidance and no mention of alternatives such as studio_export, studio_templates, or studio_job, all of which live in the same family. The agent must infer from the resource list alone whether this is the listing call it wants.

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 useful pipeline context by naming which fields are editable downstream via studio_save, but says nothing about auth requirements, failure modes, or response shape beyond 'document and revision'.

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 with no filler, and the read scope is front-loaded ahead of the studio_save editing note. Slightly compressed jargon ('document and revision') costs a bit of clarity but there is 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 single-parameter read tool with no output schema and read-only annotations, the description covers the core read scope and the edit pathway adequately. It is thin on how to obtain a projectId and on the shape of the returned document, which keeps it from 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% and the description never mentions projectId or where a valid project id comes from (e.g., studio_list or studio_templates). With a required, undocumented identifier, the description fails to compensate for the schema gap. Only the loose association between 'carousel or cover' and a project partially helps.

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 (Read) and resource (a carousel or cover's document and revision), which an agent can distinguish from the sibling studio_save and from generic post readers like get_post. It does not explicitly contrast itself with other studio_* tools beyond the editing counterpart, so it falls just short of a 5.

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

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

The mention that text, slide order, style, format and image references '(are) editable with studio_save' implicitly routes the agent to the write path and implies this tool is the read counterpart. However, there is no explicit when-to-use statement, no prerequisites, and no guidance against using it for non-carousel/cover posts.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is partly covered. The description adds real behavioral value beyond that: "No credits are spent" and that manual edits/export are free, which is precisely what an agent needs to know before deciding to quote vs. generate.

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 (no credits spent) is front-loaded, followed by a compact per-kind price list. Every clause carries information; 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?

For a read-only quoting tool with no output schema, the description supplies the cost model, the no-spend guarantee, and the count prerequisite. It stops short of saying what the returned quote actually looks like, but that gap is minor 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 schema description coverage at 0%, the description carries the burden and largely delivers: it maps enum meanings to costs (outline 2, carousel 2 + 10 per slide, cover/illustration 10) and flags that carousel requires count. It does not restate count's 2-10 bounds, so the mapping is nearly but not fully 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 states a specific action (get the exact credit charge) and resource (AI generation) and implicitly separates itself from the sibling studio_generate by stressing that no credits are spent. It stops short of naming the generate tool it precedes, but an agent can still tell the two apart.

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?

"Get the exact credit charge before generating" gives a clear usage context (call this first, then generate), and "requires count" states a prerequisite tied to one pricing branch. It does not explicitly name the alternative tool or say when a quote is unnecessary.

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 by disclosing that stale revisions are rejected (optimistic concurrency), that image IDs from another profile are refused (cross-profile scoping guard), and that manual edits incur no cost. These are exactly the kind of failure modes and side-effect boundaries an agent cannot derive from destructiveHint/idempotentHint 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?

Four short sentences, front-loaded with the core action and constraint, and each clause carries distinct information (revision guard, profile guard, cost, non-effects). No filler or repetition, though the phrasing is clipped into fragments rather than a flowing structure.

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

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

For a destructive, non-idempotent mutation with no output schema, the description covers side-effect boundaries, rejection conditions, and cost, which is most of what an agent needs. It leaves permission/auth requirements and the shape of the document payload unaddressed, but the essential behavioral picture is 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% across all three required parameters, so the description must carry the burden. It only hints at 'revision' semantics (staleness) and image IDs inside the document; projectId and the free-form document object remain entirely unexplained despite nested-object complexity.

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 (save an edited Studio document) and pins the scope to its current revision. The closing clause ('No publishing or AI generation occurs') actively differentiates it from siblings like create_post and studio_generate, so an agent can route correctly without opening a schema.

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

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

It implies the correct context by ruling out publishing and AI generation, and notes that stale revisions are refused, but it never states an explicit when-to-use condition or names an alternative sibling (e.g., use studio_generate to produce content first). Usage is inferable 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 read-only and closed-world, so the bar is lower; the description still adds real context: templates are free to call, and selecting one pushes its brief into the chat, which is a side effect an agent should know about. It does not describe pagination or how many templates come back, a minor 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?

The two sentences are dense but front-load the core identity before the workflow, and every clause carries information. The run-on phrasing around the field list and the handoff to studio_quote/studio_generate could be tightened 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?

With no parameters and no output schema, the description must itself convey what comes back, and it does by listing the fields of each template. The only omitted details are volume/pagination and any cost notes beyond 'free to 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?

There are zero parameters, so the baseline is 4. The description instead characterizes the returned objects (look, story, count, format, brief slots), which is useful for a no-arg tool but belongs to output semantics rather than parameters.

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

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

The description concretely enumerates what the tool surfaces (a slide, its look, story, slide count, format, and a brief with [slots]), which tells an agent far more than the name alone. It lacks an explicit verb ('list'/'browse'), but the resource and its contents are unambiguous and distinguishable from studio_generate/studio_quote.

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 names a clear triggering condition ('when someone wants a carousel or cover and has no idea yet') and routes the agent down the pipeline: this tool, then studio_quote, then studio_generate. No explicit when-not or exclusion against studio_list, but the use case is clearly scoped.

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 annotation, the description adds important behavioral context: it publishes nothing, returns every problem at once with each naming the channel and field, and carries no cost. This clarifies return shape and side-effect behavior where no output schema exists.

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 written sentences with zero waste. The core behavior and non-publishing guarantee are front-loaded, and the call-to-action is direct and memorable.

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 validation tool with rich schema coverage and no output schema, the description supplies the essential missing context: what the return value contains (every problem, channel and field) and the safety guarantee (publishes nothing). Nothing needed 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 coverage is 100%, so the schema already documents all seven parameters in detail. The description only mentions channels implicitly and adds no syntax or format guidance beyond what the schema provides, so the baseline 3 applies.

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

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

The description states a specific verb and resource: it checks a post against every named channel and explicitly does not publish. It also distinguishes this validation tool from the sibling create_post, making the purpose unmistakable.

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 instructs the agent to call this before create_post every time and explains why: it costs nothing and prevents learning rules by publishing badly. The alternative (skipping validation) is implicitly discouraged, and the trigger condition 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 and openWorldHint=true, so the safety profile is covered; the description goes further by disclosing the credential mode semantics (autopilot publishes vs. review only prepares), per-day post quota, and whether the subscription permits publishing at all. It doesn't cover failure modes or latency, so it stops short of the richest possible disclosure.

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

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

Two sentences, front-loaded with what the caller gets and closed with when to call it; nothing is wasted. The middle clause is a long comma-chained enumeration of return fields, which is slightly heavy but each item is distinct and load-bearing.

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 does so completely: identity, credential mode, scopes, reachable channels, remaining daily posts, and subscription publishing eligibility. An agent can call this cold and know exactly what it will learn.

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 nothing for the description to disambiguate and the baseline is 4. The description instead spends its words on the return surface, which is the right allocation for a zero-arg tool.

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

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

The description names a precise resource (the current profile's ID/name and the capabilities bound to this credential) rather than restating the 'whoami' name. It is immediately distinguishable from every sibling tool, none of which report credential state or quotas.

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 ordering guidance — 'Call this before anything else' — and justifies it with an outcome ('it answers the questions you would otherwise discover by being refused'). The condition for using it is unambiguous and no alternative tool competes for the same purpose.

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