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

The description discloses key behavioral traits beyond annotations: it explicitly states that the tool performs animation transitions and does not change content, and that it accepts multiple targets. Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description adds context about coordinated transitions and the need to combine with other tools. It could mention if there are rate limits or permission requirements, but overall quite transparent.

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 extremely concise: two sentences plus a compact argument listing. It front-loads the core purpose and caveats, with no wasted words. Every sentence adds essential 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?

Given the tool's complexity (4 parameters, 1 required, no output schema), the description is complete: it explains the purpose, usage context, relationship to other tools, parameter structure, and return format. No gaps are evident for an agent to use this tool 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 coverage is 100%, so baseline is 3. The description restates parameter structure (app/appToken, targets with subCompositionName/Id and state enum, response_format) but adds little new meaning beyond the schema's own descriptions. It does mention the return format '{ success, count }', which is not in the schema (no output schema), providing slight added value.

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 purpose: 'trigger animation state transitions to take sub-compositions on or off air'. It uses specific verbs and resources, and distinguishes itself from sibling tools like 'update_content' and 'update_and_animate' by explicitly noting what it does not do (change content).

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 explicit guidance on when to use this tool: 'to take sub-compositions on or off air', and when not: 'This does NOT change content — combine with update_content first, or use update_and_animate to do both atomically.' It names alternatives and explains the benefit of multiple targets.

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 provide safety hints (readOnly, idempotent, non-destructive). The description adds behavioral details: checks reachability, content-type, extension, and returns structured output. No contradiction.

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 concise (3 sentences), front-loaded with purpose, and efficiently covers args and returns without waste.

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?

Despite no output schema, the description specifies return fields and structure. It provides sufficient context for using the tool (pre-flight check before set_image).

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 100% and parameters are well-described. The description adds no further meaning beyond the schema, meeting baseline.

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 validates an image URL (well-formed, reachable, image-like) and explicitly links it to set_image usage, distinguishing it from sibling tools.

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 advises using this tool before set_image and as a pre-flight check. It does not explicitly list when not to use or alternatives, but the context is clear.

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, idempotentHint, destructiveHint. Description adds return format and filtering behavior without contradicting annotations, providing moderate extra context.

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-loaded with core purpose, then structured into Args and Returns. Every sentence adds value with no redundancy or fluff.

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?

Despite no output schema, description explicitly defines return structure ({ count, nodes: [...] }). Explains filtering, all 5 parameters, and typical use. Sufficient for agent to use 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 covers 100% of parameters with descriptions. Description adds examples and common use cases (e.g., 'image' for newsroom) but does not provide significant new semantic meaning beyond the schema.

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?

Description clearly states the tool searches control nodes across compositions by type/title, using specific verbs and resources. It distinguishes from siblings like singular_get_model by focusing on filtered search rather than full model retrieval.

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?

Provides clear context with examples (type='image', type='text') and mentions it saves hand-parsing, but does not explicitly state when not to use or name alternatives like singular_get_model.

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?

The description adds value beyond annotations by detailing the returned fields and mentioning 'derived control/command/model API URLs'. It also states the tool can confirm token validity. No contradictions with annotations (readOnlyHint, idempotentHint).

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 two sentences plus an 'Args' and 'Returns' line. It is front-loaded with key info and contains no redundant words.

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 no output schema, the description adequately explains return values. It covers input parameters and usage context. Could mention additional details like permissions but is sufficient for an agent.

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 100% with detailed parameter descriptions. The description briefly lists 'Args: app (alias) or appToken; response_format' but adds little new meaning. The baseline of 3 is appropriate.

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 verb 'Get' and resource 'app instance's metadata', listing specific fields such as numeric ids, name, folder, composition id, thumbnail, output URLs, and API URLs. It distinguishes from sibling tools as the only one for app metadata.

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 a specific use case: 'confirm a token points at the intended app and to grab a preview/output URL'. It does not explicitly compare to alternatives like singular_get_output_urls, but the sibling list is broader and this tool's purpose is clear.

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?

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds details on the return structure (entries with subCompositionId, subCompositionName, state, payload) and explains the state values (In/Out/Out1/Out2). This provides useful behavioral context.

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 concise with two sentences followed by a return type specification. It is front-loaded with the primary purpose, and every sentence adds value without redundancy.

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 read-only tool with comprehensive annotations, the description provides sufficient detail on the return format and state values. It lacks mention of potential limits or pagination, but is otherwise complete for its simplicity.

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 input schema covers all parameters with descriptions (100% coverage). The description merely lists the parameters without adding new meaning or clarifying usage nuances, so it meets the baseline but does not enhance understanding.

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 it gets the current on-air/staged state per sub-composition, including animation state and payload. It specifies the purpose as seeing what is live right now, but does not explicitly differentiate from sibling tools like singular_poll_onair_state.

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 says 'Use to see what is live right now,' implying a snapshot use case. However, it does not provide guidance on when not to use it or mention alternatives, such as singular_poll_onair_state for continuous monitoring.

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, idempotentHint=true, indicating safety. The description adds behavioral context by noting it returns default/reset values and that payload keys must come from this call. No contradiction with 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 sentences: first gives purpose and detailed output, second gives usage guidance and a parameter hint. No unnecessary words, front-loaded with key 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?

