combell_scheduled_tasks_update

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

Annotations indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds value by explaining the read-first then partial-update behavior, which is not obvious from annotations alone. It also implies non-destructive and idempotent semantics consistent with the annotations, with no contradictions.

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?

Two sentences, both purposeful. The first states the operation, the second adds crucial behavioral detail. No fluff or redundancy; the description is front-loaded and efficient.

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 an update tool with no output schema and annotations covering idempotency and non-destructiveness, the description provides the essential partial-update behavior. It does not mention error handling or edge cases (e.g., nonexistent task), but those are often outside the scope of tool descriptions. Given the complexity and annotations, it is reasonably complete.

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 40%, leaving enabled, domain_name, and scheduled_task_id undocumented. The tool description does not compensate; it only mentions 'fields you pass' without elaborating on their meaning or formats. While cron_expression and script_location have schema descriptions, the description adds no extra semantic value for the missing parameters.

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 operation: 'Update a scheduled task' with the verb 'update' and resource 'scheduled task'. It also distinguishes from siblings like create, delete, get, and list by focusing on partial modification. The additional sentence explaining read-first behavior further clarifies the specific purpose.

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 context on how to use the tool: 'only the fields you pass are changed' implies you should pass only the fields to modify. It doesn't explicitly name alternatives or exclusions, but the behavior is unambiguous and helps an agent decide when to use it over create/delete. This is adequate without being exhaustive.

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