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

Annotations already flag destructiveHint=true, openWorldHint=true and readOnlyHint=false, and the description usefully adds what the annotations can't: the required role and scope ('company admin and automation.manage'), the blast radius ('grants source reads and evidence capture, never customer effects'), and the side effect of disabling ('Pausing stops an active run'). It does not address the tension between idempotentHint=false and the optional idempotency_key, nor what a revision conflict does to the caller.

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 short sentences, zero filler, and the identity/upsert claim is front-loaded ahead of configuration surface, side effects and permission gates. Dense but each clause 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?

For a destructive 11-param mutation with no output schema, the definition covers authorization, effect boundaries and one side effect, which is solid. But the concurrency contract (what revision to send on create vs update, what happens on mismatch) and the audit 'reason' field are left entirely unstated, which is a meaningful gap for an upsert-by-revision 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 only 9% of 11 params, so the description carries most of the burden, yet it only enumerates name, instructions, schedule shape (interval or five-field cron), timezone and enabled at name level. It never explains expected_revision — a required field even on create, where the caller must presumably pass 0 — nor reason, company, environment or id.

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 pair (create or update) against a specific resource (scheduled native agent job) and adds the upsert framing 'at its expected revision', which distinguishes it from siblings like summer_scheduled_jobs_list, summer_scheduled_jobs_run and summer_scheduled_jobs_history. An agent can place this tool 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?

The 'create or update' framing plus 'Pausing stops an active run' makes the intended usage context clear, and the permission sentence sets a precondition. It stops short of naming explicit alternatives (e.g. use summer_scheduled_jobs_run to trigger a job now, or schedule/run naming) and gives no exclusions, so it falls short of the 5 bar.

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