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

Annotations already declare readOnlyHint, idempotentHint, and closed-world, so the safety profile is covered. The description still adds non-obvious context: no external HTTP calls, no auth required, and deterministic compile-time adapter constants, which tells the agent results can be cached and need no credentials.

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, zero padding, and the core purpose plus returned fields are front-loaded before side effects and routing guidance. Every sentence carries distinct information.

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

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

An output schema exists, so return-value documentation is not required, yet the description still sketches the payload shape. Combined with explicit side-effect and sequencing notes, the definition is complete for a single-param lookup tool.

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

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

Schema description coverage is 100% and the single 'channel' parameter is well documented with examples and the platform-prefix caveat. The description adds no additional parameter meaning, so the baseline of 3 applies.

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

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

Names a specific verb+resource ('Return static per-channel metadata') and enumerates exactly what comes back: character limits, Markdown support flags, tag vocabulary, CTA placement rules. It also implicitly separates itself from the post_* siblings by scoping itself to static, pre-composition data.

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

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

Explicit sequencing guidance: 'use channel_hints before composing a variant body' and 'use post_publish or post_schedule once you have a valid variant.' Names the alternatives and the condition that selects them, so an agent can route correctly without 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 cover the safety profile (openWorldHint, idempotentHint, destructiveHint=false), and the description adds real operational context beyond them: external HTTP requests per due entry, YAML backend writes, the exact idempotency key ('already-published (content.id, channel) pairs are skipped'), and the no-op case. Cron-safety is also disclosed explicitly.

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 action, then side effects, then routing. Every sentence carries distinct information (what it does, what it touches, when to pick it over alternatives) with no repetition.

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

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

An output schema exists, so return values need not be explained. For a single-optional-parameter trigger tool, the description supplies the side effects, idempotency semantics, failure-relevant behavior, and sibling routing an agent needs to call it correctly.

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

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

Schema coverage is 100% and the single 'now' parameter already documents its ISO-8601 format and default behavior. The description only echoes 'the given time boundary' without adding format or edge-case detail, so the schema does the heavy lifting and 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 with precise scope: 'Fire all scheduled posts due at or before the given time boundary.' The routing sentence separates it from post_publish/post_schedule (adding content) and post_status (inspecting results), so an agent can distinguish it from every sibling 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 explicitly says when to use it ('on a recurring schedule to flush the queue') and names the alternatives for adjacent jobs ('use post_publish or post_schedule to add new content; use post_status to inspect results'). Both the trigger and the exclusions are 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?

Goes well beyond the annotations by disclosing concrete side effects: outbound HTTP requests to each channel platform, writes to the local YAML publish state, and a requirement for valid credentials in the named profile. It also states the exact idempotency key (content.id, channel) and that re-runs return cached state without re-posting, which is far more specific than the generic idempotentHint=true annotation.

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, each earning its place: purpose, side effects, idempotency semantics, and sibling routing. Front-loaded with the action and scope before the caveats.

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

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

An output schema exists so return values need no explanation, and the description still covers mutation scope, auth prerequisites, idempotency, and alternatives. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100% and the nested objects are richly documented, so the schema carries the parameter burden. The description only points to helper tools (channel_hints, profile_list) rather than adding syntax or format meaning beyond the schema, making the baseline 3 appropriate.

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

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

States a specific verb (publish), resource (channel variants), and immediacy constraint in the first sentence. The immediacy qualifier distinguishes it cleanly from post_schedule and post_drain without needing the schema.

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

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

Explicitly routes: use post_publish for immediate-only delivery, post_schedule when any variant needs a future schedule_at, post_drain to flush a built queue. Names the alternatives and the condition that selects each, so no inference is required.

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

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

Annotations only declare readOnly=false, openWorld=true, idempotent=true, destructive=false. The description goes well beyond that by disclosing concrete side effects (writes to the local YAML schedule store, external HTTP calls for immediately-published variants), a credential requirement via profile_name, and the precise idempotency key (content.id, channel).

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 the core behavior, then side effects, then routing to siblings. Every sentence carries distinct information — no filler or repetition of the title.

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

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

For a 3-parameter mutation tool with nested objects, an output schema, and rich annotations, the description covers purpose, side effects, prerequisites, idempotency, and sibling routing. An agent has everything needed 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 description coverage is 100%, so the schema already documents content, variants, channel, schedule_at, extras, etc. in detail. The description restates the schedule_at/immediate split but adds no format or override semantics beyond what the schema provides; 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 ('enqueue channel variants with schedule_at for future publishing') and immediately clarifies the boundary condition that variants lacking schedule_at publish immediately. This distinguishes it cleanly from post_publish and post_drain without opening any schema.

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

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

