ds_set_schedule

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

With no annotations provided, the description carries the transparency burden. It discloses the key behavior that the schedule is created OFFLINE, requires activation, and defaults start/end times. It also notes the cron requirement change. It does not disclose error behaviors or permission needs, but for a create tool this is acceptable.

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 well-structured with a version note and a clear argument list. It is concise but slightly verbose due to the version history, though that information is valuable. Overall, all sentences contribute meaning.

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 create operation with no annotations and no output schema, the description covers the main purpose, key behavior (offline), defaults, and example format. It does not mention what is returned or any potential conflicts, but overall it is sufficiently complete for an agent to use 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 0%, so the description compensates fully. It explains every parameter: project_name and workflow_code identify the workflow, cron is a Quartz 7-field expression with an example, and start_time/end_time have explicit formats and default values. This is far more informative than the bare 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 states a specific action ('Create a schedule') on a specific resource ('workflow'), and clarifies that the schedule is created offline and must be activated with ds_online_schedule. This clearly distinguishes it from sibling schedule tools like ds_online_schedule, ds_update_schedule_cron, and ds_delete_schedule.

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 clear usage context by noting the offline creation and the need to activate with ds_online_schedule, plus a rationale for the required cron. It lacks explicit when-not-to-use guidance, but the offline/online distinction serves as a strong usage guideline.

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