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

The description significantly enriches the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=true) with concrete behavioral details: transactional rollback to prior snapshot, EXPORT returning an error without mutation, reversible EXPRESSION/BIND, protected built-ins, and no raw Python fallback. These are not present in structured data and give agents crucial expectations beyond generic mutation hints.

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 purpose in the first sentence, followed by compact behavioral details. It is reasonably concise for the complexity, though some clauses like 'no raw Python or /api/exec fallback is used' and 'Legacy page+params calls remain valid' are peripheral and could be trimmed without losing essential guidance.

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 is complex with nested operations and multiple parameters. The description covers transactionality, auth, supported types, and key safety behaviors, which is substantial. However, it does not explain the response format (no output schema exists) nor dive into the exact semantics of each operation action, leaving some gaps for such a multi-faceted tool. Overall, quite complete but not exhaustive.

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 must compensate for parameter meaning. It provides meaningful details on supported types and mode behavior (EXPRESSION/BIND reversible, EXPORT held), but does not explain the idempotency_key purpose, the precise semantics of operation actions (e.g., sort_page expects an order array), or the role of fields like menu_names vs menu_labels. Partial compensation, not fully sufficient.

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+resource: 'Transactionally add, edit, delete, sort, and organize a COMP's custom parameters.' It also lists supported types and the authenticated route, distinguishing it from sibling parameter tools like update_td_node_parameters which target existing parameters. The scope is 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 implies use for managing custom parameters and notes that legacy page+params calls remain valid, offering limited context. However, it does not explicitly contrast with alternative tools like update_td_node_parameters or set_parameter_expression, nor provide when-not-to-use conditions beyond implied protection of built-ins. Only guidance is implied, not explicitly stated.

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

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

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?

Annotations already indicate non-read-only and non-destructive behavior. The description adds that it builds a 'self-contained' network but does not disclose potential side effects like whether it overwrites an existing container, requires specific prerequisites, or validates the mapping. With annotations covering the safety profile, a 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?

The description is two sentences, front-loads the core action, and contains no fluff. Every phrase earns its place by clarifying scope ('self-contained', 'pre-translated', 'foundation primitive', 'power users').

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 the complexity of the mapping object and 7 parameters, the rich schema covers parameter semantics. The description provides the missing high-level purpose and usage context. It could mention that a container COMP is created under parent_path, but that is already in the schema, so the description is complete enough for a well-documented 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 having its own description. The tool description repeats high-level components (fragment, uniforms, channels, controls) that map to the mapping object, but adds little beyond what the schema already documents. Baseline 3 is correct.

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 action: 'Build a self-contained GLSL TOP network from a pre-translated mapping', with explicit components (fragment + uniforms + channels + controls). It distinguishes itself from siblings by positioning as a foundation primitive for Shadertoy/ISF importers and as a direct tool for power users, making it clear it is not the importer itself.

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 context on when to use: when a pre-translated mapping already exists, particularly via importers or hand-translated fragments. It does not explicitly name alternatives or state when not to use it, but the reference to importers implies that translation happens elsewhere, providing adequate usage 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 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?

Beyond annotations (readOnlyHint: false, destructiveHint: false), the description clarifies that the side effect is node creation in TD, not file writes, and that it returns the created GLSL TOP. It also notes the vault path requirement, adding useful behavioral context.

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

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

The description is concise, front-loaded with the primary action, and each sentence adds value—covering source, side effect, alternative, return value, and prerequisite. No filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With annotations, full schema coverage, and a description that includes the side effect, return value, and alternative tool, the description is complete for an agent to select and invoke the tool correctly. No output schema exists, but the description states what is returned.

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 description adds context about the shader note format but does not add significant new meaning to the individual parameters beyond what the schema already provides (e.g., note as path or name).

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 action: read a shader note from the Obsidian vault and create a GLSL TOP in TouchDesigner. It specifically names the vault as the source and distinguishes itself from create_glsl_shader, which supplies inline 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?