Despite no output schema, the description fully describes the return structure (subCompositions with fields). All 4 parameters are documented in schema, and the description adds context for their use. Siblings are addressed via usage guidance differentiating it as a discovery call.

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 100%, so baseline is 3. The description adds value by explaining that the returned control-node ids should be used as keys for writing content, and provides the full return structure, which is not in the schema.

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 specifies 'Get the structural model of an app: every sub-composition and its control nodes with id, title, type, default/reset values, and index.' It clearly states the verb, resource, and output, distinguishing it from siblings by emphasizing it as a schema-discovery call to run before writing content.

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 states 'run BEFORE writing content — payload keys must be control-node ids from here.' This provides clear when-to-use guidance and implies not to use when you already have the schema. It also mentions optional filtering via sub_composition.

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 readOnly, idempotent, non-destructive. Description adds critical behavioral context: client-side rendering and absence of server-side snapshot API. 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 short paragraphs: first gives purpose and a key note, second lists args and returns. No extraneous words, front-loaded with essential info.

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 high schema coverage, good annotations, and no output schema, description covers return fields and a major limitation. Missing error handling or edge cases, but sufficient for a simple read-only retrieval 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 100%, baseline 3. Description adds value by indicating 'app' is preferred over 'appToken' and briefly restates key args. The preference hint is useful beyond schema.

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?

Description clearly states the tool returns live output URL, broadcast URL, and thumbnail preview from an app instance. Specifies action (return/hand over) and distinguishes from siblings as it's the only tool specifically for output URLs.

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?

Description guides to hand URLs to human or browser renderer to see on-air content, and explicitly notes that Singular renders client-side with no server-side snapshot API, implying when not to use for snapshot needs. No explicit alternative tools mentioned but context is sufficient.

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 idempotentHint=true, so safety is clear. Description adds valuable context: 'never tokens' (security constraint) and return structure (count, apps with alias/name/addedAt). 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?

Single sentence with parentheticals, covering purpose, security note, parameter, and return shape. No filler words; front-loaded key info.

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 low complexity, full annotation coverage, and complete schema, the description is sufficient. Includes security constraint, return fields, and parameter hint. No missing information for a read-only listing 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 covers 100% of parameter ('response_format' with enum and default). Description adds context by showing return format and listing the parameter name. Provides return structure beyond schema.

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?

Specifically states 'List app aliases registered on this server (names + when added; never tokens)', clearly identifying the verb (list) and resource (registered app aliases). Differentiates from sibling tools like singular_register_app and singular_remove_app.

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?

No explicit guidance on when to use this tool versus alternatives. Does not mention context or prerequisites. The sibling list implies differentiation but description itself lacks usage instructions.

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, idempotentHint, destructiveHint. Description adds that it returns only aliases (no tokens) and specifies response formats. No contradictions, but lacks details on ordering or limits.

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?

One sentence covering action, args, and return value with zero wasted words. Front-loaded with core purpose.

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?

Tool is simple with 1 optional param and full annotations. Description provides return structure, but omits potential edge cases like empty list or error conditions. Adequate for a read-only list operation.

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 covers 100% of parameters with enum and default. Description adds the return structure beyond schema (count and dataStreams array), compensating for missing output schema.

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?

