schedule_content

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It reveals the fallback for Postiz, but does not disclose side effects, error handling, return values, or what happens on success/failure. Since this is a mutation tool (scheduling), the lack of information about irreversible actions or permissions is a significant 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 description is two sentences with no waste. The primary action is front-loaded, and the fallback detail is placed efficiently at the end. Every sentence contributes to understanding the tool's purpose and 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 5 parameters, no output schema, and no annotations, the description should provide more detail. It explains the parameters and fallback but omits return value information, error cases, platform-specific limitations, and how the direct API path works. An agent cannot fully predict the outcome of calling this tool beyond the scheduling intent.

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

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

Schema description coverage is only 20% (only scheduled_time has a description), so the description must compensate. It lists the parameters and notes that media_urls are optional and scheduled_time uses ISO datetime, but it repeats the schema names without adding constraints like content_text length, hashtag format, or media URL validation. It adds slight value by clarifying optionality, but does not deeply explain any parameter.

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

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

The description clearly states the tool's function: scheduling social media posts, with routing options (Postiz or direct API). It distinguishes from siblings like generate_social_posts (content creation) and get_upcoming_posts (calendar retrieval) through the specific verb 'schedule' and the resource 'social media post'.

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

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

The description explicitly mentions the fallback to PostizPublisher.publish_post() when platform=postiz, which is a usage condition for routing. However, it does not directly name alternatives or state when not to use this tool; the context implies scheduling use, but no explicit guidance against using it for content generation or listing.

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