Schedule a post

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

The annotation only says readOnlyHint=false; the description adds substantial behavioral detail: the native scheduler fires even if the machine is asleep but the post cannot be listed/canceled via this server, while the local scheduler only fires while the server runs and may post late. It also notes session liveness and text finality for the native scheduler. This goes far beyond the annotations and is critical for safe use.

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

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

The description is longer than average but every sentence earns its place. It is front-loaded with the core purpose, then organizes the two scheduler trade-offs in an easy-to-scan bulleted list. The length is justified by the complexity of the decision the user must make, and there is no redundant or extraneous 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?

Given the tool's complexity (two modes with different operational guarantees), no output schema, and only a minimal annotation, this description is remarkably complete. It covers prerequisites (session live for native), failure modes (late posting for local), and cross-references to related tools for cancellation/listing. An agent has everything needed to invoke the tool correctly and advise the user appropriately.

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 good descriptions for scheduledAt, asPage, and scheduler. The description adds crucial semantic depth to the scheduler parameter by explaining the real-world consequences of 'native' vs 'local,' which the enum alone cannot convey. It doesn't add detail for 'text' but the schema's maxLength/minLength suffices. Overall, the description enriches parameter understanding beyond the structured 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 explicitly states 'Publish a post at a future time, through ONE of two schedulers,' which clearly differentiates it from immediate posting (create_post) and specifies the action, resource, and temporal scope. This is a distinct, well-defined purpose that distinguishes it from sibling tools.

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

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

The description provides explicit usage guidance: 'There is no default — ask the user which one they want BEFORE calling this, and state the trade-off.' It then details the two scheduler options and their trade-offs, including when each is appropriate. It also references sibling tools (list_scheduled_posts, cancel_scheduled_post) that work only with the 'local' scheduler, clarifying operational context.

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