Explicit guidance is provided: 'Use this to apply a shader you keep in the vault; to supply shader code inline instead, use create_glsl_shader.' Also mentions the side effect (node creation) and the prerequisite (configured TDMCP_VAULT_PATH).

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: it discloses that explicit mode is atomic, bounded, has stale-context checks, readback, and rollback. It also clarifies the tool is non-destructive (never adds/deletes/rewires nodes), which complements the destructiveHint=false annotation. This significantly helps an agent predict 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 exceptionally concise: two sentences that front-load the primary purpose, then cover the explicit mode's key traits, legacy behavior, and safety guarantee. Every sentence provides essential information without any 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 tool with 10 parameters and complex behavior, the description covers the core behavioral aspects (modes, atomicity, non-destructive guarantee) and references the legacy response. The schema handles individual parameter details, so the description does not need to echo them. While it does not spell out the return format, no output schema exists and the description gives enough context for selection and safe 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 adds value by explaining the semantics of layout_mode (explicit atomic mutation vs automatic) and mentions annotation-aware layout, which maps to the annotation_aware parameter. While it doesn't describe every parameter, it enriches understanding of the key mode-switching parameter.

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

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

The description clearly states the tool tidies an existing network into a readable left→right data-flow layout, and also explains the alternative explicit coordinate mode. It distinguishes itself from sibling tools by explicitly stating it never adds, deletes, or rewires nodes, which differentiates it from connect/disconnect/rebuild 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 clear context for when to use automatic vs explicit layout modes, and notes that omitting layout_mode preserves the legacy response. It implies when not to use the tool (for rewiring actions) by stating it never rewires nodes, but does not explicitly name alternative tools for those 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 adds behavioral context beyond annotations by clarifying that it does not use the Blackmagic SDK directly, builds an offline-safe matrix, and includes specific functions (cut/auto/FTB, program/preview selection). This is useful since annotations only indicate non-read-only, non-destructive, and open-world hints. No contradiction.

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

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

The description is two concise sentences. The first sentence states the primary action and routing options, the second clarifies the technical approach and scope. No filler or 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 six parameters fully described in the schema and no output schema, the description explains the tool's purpose, method (OSC relay), and key capabilities. It is complete enough for an agent to understand what the tool does and when to use it, though it could briefly mention the 'inputs' parameter's effect on the created matrix.

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 does not add specific parameter semantics beyond what the schema already provides for host, port, inputs, etc. It mentions 'cut/auto/FTB and program/preview' which implies input selection but does not elaborate on parameter syntax or constraints 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 function: 'Create an OSC control preset for an ATEM switcher routed through atemOSC, Bitfocus Companion, or another OSC relay.' It specifies the verb (create), the resource (OSC control preset), and distinguishes itself from direct SDK tools and sibling tools like 'connect_blackmagic_atem' by emphasizing it builds an offline-safe TouchDesigner OSC matrix.

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 this tool: when routing through atemOSC, Companion, or another OSC relay, and when you need an offline-safe preset without SDK access. It does not explicitly name alternatives or exclusions, but the context is sufficiently clear 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?

Annotations already declare destructiveHint=true, but the description adds that the tool 'writes into the package folder (destructive)' and registers docs in the manifest, specifying exactly what gets modified. This goes beyond the annotation and provides useful behavioral context with no contradiction.

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

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

The description is two sentences, action-first, with usage context and a destructive warning. 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?

While purpose and usage are clear, the description leaves significant gaps around parameter semantics, especially for the help_snapshot object and the expected format of docs paths. With no output schema and only 25% schema coverage, an agent lacks sufficient detail to confidently invoke the tool with all parameters.

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

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

Schema description coverage is only 25%, and the description does not explain the meaning of docs, asset_dir, or manifest_path beyond the vague 'documentation files.' It fails to compensate for the low schema coverage with parameter-level guidance.

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 'Copy documentation files into a package and register them in its manifest's docs list,' which is a specific verb+resource combination. It distinguishes the tool from siblings by explicitly referencing make_portable_tox and the package manifest context.

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 after make_portable_tox' and explains the intended outcome (so docs travel with the component), giving clear context. However, it does not specify when not to use the tool or mention alternatives like bundle_dependencies or collect_project_assets.

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?

No contradiction with annotations (readOnlyHint=false, destructiveHint=true). The description adds valuable context beyond annotations: it creates the op plus callbacks DAT, returns a structured dict, and warns about cooking behavior. However, it doesn't clarify what destructive actions might occur (e.g., overwriting existing ops), which would be useful given the destructiveHint.

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 lean and well-structured: it opens with the action and resource, lists key outputs, and closes with a behavioral caveat. Every sentence serves a purpose 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 the tool's moderate complexity (5 params, no output schema), the description covers the main workflow, return values, and a key runtime nuance. It lacks details on edge cases like existing node overwrites or the meaning of 'warnings', but overall it is sufficiently complete for an agent to use correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds no new parameter semantics beyond what the schema already explains (e.g., type inference for custom_params, on_cook_body injection). It mostly restates schema info.

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

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

