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

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

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

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

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

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

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

The description covers transactionality, restrictions, supported types, and failure behavior comprehensively, which is essential for a complex tool with 5 parameters and no output schema. It does not mention return values, but the operational focus makes this acceptable. Overall, it provides enough context for correct invocation.

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

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

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

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

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

The description clearly states the tool's purpose: transactionally add, edit, delete, sort, and organize a COMP's custom parameters. This specific verb+resource combination distinguishes it from siblings like edit_td_node_metadata or set_parameters_batch, which focus on other parameter management tasks.

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

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

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

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true), the description reveals key behaviors: the text expression re-evaluates every frame, composite method, FPS probing, Null TOP output, and mode-specific behaviors (e.g., count_down clamps at zero). No contradictions.

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

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

The description is detailed but efficiently packed; every sentence serves a purpose (purpose, mode explanation, technical mechanics, sibling distinction). Slightly long but well-structured with key information 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?

The description gives a complete mental model for a tool with 8 parameters, no output schema. It covers purpose, behavior, modes, and technical implementation. The Null TOP output is mentioned. Minor gap: no mention of performance considerations or error scenarios.

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 descriptions for each parameter. The tool description adds context like the clock mode's timing origin (project start, not OS clock) and the formatter module, but does not provide additional semantics for individual parameters beyond what the schema already offers.

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 explicitly states the tool overlays a timecode as visual pixels onto a TOP, specifying modes (clock, count_up, count_down). It clearly distinguishes from sibling sync_timecode which syncs a clock signal without pixels.

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 directly compares with sync_timecode, indicating when to use this tool (for visual timecode) vs the sibling. However, it does not explicitly state when not to use this tool (e.g., if only clock signal is needed).

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

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

Annotations already indicate readOnlyHint and openWorldHint. The description adds behavioral traits: it is conservative, each flagged item carries a human-readable reason, and lists specific types of issues reported. This 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?

The description is two sentences long, front-loaded with actions and results, and every sentence adds value. No waste.

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

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

Given the tool has two parameters with full schema descriptions, an output schema, and annotations, the description covers purpose, usage context, behavioral details, and output characteristics. It is 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 descriptions cover both parameters (path and recursive) with clear meanings. The description does not add additional meaning beyond the schema, so 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 diagnoses a network for cleanup, listing specific items like dead operators, broken dependencies, orphan COMPs, and a dependency map. It distinguishes itself from siblings by naming complementary 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 it complements plan_visual and snapshot_td_graph, providing context for when to use this tool versus alternatives. It does not state explicit conditions for when not to use, but the complement statement is strong.

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 behaviors: creates LFO CHOP, binds targets, switches to expression mode. It does not mention side effects like performance or re-invocation behavior, but annotations provide safety hints (non-destructive, open world).

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 no wasted words. Front-loaded with core purpose, immediately informative.

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 main behavior and parameter usage adequately. With 7 parameters all described in schema, the description fills the gap for behavioral context. No output schema, but return value is implied.

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 adds context beyond schema, e.g., target format and behavior, waveform range sweep. This adds meaningful value despite high 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 clearly states the tool drives node parameters over time using an LFO, distinguishing it from manual keyframing. It specifies verb, resource, and mechanism, effectively differentiating from siblings like create_keyframe_animation.

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 parameter animation without manual keyframing, creating a clear contrast. However, it lacks explicit when-not-to-use or alternative guidance, though the contrast is strong.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description uses a specific verb ('Build') and resource ('self-contained GLSL TOP network') with a precise input ('pre-translated mapping'), making the tool's function immediately clear. It also distinguishes itself from sibling import tools by identifying as the 'foundation primitive' used by Shadertoy and ISF importers.

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

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

The description provides clear context: it is the underlying primitive for Shadertoy/ISF importers and is intended for power users with hand-translated fragments. It implies when to use directly versus through importers, though it does not explicitly name alternatives or exclude other tools.

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

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

Annotations indicate readOnlyHint=false, openWorldHint=true, destructiveHint=false. The description adds substantial behavioral details beyond annotations: it creates a container, exposes Strength and Bypass controls, has fallback logic for OCIO vs lookup, and explains Python parsing for .cube files without OCIO. This fully discloses the tool's behavior.

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

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

The description is efficiently structured with a clear purpose statement first, followed by functional details. Every sentence adds value. It is not overly verbose, though it could be slightly more concise without losing information. Good front-loading.

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 parameters, multiple file formats, fallback logic, exposed controls), the description covers all essential behaviors: how different file types are handled, the role of each parameter, and the result (container with controls). No output schema exists, so the description adequately explains the tool's output and side effects.

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 well-described parameters. The description adds extra meaning by explaining the purpose of source_path (grade vs standalone) and providing context for the prefer parameter (auto, ocio, lookup). This enriches understanding beyond the schema alone.

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 applies a colour LUT to an existing TOP inside a baseCOMP. It uses specific verbs and resources, and distinguishes itself from sibling tools by focusing on LUT application without confusion with other apply tools.

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

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

The description provides explicit guidance on when to use the tool and how to use it: passing source_path for grading an existing TOP or omitting it for standalone preview. It explains the preferred method for different file types, but does not explicitly compare to siblings like apply_glsl_top_mapping. The guidance is clear for the intended purpose.

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: it creates a new baseCOMP, wires effects in series, and returns a structured result. Annotations indicate non-read-only (mutating) and non-destructive, which aligns with the description. However, it does not disclose potential side effects, such as whether the parent_path must exist or if the operation is idempotent, leaving some transparency gaps.

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

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

The description is concise (four sentences) and well-structured: purpose, process, output, and alternatives are each addressed in a front-loaded manner. No fluff or redundant information is present.

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 creation process, return format, and alternative tools, but is missing details like whether the parent_path is created if missing or prerequisites for the source_path. Given the tool's moderate complexity with three parameters and no output schema, the description is adequate 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?

