Create Story Task

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

With no annotations, the description carries the full burden, but it only says 'Add a checklist task' without revealing important behavioral details. It does not disclose the write confirmation requirement (confirm='CONFIRM_WRITE'), the dry_run option, or whether the action is reversible. This leaves the agent unaware of safety mechanisms visible in the schema.

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 a single concise sentence with no filler or repetition. It is front-loaded and easy to scan, though it is sparse enough that some behavioral and parameter information is missing.

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?

Given the tool has six parameters, no annotations, and no output schema, the one-sentence description is inadequate. It does not mention the confirmation/dry-run workflow, the meaning of optional fields, or what the tool returns after creating a task, leaving significant gaps for an agent to operate 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 description coverage is only 17%, and the description does not compensate. It implicitly conveys that story_id identifies the target story and description is the task text, but it omits semantics for owner_ids, complete, confirm, and dry_run, which are not described in the schema either.

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 with a specific verb ('Add') and resource ('checklist task to a Shortcut story'). It unambiguously distinguishes this from siblings like create_story, update_story_task, and delete_story_task.

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 gives no explicit guidance on when to use this tool versus alternatives. It does not mention exclusions or direct the user to update_story_task or delete_story_task for modifications or removals, leaving usage to be inferred entirely from the name and one-line description.

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