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

The description provides rich behavioral detail beyond the annotations: it discloses transactional rollback, built-in protection, EXPORT being held with error, and EXPRESSION/BIND requiring specific settings. This significantly enhances the destructiveHint and openWorldHint annotations with concrete safety and failure semantics.

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 dense but efficient, with each sentence adding unique value about transactionality, types, restrictions, and rollback. It is slightly long but the complexity justifies the length. The main purpose is front-loaded, making the tool's role immediately clear.

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 transactionality, restrictions, supported types, and failure behavior comprehensively, which is essential for a complex tool with 5 parameters and no output schema. It does not mention return values, but the operational focus makes this acceptable. Overall, it provides enough context 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?

With 0% schema description coverage, the description partially compensates by listing supported parameter types and explaining modes like EXPRESSION, BIND, and EXPORT. However, it does not elaborate on comp_path, page, operations, or idempotency_key, relying on their self-explanatory names. This is adequate but not thorough.

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: transactionally add, edit, delete, sort, and organize a COMP's custom parameters. This specific verb+resource combination distinguishes it from siblings like edit_td_node_metadata or set_parameters_batch, which focus on other parameter management tasks.

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 implies usage for managing custom parameters but does not explicitly state when to use this tool over alternatives. It mentions 'Legacy page+params calls remain valid' but does not contrast them with this route, and there is no explicit when-not guidance. Some context is given about restricted mode and required settings, but not enough to clearly guide tool selection.

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 substantial behavioral detail beyond the annotations: the timecode is live and re-evaluates every frame, count_down clamps at zero, FPS is probed live with a fallback, and the chain ends in a Null TOP 'out'. It does not contradict the annotations and clearly indicates the tool builds a node chain (consistent with readOnlyHint=false).

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 dense but every sentence earns its place: implementation approach, mode semantics, formatter location, live FPS probing, sibling distinction, and output terminal. No wasted words. The structure flows from general action to mode details to implementation specifics.

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 (8 parameters, no output schema, open-world behavior), the description covers everything needed: what it builds, how timecode computation behaves, what the output is ('Null TOP out'), and how it differs from sync_timecode. The schema handles parameter syntax, and the description fills in behavioral context.

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 baseline is 3, but the description enriches several parameters: it clarifies that 'clock' shows time since project start and is 'NOT the OS wall clock,' that count_up starts from zero when the overlay is built, and that count_down clamps at 00:00:00:00. These are semantic clarifications not present 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 opens with a specific verb and resource: 'Overlay a running HH:MM:SS:FF timecode (or a countdown) onto an input TOP as VISUAL pixels.' It immediately distinguishes itself from sync_timecode, which is a sibling tool for syncing clock signals rather than rendering pixels. This leaves no ambiguity about what the tool does.

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 explicitly names the closest alternative (sync_timecode) and explains the difference: 'Distinct from sync_timecode, which syncs a CLOCK SIGNAL (no pixels) — this tool draws the timecode into the image.' The mode breakdown (clock/count_up/count_down) also clarifies when each mode should be used.

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 annotations already indicate readOnlyHint=true and openWorldHint=true, but the description adds valuable behavioral context: 'Read-only and conservative — every flagged item carries a human-readable reason.' This goes beyond the structured hints by explaining the conservative nature (likely under-reporting) and the presence of human-readable justifications, which helps an agent calibrate expectations. 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?

The description is compact: two sentences containing all essential information without redundancy. It front-loads the primary action ('Diagnose a network for cleanup') and lists outputs efficiently. Every clause earns its place, making it easy to parse quickly.

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 thoroughly enumerates what the tool reports (dead operators, broken dependencies, orphan COMPs, dependency map) and provides context about safety ('read-only and conservative') and relationship to sibling tools. Since an output schema is present, the description doesn't need to detail return values, and the existing coverage is sufficient for a complex analysis 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?

Both parameters are fully described in the input schema (100% coverage), so the schema carries the load. The description does not add any additional semantic details about the parameters themselves, such as how path and recursive affect the analysis output. It meets the baseline for high schema coverage but doesn't exceed it.

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 ('Diagnose') and resource ('a network for cleanup') and enumerates concrete report types: likely-dead operators, broken external-file dependencies, orphan COMPs, and a dependency map. It clearly distinguishes itself from siblings by naming plan_visual and snapshot_td_graph, so an agent can tell this tool's purpose apart from related ones.

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 says it 'Complements plan_visual (which plans a build) and snapshot_td_graph (which dumps structure),' providing direct comparison and alternatives. It also states 'Read-only and conservative,' giving an additional usage context that signals safety and caution. This gives an agent a clear sense of when to choose this tool over others.

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 (readOnly=false, openWorldHint=true), the description reveals side effects: it creates an LFO CHOP, binds targets, and switches each parameter to expression mode. This provides significant behavioral context not captured by annotations alone.

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, front-loaded with the main action, then the mechanism and benefit. No unnecessary 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 complexity and lack of output schema, the description covers the process, the target format, and the result. It is self-contained and sufficient for an agent to know what happens upon 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 100%, so the baseline is 3. The description references min, max, and period but does not add additional detail beyond the schema's own parameter 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?

Description clearly states the verb 'Drive' and resource 'node parameters over time with an LFO', specifies the mechanism (creates an LFO CHOP and binds each target) and lists waveform types. This distinguishes it from sibling animation/parameter tools such as pulse_td_parameter or set_parameter_expression.

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 implies usage for LFO-based animation without manual keyframing, and contrasts with keyframing. It does not explicitly name alternative tools or state when not to use, but the intended 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?

Beyond the annotations (readOnlyHint=false, openWorldHint=true), the description discloses two critical behavioral prerequisites: TDMCP_RAW_PYTHON=on and TDMCP_BRIDGE_ALLOW_EXEC=1. This adds valuable execution-security context not present in annotations. It does not contradict 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?

Three sentences, front-loaded with the core action, with no wasted words. It efficiently conveys the operation, requirements, and context.

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 build tool with no output schema, the description covers the essential operational context: what it builds, what inputs it needs, and environment requirements. It omits return value details and side effects on existing network state, but given the medium complexity, it is reasonably complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the input schema already explains all parameters. The description adds the qualifier 'pre-translated' and outlines the mapping contents (fragment + uniforms + channels + controls), but this adds marginal value over the schema's 'Pre-built mapping' description. Baseline 3 applies.

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 ('Build') and resource ('self-contained GLSL TOP network') with a precise input ('pre-translated mapping'), making the tool's function immediately clear. It also distinguishes itself from sibling import tools by identifying as the 'foundation primitive' used by Shadertoy and ISF importers.

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: it is the underlying primitive for Shadertoy/ISF importers and is intended for power users with hand-translated fragments. It implies when to use directly versus through importers, though it does not explicitly name alternatives or exclude other 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 declare non-read-only, open-world, non-destructive. Description adds rich behavior: creates a self-contained baseCOMP, prefers OCIO, falls back to Movie File In + Lookup TOP, parses .cube in Python, exposes Strength/Bypass controls, and handles missing source_path with a grey Constant TOP. This goes well beyond the 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 dense but well-structured: main action first, then format preferences, fallback, controls, and usage variants. Slightly long, but every sentence adds useful information; not wasteful.

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 complex tool with 9 params and no output schema, the description covers the key workflow: input formats, branch selection, fallback logic, source handling, and exposed controls. It gives an agent enough context to decide and invoke 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 detailed descriptions, so the description doesn't need to add parameter semantics. It does mention source_path and Strength/Bypass, but these already appear in the schema. No significant added meaning.

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 opens with a specific verb+resource: 'Apply a colour Look-Up Table (LUT) to an existing TOP inside a self-contained baseCOMP.' It clearly distinguishes from siblings like create_color_grade by targeting LUT application with specific file-format handling.

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: applies LUT to an existing TOP, with fallback behavior for OCIO vs image LUTs. However, it doesn't explicitly name alternative tools or state when not to use it, so not a 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?