The input schema has 100% coverage with parameter descriptions. The description adds some nuance, e.g., explaining that source_path is pulled via a Select TOP and that certain effects in the enum redirect to another tool. Overall, the added value is moderate, meeting the baseline for a schema with high 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 clearly states the tool's purpose: 'Chain post-processing effects... onto an existing TOP'. It specifies the verb 'chain' and resource 'TOP', and distinguishes from siblings by naming create_color_grade, create_glitch, and post_passes_3d as alternatives for different use cases.

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

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

The description provides explicit guidance on when to use this tool versus alternatives: 'Use create_color_grade or create_glitch instead when you want a single dedicated effect with its own exposed controls.' It also mentions that 3D-aware modes redirect to post_passes_3d. However, it does not cover all possible alternatives or explicitly state when not to use this tool beyond 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?

Annotations indicate non-destructive and open-world. The description confirms creation of new entities (baseCOMP, nodes) and adds behavioral details like auto-layout, verification, and preview. It does not contradict annotations and provides extra context beyond the structured fields.

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 paragraph that is efficient but could be slightly more structured. It front-loads the primary action and includes necessary details without excess.

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 comprehensive for a tool with two parameters and no output schema. It explains return values (summary, JSON block), error handling, and the full workflow. No missing critical information.

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 both parameters with descriptions, but the description adds meaning: id must come from list_recipes, parent_path is a COMP. This clarifies constraints and usage beyond raw 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: instantiating a built-in recipe by ID inside a COMP. It details the steps (create baseCOMP, add/wire nodes, expose controls, auto-layout, verify, preview) and distinguishes from siblings like list_recipes and other recipe-related 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 implies when to use: when you have a recipe ID and want to build a ready-made network. It mentions error handling for unknown IDs, guiding appropriate usage. It could explicitly mention alternatives like scaffold_recipe_from_network or import_recipe_bundle, but the context is sufficient.

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

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

Annotations already signal non-read-only, open-world, non-destructive behavior. The description adds valuable context beyond that: the precise side effect is 'node creation in TD, not file writes,' the return value is the created GLSL TOP, and it clarifies the source note format. This goes beyond the annotations but could be more explicit about error conditions.

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

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

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

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

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

Given the tool's complexity (reading from vault, creating a node), the description covers the key aspects: source format, action, side effects, return value, alternative tool, and required environment settings. It lacks explicit error handling information, but with no output schema, the return value description is sufficient. The prerequisites are a strong addition.

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

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

