Shoot Plan

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds that the returned state is authoritative ('truthful') and enumerates the state categories returned, which is modest added context, but it discloses nothing about freshness, caching, or auth requirements.

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?

A single front-loaded sentence with no filler; the scope categories are listed inline and nothing is repeated from the title or schema.

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?

An output schema exists, so return values need not be described in prose, and the one-line description covers what the tool reports. What is missing is the routing context (when an agent should call this instead of the sibling status/get tools), which leaves the definition slightly incomplete for a capabilities probe.

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?

The tool takes zero parameters, so the schema leaves nothing to explain and the baseline is 4. The description does not need to compensate for any undocumented parameter.

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 (Return) and a concrete resource (Shoot Plan scope, availability, privacy and commercial state), which reads as a capabilities/self-description tool and is distinguishable from create/get/list/quote/revise siblings. It stops short of naming any sibling or explicitly saying 'capabilities', so differentiation is inferential rather than stated.

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?

There is no when-to-use guidance, no mention of when to prefer this over shoot_plan_status or shoot_plan_get, and no prerequisites. The word 'truthful' hints at a source-of-truth role but never tells the agent when to call it.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and openWorldHint=false. The description adds two pieces of context those annotations do not carry: the caller must be an authenticated organisation, and an authoritative payment must already exist. That is genuine added value, but it says nothing about the consequence of a duplicate submission, whether a payment is consumed, or what the created plan contains.

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?

A single front-loaded sentence with the verb first and no filler. It is sized correctly for what it attempts, though the brevity is partly achieved by omitting information the tool needs rather than by editorial discipline.

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 high-complexity creation tool with a two-variant oneOf intake, ~20 required nested fields, a preferred intake version, a mandatory safetyAcknowledged flag, and an idempotencyKey. An output schema exists so return values need not be explained, but the description omits which intake variant is current, how safety acknowledgement is satisfied, and how the idempotency key should be generated or reused — all material for correct invocation.

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 33%: orderId is documented in the schema, while intake and idempotencyKey are not. The description mentions no parameter at all — not the idempotencyKey, not which of the two intake variants to send, not how orderId is obtained. With low coverage the description is expected to compensate, and it does not.

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 states a specific verb and resource ("Create a plan") plus two scoping conditions (authenticated organisation, post-payment). However, it does nothing to distinguish this tool from siblings such as shoot_plan_revise, shoot_plan_quote, or shoot_plan_revision_preview, leaving the agent to infer the boundary from the name alone.

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 clause "after authoritative payment confirmation" implies a precondition for calling, which is real guidance. But it names no alternatives and gives no explicit when-not condition, so an agent cannot tell from the text whether this is the first step or a follow-up to shoot_plan_quote.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the plan is synthetic, is produced by the real planner (so format-faithful), and carries provenance — telling the agent the payload is not live tenant data.

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?

A single front-loaded sentence that identifies the resource, its synthetic nature, and its provenance with no filler. Nothing is repeated from the schema or annotations and nothing is wasted.

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?

With an output schema present, return values need no explanation, and the description states what is returned and where it comes from. It could go one step further and note that the example is static/detached from any user's account, but for a no-argument read tool this is essentially 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?

The tool takes zero parameters, so the schema has nothing to document and the baseline of 4 applies. The description correctly implies a parameterless call and does not mislead about inputs.

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 states a specific verb and resource: returning a synthetic example plan, plus its provenance, which clearly separates it from data-returning siblings like shoot_plan_get and shoot_plan_list. It is clear on its own, though it never explicitly names those siblings or states that this returns no real user data.

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?

Usage is only implied: an agent can infer this is for inspecting what a plan looks like without creating one. There is no explicit when-to-use, when-not-to-use, or routing advice across the ten sibling tools, several of which (get, list, capabilities) are informational and could be confused with this one.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description reinforces it with 'Read-only' and, more valuably, discloses an access-scoping rule not present in annotations: 'Connections see only their own live or owner-test plans.' It still omits failure behavior for invalid or unauthorized IDs.

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?

Front-loading is weak: the first and longest sentence is a return-value inventory, much of which duplicates the existing output schema, while calling guidance is buried at the end. Individual clauses are information-dense, but the payload enumeration crowds out invocation guidance and reads as a run-on.

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?

With an output schema present, the description needn't detail return fields, yet it adds the pieces an agent genuinely needs: where taskId comes from, the ID-format alternatives, read-only status, and the connection visibility limit. Nothing essential for a correct call is missing.

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% (taskId is a bare string), so the description carries the full burden and does so well: taskId is a full task ID from shoot_plan_list, explicitly not a planId, and a unique eight-character prefix or orderReference is also accepted. That is real disambiguation the schema cannot provide.

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 ('Return a full plan') and enumerates exactly what the plan payload contains, so the agent knows this is the detail fetch rather than a list. It references shoot_plan_list as the source of taskId, which implicitly separates the two, but never explicitly contrasts itself with siblings like shoot_plan_status or shoot_plan_revision_preview.

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?