The description details exactly what will be created (a new baseCOMP, Select TOP, effect chain, Null TOP), how it works (pulls source in via Select TOP, wires effects in series), and what is returned (summary, JSON with paths, errors, warnings, preview). This adds substantial behavioral context beyond the annotations, which only indicate non-read-only, non-destructive, open-world 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?

Three concise sentences: first states purpose, second explains behavior and output, third gives alternative usage. No filler; every sentence contributes 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 is complete for a complex tool: it explains the node graph construction, the output structure, and alternatives, and the schema covers parameters and effect enums. The absence of an output schema is compensated by the explicit description of the JSON return block.

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%, so the schema already fully describes source_path, parent_path, and effects. The description adds no new parameter-specific semantics beyond restating that effects are applied in order, which the schema also says. 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 a specific action: 'Chain post-processing effects ... onto an existing TOP, applied in the order given.' It names the resource (existing TOP), the result (new baseCOMP with effects wired in series), and explicitly differentiates from sibling tools like create_color_grade and create_glitch.

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 explicit guidance: 'Use create_color_grade or create_glitch instead when you want a single dedicated effect with its own exposed controls.' It also notes in the schema that 3D-aware effects are redirected to post_passes_3d, offering clear 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?

The description reveals detailed behavioral steps: creating a baseCOMP, wiring nodes, exposing controls, auto-layouting, verifying, and previewing. It also describes the exact return structure (summary plus JSON block) and error handling for unknown ids. This goes well beyond the annotations, providing rich context without contradicting them.

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 compact yet comprehensive: three sentences cover the purpose, the creation process, and the return/error behavior. Each sentence provides distinct value with no redundancy, and key details are front-loaded.

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 moderate complexity, two parameters, and absence of an output schema, the description is exceptionally complete. It explains what the tool does, what it returns, how errors are handled, and even implies the prerequisite of listing recipes. There are no critical gaps.

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 documents both parameters (id, parent_path) with descriptions. The tool description adds extra meaning by referencing list_recipes for the id, clarifying parent_path as the destination COMP, and noting the friendly error for unknown ids. This supplements the schema coverage rather than merely repeating it.

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 ('Instantiate') and resource ('built-in recipe by id'), clearly distinguishing it from sibling tools like list_recipes (which merely lists) and apply_lut (which applies LUTs). It also specifies the context ('inside a COMP') and the outcome ('creates a new baseCOMP').

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 explicitly mentions 'from list_recipes', implying the prerequisite workflow, and states that the result is a ready-made network to tweak. However, it does not name explicit alternatives or 'when not to use' scenarios, so it falls short of a 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 signal non-read-only, open-world, non-destructive behavior. The description adds valuable context beyond that: the precise side effect is 'node creation in TD, not file writes,' the return value is the created GLSL TOP, and it clarifies the source note format. This goes beyond the annotations but could be more explicit about error conditions.

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 somewhat dense but every sentence serves a purpose: core action, side-effect clarification, usage guidance, return value, and prerequisites. It is front-loaded with the operation verbs in caps. Slightly long but efficient for the complexity of the tool.

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 (reading from vault, creating a node), the description covers the key aspects: source format, action, side effects, return value, alternative tool, and required environment settings. It lacks explicit error handling information, but with no output schema, the return value description is sufficient. The prerequisites are a strong addition.

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 has complete descriptions for all 3 parameters (100% coverage), so baseline is 3. The description adds semantics by describing the expected structure of the note (```glsl fragment block, optional vertex block, frontmatter) and clarifying that the 'name' parameter defaults to frontmatter or 'glsl1', which is already in the schema but reinforces the intended usage. This adds 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 the tool's specific action: READ a shader note from the Obsidian vault and CREATE a GLSL TOP in TouchDesigner from it. It explicitly names the resource (vault note) and distinguishes itself from the sibling create_glsl_shader by noting that alternative is for inline shader code.

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 when-to-use guidance: 'Use this to apply a shader you keep in the vault; to supply shader code inline instead, use create_glsl_shader.' It also lists required configuration prerequisites (TDMCP_VAULT_PATH, TDMCP_RAW_PYTHON=on, TDMCP_BRIDGE_ALLOW_EXEC=1), which informs when the tool is usable.

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 important behavioral traits beyond the annotations: atomicity, stale-context checks, readback, rollback, and legacy response preservation. It also guarantees no structural changes to nodes, which adds significant context beyond readOnlyHint:false and destructiveHint:false.

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 three sentences, front-loaded with the core purpose in the first clause, and each sentence adds distinct, non-redundant information: core function, mode-specific behavior, and non-destructive guarantee. No word 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?

For a complex 10-parameter tool with no output schema, the description provides a solid high-level orientation, covering modes, atomicity, safety guarantees, and legacy behavior. It doesn't describe return values, but given 100% schema parameter coverage, the description need not compensate for schema gaps. The main missing piece is return-value expectations, but this is acceptable given the schema richness.

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 10 parameters already have descriptions in the schema (100% coverage), raising the baseline to 3. The description adds value by contextualizing layout_mode (auto vs explicit), mentioning annotation-aware behavior, and connecting idempotency_key to the atomic/rollback guarantees, but it doesn't deeply elaborate individual parameter meanings.

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: 'Tidy an existing network into a readable left→right data-flow layout' with a specific verb and resource. It also distinguishes itself from topology-changing sibling tools by explicitly stating 'It never adds, deletes, or rewires nodes.'

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 clear mode-specific guidance, such as 'use layout_mode=explicit for one bounded, atomic exact-coordinate mutation' and notes that annotation-aware automatic layout remains available. However, it does not explicitly name alternative sibling tools or provide 'when-not-to-use' exclusions beyond the implicit 'never adds, deletes, or rewires nodes.'

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 the annotations, the description adds meaningful behavioral context: it is 'offline-safe', does not rely on the Blackmagic SDK, and builds an OSC matrix specifically for cut/auto/FTB and program/preview control. This helps the agent understand side effects and external dependencies. It does not contradict 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?

The description is two sentences and front-loads the primary purpose. Every clause adds value: routing method, SDK disclaimer, offline-safety, and the specific control functions. There is no filler or redundant repetition of the tool name 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?

For a creation tool with six parameters and no output schema, the description gives sufficient context for selection and invocation: it explains what is built, how it is built, and what functions it exposes. It could be slightly more explicit about return values or the created component's location, but the schema covers the parent_path parameter.

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%, so all six parameters already have meaningful descriptions. The tool description adds high-level purpose but does not add per-parameter semantics beyond what the schema provides. This meets the baseline but does not exceed it.

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 ('Create an OSC control preset') and clearly identifies the resource (ATEM switcher) and routing mechanism (atemOSC, Companion, or similar relay). It explicitly distinguishes itself from direct SDK usage by stating 'This does not use the Blackmagic SDK directly', which separates it from sibling tools like connect_blackmagic_atem.

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: when building an offline-safe OSC-based control matrix for an ATEM switcher via a relay. It also gives an implicit when-not by stating it does not use the Blackmagic SDK directly, but it does not explicitly name an alternative tool for direct SDK scenarios, so it stops short of a full 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 destructiveHint=true and readOnlyHint=false. The description adds value by specifying the exact destructive action: 'writes into the package folder (destructive).' It also discloses the registration in the manifest's docs list, providing behavioral context beyond the structured annotations. 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?

Two sentences, front-loaded with the primary action, then usage context and a warning. Every word earns its place, 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?

The description covers the core workflow and references make_portable_tox for context, but it omits any mention of the optional help_snapshot parameter and its nested structure. Given the tool's moderate complexity (4 params, nested object, no output schema), the description is adequate for the main use case but not comprehensive. The destructive note and usage guidance help, but parameter coverage remains incomplete.

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 25% (only help_snapshot has a description). The tool description does not explain docs, asset_dir, or manifest_path; it only mentions 'docs list' indirectly. With low schema coverage, the description should compensate for parameter meanings, but it fails to clarify the array format, defaults, or required path. This is a significant gap.

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: 'Copy documentation files into a package and register them in its manifest's docs list.' This specifies a concrete verb and resource, distinguishing it from sibling tools like make_portable_tox or bundle_dependencies. The context 'Use after make_portable_tox' further anchors its role.

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 provides explicit usage context: 'Use after make_portable_tox to bundle a README or usage notes with a component so they travel with it.' This tells the agent when to use the tool and its purpose, but lacks explicit alternatives or when-not conditions. The guidance is clear enough for most cases.

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 reveals important behavioral traits beyond annotations: it samples audio (potential latency), uses a deterministic heuristic, can hang on macOS if 'device' is used (mitigated by default), and supports dry_run to avoid building. It also explains the composite behavior of apply_top_op. These details exceed the sparse readOnlyHint/destructiveHint 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 three sentences and effectively packs the entire workflow, key defaults, and important caveats. The first sentence is long but densely informative; while it could be split for readability, it contains no fluff. It earns a 4 for appropriate brevity despite the complexity.

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 9-parameter orchestrator with no output schema, the description gives a complete high-level story: sample audio → analyze → map → dispatch. It also clarifies the most critical behaviors (dry_run, apply_top_op, default audio_source). Schema covers the remaining parameter details, so the combination is sufficient.

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%, so baseline is 3. The tool description adds minimal parameter semantics beyond what's already in the schema; it mentions audio_source default, dry_run, and apply_top_op, but the schema already documents all parameters with similar or greater detail. No significant new meaning is 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 uses specific verbs and a clear workflow: samples audio, computes a 4-feature fingerprint, runs deterministic heuristic mapping, and dispatches a generator. It explicitly lists the candidate generators, distinguishing it from siblings like create_glitch or create_audio_reactive by being an automatic dispatcher.

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 implies its primary use case: automatically select a generator based on audio fingerprint. It gives practical context (default synthetic source to avoid mic-permission hangs, dry_run for testing, apply_top_op for compositing) but doesn't explicitly state exclusions vs alternatives. The list of possible generators hints at when it's appropriate, though it stops short of saying 'use this instead of manual selection.'

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 convey that this is a write/creation operation (readOnly=false, destructiveHint=true). The description adds substantial context beyond that: creates companion callbacks DAT, appends custom params based on type, returns a specific dictionary, requires environment variables, and notes the non-cooking behavior when nothing requests the op. It does not explicitly mention overwrite conflicts, but the added context is valuable.

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?

Three well-organized sentences: front-loaded purpose, then mechanism, return value, prerequisites, and a practical cooking caveat. Every sentence contributes meaningful information with no filler, making it easy for an agent to parse quickly.

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 purpose, mechanism, return structure (explicitly lists keys), environment requirements, and a common behavioral pitfall. No output schema exists, so the return dict mention helps. Lacks details on what happens if an existing op has the same name (destructive potential), but overall the description is sufficiently complete for a creation 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 100%, with each parameter already explained in detail (e.g., family selects operator type and stub signature, custom_params type inference). The description largely mirrors schema information, adding only minimal extra context such as the per-family stub names (chan/row/point/numpy). Baseline 3 is appropriate because the schema carries the semantic load.

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 ('Scaffold') with a clear resource ('Script CHOP/DAT/SOP/TOP') and detailed outcome (onCook stub, custom parameters, companion callbacks DAT). It distinguishes from sibling tools like create_python_script and add_custom_parameters by its focus on the full Script op scaffolding workflow.

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: when to use it (scaffolding a Script op with optional custom parameters and stub generation). Also states critical prerequisites (TDMCP_RAW_PYTHON=on, TDMCP_BRIDGE_ALLOW_EXEC=1) and a behavioral caveat about cooking. However, it does not explicitly name alternatives or conditions where another tool should be used instead, so it misses full when-not 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 state readOnly=false, openWorld=true, destructive=false. The description adds substantial behavioral detail: dry-run does no writes and runs exactly one planning iteration, non-dry-run propagates to repair_network, loop stops on clean/stalled/exhausted, and it returns a structured result. 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?

The description is dense but well-structured: it starts with an overview, then adds dry-run behavior, a key limitation, and the return envelope. Each sentence contributes non-redundant information without bloat.

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?

Even with no output schema, the description fully specifies the return shape {status, iterations[], errors_before, errors_after, remaining[], recommended_prompts[], warnings} and explains termination conditions and fixer hand-offs. For a complex orchestrator, this is sufficient for an agent to invoke and interpret results.

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 already detailed parameter descriptions, so baseline is 3. The description enriches meaning by tying dry_run to one planning iteration with no writes, allowed_fixers to advisory-only behavior, and max_iterations to the 'exhausted' termination state.

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 opens with 'Driver: scan a subtree for cook errors...' and clearly describes a bounded iterative repair loop. It explicitly specifies the fixers it calls (repair_network) and those it only hands off (fix_shader/fix_reactivity), distinguishing it from sibling fix and repair 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?

It states when the loop is appropriate (subtree cook errors), its iteration bounds, dry-run default, and explicitly notes that shaders/dead reactivity are not fixed directly but surfaced via recommended_prompts for the agent to execute next turn. This gives clear routing guidance versus repair_network and fix_shader/fix_reactivity.

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?

Building on annotations (readOnlyHint=false, destructiveHint=false), the description adds meaningful behavioral specifics: write mode merges only when write:true, preserves '*'-pinned user tags, and uses a deterministic heuristic. It also discloses conditional requirements for target types, going well beyond the structured 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, front-loaded with the core purpose, then the use case and prerequisites. No wasted words; every clause contributes to understanding. Excellent density without becoming a wall of text.

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 10-parameter tool with no output schema, the description covers the essential behavior (what it emits), the primary use case, and environmental prerequisites. The detailed parameter descriptions in the schema fill in the rest, so the description is complete enough for an agent to select and invoke the tool confidently.

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%, so the schema already explains each parameter. The description adds marginal value by clarifying the write flag's effect and target-specific bridge requirements. This is a slight bump above baseline without duplicating 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 the tool 'inspects a captured library asset' and emits a 'suggested tag set, difficulty, and one-line description', with an optional write mode that merges into frontmatter. It differentiates itself by naming the downstream consumer 'browse_vault_library' and by the 'auto-' prefix in the name, distinguishing it from sibling tagging/search 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 explicitly says 'Use this to backfill consistent tags across a library so browse_vault_library can find by category', giving a clear when-to-use directive. It also states prerequisites (TDMCP_VAULT_PATH, bridge for td_comp). It does not provide when-not-to-use or explicit alternative tools, but the directive is strong enough for a 4.

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=false and destructiveHint=false, and the description adds meaningful behavioral detail: it reads source_path, infers slider/toggle/text controls, appends them as custom parameters on comp_path, and optionally binds each control back to the source parameter. This goes beyond the annotations by explaining the side effects and flow, although it does not discuss failure modes or edge cases like existing custom parameter collisions.

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?

Three compact sentences front-load the primary purpose, then outline the mechanism and the intended use case. Every sentence contributes without repetition or extraneous detail.

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 7-parameter schema with full descriptions and no output schema, the description effectively explains the core workflow and when to use it. It could mention what happens if 'parameters' limits the list or how max_controls interacts with inference, but those are already in the schema, so the description is sufficiently complete for practical 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?

The input schema already covers all 7 parameters with descriptions (100% coverage), so the baseline is 3. The description adds some relationship context (e.g., comp_path defaults to source_path, controls are inferred from primitive parameters) but does not significantly deepen meaning beyond the schema's own per-parameter 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 starts with a specific verb and resource: 'Generate a performable control panel from an existing node/COMP's primitive parameters.' It clearly distinguishes this from siblings like add_custom_parameters by focusing on the infer-and-append workflow and the optional binding behavior.

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 explicit context: 'Use when a generated component has useful parameters but no playable UI yet.' It does not name alternatives or exclusions, but the use case is clear enough to guide selection among the large sibling set.

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 critical behavioral traits beyond annotations: 'fail-forward, per-operation warnings; not transactional' and 'Names created earlier can be referenced by later connect/setParam operations.' These are not derivable from the readOnlyHint/destructiveHint annotations and are essential for the agent to predict partial failure behavior and cross-referencing semantics.

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, followed immediately by the key behavioral caveat and a sibling distinction. Every sentence earns its place with no filler or redundant repetition of schema details.

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 a complex nested schema and multiple operation types, the description covers all essential aspects: what it does, the non-transactional behavior, name referencing, and relationship to a similar tool. Since an output schema exists, not explaining return values is acceptable. The description fully equips an agent to select and invoke the 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?

The input schema already provides comprehensive descriptions for all parameters (100% coverage), including the operations array's ordering and fail-forward behavior. The description reinforces these points but adds no new parameter-level details. The baseline of 3 is appropriate given the schema's completeness; the description does not need to compensate.

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 exactly what the tool does: 'Run an ordered list of create / connect / setParam operations in one call.' It clearly identifies the resource (network builder) and the scope of operations. It also distinguishes itself from a sibling tool ('distinct from set_parameters_batch'), leaving no ambiguity about its purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly names an alternative tool (set_parameters_batch) and explains the difference, which helps with selection. It implies use for multi-step network construction via 'Exposes the network builder as a general primitive,' but doesn't explicitly state when not to use it (e.g., for single operations). This is clear context but lacks formal exclusions.

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 key behavioral traits beyond the annotations: it switches knobs to expression mode, appends a master knob, and fails forward with warnings rather than errors. It explicitly states that only a missing/non-COMP target is fatal, and that missing CHOPs/channels/already-bound parameters are non-fatal warnings. This is rich behavioral context not present in the minimal 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 long but every sentence earns its place, covering purpose, mechanism, parameters, error behavior, and alternatives. It is front-loaded with the core value proposition and structured logically from how-to to edge cases to sibling tool distinctions.

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 is complete for this mutating tool with 5 params and no output schema. It covers prerequisites, exact parameter semantics, auto-mapping heuristics, master knob behavior, fail-forward error handling, and explicit alternatives to sibling tools. Nothing important appears to be 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?

The description adds significant meaning beyond the schema's 100% coverage, detailing the auto-mapping heuristic (bright/level/opacity→level, scale/size/zoom→bass, hue/color→treble, speed/rate/rot→mid) and clarifying the interplay between intensity and add_master (master knob scales every binding). It also explains the fail-forward behavior for missing channels, 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 clearly states the tool's purpose: 'Make a whole COMP react to the music in one call' and explains the mechanism (point target at a COMP, source_chop at an audio CHOP). It distinguishes itself from siblings by explicitly naming create_audio_reactive and bind_to_channel as alternatives for different needs.

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 explicit usage guidance: 'This tool only WIRES an existing COMP to an existing CHOP, building no nodes' and directs users to produce the feature CHOP first, then use this tool. It clearly states when to use alternatives: create_audio_reactive for a whole new network, bind_to_channel for finer single-parameter control.

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 the annotations (readOnly=false, destructive=false), the description discloses the key mutation: 'Each is switched to expression mode so it tracks the channel live.' It also details the smoothing mechanism ('insert a Lag CHOP between the channel and the parameter'). This adds important behavioral context that annotations do not 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 two sentences but is somewhat long. However, each clause contributes meaningful information: purpose, typical sources, smoothing options, and a concrete example. The structure front-loads the core action ('Drive one or more node parameters...') then elaborates, making it easy to scan.

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 9 parameters and no output schema, the description covers purpose, usage context, parameter semantics, and side effects. It doesn't discuss potential failure modes or prerequisites beyond pointing at a source CHOP, but for this complexity it is quite complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds extra meaning by explaining how smoothing parameters work together ('fast attack + slow release for a punchy hit that decays smoothly') and explains the 'smooth' convenience parameter as symmetric attack/release. This adds value beyond the schema's individual parameter 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's function: 'Drive one or more node parameters from a CHOP channel by expression' and its purpose ('the link that makes a visual react'). It also distinguishes from sibling tools by explicitly naming the upstream tools it connects: 'This is how you wire extract_audio_features / create_tempo_sync into a visual system.'

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 when-to-use context by pointing at specific channel types ('audio_features channel (bass/mid/treble/level) or a tempo_sync channel') and referencing upstream tools. It does not explicitly state when not to use or name alternative tools, so it stops short of full explicit exclusions.

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 goes well beyond the annotations by disclosing specific side effects: node creation and reading the note file, while explicitly stating it does NOT write to the vault. It also explains the sync behavior, return values, and configuration requirements. This addresses operational expectations comprehensively.

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 front-loaded with the core action and then adds side effects, usage guidance, return values, and prerequisites. Every sentence contributes useful information, but the length is somewhat dense; a slight trimming could improve conciseness without losing critical context.

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 (node creation, sync behavior, external file access, return values), the description covers all essential aspects: side effects, does-not-do clarification, configuration prerequisites, and output. Since there is no output schema, the explicit list of returned fields is especially valuable. The description is complete enough for an agent to invoke the 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% for all 4 parameters, so the baseline is 3. The description reinforces the 'file' parameter pointing at a vault note and mentions sync with 'sync:true', but these details are already present in the schema property descriptions. Thus, the description adds minimal additional semantic value beyond what the schema already provides.

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 ('CREATE a Text DAT in TouchDesigner'), the specific resource (a Text DAT whose `file` parameter points at a vault note), and the intended outcome (note text loads into TD). It is distinct from generic node creation siblings by emphasizing the vault binding and sync behavior.

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 usage context, including the intended visual use case ('text/lyrics source for your visuals') and a concrete integration step ('Wire the DAT into a Text TOP to render it'). It also lists explicit prerequisites (TDMCP_VAULT_PATH, TDMCP_RAW_PYTHON=on, TDMCP_BRIDGE_ALLOW_EXEC=1). It does not explicitly name alternatives or exclusions, but the guidance is sufficiently clear for most scenarios.

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 a non-read-only, non-destructive, open-world operation. The description adds specific behavioral context: it creates a scaffold with listed components, uses a fallback primitive when no path is given, and warns when a .blend may need export. This goes beyond annotations without contradicting them.

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, front-loaded with purpose, listing components and supported formats without redundancy. 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?

Given the tool's complexity (11 params, no output schema), the description explains the scaffold, fallback behavior, and format support, and includes a warning about .blend export. It doesn't need to detail return values since there is no output schema. It leaves some ambiguity about how the scaffold integrates with the existing network, but openWorldHint and the reference to parent_path in schema cover that.

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 11 parameters have schema descriptions covering 100%, so the schema carries the parameter semantics. The tool description doesn't elaborate on individual parameters but provides broader context about formats and fallback, which is consistent with the schema. 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 a specific action ('Create a self-contained TouchDesigner render scaffold') with a defined scope (Blender scene or Blender-exported asset) and enumerates the produced components (File In SOP, Geometry COMP, PBR material, lights, Camera, Render TOP, Null TOP). It distinguishes itself from generic import/model tools by focusing on Blender-specific assets and including a warning about .blend export.

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 implies usage context: it is for Blender scenes/exported assets and creates a full render scaffold. It mentions supported formats and warns about potential need to export .blend first, which acts as a prerequisite. It doesn't name alternative tools or explicitly say when not to use it, 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=true and destructiveHint=false. The description adds that it's a discovery step returning matching recipes/packages for selection, which is useful context beyond the annotations. No contradictions found.

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 with the main purpose front-loaded. The second sentence packs in usage context and output without wasting words. No redundant phrases or 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?

Has an output schema, so return values are covered. The description explains the purpose, the workflow context, and what the tool returns (matching recipes/packages). Minor gaps in parameter semantics remain, but given five optional parameters and a rich output schema, the description is mostly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not explain the tags, query, or package_dir parameters. It only loosely maps to include_recipes/include_packages via the terms 'recipes' and 'packages'. The word 'matching' implies filtering but gives no specifics, so the description fails to compensate for the missing 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 'Browse built-in/vault recipes and optional local component packages' with a specific verb and resource. It also distinguishes this tool from apply_recipe and install_library_package by describing it as a discovery step, making its unique role obvious.

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 'Read-only discovery step before instantiating a recipe (apply_recipe) or installing a package (install_library_package)', which clearly tells when to use this tool versus the named alternatives. It also explains the expected outcome ('returns the matching recipes and packages'), giving solid 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 already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with "Read-only". It adds valuable context: "No TouchDesigner connection required — reads the local vault on disk" and "Requires a configured TDMCP_VAULT_PATH". It also describes the return format (flat items array and per-category counts), going 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 three sentences, front-loaded with the primary purpose. Every sentence adds value: purpose, filtering options, and important constraints/returns. 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?

For a simple list tool with two optional parameters and an existing output schema, the description is complete. It covers what the tool does, how to filter, what it returns, and the required environment variable, making it fully self-sufficient.

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%, so the baseline is 3. The description says "Filter by category (kinds) and/or a substring query", which paraphrases the schema's parameter descriptions. It adds no new syntax or format details beyond what the schema already provides.

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 "list" and the resource "the vault's recipes, shaders, presets, components, and setlists" with specific fields (title, tags, description). It distinguishes from siblings by emphasizing the local vault on disk and no TouchDesigner connection needed.

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 "so the agent can pick from the library without opening individual notes", which clarifies when to use this tool. It also notes "No TouchDesigner connection required", helping choose this over TD-connected tools. It does not explicitly name 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?

The description reveals key behavioral traits not in annotations: fail-forward warnings, partial chain returns, and the wiring pattern. It adds useful context beyond the readOnly/destructive hints. 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?

Three sentences, each earning its place: purpose, usage/wiring, and failure behavior plus a tip. Front-loaded and free of 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?

The schema richly covers inputs, but with no output schema the description only vaguely says 'returns useful info' without specifying the return format. For a side-effecting builder, this is a gap, though fail-forward behavior is helpfully disclosed.

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 the description repeats what the schema already documents (ops list structure, wiring, parent default). It adds no new param-level semantics, so a baseline score 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 tool builds an ordered CHOP processing chain declaratively, identifying the resource (CHOP chain) and distinguishing it from sibling tools like build_pop_chain. The verb 'builder' plus specific 'CHOP' resource makes the purpose 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 the core usage pattern (pass an ops list, wiring output 0 to input 0, parent default) and offers a practical tip about ending with nullCHOP for bind_to_channel readiness. It does not explicitly list alternative tools or when-not-to-use, 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?

Beyond the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false), the description reveals that unknown parameter names are tolerated with warnings (fail-forward), that results carry an 'unverified' experimental marker, and that nodes are wired under a specified `parent`. These are useful behavioral details not encoded in 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 roughly 100 words, front-loaded with the core purpose, and every sentence earns its place: structure, defaults, multi-input handling, experimental status, and a practical tip. There is no redundant 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 complex tool with 77 POP types and multi-input wiring, the description covers the essential behavioral model, wiring semantics, failure mode (warnings), and result marker. It does not describe the return value structure or re-run/overwrite behavior, but the annotations and schema mitigate those gaps. Overall it is a solid, near-complete description.

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 baseline is 3, but the description adds meaning by stating that per-kind safe defaults are applied before user params and that unknown names become warnings. This goes beyond the schema's generic 'Par overlay' explanation and helps the agent understand how to handle arbitrary params.

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 opens with a specific verb+resource: 'Declarative Layer-2 builder for an ordered POP (Point OPerator) chain.' It clearly distinguishes itself from sibling tools like build_chop_chain by explicitly targeting POPs, and the chain-building mechanism is precisely described.

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 provides concrete usage instructions: pass a `chain` list, each entry wired output 0 → input 0 of the next, with `extra_inputs` for multi-input POPs, and a tip to end with `null_pop`. However, it does not explicitly contrast with alternative tools or state when not to use it, so it lacks explicit exclusions.

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 a non-read-only, non-destructive operation. The description adds valuable behavioral disclosure: per-op failures become warnings (fail-forward), partial chains still return useful info, and wiring occurs under a configurable parent. It does not detail what the returned 'useful info' contains, but this is a minor gap given the annotation coverage.

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 compact and well-structured: a one-sentence purpose, a concise explanation of the wiring pattern, a note on failure behavior, a useful tip, and an explicit alternative. Every sentence adds value without 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?

Given the schema covers all parameters and the description explains the wiring, failure handling, and best-practice tip, the tool is well contextualized. The only notable omission is a precise description of the return value (especially since there is no output schema), though 'returns useful info' partially addresses this.

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 has 100% parameter description coverage, so the description does not need to explain each parameter in depth. It reinforces that `ops` contains type/name/params and mentions the parent default, but adds little beyond the schema. The special string-resolution behavior for params is already documented 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 clearly identifies the tool as a 'Declarative Layer-2 builder for an ordered SOP geometry chain' with a specific verb ('builds') and resource ('SOP geometry chain'). It explains the linear wiring model (op[i] output 0 → op[i+1] input 0) and explicitly contrasts with `connect_nodes` for multi-input fan-in, 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 states when to use this tool (for ordered, linear SOP chains) and explicitly directs users to `connect_nodes` for multi-input scenarios, serving as a clear when-not/alternative. The tip about ending with `nullSOP` for stable handoff adds practical usage 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?

The annotations already flag destructiveHint=true and readOnlyHint=false, but the description goes further by disclosing exactly what is mutated (parameters in the live network), what is created (assets folder, .tox, manifest), and how missing files are handled. 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?

Every sentence in the description carries essential, non-redundant information. It is front-loaded with the main purpose, then covers output structure, sibling distinctions, and a critical mutation warning—all without 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?

Given the complexity of a 5-parameter tool with destructive side effects, the description is remarkably complete. It covers the full process, the delivered artifact, how it differs from alternatives, and the key caveat about live network mutation. An output schema exists, so return values are already covered.

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%, so a baseline of 3 applies. The description adds contextual meaning by explaining the relationship between the workflow and parameters, especially rewrite_refs (mutation behavior) and out_dir/assets structure. It doesn't add per-parameter detail beyond schema but augments understanding of the overall flow.

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 begins with 'Make a COMP self-contained' and details the exact workflow: scan, copy, rewrite, save with manifest. It also explicitly distinguishes itself from make_portable_tox (which leaves assets behind) and collect_project_assets (which only reports), so the agent knows exactly what this tool accomplishes.

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 contrasts this tool with sibling tools make_portable_tox and collect_project_assets, telling the agent when this is the right choice. It also provides a critical usage caveat: rewriting mutates the live network, and setting rewrite_refs=false enables a copy-and-report mode without mutations.

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 the annotations (readOnly, openWorld, non-destructive), the description discloses crucial behaviors: the deterministic luma/color-histogram fallback that 'always works, no model needed', the current inert vision path, and the return structure including 'source: vision|histogram' and warnings. This provides rich context about reliability, fallback logic, and potential warnings, going well beyond the structured 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 front-loaded with the core action ('Read-only: render a TOP's preview and return a plain-text description'), then efficiently explains the two paths, the outputs, the use case, and a caveat about the vision path. Every sentence contributes value without redundancy, and the structure flows logically.

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 explicitly enumerates the return fields ('{node_path, width, height, source:... caption, stats{...}, warnings}'). It explains both execution modes, the deterministic fallback, the intended usage scenario, and a current limitation. For a tool with 4 parameters and no output schema, this description is exceptionally complete and self-contained.

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 thorough descriptions for all four parameters (width, height, node_path, use_vision), including defaults and the 'smaller is faster' note. The description adds context about the two paths (vision vs histogram) and the inert vision path, but most parameter-specific information is already in the schema. Since coverage is 100%, a baseline score 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 tool's function: 'render a TOP's preview and return a plain-text description of it'. It also labels it as the 'headless is the output alive? primitive', and specifies the exact outputs (dominant colors, mean luma, near-black fraction, classification, caption). This is a specific verb+resource and distinguishes it from sibling tools like get_inline_preview or render_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 gives an explicit use case: 'Use it after a build to confirm the network is actually rendering instead of a black frame.' It also clarifies the two execution paths and warns that the vision path is currently inert. However, it doesn't explicitly state when not to use this tool or compare it to alternative tools, so it lacks exclusions.

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 a non-read-only, open-world operation. Description adds crucial side effects: writes PNG to <gallery>/images/ and appends to <gallery>/<note>.md, plus default date behavior and prerequisite TDMCP_VAULT_PATH. 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?

Three sentences, each adds value: purpose, mechanics, and use cases/prerequisite. Well-structured and front-loaded with the main action.

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 write tool with 6 params and no output schema, description covers purpose, side effects, location details, and required environment variable. It is sufficiently complete for an agent to know when to call it and what to expect.

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, so baseline is 3. The description adds workflow context (defaults to today's date, daily accumulation) but does not elaborate on individual parameters beyond the schema. It is acceptable but not exceptional.

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 'Captures a preview still from a TOP and appends it to a dated gallery note in the Obsidian vault', identifying both the action and target. This differentiates it from sibling vault tools like save_component_to_vault or export_network_to_vault, which target different resources.

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 explicit use cases: 'Use this to document looks, reference frames, or build a browsable gallery of your session's visuals.' It does not mention alternatives or exclusions, but the context is sufficient for when 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 declare read-only and non-destructive behavior. The description adds valuable context beyond annotations: it retrieves data from a live API endpoint, works even when TDMCP_BRIDGE_ALLOW_EXEC=0, and indicates which operators are deprecated or unavailable. This enriches the behavioral picture without contradicting 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?

The description is four concise sentences, each contributing unique information: the reconciliation purpose, the flagging behavior, single-operator usage, and the environment-survival note. No wasteful repetition; information is front-loaded with the 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?

The description covers the main function, optional modes, and a special environment condition, making it reasonably complete for a reporting-style tool. It lacks an explicit description of the output format (e.g., flag structure), but given the simple nature of the tool and lack of an output schema, this is a minor gap.

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 thoroughly (100% coverage). The description adds a small usage note about passing a single operator name, but largely restates what the schema already conveys, so it meets the baseline without adding significant new semantic meaning.

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: reconciling the operator knowledge base against the live TouchDesigner creatable-optype list. It uses a specific verb ('Reconcile') and names both the knowledge base and the running TouchDesigner, distinguishing it from sibling tools like search_operators.

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 provides clear context for when to use the tool (checking documentation against a running build) and how to use the single-operator mode. However, it does not explicitly mention alternative tools or exclusions, so it stops short of a full when/when-not explanation.

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?

With sparse annotations, the description carries the burden of explaining side effects and outputs. It states that 'action=compute walks a path and writes a tdmcp-checksums.json manifest' and 'action=verify re-hashes files and reports ok/mismatch/missing/extra'. This discloses the write behavior and report format. It does not mention potential overwrites or error conditions, but the provided detail is solid.

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 three sentences, each providing essential information: what it does, how compute behaves, and how verify behaves. No filler or redundant phrasing. It is front-loaded with the 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?

Given the tool's complexity (9 params, nested manifest object, no output schema), the description is too sparse to be complete. It does not mention the manifest format beyond the filename, nor the meaning of 'strict', glob filters, size limits, or symlink behavior. For a sophisticated tool with no output schema, more detail is needed.

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 0%, so the description must compensate. It only explicitly explains 'action' and 'path' (the required params). The other seven parameters (strict, manifest, manifest_out, exclude_globs, include_globs, max_file_bytes, follow_symlinks) are left completely unexplained. This is a significant gap for a tool with 9 parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Compute or verify SHA-256 checksums for tdmcp artifacts'. It specifies the resource (tdmcp artifacts) and the two primary actions (compute/verify). This distinguishes it from siblings that deal with other artifact operations.

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: for checksum computation or verification of tdmcp artifacts. It also notes 'No TD bridge required', which is a pertinent usage constraint. However, it does not explicitly name alternatives or state when not to use it, so a perfect score is not warranted.

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 readOnlyHint=false and destructiveHint=false, and the description adds behavioral specifics: it creates a synchronized container with deterministic layout and binds Play/Loop/Speed controls across both lanes. This goes beyond the annotations by describing what the created structure includes, which is useful context for a mutation tool.

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 main action, and every clause adds meaningful detail (structure, optionality, determinism, controls, use-case). No filler or redundant 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 9-parameter creation tool with no output schema, the description adequately sets expectations by describing the created structure (video lane, audio lane, Null outputs, controls) and the deterministic layout. It doesn't describe return values, but that is not essential for a creation tool. A small gap is lack of mention of error conditions or prerequisites, but overall it is complete enough.

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%, so the baseline is 3. The description adds some meaning by referencing the Play/Loop/Speed controls and optional Audio File In CHOP lane, which map to parameters like loop, speed, autoplay, and include_audio. However, it doesn't provide substantial additional semantics beyond what the schema already documents.

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 with a specific verb ('Create') and resource ('synchronized clip transport container'), and enumerates its components (Movie File In TOP video lane, optional Audio File In CHOP lane, Null outputs, controls). It explicitly positions the tool as a reusable building block before clip launchers, VJ decks, or stream/output chains, 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 provides explicit usage context: 'Use it as a reusable building block before clip launchers, VJ decks, or stream/output chains.' This clearly indicates when to use this tool in relation to higher-level alternatives. It doesn't explicitly say when not to use it, but the relationship to alternatives is clear, which is strong 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?

Goes well beyond annotations by clarifying that the scan is read-only but writing out_manifest may overwrite an existing file, which explains the readOnlyHint=false and destructiveHint=true annotations. Also discloses that file-par detection heuristics are UNVERIFIED across TD builds and that style_supported records reliability. 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?

The first sentence front-loads the core purpose, and the rest provides necessary safety and reliability caveats. Longer than average but every sentence carries information essential for correct invocation and expectation-setting. Could be tightened slightly but not wasteful.

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 moderate complexity and the existence of an output schema, the description covers purpose, safety, parameter behavior, and reliability of heuristics. It fully explains what will be reported and the side effects, making it complete for an agent to select and invoke 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 already covers all three parameters with descriptions (100% coverage), baseline is 3. Description adds meaningful context by warning that out_manifest may overwrite and by explaining the heuristic fallback behavior related to par.style, which enriches understanding of parent_path and output behavior.

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 a specific action: scan a COMP subtree for external file dependencies and report each referenced file, the referencing node+parameter, and file existence. Distinguishes from siblings like make_portable_tox or bundle_dependencies by emphasizing it only reports and does not copy/rewrite the network.

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?

Implies usage by describing the read-only scan and optional manifest write, and hints at a contrast with tools that copy dependencies, but does not explicitly state when to use this tool over alternatives or provide exclusions. The guidance is context, not direct instruction.

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 destructiveHint=false, and the description adds valuable context beyond that: it reveals the tool uses getNetworkTopology and getNetworkErrors, performs 'no new bridge work,' and returns an approxTokens count. This gives the agent a clear mental model of cost and side effects.

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 three sentences, front-loaded with the read-only flag, and every sentence carries unique information: what it does, what it returns, and how it compares to alternatives. There is no wasted text.

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 the return shape is already documented, and the description covers the tool's purpose, underlying mechanism, and relative cost vs. siblings. For a read-only planning digest, this is complete enough for an agent to select and invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all six parameters already have robust descriptions. The tool description mentions max_tokens as a default budget but does not add new per-parameter semantics beyond what the schema already provides, so the baseline score 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 opens with a specific verb-resource pairing: 'compress a TD subtree into a structured digest,' which clearly states the tool's function. It further differentiates from siblings by explicitly naming get_td_topology and snapshot_td_graph as costlier alternatives, so purpose and differentiation are both strong.

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 a clear use case ('for planning turns') and explicitly names alternatives ('Cheaper than get_td_topology / snapshot_td_graph'), which tells the agent when this is preferable. However, it does not explicitly state when not to use it, so it falls just short of a full 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 and destructiveHint, so the 'Read-only' prefix aligns with them rather than adding new safety info. However, the description adds useful context about the embedded offline knowledge base and the exact comparison scope (overview metadata, shared/unique parameters), which goes 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 sentences, front-loaded with the key action and safety qualifier. Every clause adds value: read-only indicator, comparison target, offline KB, parameter types, and explicit distinction from live-node comparison.

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 a rich output schema, clear annotations, and a precise description of purpose and scope, the tool is fully contextualized. The distinction from compare_td_nodes and mention of the offline KB cover the main potential confusions. No material gaps remain.

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 all four parameters in detail. The description adds contextual value by explaining the comparison nature and what "documented parameters" means, but it doesn't describe the parameters themselves beyond what the schema provides. 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 a specific verb ('compare') and resource ('two TouchDesigner operator types from the embedded offline knowledge base'), and explicitly distinguishes from sibling tool compare_td_nodes by clarifying it compares documentation, not live node settings.

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 explicitly states when to use this tool (for comparing offline documentation) and when not to (for live node parameter diffs), naming the alternative tool compare_td_nodes. This provides clear usage boundaries.

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?

Description says 'Read-only' which complements readOnlyHint: true and adds the default behavior of returning only differing values. The return object structure is disclosed. No contradiction with annotations, and no hidden side effects beyond what is implied.

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?

Three sentences with a clear flow: operation + default behavior, return structure, and usage guidance. Every sentence adds value with no 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?

Given the presence of an output schema and annotations covering safety, the description fully covers purpose, usage, and the distinction from the key sibling. It is complete enough for an agent to select and invoke the 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?

Input schema has 100% coverage with descriptions for all three parameters (path_a, path_b, only_diff with default). Description adds no extra parameter-level information beyond referring to 'by default', 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 the tool diffs parameters of two nodes and returns differing values by default. Includes the exact return structure and explicitly mentions it operates on live nodes, distinguishing it from diff_snapshots.

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 concrete use case (aligning settings across similar operators) and explicitly contrasts with diff_snapshots (whole-network snapshots over time). This provides clear when-to-use guidance and naming of an alternative.

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 behavioral context beyond annotations: append-only nature, offline operation, and file output behavior (rendering markdown into vault). The annotations already indicate readOnly=false and destructive=false, and the description aligns 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 appropriately sized for the tool's complexity, front-loads the core purpose, then systematically covers the three actions, location, offline capability, and related tools. Every sentence contributes meaningful information 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?

Given 5 parameters (one nested object), no output schema, and multiple actions, the description covers all key aspects: file format, storage location, action semantics, and relationships. It's sufficient for an agent to understand and invoke the tool correctly without needing additional clues.

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 the meaning of actions ('read' returns JSON, 'export' renders markdown), clarifies the trail file naming convention, and mentions the optional sha256 hash and changed-param list, which enriches understanding 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 specifies a clear verb ('Maintains') and resource (append-only per-component revision history as JSONL trail), with three distinct actions. It distinguishes itself from siblings by noting it pairs with save_component_to_vault and provenance_stamp, and explicitly states it operates offline.

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: it's for maintaining revision history offline, and mentions complementary sibling tools. However, it doesn't explicitly state when NOT to use it or compare against alternatives like version_library_asset or manage_component_storage, so it lacks exclusions.

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, openWorldHint=true, and destructiveHint=false. The description adds behavioral context by specifying what is probed (live COMPs, external .tox paths) and what is reported (missing or broken files). This goes beyond the annotations without contradicting them.

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, front-loaded with the core action ('Probe live COMPs...'), then a brief usage note. Every sentence earns its place with no 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 simple read-only diagnostic, the purpose and usage are clear, and annotations cover safety. However, the lack of parameter explanations and return format details (no output schema presents additional burden) leaves gaps for an agent to use it correctly without further inference.

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%, and the description provides no meaning for the two parameters (paths, parent_path). The description does not compensate for the lack of schema documentation, leaving parameter semantics entirely unclear.

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 probes live COMPs for external .tox paths and reports missing or broken linked files. It distinguishes itself from siblings like inspect_component_manifest and make_portable_tox by focusing on link health specifically.

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 a clear when-to-use context: 'run it when externally-linked .tox components may have moved or gone stale, before relying on them in a build.' It does not name explicit alternatives, but the context is sufficient to guide selection.

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 the LLM vs deterministic parser fallback, which is a behavioral trait beyond the annotations. It also mentions optional chaining into create_cue_sequencer, indicating potential side effects. Annotations already cover readOnly/destructive hints, so this adds value.

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?

Three sentences, front-loaded with purpose, no redundant content. Every sentence adds information about behavior or chaining.

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 tool has 8 parameters but all are well-documented in the schema. The description clearly states input, output (via schema hint), and fallback/chaining behavior. It lacks explicit return format but is adequate given no output schema.

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 has 100% coverage, so baseline is 3. The description adds context for apply/containerName by mentioning optional chaining, and for preferLlm by discussing the LLM vs grammar parser. This elevates to 4.

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 'turn into' and identifies the resource (natural-language show description → validated cue list). It distinguishes from siblings by naming the specific schema variant (scenes[]) and explicitly referencing create_cue_sequencer as a downstream chain.

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 implies usage context (NL show description to cue list) but does not provide explicit when-to-use vs alternatives, nor exclusions. It mentions the LLM/grammar fallback and optional chaining, which are behavioral details rather than usage guidelines.

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 useful context by calling it a 'scaffold' rather than an actual live connection, implying it builds a structure instead of connecting to a server. However, annotations already convey create/non-read-only/non-destructive intent, and the description does not reveal side effects, file output, or network behavior beyond that.

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 sentence that is front-loaded with the verb 'Create' and packs all key features without fluff. It is efficient and well-structured, earning 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?

With 8 parameters and no output schema, the description needs to set expectations for the scaffold's structure and how parameters affect it. It only lists high-level feature names and omits return values, parameter-specific behavior, or post-creation expectations, making it incomplete for moderate 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 description coverage is only 38%, and the description partially maps to just two parameters (prompt_slot_count via 'prompt slots', include_controlnet via 'ControlNet hints'). It does not explain server_url, endpoint_kind, output_folder, active, or parent_path semantics, leaving significant gaps for the agent.

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 creates an AUTOMATIC1111/Forge Stable Diffusion WebUI handoff scaffold with specific components (prompt slots, result maps, ControlNet hints, adapter notes), distinguishing it from sibling bridge tools like connect_comfyui for other image-generation backends.

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 guidance is provided on when to use this tool vs alternatives. The description only states what the tool creates; it does not compare to other bridge tools or specify prerequisites, exclusions, or preferred scenarios.

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 it's a mutating, open-world tool. The description adds that it 'creates' a scaffold, but doesn't disclose side effects like whether it modifies existing sessions, network connectivity needs, or what happens to a pre-existing link session. Given annotations cover the safety profile, a baseline 3 is appropriate.

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 concise sentence, front-loaded with the action verb, 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?

For a tool with 7 parameters, no output schema, and low schema coverage, the description is too brief. It doesn't explain the return value, prerequisites, how the scaffold integrates into an Ableton Link setup, or what 'connect' implies vs 'create'. The description leaves significant gaps for an agent to invoke 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 only 29% (2/7 params described). The description vaguely mentions 'beat/bar maps' which relates to signature/export_bars but doesn't explicitly explain any of the 7 parameters. With such low schema coverage, the description was expected to compensate but doesn't.

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 ('Create') and resource ('Ableton Link timing scaffold') with a clear scope ('beat/bar maps for tempo-locked visual systems'). It clearly distinguishes itself from generic create tools by specifying the timing domain.

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 guidance on when to use this tool versus alternatives like create_tempo_sync or sync_external_clock. It lacks explicit contextual triggers, prerequisites, or exclusions.

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 readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the create behavior is consistent. The description adds useful context by listing the scaffold's contents (sanitized rows, altitude bands, track history, adapter source, notes), which goes beyond the raw annotations. However, it does not disclose operational details such as how the connection is established, whether it initiates network traffic, or what 'sanitized' implies in terms of data 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?

The description is a single sentence that leads with the verb 'Create' and front-loads the primary resource. It is efficient and contains no filler. The long list of components makes it slightly dense, but it remains scannable and avoids unnecessary detail.

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 10 parameters, no output schema, and a likely external integration role, the description is too short to fully equip an agent. It omits what 'connecting' entails, how the scaffold is structured, the meaning of 'feed/privacy notes', and how this tool relates to sibling 'connect_*' and 'create_*' tools. The description provides only a high-level component list without operational or relational context.

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 only 20%, so the description must compensate for the nine undocumented parameters. It does reference several parameter concepts: 'adapter source' hints at provider/adapter_url/adapter_mode, 'altitude bands' maps to altitude_band_count, and 'track history metadata' maps to track_history_count. But the mapping is implicit, and parameters like active, airspace_label, and aircraft_count are not clearly tied to the description, leaving gaps for the agent.

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 'Create' and the resource 'ADS-B aircraft scaffold', then lists specific components (sanitized aircraft rows, altitude bands, track history metadata, adapter source, feed/privacy notes). This provides a concrete picture of what the tool produces. However, the tool name says 'connect' while the description says 'create', introducing slight ambiguity, and it doesn't explicitly contrast with similar data bus tools, though the aircraft-specific details differentiate it.

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 is given for when to use this tool versus alternatives such as connect_ais_vessel_bus or other create_* scaffolding tools. The description implies it is for ADS-B aircraft data, but it does not state prerequisites, exclusions, or scenarios where another tool would be more appropriate.

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=false and openWorldHint=true, which align with the 'Create' action in the description. The description adds a few behavioral details by listing specific scaffold components, including 'token/rate-limit safety notes,' but it does not disclose side effects, auth requirements, or whether existing structures could be overwritten. Some value is added beyond annotations, but not deeply.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that lists all major scaffold components without redundancy. It is concise and every phrase adds meaning.

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, no output schema, and minimal schema descriptions, the one-line description is insufficient. It does not explain return values, parameter semantics, enum choices, or when to use the tool, leaving an agent with only vague hints about the scaffold contents.

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%, and the description does not compensate by explaining key parameters such as base_id, table_name, sync_direction, adapter_mode, or record_count. Terms like 'record maps' and 'sync policy' hint at parameter purposes, but not enough for an agent to select or configure all 11 parameters correctly.

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 ('Create') and identifies a clear resource ('Airtable content scaffold') while detailing exactly what the scaffold contains: record maps, field maps, sync policy, adapter source, and token/rate-limit safety notes. This distinguishes it from sibling tools like connect_google_sheets_cue_table or connect_ableton_link_session by focusing on Airtable content-bus scaffolding.

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 implies the tool is for creating an Airtable content bus scaffold, but it does not state when to choose this over alternatives, nor does it provide exclusions or prerequisites. There is no explicit 'when to use' or mention of related tools such as connect_notion_show_rundown or connect_google_sheets_cue_table.

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 some behavior context beyond annotations by mentioning 'sanitized vessel rows' and 'receiver/privacy notes', implying data cleaning and privacy handling. It also says 'adapter source' which hints at external connectivity, consistent with openWorldHint=true. However, it does not detail side effects, permission needs, or what happens to existing data, so the score is moderate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that immediately states the action and key deliverables. It is concise without redundant words, though the brevity limits the amount of useful information conveyed.

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 this tool has 10 parameters, no output schema, and very low schema coverage, the description is far too thin. It does not explain return values, output structure, prerequisites, or what the resulting scaffold contains operationally. This leaves the agent with substantial ambiguity about how to invoke and interpret results.

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 schema description coverage at only 20%, the description needed to compensate by explaining key parameters. It references zone_count, route_count, adapter, and vessel-related concepts but does not map them to specific parameter names or clarify their values/meaning. The description adds vague high-level semantics, insufficient for a 10-parameter tool.

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 creates an AIS vessel scaffold and lists its key components (sanitized vessel rows, zone maps, route hints, adapter source, receiver/privacy notes). This is specific enough to distinguish it from sibling connect_* tools like connect_adsb_aircraft_bus or connect_gps_fleet_tracker, though 'scaffold' could be more explicit about the resulting TouchDesigner structure.

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 guidance is given on when to use this tool versus alternatives such as other connect_* tools or generic create_* tools. The description provides no context about prerequisites, typical use cases, or scenarios where this tool is preferred.

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 this is not read-only, not destructive, and open-world. The description adds that it creates a scaffold with specific maps, which is helpful but doesn't disclose side effects, dependencies, or prerequisites beyond that.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that states the core action and key components with no filler. Every word contributes to understanding the tool's 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?

For a 7-parameter tool with no output schema and low schema coverage, this description is under-specified. It omits how the scaffold behaves, prerequisites (e.g., iPhone app, OSC setup), and what happens after creation, leaving the agent with insufficient context to use the tool effectively.

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 schema description coverage at only 29%, the description should compensate but doesn't mention any parameters. It only vaguely references 'blendshape and head-transform maps' without explaining how parameters like face_count or include_head_transform relate. The schema provides defaults but the description adds no parameter clarity.

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 'Create' and a specific resource 'ARKit Face Capture OSC scaffold' with details about blendshape and head-transform maps. It clearly distinguishes this from sibling tools by targeting a niche ARKit/OSC workflow.

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 phrase 'for iPhone-driven facial performance' implies the usage context, but there is no explicit guidance on when to use this versus alternatives like setup_face_tracking or other connect_* tools. No exclusions are mentioned.

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 valuable behavioral context beyond the annotations by clarifying that this creates a scaffold with UDP transport placeholders and operator approval notes—not a live functional connection. This nuance is not captured by readOnlyHint=false or openWorldHint=true, though it stops short of detailing side effects like created COMP placement or overwrite 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 a single, front-loaded sentence with no filler or redundancy. It efficiently conveys the core purpose and key deliverables.

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 9 parameters and no output schema, this one-sentence description is not enough to be fully actionable. It omits explanation of the individual parameters, defaults, side effects, or what the resulting scaffold actually looks like (e.g., how 'operator approval notes' are structured). The scaffold concept is underspecified.

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 33% schema description coverage, the description needs to compensate for the 9 parameters, but it only mentions high-level concepts like 'input maps' and 'macro maps' without referencing parameters such as atem_host, send_port, input_count, macro_count, or include_cut_auto. It does not meaningfully clarify parameter meanings beyond what the schema already provides for the three described fields.

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 ('Create') and a specific resource ('Blackmagic ATEM command-map scaffold') with concrete contents (UDP transport placeholders, input maps, macro maps, operator approval notes). This clearly distinguishes it from sibling tools like atem_switcher_control, which is for actual control rather than scaffolding.

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 is given on when to use this tool versus alternatives. While the sibling atem_switcher_control implies a distinction between scaffold creation and actual control, the description never states this exclusion or provides any usage 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?

With annotations already indicating readOnlyHint=false and destructiveHint=false, the description adds some behavioral context by listing what the scaffold creates (sanitized beacon rows, zone maps, etc.). However, it does not disclose side effects, required permissions, or integration behavior beyond the creation act. 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?

The description is a single sentence that front-loads the action and lists key components. It is concise and avoids fluff, though the long list of components makes it slightly dense. It earns its place but could benefit from a short preface or examples.

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, no output schema, and no usage guidance, the description is insufficiently complete. It does not explain how the scaffold integrates with the project, what 'sanitized beacon rows' means, whether existing nodes are modified, or what the expected outcome is beyond a vague scaffold. An agent would likely need to inspect parameter descriptions or ask for more details.

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 20% (name and parent_path), so the description must compensate. It mentions concepts like 'smoothing policy' and 'adapter source' that loosely map to parameters (smoothing_window_sec, adapter_url/adapter_mode), but it does not systematically explain each parameter's purpose or relationships. Partial compensation, but gaps remain for many of the 10 parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb+resource: 'Create a BLE beacon proximity scaffold' and lists concrete components (sanitized beacon rows, zone maps, smoothing policy, adapter source, device-privacy notes). This clearly distinguishes it from sibling tools like connect_serial_device_bus or create_geojson_feature_bus. The minor mismatch between 'connect' in the title and 'Create' in the description does not obscure the purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. It does not mention any conditions, prerequisites, or that other tools (e.g., connect_websocket_control_bus) might be more appropriate for different bus types. The description simply states what it does without contextualizing the decision.

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