The description clearly states the tool scaffolds a Script CHOP/DAT/SOP/TOP with an onCook stub and custom parameters. It distinguishes itself from sibling creation tools by detailing the companion callbacks DAT and per-family stub generation.

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 by describing the creation process, but does not explicitly mention when to use this tool versus alternatives like create_td_node or add_custom_parameters. The cooking note provides some context, but no clear exclusions or 'when-not-to-use' 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?

The description discloses concrete mutation behavior: 'appends them as custom parameters on comp_path (default source_path), and optionally binds each control back to the source parameter.' It also reveals inference behavior ('infers sliders/toggles/text fields'). Annotations only state non-readonly/non-destructive, so the description adds meaningful behavioral context beyond them, though it doesn't cover edge cases like existing controls or overwriting.

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, all dense and front-loaded. The first sentence states the core action, the second explains mechanics, and the third gives usage context. No filler or 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 7 parameters and no output schema, the description covers the core workflow (read, infer, append, bind) and primary use case. It doesn't specify return values or behavior with pre-existing controls, but within the open-world context it is sufficiently complete for an agent to decide when and how to invoke it.

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. The description adds context for source_path (read from), comp_path (defaults to source_path), and bind (optional binding), but does not elaborate on page, exclude, parameters, or max_controls, which are already fully 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 starts with a specific verb and resource: 'Generate a performable control panel from an existing node/COMP's primitive parameters.' It clearly distinguishes this tool from siblings like create_control_panel by emphasizing automatic inference from existing parameters and optional binding.

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 final sentence gives explicit usage context: 'Use when a generated component has useful parameters but no playable UI yet.' This provides clear guidance but does not state explicit exclusions or name alternatives, making it a clear context without exhaustive 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 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?

Beyond annotations, the description details side effects (node creation + file read), explicitly states it does not write to the vault, explains sync behavior, and lists return values. This adds significant context over the readOnlyHint/destructiveHint/openWorldHint 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?

Concise at 4 sentences, action-first opening, includes side effects, usage, returns, and requirement without extraneous detail. Every sentence contributes.

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 without an output schema, the description adequately explains return values, side effects, and prerequisites. It covers the full workflow and boundaries, making it sufficient 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 covers 100% of parameters with descriptions, so baseline is 3. The description does not add much parameter-level meaning; it mentions sync's live-editing effect, but the schema already states that. No new parameter insights are provided.

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 'CREATE a Text DAT in TouchDesigner whose file parameter points at a vault note', specifying the exact action and resource. It clearly differentiates from sibling tools like create_td_node or edit_dat_content by focusing on vault-note-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 clear context: use this to turn the vault into text/lyrics source for visuals, and mentions a workflow step (wire into Text TOP). It notes prerequisites (TDMCP_VAULT_PATH) and boundaries (does not write to vault), but does not explicitly name alternative tools or when-not-to-use conditions.

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 a write operation (readOnlyHint=false) and non-destructive. The description adds value by disclosing that it warns when a .blend may need export from Blender first, and that it falls back to a primitive if no scene_path is provided. These behaviors go beyond what annotations convey, though it does not detail side effects like potential node creation at parent_path or any prerequisites beyond file format support.

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, each earning its place. The first front-loads the purpose and component list; the second concisely covers formats and the warning behavior. No redundant phrases or filler, making it easy to scan and understand 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 tool is complex (11 parameters, no output schema), yet the description covers the main deliverable (render scaffold), supported formats, and a behavioral warning. It does not explicitly state what the tool returns (e.g., the container path), but given the rich schema and annotations, the description is reasonably complete. Missing explicit output/return information is a minor gap in an otherwise thorough 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 description coverage is 100%, so every parameter already has a meaningful description. The tool description does not add additional parameter-level semantics; it mentions supported file formats which maps to scene_path, but the schema already lists the same formats. Baseline 3 is appropriate since the schema carries the full burden and the description does not enhance 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 clearly states the tool's function with a specific verb ('Create') and resource ('self-contained TouchDesigner render scaffold for a Blender scene or Blender-exported asset'). It enumerates the major components (File In SOP, Geometry COMP, PBR material, lights, Camera, Render TOP, Null TOP) which distinguishes it from simple model import tools like 'import_model'. The supported file formats and caveat about .blend export further clarify its scope.

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: use this when you need a full render scaffold for Blender scenes or exported assets. It implies the scenario (importing Blender geometry into TouchDesigner for rendering) but does not explicitly contrast with alternatives like 'import_model' or 'create_3d_scene'. There are no exclusions or 'when not to use' notes, but the context is unambiguous enough 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?

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 this is a non-read-only, non-destructive operation. The description adds behavioral specifics: 'synchronized', 'deterministic layout', 'Null outputs', and 'Play/Loop/Speed controls bound across both lanes.' It also notes the audio lane is optional, matching the include_audio parameter. No contradictions with annotations. It could go further by noting what happens when file paths are missing or whether existing container paths are overwritten.

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 with zero filler. The first sentence front-loads the primary action and components; the second sentence provides usage context. Every phrase contributes value, making it a model of concise, structured description.

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, full schema documentation, and annotations providing safety cues, the description is largely complete. It explains what is created and when to use it. However, since there is no output schema, the description does not disclose whether the tool returns a path or reference to the created container, and it omits potential failure conditions (e.g., invalid file paths). Still, it is well above the minimum viable level.

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 documents each parameter with descriptions. The description only lightly references parameters conceptually (e.g., 'Play/Loop/Speed controls' maps to loop/speed/autoplay, 'optional Audio File In CHOP lane' maps to include_audio/audio_file) but adds no technical detail beyond 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 the tool's function with a specific verb and resource: 'Create a synchronized clip transport container.' It enumerates the core components (Movie File In TOP video lane, optional Audio File In CHOP lane, Null outputs, deterministic layout, Play/Loop/Speed controls), distinguishing it from generic create tools and sibling tools like create_clip_launcher or create_video_player.

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

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