Gives concrete input-sourcing guidance ('Use the full taskId from shoot_plan_list (not planId)') and an explicit alternative ('a unique eight-character task prefix or orderReference also works'), plus redirects to shotId for progress work. It does not state when not to use this tool or what happens on a missing/ambiguous ID.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavioral detail beyond that: default sort order, default exclusion of archived plans, and suppression of private intake/full plan content. It does not discuss pagination or result-size limits for a list endpoint.

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 tight, front-loaded sentences ordered from scope to ordering to filtering to ID linkage; each contributes. The trailing 'Structured result: {plans:[...]}' is mildly redundant given an output schema exists, which keeps it from a 5.

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?

With an output schema present and annotations covering the read-only profile, the description only needed to cover scope, ordering, filtering defaults, and cross-tool ID semantics — all of which it delivers. Nothing required to call this list tool correctly is missing.

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 100% with a single, fully documented boolean ('Default false'), so the schema already does the heavy lifting and the baseline is 3. The description's restatement of includeArchived adds no syntax or default nuance the schema lacks.

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 ('List the authenticated organisation's Shoot Plans') plus scope (organisation-wide), ordering ('most recently changed first'), and content boundaries. It also links itself to siblings by noting taskId is 'the ID every other plan tool takes', so an agent can distinguish it from shoot_plan_get without opening schemas.

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?

Gives a clear condition for the archived case ('Archived plans are left out unless includeArchived is true') and an implicit routing cue by stating it does not return 'private intake or full plan content', pointing toward the detail tool. It never explicitly names an alternative tool or states when-not-to-use, so it stops short of full dual-sided guidance.

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

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

Annotations only assert idempotentHint/destructiveHint; the description goes well beyond them by explaining retry safety (same opId does nothing twice), the stale-version conflict rule (older basePlanVersion still applies unless the item changed, otherwise item_changed_in_current_version with no mutation), and that 'complete' means a human checked the shot, not technical quality. This is exactly the mutation/conflict context an agent needs before writing.

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 core action leads, followed by the op payload contract, retry/conflict semantics, and identifier rules, so it is front-loaded and every sentence carries information. It is dense and telegraphic, and the identifier/visibility details could be split more cleanly, but there is no filler.

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 batched idempotent mutation with a nested op array and repeated parameters, the description covers payload construction, idempotency, version conflict outcomes, identifier sourcing, and access scoping. With an output schema present it does not need to describe return shapes, and it already names the partial-failure result string.

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 full burden and does: it defines opId as a fresh random UUID v4, basePlanVersion as the plan's current version, itemKey syntax, and the state enum values, plus the taskId format rules (full id vs. 8-char prefix vs. orderReference). Only the optional recordedAt field is left undiscussed, which is minor.

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 precise verb pair (tick/untick) and the exact resources affected (shot:<shotId> and check:<itemId> items in a shoot plan), which is far more specific than the title 'Tick off shots'. It references shoot_plan_get and shoot_plan_list as the sources for its inputs, implicitly separating it from those read-only siblings, though it never names a sibling it replaces or rules out.

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?

Gives clear operating context: itemKey values come from shoot_plan_get, taskId comes from shoot_plan_list (not planId, with prefix/orderReference alternatives allowed), and the visibility rule for Connections is stated. There is no explicit when-not-to-use or routing against alternatives such as shoot_plan_revise, which is the only gap.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds meaningful context beyond that: the quote is deterministic, based on public/non-private metadata, and must not include a script or brief. Those are useful behavioral constraints not present in the annotations.

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 tightly written sentences with no filler. The core purpose is front-loaded, followed immediately by the key exclusion, so every sentence earns its place.

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 tool with 11 parameters, 7 required fields, and very low schema description coverage, the description is too sparse. It covers privacy and determinism but leaves required inputs, enum meanings, and constraints undocumented. The existing output schema reduces the need to explain return values, but the input contract remains inadequately explained.

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 18% for 11 parameters, so the description must compensate but does not. It mentions no specific fields, enums, required values, or constraints; only the generic phrase 'project metadata' appears.

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+resource: calculate a deterministic public quote. It clarifies the input domain as non-private project metadata, which helps distinguish it from sibling tools such as create/get/list. It does not explicitly name or compare alternatives, so it stops short of a 5.

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 an explicit exclusion — 'Do not send a script or brief' — and implies the correct input is project metadata. However, it does not say when to choose this over sibling tools like shoot_plan_timing or shoot_plan_create, leaving usage partly inferred.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds meaningful context beyond them: the change is irreversible, it consumes a one-time allowance/quota, it requires human confirmation via a preview call, and it is scoped by connection visibility. That is exactly the kind of irreversibility and budget information an agent needs before committing.

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?

Front-loads the purpose and the destructive consequence in the first sentence, then layers prerequisites and parameter guidance. Dense but waste-free; the trailing taskId and visibility clauses are useful, though they read as appended rather than integrated.

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?

An output schema exists, so return values need not be explained, and annotations carry the safety profile. However, for a tool with nested objects and two undocumented required parameters, the description omits what belongs in `request` and how idempotencyKey governs retry behavior — gaps an agent must close elsewhere.

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 13% with 8 parameters (3 required), so the schema leaves most semantics unexplained. The description compensates partially by naming constraintUpdates.availableMinutes, locationTransferMinutes, framing, and structuredChanges, and by explaining the taskId prefix/orderReference fallback, but the required `request` payload and required `idempotencyKey` are never described, nor are replacementBeats or audioPriority.

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 action on a specific resource: "Use the plan's one included revision," and enumerates what a revision can change (filming time, transfer time, framing, structuredChanges) for structured plans. An agent can distinguish it from shoot_plan_revision_preview, though the term "included revision" leans on product jargon that isn't self-defining.

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?

Explicit sequencing and preconditions: call shoot_plan_revision_preview first and confirm with the person, since the action cannot be undone. It also names the correct identifier source (full taskId from shoot_plan_list, not planId) and the visibility scope (connections see only their own live or owner-test plans). Both when-to-use and the prerequisite alternative are stated.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), so the bar is lower. The description adds real context: it never consumes the provided revision, it is limited to structured plans, and Connections see only their own live or owner-test plans (an authorization/visibility constraint). These are useful non-obvious behaviors beyond the annotations.

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?