Description uses specific verb 'List' and specifies resource 'data streams registered on this server', clearly distinguishing it from sibling tools like push_datastream or register_data_stream. Parenthetical 'no tokens' adds precision.

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?

Clearly implies usage for listing aliases without tokens. No explicit when-not-to-use or alternative guidance, but sibling context makes this obvious. Could be slightly improved by noting it's the only list tool for data streams.

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, idempotentHint=true, destructiveHint=false, so the tool's safe read nature is clear. The description adds that it returns count and templates array, which is useful but does not significantly expand beyond what annotations convey.

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 two sentences, front-loaded with the core purpose, and efficiently conveys the return shape. No wasted words, though the args could be slightly better 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?

Given the tool's simplicity (one optional param, read-only, good annotations), the description covers the functionality and return format adequately. Minor gaps like pagination or ordering are not critical for a simple list 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 100% for the single parameter response_format, with a clear description of its purpose and default. The description mentions 'Args: response_format' but adds no new meaning beyond the schema.

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 it lists mapped rundown templates with their app, sub-composition, and field maps. This distinguishes it from sibling tools like singular_map_rundown_template which does mapping/creation, and singular_list_apps which lists apps.

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 mentions listing templates but provides no guidance on when to use this tool vs alternatives such as singular_map_rundown_template or other list tools. There is no explicit when-to-use or when-not-to-use context.

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 provide readOnlyHint, idempotentHint, destructiveHint; the description adds that it is a 'convenience read' and explains what it returns (joined model and state), plus mentions return format options. No contradictions, and the description enriches annotations with specific 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?

The description is two short paragraphs with no fluff. First paragraph explains the tool's purpose and return structure, second lists args and return format. 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?

Despite having no output schema, the description explicitly provides the return structure with nested fields (subCompositions containing nodes). Combined with 100% parameter coverage and clear annotations, the description is complete for the tool's complexity.

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 100%, so baseline is 3. The description adds minimal extra meaning beyond the schema: it notes that 'app' is preferred over 'appToken', which is a useful nuance, but does not provide new details for each 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?