The description provides a clear use case: 'Use it as a reusable building block before clip launchers, VJ decks, or stream/output chains.' This indicates when to apply the tool and implicitly positions it as a foundation for those downstream systems. However, it does not explicitly state when not to use it or name specific alternative sibling tools, so it falls 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?

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?

Annotations indicate a non-read-only, non-destructive, open-world operation. Description adds context by listing scaffold contents but does not disclose side effects like filesystem writes, component creation, or modifications to existing project structure. Some value beyond annotations but limited.

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

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

Single sentence, no redundancy, immediately states the primary action and target. Every phrase carries 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?

Complex tool with 8 parameters, no output schema, minimal annotations; description omits parameter semantics, invocation context, and return behavior. Incomplete for correct usage.

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 38%, and the description does not explain any parameters. Terms like prompt slots and ControlNet hints vaguely map to prompt_slot_count and include_controlnet, but no specific parameter meanings, defaults, or relationships are described.

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 specifies the verb 'Create' and the resource 'AUTOMATIC1111/Forge Stable Diffusion WebUI handoff scaffold', enumerating specific components (prompt slots, result maps, ControlNet hints, adapter notes). This uniquely identifies the tool among many connect_* bridge siblings by naming the target 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?

No guidance on when to use this tool vs alternatives. Does not specify prerequisites, use cases, or exclusions. Context only implied by name and title.

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 readOnly=false, openWorld=true, and destructive=false, and the description's 'Create' aligns with these. However, the description adds no extra behavioral context such as side effects, required external connections, or what specifically is generated. It does not contradict the annotations, but also does not go beyond 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 one short sentence that gets straight to the point. No filler, no redundancy, and the main action is front-loaded. It earns high marks for conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having 7 parameters, no output schema, and moderate annotation coverage, the description provides only a one-line purpose. It omits information about what the scaffold includes, how parameters interact, expected return, and when to use it. The combination of low schema coverage and brief description leaves significant gaps for an agent.

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

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