It is front-loaded with the most important constraints (structured-plans-only, never uses the revision) before the explanatory example and id guidance. Dense but each sentence carries weight; slightly list-like rather than smoothly structured.

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 complex nested schema and the presence of an output schema, the description need not explain return values, and it covers eligibility, id sourcing, and scope visibility. It is largely complete, with the gap being undocumented meanings for several optional parameters.

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?

With only 17% schema description coverage, the description should carry more of the param burden. It does explain taskId semantics well (full id vs planId, prefix/orderReference accepted) and gives a concrete example for constraintUpdates.availableMinutes, but framingMode, audioPriority, replacementBeats, and the structuredChanges object are left unexplained in both schema and description.

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 gives a specific verb+resource ('Preview a revision') and explicitly scopes the behavior against the sibling shoot_plan_revise with 'without using it' and 'Never uses the included revision.' It also states the three concrete outputs (what would change, which checked shots would be cleared, whether it still fits), so an agent can tell exactly what this does and how it differs from applying a revision.

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?

It states eligibility rules ('Structured plans only; older free-text plans cannot be previewed') and how to source the id ('Use the full taskId from shoot_plan_list... A unique eight-character task prefix or orderReference also works'). It implies the when-to-use case (dry-run before applying) but does not explicitly say to prefer it over shoot_plan_revise, so 4 rather than 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the 'Read-only' sentence is largely redundant. The one genuinely additive disclosure is the visibility constraint — Connections only see their own live or owner-test plans — which is a permission/scope behavior not captured by the annotations. No rate limits or failure modes are mentioned.

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 definition is compact and front-loads the return payload before moving to constraints. The opening sentence is a long comma-separated enumeration that reads a little list-like, but no sentence is wasted.

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?

An output schema exists, so return values need not be restated, yet the description still summarizes them usefully. Combined with the id-format guidance and the visibility constraint, an agent has everything needed to call this correctly without opening another 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 description coverage is 0%, so the description must carry the full load, and it does: it names the correct id type (taskId, not planId), names the tool that supplies it, and discloses two non-obvious accepted value forms (an eight-character task prefix and an orderReference). This meaningfully expands what the bare string schema conveys.

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 uses a specific verb ('Return') and enumerates exactly what comes back: status, version, whether the included revision is used, order reference, and progress details. That is far more specific than a tautology. However, it never differentiates itself from the sibling shoot_plan_get, leaving the agent to infer which of the two retrieval tools to pick.

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?

It gives concrete input-sourcing guidance ('Use the full taskId from shoot_plan_list (not planId)') and notes that a unique eight-character prefix or orderReference also works. The access caveat about Connections seeing only their own live or owner-test plans sets context. What's missing is any explicit when-not-to-use or comparison against the other read tools.

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

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.