The description states a specific verb ('joins') and resource ('model + live control state'), and explicitly lists the returned fields (id, title, type, current value). It distinguishes from sibling tools like singular_get_model and singular_get_control_state by noting it combines both.

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 clearly advises when to use this tool ('best single call to understand what can I fill and what's in it now'). It implies usage context but does not explicitly state when not to use or name alternatives, though the sibling list provides those hints.

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?

The description discloses that by default it validates the sub-composition and node ids against the live model, adding behavioral context beyond the annotations. Annotations are present and consistent; the description provides additional details like default validation and return structure, which compensates fairly.

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 relatively concise, front-loading the purpose. However, the 'Args:' section repeats schema information, adding some redundancy. Overall, it is efficient but could be slightly tighter.

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?

Despite having 7 parameters and no output schema, the description provides the core purpose, usage context (used by other tools), default behavior (validation), and return structure. It is sufficient for an agent to understand what the tool does and what it returns.

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 100%, so baseline is 3. The description lists the arguments but does not add new meaning beyond what the schema already provides. For example, 'fieldMap' is described as 'story field → nodeId' which mirrors the schema description. No extra semantics are added.

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 binds a rundown item type to a specific app + sub-composition and a field map. It provides concrete examples of item types like 'lower-third', 'ots', etc. It distinguishes itself from sibling tools by noting it is used by prepare_item and play_rundown_item.

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 mentions that this tool is used by 'prepare_item' and 'play_rundown_item', which provides context on when to use it. However, it does not explicitly state when not to use it or mention alternative tools. The usage is implied but not fully delineated.

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?

The description adds value beyond annotations by disclosing atomicity, in-memory auto-out that doesn't survive restart, and the return structure. Annotations already indicate it's not read-only, so the description appropriately details the behavior without contradiction.

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 concise with no wasted words. It front-loads the purpose, then lists arguments and return values in a structured manner. Every sentence serves a clear purpose.

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 complexity of the tool (write, atomic, nested input, return values), the description adequately covers inputs, key behaviors, and return fields. However, it lacks explanation of some return fields like 'unmappedFields' and 'missingNodes', and provides no guidance on when to use this tool relative to siblings.

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 100%, so baseline is 3. The description lists parameters in a human-readable format but adds little new meaning beyond the schema, except clarifying that 'fields' is a storyField→value mapping.

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 resolves a rundown item from its template and takes it to air, with atomic animation and optional auto-out. The verb 'take to air' is specific to this tool, distinguishing it from siblings like singular_prepare_item or singular_update_and_animate.

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?

No explicit guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusion cases, or compare to sibling tools like singular_prepare_item or singular_take_out_all.

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 indicate readOnly, openWorld, idempotent, non-destructive. The description confirms polling behavior and state reporting, adding context about change tracking. 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 short paragraphs, front-loaded with purpose. Every sentence is informative with no fluff.

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 annotations and schema richness, the description fully covers purpose, parameters, and return structure. It provides enough detail for an agent to use 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 coverage is 100%, so baseline is 3. The description restates parameter names and hints at usage but adds no new meaningful information beyond schema descriptions.

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 it polls live control state and reports which sub-compositions are on air vs off, plus changes since last poll. It distinguishes from siblings by highlighting its unique polling mechanism and change detection.

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 explains why polling is necessary (no webhooks) and includes the change-detection feature. However, it does not explicitly list alternatives or when not to use this tool.

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 indicate readOnlyHint, idempotentHint, openWorldHint, destructiveHint=false. The description reinforces that nothing is sent, and adds details about validation and return payload. 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 paragraphs: first explains purpose and usage, second lists args and returns. No redundant information. Slightly verbose but efficient overall.

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?

Despite no output schema, the description details the return object structure (template, subComposition, payload, unmappedFields, missingNodes, wouldSend). Combined with clear purpose and guidelines, it is fully informative.

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 100% (baseline 3). Description adds meaning by listing args in plain language: 'template (name)', 'fields (storyField → value)', 'response_format'. Also describes return fields, providing context beyond schema.

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 'dry run — does not go to air' and explains it resolves a rundown item against its template without sending. It distinguishes from sibling play_rundown_item by specifying it does not send.

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 says 'Use to preview/verify before air' and contrasts with play_rundown_item. The description makes clear when to use (preview) and when not (actual air).

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 (readOnlyHint: false, idempotentHint: false, destructiveHint: false) are supplemented by the description, which adds the 60 KB per package hard limit, sub-300ms delivery, and payload shape constraint. No contradictions, but could mention error handling.

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 and a brief args line convey all essential information without redundancy. The primary action is front-loaded, and every sentence adds value.

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?

The description covers key details: delivery time, rate limit bypass, payload size cap, shape requirement, and return format. No output schema exists, but return values { success, bytes } are provided. Missing error behavior, but adequate for a push operation.

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 100%, but the description adds value by clarifying the relationship between stream (alias) and privateToken (alternatives), emphasizing data is a JSON object (typical shape), and noting default response_format. This goes beyond the schema's descriptions.

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 pushes a JSON payload to a data stream for sub-300ms delivery, distinguishing it from other tools like singular_register_data_stream (registration) and singular_get_control_state (control API) by emphasizing speed and bypassing rate limits.

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 explicitly mentions when to use this tool (to bypass the control API's per-minute rate limits) and a prerequisite (payload shape must match linked sub-composition's expectations). It implies when not to use (if you need to use the control API), but does not explicitly list alternatives.

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?

Describes verification behavior (fetching metadata by default) and token security (never returned). Annotations already note readOnlyHint=false and destructiveHint=false; description adds useful context beyond these.

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 focused sentences plus a terse listing of args and return. No unnecessary words; every part 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?

Covers core behavior and return structure but does not address idempotency (whether re-registering with same alias updates or errors) or error conditions. With no output schema, more detail on verification failure could improve completeness.

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?

All 5 parameters are documented in the schema (100% coverage). The description adds value by explaining the token security implication and default verification behavior, which go beyond schema descriptions.

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?

Clearly states the tool stores a Singular app token under a friendly alias for later reference, with specific mention that the raw token is never returned. Distinguishes from sibling tools like singular_remove_app or singular_list_apps.

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?

Implicitly indicates use when needing to register an app token for alias-based referencing, but does not provide explicit when-to-use or when-not-to-use guidance compared to alternatives like singular_remove_app.

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 are all false, leaving behavioral disclosure to the description. The description mentions that the raw token is never echoed back and returns only the alias. However, it does not state whether storing the token overwrites an existing alias or any other side effects, which leaves gaps.

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 very concise with three sentences: main purpose, prerequisite/lifecycle, and args/returns. It is front-loaded with the key concept and has no wasted words.

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 only 3 parameters, no nested objects, and no output schema, the description covers the essential lifecycle (getting token from Dashboard, using with push_datastream) and return value. It does not explain error handling or alias uniqueness, but the tool is simple enough that these are minor omissions.

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 100%, so the schema already documents each parameter. The description adds minimal extra meaning beyond listing the args (e.g., alias, privateToken, response_format) and stating the return value. Baseline 3 is appropriate.

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 stores a private token under an alias for use by push_datastream. It specifies the verb 'store' and resource 'data stream private token', and distinguishes it from the sibling push_datastream by explaining the token is never echoed back.

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 explicit prerequisite steps ('Create the stream and get its private token from the Dashboard → Data Stream Manager') and explains the token is used by push_datastream. It lacks explicit when-not-to-use or alternatives, but the context is clear and helpful.

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?

The description claims the tool 'delete's' an app alias, which implies destructive behavior. However, annotations have destructiveHint: false, indicating the tool is not considered destructive. This contradiction is critical. No additional behavioral context (e.g., permission requirements, irreversibility) is provided beyond the annotation mismatch.

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 extremely concise: two sentences that front-load the main action and quickly list arguments and return value. No extraneous 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 simple 2-parameter tool without an output schema, the description covers the core action and return format. It could mention error behavior (e.g., what if alias does not exist) or dependencies, but overall it is fairly complete and usable.

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 schema already describes both parameters with 100% coverage. The description adds value by specifying the return structure '{ alias, removed }', which is not present in the schema. It also clarifies the purpose of alias as removing both the alias and its stored token, adding context beyond the schema's 'Alias to remove.'

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 action 'Delete an app alias (and its stored token) from the registry', using the specific verb 'delete' and identifying the resource as an app alias. This distinguishes it from sibling tools like 'singular_register_app' (create) and 'singular_list_apps' (list).

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 does not explicitly state when to use this tool versus alternatives, nor does it mention prerequisites or exclusions. However, the action is clear: if the goal is to delete an app alias, this is the tool. It lacks guidance on when not to use it or what to do instead (e.g., update).

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?

Adds context beyond annotations by specifying 'This changes on-air content if the sub-composition is live.' This explains the destructive nature beyond the destructiveHint annotation.

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 concise paragraphs. First explains purpose, second lists args and returns. No wasted words, front-loaded with key 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?

Covers return format and optional parameters adequately. Missing error conditions or prerequisites like requiring the model to exist, but still sufficiently complete for typical use.

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 100%, so the description adds minimal extra meaning beyond grouping parameters and confirming defaults. The baseline of 3 is appropriate.

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 verb ('Clear/reset') and resource ('control nodes to their resetValue'). It distinguishes from siblings like singular_update_content by focusing on resetting to a default value, not arbitrary updates.

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?

Provides a concrete use case ('handy to blank a template between stories/segments') but does not explicitly contrast with alternative tools or state when not to use 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 indicate read-only, idempotent, non-destructive. The description adds that it reveals only a boolean for token configuration (not the token itself) and lists the return fields, providing behavioral context beyond 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 concise sentences plus a one-line arg/return list. No filler. Front-loaded with purpose. Every sentence adds value.

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 simple info tool with one optional parameter, the description explains the return fields and security caveat. It doesn't need more. Missing explicit mention of idempotency, but that's covered by annotations.

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 input schema already provides a clear description for the only parameter (response_format with enum and default). The description mentions 'Args: response_format' but adds no new semantic meaning. Schema coverage is 100%, so baseline 3 is appropriate.

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?

Clearly states it reports server runtime configuration and health. The verb 'report' and resource 'server info' are specific. It distinguishes from sibling tools that are action-oriented or query specific entities.

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?

Implied usage context is obvious for getting server-level info. No explicit when-not instructions, but given the sibling list, this is the only tool for this purpose. The description states it doesn't reveal secrets, which guides usage.

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 provide safety hints, but the description adds significant behavioral detail: it validates node type via get_model, checks URL reachability, and supports force bypass. It also explains that validation is default on and mentions the urlCheck return field, giving full transparency beyond 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?

The description is well-structured with the main action first, then constraints, then parameter list. It is slightly verbose but every sentence adds value. Could be tightened, but not excessively long.

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 10 parameters and no output schema, the description covers all necessary context: authentication, node identification, validation behavior, force override, and return values. It also explains the limitation of no upload API, providing complete context for the agent.

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 100% schema coverage, baseline is 3, but the description adds strong value: it explains the preference for nodeId over nodeTitle, the interplay of app vs appToken, the effect of validate_url and force, and the response_format options. This goes well beyond the schema definitions.

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 purpose: 'Set an image-type control node to a hosted image URL'. It distinguishes this tool from siblings by specifying it's the only way to place imagery in Singular and explains the need for public URLs, making the intent unambiguous.

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 explains when to use the tool (the only way to set imagery) and provides guidance on validation and force flags. However, it doesn't explicitly mention when not to use it or compare to alternative tools like singular_update_content, though context implies its specific use case.

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 indicate destructiveHint=true and readOnlyHint=false. The description adds behavioral context: it uses POST /command with the action 'TakeOutAllOutput', animates overlays to Out state, and returns a success object. This adds value beyond annotations without contradiction.

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 extremely concise: two sentences plus a brief line for arguments and return value. Every sentence contributes essential information, with the purpose front-loaded. No wasted words.

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's simplicity (3 parameters, no output schema) and the presence of annotations, the description is largely complete. It covers purpose, action, HTTP method, and return format. Minor missing details (e.g., error handling) do not significantly impact usability for this clear-all operation.

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 100%, so baseline is 3. The description briefly lists parameters ('app/appToken; response_format') but adds no additional meaning beyond the schema's descriptions. It does not compensate for any gaps since there are none.

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 purpose: 'Animate every overlay in the control app to its Out state' and uses explicit terms like 'clear the screen', 'segment-end', and 'panic control'. It specifies the exact action and differentiates from siblings like singular_animate_state by focusing on clearing all output.

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 for when to use the tool ('clear the screen / segment-end / panic control') and mentions it is the only documented command action. However, it does not explicitly state when not to use it or mention alternative tools, which would strengthen 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 indicate mutability but no destructiveness. The description adds atomicity and the specific benefit of avoiding flash, plus the return structure. It does not contradict annotations and adds meaningful behavioral context beyond what annotations provide.

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 very concise: two sentences and an argument list. It front-loads the core purpose and eliminates unnecessary words. Every sentence adds value.

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's complexity (7 params, nested object) and no output schema, the description covers the return value and the core atomicity benefit. It could include more on error handling or idempotency, but the essential context is present.

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 100%, so parameters are already well-documented. The description lists argument groups but does not add significant new meaning beyond the schema. It provides some context for payload and state but mostly restates schema info.

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 performs an atomic set of payload and animation state to avoid flash, distinguishing it from separate fill-then-animate sequences. It uses a specific verb-resource combination and references sibling tools implicitly.

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 explains when to use the tool (to avoid stale content flash) and contrasts with a separate fill-then-animate approach. However, it does not explicitly list when not to use it or mention alternatives by name, though sibling tools exist.

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 indicate non-readonly, open world, not idempotent, not destructive. Description adds context: it sets content only, does not animate, and provides value formats per node type. Does not contradict 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?

Description is concise and well-structured: purpose, value formats, batching, exclusions. Each sentence adds value, though could be slightly tighter.

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?

Covers all aspects: purpose, parameters, value formats, batching, exclusions, and return value. No output schema, but return is described as { success, updatedCount }.

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 100%, but description adds significant meaning: explains value formats per node type, source of node ids, batching benefit, and preference of 'app' over 'appToken'. This goes beyond schema descriptions.

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 it fills control nodes of sub-compositions via PATCH, with specific verb 'Fill' and resource 'control nodes of one or more sub-compositions'. Distinguishes from siblings by explicitly noting it does not animate, compared to animate_state and update_and_animate.

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 says to use this for content-only updates, and directs to animate_state or update_and_animate for animation/taking on/off air. Also mentions batching multiple sub-compositions to conserve rate limit, providing clear when-to-use and alternatives.

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