With only 29% schema description coverage (2 of 7 parameters described), the description needed to compensate but does not. It only vaguely hints at 'beat/bar maps' which loosely relates to signature and tempo, but provides no clarification for parameters like active, export_bars, or start_stop_sync. The agent is left without enough meaning for correct invocation.

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 target resource ('Ableton Link timing scaffold'), and a purpose ('tempo-locked visual systems'). This distinguishes it from generic sync tools like create_tempo_sync or sync_external_clock, and is not a tautology of the tool name.

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 tempo-locked visual systems' implies a use case, but the description does not explicitly say when to use this tool over alternatives, nor does it mention prerequisites or exclusions. No sibling tool is referenced, so the agent must infer context from the name.

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 openWorldHint=true and readOnlyHint=false, warning of side effects, but the description does not elaborate on what those side effects are. It does not mention that the scaffold may connect to an external adapter URL, fetch live data, or that existing components might be modified. The phrase 'sanitized aircraft rows' hints at data processing but not at runtime behavior or dependencies.

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 primary action and then lists the scaffold's contents. It is concise, scannable, and contains no filler or duplication of structured data.

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 an openWorldHint, the description is insufficient for an agent to anticipate the tool's full impact. It does not explain what the agent should expect after creation, whether it returns a reference, how the adapter is used, or how the privacy notes are applied. The tool likely has network and lifecycle implications that are left undisclosed.

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 low (20%), so the description needs to compensate. It provides thematic links: 'altitude bands' to altitude_band_count, 'track history metadata' to track_history_count, 'adapter source' to provider/adapter_url/adapter_mode, and 'aircraft rows' to aircraft_count. However, parameters like 'active', 'airspace_label', and 'adapter_mode' remain unexplained, and the mapping is implicit rather than explicit.

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 an ADS-B aircraft scaffold') and lists key components (aircraft rows, altitude bands, track history, adapter source, feed/privacy notes). This distinguishes it from most sibling tools. However, the tool name/title use 'connect' while the description says 'create', creating a minor mismatch about whether the tool connects to an existing bus or builds a new scaffold.

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 alternative bus-creation tools. There are dozens of similar tools (e.g., connect_ais_vessel_bus, create_blacktrax_tracking_bus), and the description does not state the intended context, prerequisites, or that this is the tool for ADS-B aircraft data. It relies solely on the domain in the name.

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

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

Annotations already indicate non-readOnly and openWorld behavior, so the description is not required to restate that. It does add 'token/rate-limit safety notes' as a scaffold component, which is extra context. However, it doesn't detail actual side effects (e.g., external Airtable access, local file creation) beyond what annotations imply.

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. Every phrase adds information about what the scaffold includes, making it appropriately concise for the 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?

With 11 parameters, no output schema, and only 18% schema coverage, a one-sentence description is insufficient. It lacks prerequisites, expected outputs, and clarification of what 'content scaffold' actually entails, leaving significant gaps 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?

Schema description coverage is only 18%, and the description provides no parameter-level explanations. It references high-level components like 'record maps' and 'sync policy' but never connects them to the 11 parameters (e.g., base_id, sync_direction), so it fails to compensate for the low schema coverage.

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 the resource as 'Airtable content scaffold' with explicit deliverables (record maps, field maps, sync policy, adapter source, and token/rate-limit safety notes). This clearly differentiates it from generic 'connect' sibling tools and states a clear action.

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

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

Usage context is implied by the name and description ('create an Airtable content scaffold'), but there is no explicit guidance on when to use this tool versus alternatives, nor any when-not-to-use exclusions. The description says what it does but not when to choose it.

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

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

