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

Annotations already declare readOnlyHint=true, and the description confirms 'Read-only' consistently. It adds real context beyond the annotations: connection-level visibility ('Connections see only their own live or owner-test plans') and the distinction between plannedSeconds (the measured tick-to-tick steps only) and planPlannedSeconds (the whole plan's shot work). Missing only things like rate limits or precision/rounding 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?

Five compact sentences, each earning its place, with the scope caveat and the field-semantics warning front-loaded. Slightly dense and mixes field definitions with usage rules, but there is no filler or repetition.

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?

Because an output schema exists, return values need not be enumerated, yet the description still clarifies the ambiguous plannedSeconds vs planPlannedSeconds distinction. Combined with the read-only confirmation and access scoping, an agent has what it needs; only edge cases like empty ranges or non-tick plans are unaddressed.

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 carries the burden for the single taskId parameter — and it does so well, specifying the source of the value, the correct field name versus planId, and acceptable alternative formats (8-char task prefix, orderReference). No format example or case sensitivity is given, keeping it short of a 5.

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 and resource — comparing planned versus actual filming time between consecutive ticks in field mode — and immediately scopes it to structured plans, distinguishing it from the free-text plan surface. An agent can tell what this tool produces without opening a 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?

Explicitly excludes older free-text plans and tells the caller exactly which identifier to use: the full taskId from shoot_plan_list, not planId, with prefix or orderReference as accepted alternatives. This is the kind of routing detail that prevents a wrong-tool or wrong-argument call.

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