Explicitly gives when-to-use ('any variant needs a future publish time') and names both alternatives with their selecting conditions: post_publish for all-immediate delivery and post_drain to process the scheduled queue later. Nothing 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 declare readOnly/idempotent/non-destructive, and the description adds meaningful extra context beyond them: no external HTTP calls, no auth required, deterministic given unchanged backend state. This is exactly the kind of behavioral detail the schema and annotations don't convey.

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

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

Three tight sentences, front-loaded with the return/filter behavior, then side effects, then sibling routing. No redundant or filler content.

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

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

With an output schema covering return values and annotations covering safety, the description adds the scoping, side-effect, and routing details an agent needs. Nothing essential to correct invocation is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds the combined-filter semantics ('content_id, channel, or both; returns all entries when neither') that clarify how the two optional params interact, slightly exceeding what the schema states per-field.

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 ('Return publish state for content pieces') and defines the filtering scope (content_id, channel, or both; all entries otherwise). It clearly separates itself from the mutating siblings it names (post_publish, post_schedule, post_drain).

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 use cases ('inspect what has been published, what is queued, or what errored') and routes the agent to the correct alternative tools for state changes. The when-to-use vs when-to-change distinction is unambiguous.

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

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

Annotations already declare destructive, non-idempotent, and open-world, but the description adds substantial context beyond them: it describes the actual side effect (external HTTP DELETE or update request), platform-specific behavior (DEV.to soft-deletes via published=false; platforms lacking a delete API return success=false without error), and the non-idempotent 404 case. This is exactly the behavioral detail structured fields cannot convey.

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

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

Front-loaded with the core action, then side effects, then usage routing. Every clause carries distinct information — no filler, no repetition of the title or schema.

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

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

An output schema exists, so return-value explanation is unnecessary; the description instead covers the risk profile an agent needs (soft delete, silent success=false, 404 on repeat). Complete for a destructive cross-platform tool.

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

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

Schema coverage is 100% with clear per-parameter descriptions (channel slug, live_url format), so the schema already carries parameter meaning. The description references live_url via post_status but adds no syntax or format detail beyond the schema, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Best-effort delete of a published post on the target platform') and immediately frames the scope as retracting a live post. An agent can distinguish it from post_publish, post_status, and post_schedule without opening any schema.

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

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

Explicitly routes the agent: use this to retract a live post, use post_status first to obtain the live_url, and use post_publish to re-publish afterward. It names both the prerequisite and the reverse operation, 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, idempotentHint, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context beyond them: no external HTTP calls and deterministic results given backend state, which tells the agent the call is cheap and stable to repeat. It does not cover item shape, but the output schema handles that.

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 return value, then side effects, then usage, all in a compact block. The 'read-only' note mildly duplicates the readOnlyHint annotation, costing a little redundancy, but the rest of the sentence earns its place.

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

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

For a no-arg list tool with a full annotation set and an output schema, the description supplies everything needed: what it returns, where it reads from, determinism, and how the result feeds other tools. Return-value detail is correctly left to the output schema.

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

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

The tool takes zero parameters, so the baseline is 4. The description still helpfully explains the role of the value it produces (profile names, consumed as profile_name elsewhere) without inventing parameter semantics that don't exist.

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 ('Return all distribution profile names') and scopes it to the 'YAML backend', which clarifies it is not scanning external systems. An agent can distinguish it from the post_* siblings, which perform actions rather than enumerate profiles.

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 tells the agent when to use it ('to discover available profiles before calling post_publish, post_schedule, or subreddit_list') and what to do with the result ('pass the chosen name as profile_name'). This is a full when-to-use plus downstream wiring, 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, idempotentHint=true, destructiveHint=false and openWorldHint=false. The description goes beyond that by adding 'no external HTTP calls' and 'Deterministic given backend state,' which are useful operational guarantees. It does not cover error/empty-catalog behavior, so it is 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?

Three sentences, front-loaded with what is returned, then the optional filter, then the intended workflow. Slightly redundant with the annotations ('Side effects: read-only') but overall dense and without filler.

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

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

An output schema exists, so return-value explanation is not strictly required, yet the description still names the key returned fields. Combined with the workflow guidance and the single fully-documented parameter, an agent has what it needs; only edge behavior (empty catalog, invalid profile_name) is unaddressed.

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

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

Schema description coverage is 100%, so profile_name's filtering semantics are already fully documented in the schema. The description restates the same filter behavior (subreddits allowed by the named profile) without adding format, matching, or precedence detail beyond the schema, 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 and resource ('Return all subreddits in the Subreddit Catalog') and enumerates the payload fields (cooldown windows, flair vocabulary, last-posted metadata). It is clearly distinguishable from the post_* and profile_list siblings, which operate on posts and profiles rather than the subreddit catalog.

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

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

Explicitly states when to use it: 'Use subreddit_list to select a subreddit and obtain flair IDs before composing a reddit: channel variant' and where to put the result (variant.extras.flair). It also states the optional profile filter and that omitting it returns the full catalog, leaving no ambiguity about invocation.

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