Annotations already indicate that this is not read-only (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds context about 'sanitized vessel rows' and 'receiver/privacy notes', which hints at data sanitization and privacy handling, but it does not elaborate on side effects, permissions, or reversibility.

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 is front-loaded with the primary action and resource, and it enumerates scaffold components compactly. It is concise without unnecessary filler, though the list format could be clearer.

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 limited annotation detail, a high-level one-sentence overview is insufficient. The description does not explain what the scaffold includes beyond a few components, nor does it describe return values or how the scaffold is structured, leaving gaps for a tool of this 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 20% (2 of 10 parameters have descriptions). The description mentions concepts like 'zone maps' and 'route hints' that loosely map to zone_count and route_count, but it does not explain individual parameters such as adapter_mode, adapter_url, vessel_count, or waterway_label. The description does not compensate for the low schema coverage.

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 the resource as an 'AIS vessel scaffold', listing key components (sanitized vessel rows, zone maps, route hints, adapter source, receiver/privacy notes). It clearly distinguishes the tool's purpose from generic 'connect' tools, though the name says 'connect' while description says 'create', causing slight ambiguity.

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

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

There is no guidance on when to use this tool versus alternatives like connect_adsb_aircraft_bus or other connect_* bus tools. No exclusions or prerequisites are mentioned, so the agent must infer usage from the name alone.

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 a mutating operation (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds that it creates a scaffold with OSC maps, but does not disclose side effects like network changes or dependencies. This is adequate but not rich.

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, focused sentence that front-loads the verb and essential details. It contains zero filler words and earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 7 parameters, no output schema, and only 29% schema description coverage, the description does not provide enough context about what the scaffold includes, how parameters affect the result, or what the output looks like. It is too sparse for a tool of this 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 29%, so the description must compensate for lack of parameter documentation. It vaguely references 'blendshape and head-transform maps' but does not explain key parameters like face_count, receive_port, active, or name. The description adds little beyond the schema 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 resource ('ARKit Face Capture OSC scaffold') with concrete details (blendshape and head-transform maps, iPhone-driven). This clearly distinguishes it from siblings like setup_face_tracking, making the purpose unmistakable.

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 intended use case, but there is no explicit statement of when to use this tool versus alternatives, nor any exclusions or prerequisites. Context is clear but guidance is minimal.

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 and not destructive, and the description adds useful context about creating placeholders and maps. However, it does not disclose potential side effects like overwriting existing components or whether network access is required, which would enhance transparency beyond annotations.

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

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

The description is a single sentence that packs substantial detail without excessive verbosity. It could be more structured (e.g., separated into two sentences) but remains efficient and 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?

With 9 parameters, no output schema, and no mention of return values or prerequisites, the description is incomplete for a tool of this complexity. It does not state what the scaffold will include in relation to the parameters or what the agent should expect after invocation, leaving significant 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?

Schema description coverage is only 33%, and the tool description does not compensate by explaining individual parameters. While some parameter names are self-explanatory, ambiguous ones like 'include_cut_auto' and 'active' remain undocumented, providing minimal guidance for agents.

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 a Blackmagic ATEM command-map scaffold, specifying the verb 'Create' and the resource. It distinguishes itself from sibling tools like 'atem_switcher_control' by noting it builds a scaffold with placeholders, input maps, macro maps, and operator approval notes.

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 this tool is for initial scaffolding rather than direct control, but it does not explicitly state when to use it versus alternatives. No alternatives or exclusions are mentioned, leaving the agent to infer the intended context from the tool name and sibling list.

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 readOnly=false and destructive=false. The description adds a concrete list of created scaffold elements, which goes beyond the schema. However, it does not disclose side effects such as whether existing components are overwritten, whether connections are established, or what 'device-privacy notes' implies behaviorally.

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 core action and resource, then packs a list of included artifacts without wasted words. It is concise and easy to scan, though it could be structured more explicitly around inputs and outputs.

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 minimal annotations, the one-sentence description is insufficient for reliable invocation. It omits usage context, return/result behavior, side-effect expectations, and detailed parameter semantics, leaving significant 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?

Schema description coverage is only 20%, so the description must compensate. It hints at mappings (zone maps -> zone_count, smoothing policy -> smoothing_window_sec, adapter source -> adapter_url/adapter_mode) but leaves several parameters (name, active, site_label, parent_path, etc.) unexplained and provides no defaults or constraints 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 uses a specific verb and resource: 'Create a BLE beacon proximity scaffold', and then enumerates its key components (sanitized beacon rows, zone maps, smoothing policy, adapter source, device-privacy notes). This clearly differentiates the tool from sibling tracking-bus creators by domain and artifact type.

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 provided on when to use this tool versus alternative tracking/scaffold tools. The phrase 'BLE beacon proximity' implies a context, but there are no exclusions, prerequisites, or mentions of sibling tools to help an agent choose this over a similar bus.

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

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

Annotations already indicate non-readonly, non-destructive, and open-world behavior, and the description's 'create' aligns with those. The description adds some context by enumerating scaffold contents and mentioning credential/privacy safety notes, but it does not disclose side effects, reversibility, or whether existing components are modified. This is acceptable but not rich.

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 efficiently lists key components without fluff. It is front-loaded with the primary action and resource, though the dense chain of technical terms could be more readable. Overall, it is appropriately concise for a scaffolding 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?

For a tool with 10 parameters, no output schema, and minimal annotations, the description is too brief to provide a complete picture. It omits return values, side effects, common usage patterns, and parameter semantics. Given the complexity, a longer description with structured examples or parameter explanations would be necessary for reliable invocation.

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

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

Schema description coverage is only 20% (2 of 10 parameters have descriptions). The description provides a high-level mapping to some concepts (adapter source, reminder maps) but does not clarify the meaning or expected format of most parameters (e.g., provider, timezone, event_count, adapter_mode). With such low coverage, the description does not adequately compensate for the missing parameter documentation.

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