The input schema already has complete descriptions for all 3 parameters (100% coverage), so baseline is 3. The description adds semantics by describing the expected structure of the note (```glsl fragment block, optional vertex block, frontmatter) and clarifying that the 'name' parameter defaults to frontmatter or 'glsl1', which is already in the schema but reinforces the intended usage. This adds meaning beyond the schema.

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

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

The description clearly states the tool's specific action: READ a shader note from the Obsidian vault and CREATE a GLSL TOP in TouchDesigner from it. It explicitly names the resource (vault note) and distinguishes itself from the sibling create_glsl_shader by noting that alternative is for inline shader code.

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

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

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

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

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

The description discloses important behavioral traits beyond the annotations: atomicity, stale-context checks, readback, rollback, and legacy response preservation. It also guarantees no structural changes to nodes, which adds significant context beyond readOnlyHint:false and destructiveHint:false.

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

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

The description is three sentences, front-loaded with the core purpose in the first clause, and each sentence adds distinct, non-redundant information: core function, mode-specific behavior, and non-destructive guarantee. No word is wasted.

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

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

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

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

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

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

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

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

The description clearly states the tool's purpose: 'Tidy an existing network into a readable left→right data-flow layout' with a specific verb and resource. It also distinguishes itself from topology-changing sibling tools by explicitly stating 'It never adds, deletes, or rewires nodes.'

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Schema description coverage is 100%, so all six parameters already have meaningful descriptions. The tool description adds high-level purpose but does not add per-parameter semantics beyond what the schema provides. This meets the baseline but does not exceed it.

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

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

The description uses a specific verb ('Create an OSC control preset') and clearly identifies the resource (ATEM switcher) and routing mechanism (atemOSC, Companion, or similar relay). It explicitly distinguishes itself from direct SDK usage by stating 'This does not use the Blackmagic SDK directly', which separates it from sibling tools like connect_blackmagic_atem.

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

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

The description provides clear context for when to use the tool: when building an offline-safe OSC-based control matrix for an ATEM switcher via a relay. It also gives an implicit when-not by stating it does not use the Blackmagic SDK directly, but it does not explicitly name an alternative tool for direct SDK scenarios, so it stops short of a full 5.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds value by specifying the exact destructive action: 'writes into the package folder (destructive).' It also discloses the registration in the manifest's docs list, providing behavioral context beyond the structured annotations. No contradiction.

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

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

Two sentences, front-loaded with the primary action, then usage context and a warning. Every word earns its place, with no redundancy or fluff.

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

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

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

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

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

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

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

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

The description clearly states the action: 'Copy documentation files into a package and register them in its manifest's docs list.' This specifies a concrete verb and resource, distinguishing it from sibling tools like make_portable_tox or bundle_dependencies. The context 'Use after make_portable_tox' further anchors its role.

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

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

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

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

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

Discloses the full workflow: sampling, fingerprint extraction, heuristic mapping, parameter tuning, dispatch, and optional compositing via apply_top_op. Also explains the dry_run behavior and the rationale for the synthetic default. No contradictions with annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true).

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 dense paragraph covering the core algorithm, default behavior, and key options. It front-loads the main action, but could be more structured (e.g., bullet points for clarity). Still concise and informative.

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 9 parameters, no output schema, the description explains the algorithm and default rationale but does not describe the normal return value (the generated generator) or details of the heuristic mapping. The gap for normal-case output reduces completeness.

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

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

With 100% schema description coverage, the baseline is 3. The description adds value beyond the schema by explaining why 'synthetic' is the default (macOS permission hangs) and clarifying dry_run's purpose (returns mapping without building). This justifies a 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 clearly states what the tool does: sample audio, compute a 4-feature fingerprint, run a deterministic heuristic to pick a Layer 1 generator (naming specific options), and dispatch it with tuned parameters. This distinguishes it from sibling create_* tools as an orchestrator.

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 on audio_source defaulting to 'synthetic' to avoid macOS mic-permission hangs, and mentions dry_run for testing. However, it does not explicitly contrast with using individual create_* tools directly, limiting when-not-to-use advice.

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

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

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

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

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

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

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

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

Covers purpose, mechanism, return structure (explicitly lists keys), environment requirements, and a common behavioral pitfall. No output schema exists, so the return dict mention helps. Lacks details on what happens if an existing op has the same name (destructive potential), but overall the description is sufficiently complete for a creation tool.

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

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

Schema description coverage is 100%, with each parameter already explained in detail (e.g., family selects operator type and stub signature, custom_params type inference). The description largely mirrors schema information, adding only minimal extra context such as the per-family stub names (chan/row/point/numpy). Baseline 3 is appropriate because the schema carries the semantic load.

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

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

The description uses a specific verb ('Scaffold') with a clear resource ('Script CHOP/DAT/SOP/TOP') and detailed outcome (onCook stub, custom parameters, companion callbacks DAT). It distinguishes from sibling tools like create_python_script and add_custom_parameters by its focus on the full Script op scaffolding workflow.

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

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

Provides clear context: when to use it (scaffolding a Script op with optional custom parameters and stub generation). Also states critical prerequisites (TDMCP_RAW_PYTHON=on, TDMCP_BRIDGE_ALLOW_EXEC=1) and a behavioral caveat about cooking. However, it does not explicitly name alternatives or conditions where another tool should be used instead, so it misses full when-not guidance.

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

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

Annotations (readOnlyHint=false, destructiveHint=false) are consistent with the description. The description adds rich behavioral context: iterative execution, dry-run mode, convergence detection, and what the loop cannot do. It also details the return object structure, enhancing 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 concise, single paragraph, front-loaded with key actions: scan, cluster, route, re-check, iterate. Every sentence adds value without redundancy. It efficiently conveys the tool's purpose, behavior, and limitations.

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

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

Given no output schema, the description fully details return values: status, iterations[], errors_before, errors_after, remaining[], recommended_prompts[], warnings. It also covers parameter interactions (dry_run, allowed_fixers) and edge cases (stalled, exhausted). The description is comprehensive for an iterative repair 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%, so baseline is 3. The description adds value by explaining behavior beyond schema, e.g., dry_run implies one iteration, allowed_fixers can be dropped for advisory mode. This extra context justifies a score of 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 clearly states the tool's purpose: scan a subtree for cook errors, cluster them, route to fixers, re-check, and iterate until clean, stalled, or exhausted. It uses specific verbs and resources, and distinguishes from sibling tools by naming specific fixers like repair_network, fix_shader, fix_reactivity.

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 states default dry-run mode (planning only, no writes), the loop's limitation (cannot fix shaders or dead reactivity itself, points agent to recommended_prompts), and the convergence threshold via min_progress parameter. It also explains the allowed_fixers parameter behavior, providing clear guidance on when to use and alternatives.

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

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

The description adds significant detail beyond the annotations: it explains the deterministic heuristic, the dry-run vs. write mode, the preservation of '*'-pinned user tags, and the required configuration. This provides rich behavioral context that the annotations alone do not convey.

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

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

The description is front-loaded with the core action and key behaviors (write flag, use case, prerequisites). While it is relatively long, every sentence adds necessary context. It could be slightly more concise but remains clear and well-structured.

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

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

Given the tool's complexity (10 parameters, no output schema), the description covers purpose, usage, prerequisites, and the key behavior of writing. It does not detail error handling or edge cases, but it is sufficient for correct selection and invocation in most scenarios.

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

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

All 10 parameters have descriptions in the input schema (100% coverage), which is thorough. The tool description does not repeat or augment these parameter-level details; it offers an overview but no additional semantics. As per guidelines, this results in a baseline score of 3.

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 that the tool inspects a library asset and emits a suggested tag set, difficulty, and description. It explicitly ties this to the goal of backfilling consistent tags for browsing by category, which distinguishes it from related siblings like tag_and_search_library (which combines tagging and search) and browse_vault_library (which only searches).

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 primary use case ('Use this to backfill consistent tags across a library') and lists prerequisites (TDMCP_VAULT_PATH and bridge for td_comp). However, it does not explicitly describe when not to use the tool or provide direct alternatives, though the sibling context makes it implicit.

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

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

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

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

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

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

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

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

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

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

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

The input schema already covers all 7 parameters with descriptions (100% coverage), so the baseline is 3. The description adds some relationship context (e.g., comp_path defaults to source_path, controls are inferred from primitive parameters) but does not significantly deepen meaning beyond the schema's own per-parameter descriptions.

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

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

The description starts with a specific verb and resource: 'Generate a performable control panel from an existing node/COMP's primitive parameters.' It clearly distinguishes this from siblings like add_custom_parameters by focusing on the infer-and-append workflow and the optional binding behavior.

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

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

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

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description adds critical behavior: 'fail-forward, per-operation warnings; not transactional' and 'Names created earlier can be referenced by later operations'. This provides meaningful context 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 two sentences, front-loading the core purpose and key differentiator. Every word adds value, 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 tool's complexity (multi-operation chaining, failure behavior, name referencing) and the presence of an output schema, the description covers all essential aspects. It fully prepares 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?

With 100% schema coverage, baseline is 3. The description adds the important concept that names created earlier can be referenced by later operations, which is not explicit in the schema but crucial for understanding parameter usage.

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 'Run an ordered list of create / connect / setParam operations in one call', specifying a unique verb and resource. It explicitly distinguishes from sibling 'set_parameters_batch' by noting it only sets parameters.

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 with set_parameters_batch, providing a clear usage boundary. However, it does not comprehensively cover when not to use this tool or list other alternatives among the many siblings.

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?

Disclosures beyond annotations: auto-mapping heuristics, master knob appending, fail-forward warnings, and fatal conditions. No contradictions.

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

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

Concise yet dense, no filler. Front-loaded with core action, then alternatives, then details. Every sentence adds value.

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

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

Given 5 params, no output schema, and annotations present, description covers usage, behavior, error handling, and sibling contrasts completely.

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 100%; description adds auto-mapping heuristic details (bright→level, scale/size→bass, etc.) and clarifies intensity scale. Highly informative.

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

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

States 'Make a whole COMP react to the music in one call' with specific verb and resource. Explicitly distinguishes from siblings create_audio_reactive and bind_to_channel.

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 when-to-use vs alternatives, lists prerequisites (produce feature CHOP first), and describes fail-forward behavior. Complete 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 (readOnlyHint=false, destructiveHint=false) provide basic safety info. The description adds behavioral context: parameters are switched to expression mode for live tracking, optional Lag CHOP insertion for smoothing, and envelope follow behavior. This goes well beyond the annotations, though it could mention if existing expressions 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: the first states purpose and typical sources, the second expands on smoothing behavior with a concrete example. Every sentence is substantive, no redundancy, and the most critical information (what it does) is 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 complexity (9 parameters, smoothing options, expression mode) and no output schema, the description covers the primary workflow and smoothing options. It lacks explicit mention of return values or side effects beyond expression mode changes, but overall it is sufficient for correct tool 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?

All 9 parameters have descriptions in the schema, and the description adds practical meaning: explaining scale/offset as mapping gain, attack/release as envelope follower times, smooth as symmetric convenience, and smoothing_container location. The second sentence provides a usage example that clarifies semantic nuances.

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 'Drive one or more node parameters from a CHOP channel by expression' and specifies the scope (audio_features/tempo_sync channels). It distinguishes from siblings by explicitly naming 'extract_audio_features / create_tempo_sync' as complementary tools, making the purpose and context unambiguous.

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

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

The description explains when to use the tool (to wire audio or tempo data into visuals) and how to apply smoothing (attack/release vs smooth). It gives concrete scenarios like 'fast attack + slow release for a punchy hit'. However, it does not explicitly state when NOT to use it or provide direct comparisons to alternatives like 'bind_audio_reactive'.

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

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

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

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

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

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

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

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

Given the tool's complexity (node creation, sync behavior, external file access, return values), the description covers all essential aspects: side effects, does-not-do clarification, configuration prerequisites, and output. Since there is no output schema, the explicit list of returned fields is especially valuable. The description is complete enough for an agent to invoke the tool correctly.

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

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

Schema coverage is 100% for all 4 parameters, so the baseline is 3. The description reinforces the 'file' parameter pointing at a vault note and mentions sync with 'sync:true', but these details are already present in the schema property descriptions. Thus, the description adds minimal additional semantic value beyond what the schema already provides.

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

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

The description clearly states the action ('CREATE a Text DAT in TouchDesigner'), the specific resource (a Text DAT whose `file` parameter points at a vault note), and the intended outcome (note text loads into TD). It is distinct from generic node creation siblings by emphasizing the vault binding and sync behavior.

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

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

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

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

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

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

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

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

Two sentences, front-loaded with purpose, listing components and supported formats without redundancy. No filler.

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

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

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

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

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

All 11 parameters have schema descriptions covering 100%, so the schema carries the parameter semantics. The tool description doesn't elaborate on individual parameters but provides broader context about formats and fallback, which is consistent with the schema. Baseline 3 is appropriate.

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

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

The description clearly states a specific action ('Create a self-contained TouchDesigner render scaffold') with a defined scope (Blender scene or Blender-exported asset) and enumerates the produced components (File In SOP, Geometry COMP, PBR material, lights, Camera, Render TOP, Null TOP). It distinguishes itself from generic import/model tools by focusing on Blender-specific assets and including a warning about .blend export.

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

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

The description implies usage context: it is for Blender scenes/exported assets and creates a full render scaffold. It mentions supported formats and warns about potential need to export .blend first, which acts as a prerequisite. It doesn't name alternative tools or explicitly say when not to use it, but the context is clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds context: it is a read-only discovery step and returns matching recipes/packages for selection. No contradictions.

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

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

Two sentences with no unnecessary words. Information is front-loaded and efficient.

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

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

With output schema present and strong annotations, the description adequately covers the tool's purpose, workflow, and return values. No missing critical information.

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%, but the description hints at the purpose of include_recipes and include_packages. However, tags, query, and package_dir are not explained beyond their names, leaving gaps.

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 'browse', the resources (recipes and packages), and the context (read-only discovery step). It distinguishes from siblings like apply_recipe and install_library_package.

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 when to use: before instantiating a recipe or installing a package. It does not mention when not to use, but the context is clear given sibling names.

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 states it is read-only, requires no TouchDesigner connection, reads from local disk, and returns a flat items array with per-category counts. This aligns with annotations (readOnlyHint, destructiveHint=false) and adds valuable behavioral context beyond what annotations provide.

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

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

The description is two sentences plus a final requirement line, front-loaded with purpose and key features. Every sentence adds value with no unnecessary 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?

Given the tool's simplicity, the description covers inputs, behavior, and output format. However, it does not mention if there is any limit on results or pagination; this is minor given that an output schema exists but is not shown. Still, a complete description would address potential result size.

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 coverage is 100% and the description elaborates that 'kinds' filters by category and 'query' is a case-insensitive substring filter on title/tags, adding clarity beyond the schema alone. The description could also mention that 'all' lists every known category.

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 'vault's recipes, shaders, presets, components, and setlists'. It explicitly distinguishes from sibling tools like 'browse_library' and 'list_recipes' by specifying it lists vault items with title/tags/description for selection without opening 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 indicates when to use ('so the agent can pick from the library without opening individual notes'), provides filter options (category and substring query), and notes the prerequisite (TDMCP_VAULT_PATH). It does not explicitly exclude alternative tools, but the context is sufficient. A slight improvement could be noting when not to use this tool.

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

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

Annotations indicate it's not read-only, not destructive, and open-world. Description adds that failures become warnings (fail-forward) and partial chain returns useful info, which is beyond annotations. However, it does not detail all error behaviors.

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, front-loaded with purpose. Every sentence adds value with no waste. Efficient structure.

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?

No output schema, description vaguely mentions 'useful info' but doesn't specify return structure. For a tool with nested ops array and partial success behavior, more detail on return format would improve completeness.

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

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

Schema coverage is 100%, baseline 3. Description adds meaning beyond schema: explains ops array wiring, parameter resolution (string matching op name resolves to path), and naming conventions. Adds substantial value.

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

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

The description clearly states it is a 'Declarative Layer-2 builder for an ordered CHOP processing chain,' using specific verb 'build' and resource 'CHOP chain'. It distinguishes from sibling tools like 'create_node_chain' by focusing on CHOPs and wiring pattern.

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?

Includes a usage tip about ending with nullCHOP for bind_to_channel readiness, but does not explicitly state when to use this tool versus alternatives like connect_nodes or create_node_chain. Context is implied but not fully specified.

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 (not read-only) and destructive=false (non-destructive). The description adds important behavioral context: 'POPs are Experimental — result carries `unverified` marker', 'unknown par names become warnings (fail-forward)', and per-kind safe defaults. This complements the annotations well.

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 dense paragraph that front-loads key info (purpose), then explains usage, defaults, experimental note, and a tip. It is concise with no wasted words, though it could be slightly more structured (e.g., bullet points) for easier scanning.

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 (3 parameters with a nested array), the description covers purpose, wiring logic, defaults, experimental nature, and a tip. No output schema exists, so return values are not expected. It is fairly complete for a builder tool, though it could mention that it creates a network of POP operators.

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: for `chain`, it explains wiring logic and defaults; for `params`, it notes that string values resolving to op paths add functionality; for `parent`, it references sibling tool semantics. This adds moderate semantic value 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 'Declarative Layer-2 builder for an ordered POP chain', specifying the verb (build), resource (POP chain), and distinguishing it from siblings like build_chop_chain and build_sop_geometry. The term 'POP (Point OPerator)' is domain-specific but precise.

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 detailed usage guidance: how to pass a `chain` list, wiring rules, default behavior for `parent`, per-kind defaults, and a tip to end with `null_pop`. It does not explicitly exclude any use cases or compare with alternatives, but the context of sibling tools implies appropriate usage.

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

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

Annotations already indicate non-read-only and non-destructive. Description adds fail-forward behavior (partial chain returns info) and wiring semantics. Minor gap: doesn't specify if existing nodes are overwritten, but openWorldHint provides 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?

Compact single paragraph with no wasted words. Each sentence serves a purpose: purpose, behavior, tip, sibling differentiation.

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

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

Covers core chain-building, error handling, best practice (nullSOP), and alternative for multi-input. No output schema but description mentions useful info from partial chain. Complete for agent use.

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

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

Description adds significant meaning beyond 100% schema coverage: explains wiring logic, fail-forward on per-op failures, and param string values resolving to op paths. This compensates the high 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 clearly states 'Declarative Layer-2 builder for an ordered SOP geometry chain' with specific verb 'build' and resource 'SOP geometry chain'. It distinguishes from siblings like `connect_nodes` and `build_chop_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?

Explicitly advises using `connect_nodes` for multi-input fan-in and recommends ending with `nullSOP` for handoffs. Provides clear context for when to use this tool vs 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?

Annotations declare destructiveHint=true, and the description adds valuable details: 'Rewriting mutates the live network' and explains the rewiring process. The ability to avoid mutation via rewrite_refs=false is clearly stated, surpassing the basic annotation.

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

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

The description is front-loaded with the main action, then a clear step-by-step breakdown, followed by sibling comparison and a behavioral warning. Every sentence adds value, and the structure is logical 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 complexity (scan, copy, rewrite, save), the description covers all essential aspects: purpose, workflow, parameter roles, side effects, and alternatives. The output schema is present, so return value details are not needed. Comprehensive for an agent.

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

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

Schema coverage is 100% with parameter descriptions, but the description enriches understanding by contextualizing each parameter within the workflow. For example, rewrite_refs is explained in terms of its impact on live network mutation, and include_missing is clarified with behavior when missing files.

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: to make a COMP self-contained by recursively scanning, copying assets, rewriting references, and saving as a .tox with manifest. It explicitly distinguishes from siblings make_portable_tox and collect_project_assets, providing a precise verb+resource+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 explicitly provides when-use guidance by contrasting with sibling tools: 'Delta vs make_portable_tox (which saves the .tox only, leaving external assets behind) and collect_project_assets (which only reports refs).' It also notes the mutative behavior and the option to set rewrite_refs=false for a non-destructive run.

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 readOnlyHint and destructiveHint; description adds implementation details (vision vs histogram), fallback behavior, and return structure. 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?

Single paragraph front-loads purpose, then explains paths, return, and usage. Generally efficient, though slightly verbose in listing return fields.

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 4 parameters, no output schema, the description explains return structure, usage context, and warns about vision path inertness. Fully sufficient for this simple tool.

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

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

Schema covers 100% of parameters, description adds context like 'Smaller is faster' for width/height and explains use_vision behavior, adding value beyond schema.

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

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

The description clearly states the verb (render/describe), resource (TOP preview), and scope (check if alive). It distinguishes itself from sibling tools which are mostly creation or other utilities.

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

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

Explicitly says to use after a build to confirm rendering, not just black frame. Mentions two paths and that vision is currently inert. Does not list alternatives but 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 indicate write (readOnlyHint=false) and non-destructive (destructiveHint=false) with openWorldHint=true. Description confirms it writes PNG images and appends to note, adding details on file structure and default behavior. 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?

Three sentences, no wasted words, front-loaded with main action and result. Clearly structured with purpose, mechanism, and usage.

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

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

Covers all necessary aspects: what it does, where files go, default behavior, prerequisites. No output schema needed as actions are fully described.

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

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

Schema coverage is 100% but description adds meaning: explains note defaults to today's date for accumulation, gallery subfolder, and width/height defaults. Provides context beyond schema definitions.

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

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

Description clearly states verb 'Captures', resource 'preview still from a TOP', and purpose: appends to a dated gallery note in Obsidian vault. Distinguishes from sibling tools like record_movie or snapshot_td_graph by specifying the exact action and target.

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.' Also notes prerequisite: 'Requires a configured TDMCP_VAULT_PATH.' Does not explicitly exclude alternatives but gives sufficient context.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true. The description adds valuable behavioral context: it 'survives TDMCP_BRIDGE_ALLOW_EXEC=0' (important for safety), explains the reconciliation process, and the optional inclusion of undocumented optypes. No contradictions.

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

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

Four sentences, each serving a purpose: main function, optional behavior, single operator usage, and a safety constraint. No redundancy, front-loaded with key information.

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

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

Given the simplicity of the tool (2 optional params, no output schema) and good annotations, the description is largely complete. It covers both modes and the constraint. However, it does not explicitly describe the return format or what 'flags' means, which would be helpful for an agent.

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

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

Schema coverage is 100% with both parameters described. The description adds that omitting operator checks the whole knowledge base and passing one checks only that one, which aligns with the schema's optional nature. This adds marginal value beyond the schema, but not enough to exceed baseline 3.

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 'reconcile' and the resources: 'operator knowledge base' vs 'ground-truth creatable-optype list'. It specifies the exact function: flag documented operators that are creatable vs deprecated/unavailable, and optionally list undocumented live optypes. This distinguishes it from sibling tools like search_operators or validate_operator_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 provides clear context: use to check availability of operators, optionally for a single operator or the whole knowledge base. It mentions the constraint 'Survives TDMCP_BRIDGE_ALLOW_EXEC=0'. However, it does not explicitly state when not to use or name alternative tools.

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

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

Annotations indicate write (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds that compute writes a manifest and verify re-hashes for comparison, and that no TD bridge is needed, providing useful behavioral context beyond annotations.

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

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

Two sentences efficiently convey the core functionality and actions. Could be improved by briefly listing key parameters or providing a more structured summary, but it is clear and direct.

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 (9 params, nested objects, no output schema), the description covers the main workflow but lacks details on parameter usage, default exclusions, and manifest format. It is minimally complete for a basic understanding but not fully 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 has 9 parameters with 0% description coverage. The description only implicitly mentions 'action' and 'path', leaving other parameters like strict, manifest, exclude_globs, etc. unexplained. This does not compensate for the lack of 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 the tool computes or verifies SHA-256 checksums for tdmcp artifacts, with specific actions compute and verify. It distinguishes itself from sibling tools by focusing on checksum operations for packaging artifacts.

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 explains that action=compute writes a manifest and action=verify reports mismatches. It also mentions 'No TD bridge required,' but does not explicitly state when to use this tool versus alternatives or provide exclusions.

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

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

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

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

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

The description is two sentences, front-loaded with the main action, and every clause adds meaningful detail (structure, optionality, determinism, controls, use-case). No filler or redundant information.

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

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

For a 9-parameter creation tool with no output schema, the description adequately sets expectations by describing the created structure (video lane, audio lane, Null outputs, controls) and the deterministic layout. It doesn't describe return values, but that is not essential for a creation tool. A small gap is lack of mention of error conditions or prerequisites, but overall it is complete enough.

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

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

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

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

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

The description clearly states the tool's purpose with a specific verb ('Create') and resource ('synchronized clip transport container'), and enumerates its components (Movie File In TOP video lane, optional Audio File In CHOP lane, Null outputs, controls). It explicitly positions the tool as a reusable building block before clip launchers, VJ decks, or stream/output chains, distinguishing it from sibling tools.

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

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

The description provides explicit usage context: 'Use it as a reusable building block before clip launchers, VJ decks, or stream/output chains.' This clearly indicates when to use this tool in relation to higher-level alternatives. It doesn't explicitly say when not to use it, but the relationship to alternatives is clear, which is strong guidance.

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

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

The description discloses that the TD scan is read-only, but writing the manifest (when out_manifest is set) may overwrite an existing file, aligning with destructiveHint=true. It also reveals the fallback heuristic for file detection and notes it is UNVERIFIED across TD builds, which is critical behavioral context beyond the annotations.

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

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

The description is a single, well-structured paragraph that front-loads the main purpose. Every sentence provides necessary information: scan target, reporting details, read-only nature, file-writing condition, and detection heuristic caveat. No redundant or extraneous content.

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 (scanning a network, detecting multiple dependency types, varying par support) and the presence of an output schema, the description covers all essential aspects: scope, reporting, mutability, heuristic limitations, and the style_supported flag. It is sufficient for an agent to understand the tool's capabilities and constraints.

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

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

Schema coverage is 100% for three parameters. The description adds context: explains parent_path as root of subtree, out_manifest as optional write path (empty means no file), and include_missing_only as filter. This adds meaning beyond the schema, justifying a score above baseline 3.

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 scans a COMP subtree for external file dependencies (movie/image, fonts, LUTs, externaltox) and reports each referenced file with node+parameter and existence status. The verb 'scan' and specific resource 'COMP subtree' are precise, and the tool is well-differentiated from siblings like create_media_bin or get_td_nodes.

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

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

The description implies usage when an agent needs to inventory external file dependencies in a TouchDesigner network. However, it does not explicitly state when not to use this tool or provide alternatives. Given the specificity, the usage context is clear but lacks explicit exclusion 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 indicate readOnlyHint=true and destructiveHint=false. Description adds that it uses getNetworkTopology + getNetworkErrors, and lists the exact return shape, 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?

Four concise sentences, front-loaded with key purpose and behavior. Every sentence adds value: read-only, compress, return structure, underlying methods, comparison to siblings.

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 output schema, description lists return keys. Covers use case, limitations, and relationship to other tools. Adequate for a tool with 6 optional parameters and no required fields.

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

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

All 6 parameters have full schema coverage (100%). Description adds context like 'Hard ceiling on approximate output tokens' and 'Include top-3 grouped error keys. Off for purely structural turns.' Enhances understanding beyond schema.

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

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

Clearly states 'compress a TD subtree into a structured digest' with a specific verb and resource. Distinguishes from siblings by referencing get_td_topology / snapshot_td_graph and noting it's cheaper for planning.

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' and 'no new bridge work. Cheaper than... for planning turns.' Provides clear context for when to use this tool over alternatives, with named sibling tools.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false. The description adds that it is read-only, compares documentation rather than live settings, and pulls from an offline knowledge base. This aligns with annotations and provides context 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 a single, efficient sentence. It front-loads 'Read-only' and immediately states the core purpose, with no wasted words.

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

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

Given the presence of an output schema, the description does not need to detail return values. It covers the key contextual information: source (offline knowledge base), scope (documentation vs live nodes), and provides an explicit alternative (compare_td_nodes). The sibling list includes that alternative, aiding agent decision-making.

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 mentions 'overview metadata plus shared and unique documented parameters' which aligns with the include_parameters parameter, but does not add detailed semantics 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 verb 'compare' and the resource 'TouchDesigner operator types' from the embedded offline knowledge base. It distinguishes itself from the sibling tool 'compare_td_nodes' by specifying 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?

The description explicitly says when to use this tool (compare operator documentation) and when not (for live node parameter diffs, use compare_td_nodes). This provides clear guidance on tool selection.

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

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

Annotations already convey readOnlyHint and destructiveHint. Description adds value by specifying default diff behavior (only differing values) and the exact return structure, but the read-only note is redundant with annotations.

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

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

Two concise sentences front-loaded with key info (read-only, diff, returns), no filler, every sentence adds value.

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

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

Covers purpose, usage context, behavioral traits, and return values. Output schema exists and is referenced in description. Distinguishes from sibling. Complete for the tool's complexity.

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

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

Schema coverage is 100% and description does not add additional parameter-level context beyond what the schema already provides. 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?

Description clearly states it diffs parameters of two nodes, mentions read-only nature, and distinguishes from sibling tool diff_snapshots by specifying that it compares live nodes versus whole-network 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?

Explicitly says 'useful for aligning settings across similar operators' and contrasts with diff_snapshots, providing clear when-to-use and 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?

The description details the append-only nature, file format (JSONL), storage location, and offline capability, going well beyond the sparse annotations. It also explains the behavior of each action, providing comprehensive behavioral transparency.

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 main purpose and is concise, though slightly dense. It effectively communicates key information without 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 no output schema, the description explains return formats (JSON for read, markdown for export) and the trail file format. It covers all three actions and their parameters adequately 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?

With 100% schema description coverage, the description adds some value by explaining defaults and context (e.g., 'Ignored for read/export'), but does not significantly enhance 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 clearly states it maintains an append-only per-component revision history as a JSONL trail, listing three distinct actions (append, read, export). It distinguishes from siblings by mentioning it pairs with save_component_to_vault and provenance_stamp.

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 context for when to use the tool (offline, no TD bridge required) and mentions related tools. However, it does not explicitly state when not to use it or provide direct comparisons with alternatives, which slightly limits 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 provide readOnlyHint=true and destructiveHint=false. The description reinforces that it is a 'Read-only diagnostic' and adds behavioral context: it probes live COMPs and reports missing/broken files. No contradictions.

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

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

Two succinct sentences with front-loaded purpose and context. Every word adds value; 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 the description explains the tool's purpose and when to use it, it omits explanation of parameters and does not describe the output format (e.g., what the 'report' looks like). Given no output schema and 0% parameter coverage, this is a 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?

Schema description coverage is 0%, meaning the description does not explain the parameters 'paths' and 'parent_path'. The description fails to add meaning beyond the schema, such as how to use these parameters or their defaults. Agent cannot infer correct usage.

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 externaltox paths and reports missing/broken linked component files. It is a read-only diagnostic, which distinguishes it from sibling tools like 'manage_component' or 'inspect_component_manifest' that may have different purposes.

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

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

The description provides explicit when-to-use guidance: 'run it when externally-linked .tox components may have moved or gone stale, before relying on them in a build.' It does not mention when not to use or list alternatives, but the context is clear enough.

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-destructive and open-world behavior. The description adds transparency by detailing the two execution paths (LLM or grammar parser) and the chaining capability, which are not evident from 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?

The description is extremely concise with two sentences that front-load the purpose and provide key behavioral details. Every word is necessary, and no information is redundant.

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), the description covers the main purpose and execution modes. However, it could be more complete by explaining what 'validated' entails or how errors are handled, but the essentials are present.

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

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

Schema coverage is 100%, so the description adds value by explaining how parameters like 'apply' and 'containerName' relate to chaining into create_cue_sequencer, providing context beyond the 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 the tool's function: converting natural language to a validated cue list (SetlistSchema variant). It distinguishes itself from siblings by mentioning the optional chaining into create_cue_sequencer and specifying the use of LLM or grammar parser.

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 creating cue lists from descriptions, but lacks explicit guidance on when to use this tool versus alternatives like create_cue_sequencer or create_setlist_runner. It mentions the chaining option but doesn't specify conditions for preferring the LLM over the grammar parser.

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

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

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

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

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

A single sentence that is front-loaded with the verb 'Create' and packs all key features without fluff. It is efficient and well-structured, earning its place.

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

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

With 8 parameters and no output schema, the description needs to set expectations for the scaffold's structure and how parameters affect it. It only lists high-level feature names and omits return values, parameter-specific behavior, or post-creation expectations, making it incomplete for moderate complexity.

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

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

Schema description coverage is only 38%, and the description partially maps to just two parameters (prompt_slot_count via 'prompt slots', include_controlnet via 'ControlNet hints'). It does not explain server_url, endpoint_kind, output_folder, active, or parent_path semantics, leaving significant gaps for the agent.

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

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

The description clearly states the tool creates an AUTOMATIC1111/Forge Stable Diffusion WebUI handoff scaffold with specific components (prompt slots, result maps, ControlNet hints, adapter notes), distinguishing it from sibling bridge tools like connect_comfyui for other image-generation backends.

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

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

No guidance is provided on when to use this tool vs alternatives. The description only states what the tool creates; it does not compare to other bridge tools or specify prerequisites, exclusions, or preferred scenarios.

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

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

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

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

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

Single concise sentence, front-loaded with the action verb, no wasted words.

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

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

For a tool with 7 parameters, no output schema, and low schema coverage, the description is too brief. It doesn't explain the return value, prerequisites, how the scaffold integrates into an Ableton Link setup, or what 'connect' implies vs 'create'. The description leaves significant gaps for an agent to invoke correctly.

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

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

Schema coverage is only 29% (2/7 params described). The description vaguely mentions 'beat/bar maps' which relates to signature/export_bars but doesn't explicitly explain any of the 7 parameters. With such low schema coverage, the description was expected to compensate but doesn't.

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

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

The description uses a specific verb ('Create') and resource ('Ableton Link timing scaffold') with a clear scope ('beat/bar maps for tempo-locked visual systems'). It clearly distinguishes itself from generic create tools by specifying the timing domain.

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

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

No guidance on when to use this tool versus alternatives like create_tempo_sync or sync_external_clock. It lacks explicit contextual triggers, prerequisites, or exclusions.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

For a tool with 11 parameters, no output schema, and minimal schema descriptions, the one-line description is insufficient. It does not explain return values, parameter semantics, enum choices, or when to use the tool, leaving an agent with only vague hints about the scaffold contents.

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

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

Schema description coverage is only 18%, and the description does not compensate by explaining key parameters such as base_id, table_name, sync_direction, adapter_mode, or record_count. Terms like 'record maps' and 'sync policy' hint at parameter purposes, but not enough for an agent to select or configure all 11 parameters correctly.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

No guidance is given on when to use this tool versus alternatives such as other connect_* tools or generic create_* tools. The description provides no context about prerequisites, typical use cases, or scenarios where this tool is preferred.

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

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

Annotations already indicate this is not read-only, not destructive, and open-world. The description adds that it creates a scaffold with specific maps, which is helpful but doesn't disclose side effects, dependencies, or prerequisites beyond that.

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

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

The description is a single, front-loaded sentence that states the core action and key components with no filler. Every word contributes to understanding the tool's purpose.

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

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

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

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

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

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

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

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

The description uses a specific verb 'Create' and a specific resource 'ARKit Face Capture OSC scaffold' with details about blendshape and head-transform maps. It clearly distinguishes this from sibling tools by targeting a niche ARKit/OSC workflow.

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

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

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

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

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

The description adds valuable behavioral context beyond the annotations by clarifying that this creates a scaffold with UDP transport placeholders and operator approval notes—not a live functional connection. This nuance is not captured by readOnlyHint=false or openWorldHint=true, though it stops short of detailing side effects like created COMP placement or overwrite behavior.

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

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

The description is a single, front-loaded sentence with no filler or redundancy. It efficiently conveys the core purpose and key deliverables.

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

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

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

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

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

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

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

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

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

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

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

No explicit guidance is given on when to use this tool versus alternatives. While the sibling atem_switcher_control implies a distinction between scaffold creation and actual control, the description never states this exclusion or provides any usage context.

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

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

With annotations already indicating readOnlyHint=false and destructiveHint=false, the description adds some behavioral context by listing what the scaffold creates (sanitized beacon rows, zone maps, etc.). However, it does not disclose side effects, required permissions, or integration behavior beyond the creation act. No contradiction with annotations.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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