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

Annotations already declare destructiveHint=true, readOnlyHint=false and openWorldHint=true; the description adds genuinely useful context beyond that — each run hits the live web and refresh charges half rate for a changed row versus 1 cent for an unchanged one. However, it never discloses the consequences of creation (a persistent, billable, cancelable schedule), and it names fields that do not exist in the schema (monthly_maximum_cents, scheduled_monthly_cents), which muddies rather than clarifies behavior.

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 opening clause is front-loaded and the sentences are dense but on-topic, with no filler. It nevertheless restates the per-period limit concept three times in successive sentences while spending zero words on the majority of required parameters, so the budget is misallocated relative to what an agent needs.

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?

This is a complex creation tool: 8 parameters, 7 required, a nested scope object with its own required ast_hash, a nested calendar_schedule, and no output schema. Against that complexity the description covers only the cost model portion of two fields and leaves the scope selector, validity window, first due time, idempotency key, and the cadence_seconds/calendar_schedule relationship entirely unexplained.

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 the param burden, yet it explains only per-run versus per-period limits and does so using names absent from the schema (monthly_maximum_cents, scheduled_monthly_cents versus the actual period_cents / per_run_cents). Seven required parameters — idempotency_key, valid_until, first_due_at, scope, and the cadence_seconds vs calendar_schedule choice — receive no explanation, and the 'hourly to yearly' phrasing only hints at the cadence_seconds >= 3600 floor.

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 conveys the core idea — a recurring scheduled request that reads the live web — but never plainly states that this tool creates a new monitor/schedule, and it never distinguishes itself from update_capacity_schedule or list_capacity_schedules. The verb 'Runs a request on a schedule' describes ongoing behavior rather than the creation action the name and title imply.

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?

No when-to-use guidance at all: nothing about prerequisites (capacity balance, authorization), nothing about when to use this versus update_capacity_schedule or list_capacity_schedules, and no exclusions. The budgeting sentences explain the economics of a monitor but not when an agent should create one.

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