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

With no annotations, the description carries the full behavioral burden, and it delivers real value: it declares the call idempotent, states the side effects (release protected result artifacts, eventually reap the job), and explains the automatic-acknowledgement path. It stops short of covering authorization requirements, failure/indeterminate-result semantics beyond the retry hint, or concurrency concerns.

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 dense sentences, front-loaded with the core action and immediately followed by the side effects and the usage routing. No filler, though the middle sentence packs two distinct consequences (artifact release and job reaping) that could be slightly clearer.

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

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

For a required-args-only mutation with no annotations and no output schema, the description covers behavior and usage well but omits parameter identification and any notion of what a failed or already-acknowledged call returns. It is adequate but has a real gap on the inputs the agent must supply.

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% across three required parameters (convoy_id, delivery_id, target_host_id), so the schema provides no meaning at all. The description refers obliquely to 'this controller' and 'the target' and 'one terminal Convoy delivery' but never maps those concepts to the parameter names, so an agent must guess which identifier is which.

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 names a specific verb (acknowledge) and a specific resource (a terminal Convoy delivery observed by this controller), and it distinguishes the operation from siblings by noting that convoy_get_artifact/convoy_save_artifact success paths auto-acknowledge. An agent can tell what this tool does and roughly where it sits relative to the artifact tools without opening any schema.

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

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

It states both when the tool is NOT needed ('Verified artifact downloads and successful artifact saves acknowledge automatically') and when it IS needed ('for other terminal results or to retry an indeterminate acknowledgement'). This is explicit when/when-not guidance with an implied alternative path, which is exactly the routing information an agent needs.

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 no annotations, the description carries the full burden and does well on the core contract: targets run independently, may run concurrently, results preserve input order, partial success is possible, and there is explicitly no distributed atomicity or rollback. It omits auth requirements, per-target error behavior, and what the default-true 'wait' flag changes, so it is not a 5.

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 tight sentences, front-loaded with the operation and fan-out scope, then the concurrency/ordering guarantee, then the explicit limitation. Every sentence earns its place with no filler.

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

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

For a 6-parameter batch tool with no annotations and no output schema, the description supplies the concurrency contract and some return-shape information (order preservation, partial success). It is still incomplete on parameter behavior (wait, override, timeout_s) and on how partial failures surface, which the agent needs to call it correctly.

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

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

Schema description coverage is only 17% (effectively just idempotency_key), so the description must compensate for six parameters and does not. It never explains wait, override, timeout_s, or expected_runtime_id, leaving the majority of the schema's meaning unstated.

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

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

The description states a specific verb and resource ('Run one ordered Envoy batch on each explicit Convoy target'), and the fan-out framing distinguishes it from single-target siblings like convoy_call. It does not name a sibling or state explicitly what it is not, so it falls short of a 5.

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

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

Usage is implied: the fan-out phrasing ('on each explicit Convoy target') signals this is for multi-target work versus a single-target call. However, there is no explicit when-to-use guidance, no stated prerequisites, and no named alternative among the many convoy_* 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?

No annotations are provided, so the description carries the full burden. It usefully discloses that the target is always explicit and that there is no silent local TouchDesigner fallback, which is real behavioral context, but it omits failure semantics, auth/connectivity requirements, and what the remote relay actually returns.

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 tight sentences, front-loaded with the core action and free of filler. It is efficient, though arguably too sparse given the tool's complexity.

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

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

For a tool with 9 parameters, nested arguments, no output schema, and no annotations, the description is too thin. It never explains operation semantics, the arguments payload, timeout/retry behavior, or what a call returns, leaving the agent under-equipped to invoke it correctly.

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

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

Schema coverage is only 22% (9 params, only wait and idempotency_key documented), so the description should compensate but largely does not. It references the target concept by 'host_id and node_id', which hints at target_host_id/target_node_id, yet leaves operation, convoy_id, arguments, timeout_s, and expected_runtime_id unexplained.

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

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

The description states a specific verb and resource ('Relay one Envoy operation to an explicit Embody node'), which an agent can distinguish from convoy_batch ('one' operation vs. batch) and from node-management siblings. It does not explicitly name the alternative it contrasts with, but the action is unambiguous.

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

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

There is no explicit when-to-use / when-not guidance and no sibling is named as an alternative, so routing decisions among convoy_call, convoy_batch, and convoy_start_node must be inferred. The 'never silently falls back' line clarifies routing behavior rather than selection criteria.

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 no annotations, the description carries the full burden and does so well: it discloses that cancellation is a routed request, that queued work cancels definitively while active work gets best-effort process-tree termination, that past-boundary TouchDesigner work is reported non-cancellable rather than simulated, and that cancellation never wakes TouchDesigner. These are non-obvious side-effect and guarantee disclosures an agent needs.

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, front-loaded with the core action, and each sentence adds a distinct behavioral fact. It is dense with domain jargon ('host boundary', 'durable delivery') but there is no filler.

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

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

Behavioral coverage is strong, but for a 3-required-param mutation tool with no annotations and no output schema, the description omits parameter meaning entirely and says nothing about what is returned when cancellation succeeds or fails. Adequate but with clear gaps.

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

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

Schema coverage is 0% and all three parameters (target_host_id, convoy_id, delivery_id) are required, yet the description never explains what any of them identify or their format. Phrases like 'the exact host' and 'durable delivery' gesture at target_host_id and delivery_id but do not map clearly enough to compensate for the total schema 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?

States a specific verb (cancel) and resource (job / durable delivery), and scopes it to the owning host. It is distinguishable from siblings like convoy_get_job and convoy_ack_job, though it never names an alternative tool explicitly.

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

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

The description implies usage by describing the three delivery states (queued, active, past-host-boundary), which tells the agent what outcomes to expect. However, it gives no explicit when-to-use versus convoy_ack_job or other convoy tools, leaving routing to inference.

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 no annotations, the description carries the full burden and does so: it discloses the refusal condition (unfinished delivery), that it names blocking delivery ids for cancellation, that finished results never hold a row, that online rows are never forgotten, and that relayed requests follow the owning host's rules. These are exactly the mutation-safety and side-effect details an agent needs.

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?

Information-dense and front-loaded, with the core action first and constraints following. It is long and packs many clauses into run-on sentences, but virtually every clause (refusal, auto-eviction, bulk equivalent) earns its place, so little 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?

No output schema or annotations exist, yet the description covers action, targeting, refusal behavior, blocking-id feedback, auto-eviction context, and the bulk alternative. An agent has everything needed to call this 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 50% (host_id documented, node_id not), and the description compensates by explaining host_id's origin (convoy_list_nodes), the omit-for-local default, and the relay behavior it triggers. node_id's meaning is only implied as 'the row,' leaving a small 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?

States a specific verb (delete/forget) and resource (a stale node row), and immediately clarifies what a stale row is ('the row a renamed, moved, or deleted project left behind'). An agent can distinguish this from convoy_list_nodes, convoy_cancel_job, and convoy_start_node without opening a schema.

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

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

Gives explicit when-to-use (cleaning up stale rows), the local-vs-relayed condition governed by host_id, and the automatic alternative ('Rows unseen for a week are evicted automatically; this is the immediate manual path'). It also names the bulk in-TD equivalent (Forget Offline Nodes... button), covering the alternative surface.

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 no annotations, the description carries the burden and does disclose meaningful behavior: images come back as MCP image content, other files are verified and returned as a local temporary path, and the artifact is private. It omits the side effect of writing a temp file to the client machine, permission requirements, and what happens on timeout.

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 tight sentences with the core action front-loaded, followed by output behavior and then the input guidance. No filler or restated name/title.

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?

Return-values are well explained, which matters since there is no output schema. However, with no annotations and four required parameters at zero description coverage, the definition leaves the host/node/convoy identifier relationships and failure modes undocumented.

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% across 5 parameters, including a nested 'artifact' object, so the description must compensate and largely does not. It clarifies the 'artifact' parameter (a reference returned by a Convoy job) but says nothing about target_host_id, target_node_id, convoy_id, or the timeout_s bound.

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

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

States a specific verb and resource ('Materialize one private Convoy artifact from its owning host onto this client machine') and immediately distinguishes itself from convoy_save_artifact by direction of data flow. The return-format sentence makes the operation's nature 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?

Gives a concrete usage directive: use the artifact reference returned by a Convoy job rather than a remote filesystem path. This tells the agent what input to supply, but it never contrasts this tool with sibling convoy_save_artifact or explains when retrieval is appropriate versus leaving the artifact on the host.

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 no annotations, the description carries the full burden; it does state this is a read ('Read'), which implies non-mutating, and discloses the meaningful trait that the record lives on the owning peer (so that peer may need to be reachable). It says nothing about blocking vs. non-blocking behavior, error state when the delivery isn't ready, or permissions, which are real gaps for a zero-annotation 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?

Two sentences, front-loaded with the action before the parameter provenance hint, and every clause conveys information the agent needs. No filler or restatement of the tool name.

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 no output schema, no annotations, and 0% schema coverage across four parameters, the description should do far more: it never describes what is returned, whether the call waits for the delivery, what 'since' does, or how a missing/expired job fails. The provenance hint is useful but insufficient for the complexity of this tool.

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

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

Schema description coverage is 0%, so the description must compensate, and it partially does by telling the agent where the three required IDs (target_host_id, convoy_id, delivery_id) originate. It adds no format or value semantics for those IDs and completely ignores the optional 'since' parameter, leaving one of four parameters unexplained anywhere.

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?

Names a specific verb and resource ('Read a previously relayed Convoy delivery') and adds scope ('from its owning peer'), which is more precise than a generic fetch. It doesn't explicitly contrast itself with near neighbors like convoy_get_artifact or convoy_ack_job, so an agent must infer the boundary from the convoy_call reference.

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

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

Gives one concrete prerequisite: the three IDs must come from convoy_call, which tells the agent this is a follow-up read rather than an initiating call. It offers no when-not-to-use guidance or comparison against convoy_get_artifact, convoy_ack_job, or convoy_cancel_job, so the usage context is only implied.

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 no annotations, the description carries the full burden, and it does disclose two meaningful traits: read-only and non-waking (no side effects on TouchDesigner), plus the implicit skip of unreachable hosts. It says nothing about permissions, result shape, pagination, or failure behavior, so coverage remains partial.

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

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

Two tightly written sentences with the resource scope front-loaded and the behavioral guarantee second. No filler, no repetition of the 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 low-complexity, zero-required-parameter list tool with no output schema, the description covers purpose, scope, and safety behavior, and even notes that only reachable hosts are queried. The remaining gap is the absence of any return-format or empty-result expectation.

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 all three filters are self-documented as optional host/node/namespace selectors, so the baseline of 3 applies. The description adds no semantics beyond the schema, such as whether filters combine as AND or how multiple filters interact.

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 ("List") and enumerates the exact resources returned: controller sessions, selected targets, leases, and active work. The scope ("across reachable Convoy hosts") is precise, though it never names a sibling such as convoy_list_nodes to distinguish itself explicitly.

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

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

Usage is only implied: it reads as a discovery/monitoring call, and "never wakes TouchDesigner" hints that it is the safe choice when you don't want side effects. There is no explicit when-to-use vs. when-not guidance or pointer to an alternative sibling.

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 no annotations, the description carries the full load and does well: it names the return fields (host/node/runtime identity, connection state, address, version), and discloses the non-obvious rule that local nodes expose capabilities (td_python, full_shell) while remote nodes deliberately omit the field, where absence means unknown rather than permitted. It doesn't mention permissions or behavior when the host is unreachable, keeping it below 5.

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 dense sentences with the scope statement front-loaded and no filler. The final sentence about the capabilities asymmetry is verbose but earns its place by preventing a dangerous misreading of an absent field.

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 no output schema or annotations, the description compensates by enumerating the returned metadata and the local/remote capabilities distinction—enough for an agent to consume the result correctly. It omits pagination, failure modes, and permissions, which are minor for a listing tool.

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

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

Schema coverage is 100% and the single convoy_id parameter is already documented in the schema as an optional namespace filter. The description adds no syntax, format, or default details beyond that, so the 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 gives a specific verb and resource ('List the local and reachable remote Embody nodes known to this machine's Convoy host'), which is more precise than the bare name. It doesn't explicitly distinguish itself from siblings like convoy_list_controllers or get_convoy_status, so it stops short of a 5.

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

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

It bounds the result set (local plus reachable remote nodes) but never states when an agent should call this versus convoy_list_controllers, convoy_ping, or get_convoy_status. There are no exclusions or prerequisites, leaving selection entirely to inference.

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 no annotations, the description carries the full burden, and it does add real behavioral context: host-private scope, the opt-in gate and idempotency requirement for command submission, and the refusal of mcp_tool_call. It stops short of disclosing return format, timeout behavior, pagination, or error semantics for a tool with seven actions.

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 tool's identity and scope before the preconditions and the exclusion. Dense but every sentence carries distinct information; no filler.

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

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

For a 7-action, 8-parameter tool with no annotations, no output schema, and 0% schema coverage, the description omits the action vocabulary, the nested params contract, and timeout semantics. What it covers is valuable but far from sufficient to call the tool correctly across all actions.

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% across 8 parameters, including a nested 'params' object that is entirely opaque. The description rescues idempotency_key and implies the id-bearing params via 'site/machine inventory... command status,' but timeout_seconds, command_type, and the action enum values themselves are never explained.

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 names a specific resource ('consumer of Owlette's published API') and enumerates its scope ('site/machine inventory, online detail, and command status'), which maps onto the action enum. It also distinguishes itself from siblings by stating 'Owlette is not the Convoy LAN transport,' so an agent can separate it from convoy_call/convoy_batch without opening the schema.

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

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

It gives a precondition for the submit_command path (separate local host opt-in plus idempotency key) and a hard exclusion (mcp_tool_call is always refused here). However, it never states when to choose this tool over the numerous convoy_* siblings for inventory or status reads, leaving the read paths' routing implied.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses a side-effect constraint ('without starting or waking TouchDesigner') and that it reports 'known online state,' which is meaningful behavioral context. However, it omits timeout behavior, failure modes, idempotency handling, and whether the call is read-only or has side effects on Convoy state.

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 tight sentences, no filler, front-loaded with the action (measure reachability) and immediately scoped. Every clause earns its place.

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

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

For a tool with 5 params at 0% coverage, no annotations, no output schema, and a large sibling set, the description is too thin. An agent cannot tell what target_host_id vs target_node_id mean, what happens on timeout, or how results are surfaced. The non-waking guarantee is the only substantive context provided.

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

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

Schema description coverage is 0%, so all five parameters are undocumented in both schema and description. The description mentions 'one explicit node' which loosely maps to target_node_id, but target_host_id, convoy_id, timeout_s, and idempotency_key get no semantic explanation. The description fails to compensate for the severe coverage 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?

States a specific verb (Measure) and resource (Convoy reachability to one explicit node) via host-native ping. Distinguishes itself reasonably from siblings like convoy_get_job or convoy_owlette, but doesn't explicitly name an alternative like get_convoy_status which could confuse an agent choosing between them.

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 when-to-use guidance or alternatives named. The phrase 'one explicit node' hints at scope, and 'without starting or waking TouchDesigner' implies a non-invasive check, but the agent is left to infer when convoy_ping is preferable to get_convoy_status or get_td_status.

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 no annotations the description carries the full burden, and it does disclose meaningful traits: the target node must be 'running', require_clean refuses dirty/unsaved/unverifiable state, save_then_restart saves first, and destructive policies are unavailable. It omits other behavioral concerns such as idempotency, concurrency via expected_runtime_id, and timeout/blocking behavior.

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

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

Three dense sentences, front-loaded with the core action followed by policy semantics; essentially no filler. Slightly compressed wording ('one exact running') costs a little clarity but overall it is well-sized.

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 an 8-parameter mutation tool with 0% schema coverage, no annotations, and no output schema, the description covers purpose and policy but leaves the required expected_runtime_id, the four required identity parameters, and the idempotency/timeout controls unexplained. Insufficient 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 description coverage is 0%, so the description must compensate for all 8 parameters, yet it only explains the `policy` enum values. target_host_id, convoy_id, target_node_id, expected_runtime_id, wait, timeout_s, and idempotency_key receive no meaning beyond their names, leaving most of the parameter surface undocumented.

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

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

States a specific verb (Restart) and resource (TouchDesigner node) with a clear scope: 'one exact running' node. This implicitly distinguishes it from the sibling restart_td (whole-instance restart) and convoy_start_node, though no sibling is named explicitly.

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 policy explanation ('default require_clean ... save_then_restart explicitly saves first') implies when each mode is appropriate, giving useful selection context. However, it never states when to choose this tool over siblings like restart_td, convoy_start_node, or convoy_forget_node, nor any prerequisites.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses that existing files are preserved unless overwrite is true, and that project root is derived rather than caller-selected. However, it says nothing about authorization/permission requirements, timeout behavior, what verification entails, or failure modes for a 7-param mutating 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?

Three focused sentences, front-loaded with the action. The middle sentence about project derivation is a bit awkward but earns its place by clarifying scope. 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?

A mutating, multi-parameter tool with nested object input, no annotations, no output schema, and 14% schema coverage demands substantially more behavioral context than provided. Verification semantics, timeout behavior, permission/auth needs, and the artifact object's structure are absent.

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 14%, so only the filename field and overwrite semantics are covered between description and schema. The description explains overwrite and the derived project root, but target_host_id, convoy_id, target_node_id, artifact (nested), and timeout_s are semantically undocumented in both places.

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

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

States a specific action (verify and save) and a specific resource (a Convoy artifact into the bridge project's .embody/convoy/artifacts directory). Differentiates from the sibling convoy_get_artifact, which presumably retrieves rather than persists. Not a tautology, though scope phrasing is slightly convoluted.

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

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

Implies when the tool is used (verifying and persisting an artifact locally) but never names an alternative such as convoy_get_artifact or states explicit when-not conditions. Adequate but leaves the agent to infer the distinction from the sibling list.

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

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

With no annotations, the description carries the full burden and does well: it discloses that the selection survives peer dropouts, never falls back to local TouchDesigner, and that clear restores direct routing. It omits auth/permission requirements and error or conflict behavior when a selection already exists.

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 tight sentences: the core action is front-loaded, followed by critical behavioral guarantees, then the argument shortcuts. Every sentence earns its place with no redundancy.

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

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

No output schema or annotations exist, and 4 of 5 parameters are undocumented. The description conceptually completes the tool's role and behavior but leaves the parameter model (which IDs select the node) unexplained, which is a meaningful gap for a 5-param tool.

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

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

Schema description coverage is 0% across 5 parameters. The description only explains clear (and the no-arg case); convoy_id, target_host_id, target_node_id, and expected_runtime_id are entirely undocumented, so it fails to compensate for the coverage 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?

States a specific verb and resource: pinning this session's ordinary Envoy tool calls to one exact Convoy node. The purpose is clear and scoped to this MCP session. It does not explicitly distinguish itself from siblings like convoy_list_nodes or convoy_call, but the operation is unambiguous.

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

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

Gives two concrete usage modes: call with no arguments to inspect the selection, or clear=true to restore direct local routing. However, it does not say when to select a node versus leaving routing local, nor differentiate from related siblings such as convoy_list_nodes or convoy_get_status.

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 no annotations, the description carries the full burden and does disclose a meaningful behavioral trait: no executable, path, argv, or environment is accepted, so the launch profile is host-pinned and not caller-controlled. It still omits failure behavior, whether 'wait' blocks, timeout/idempotency semantics, and auth requirements, so the disclosure is partial rather than rich.

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

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

Two tightly written sentences, front-loaded with the action and scope, followed by the security constraint. No filler or repetition.

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

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

A mutation-style start operation with no annotations, no output schema, and six fully undocumented parameters leaves significant gaps: nothing about return values, success/failure signals, timeout defaults, or idempotency behavior. The security note is valuable but does not cover the operational surface an agent needs.

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% across six parameters, and the description explains none of them. target_host_id, convoy_id, and target_node_id are at least implied by 'host-pinned launch profile' and 'previously registered node', but wait, timeout_s, and idempotency_key receive no explanation anywhere.

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?

Names a specific verb (start) and resource (a previously registered offline TouchDesigner node from its host-pinned launch profile), which is more precise than a generic launch tool. The 'offline, previously registered' qualifier implicitly distinguishes it from restart-style siblings, but no sibling is named explicitly, so it stops short of a 5.

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

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

The phrase 'previously registered offline' implies a precondition (the node must already exist and be stopped), which gives usable context. However, it never states when to prefer this over convoy_restart_node, restart_td, or launch_td, leaving the selection to inference.

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 no annotations, the description carries the full behavioral burden and does well: it discloses the sha256-pinned manifest, downgrade-refusing behavior, durable per-node job dispatch, returned handles, and the auth note ('without the TD Python grant'). It omits failure modes, reversibility, and what the handles actually contain, so not a full 5.

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

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

Front-loaded with purpose and scope, then behavior, then the prerequisite. Dense but every clause earns its place; slightly run-on but no filler.

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

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

For a mutation tool with no output schema and no annotations, it explains the dispatch model, return handles, follow-up (poll convoy_get_job), and version prerequisite. The main gap is the unexplained convoy_id and timeout_s parameters and no error/failure behavior.

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 50%, so the description must compensate and only partially does: 'one node or the whole fleet' maps to the node/all parameters and the mutual exclusivity is confirmed in the schema. convoy_id and timeout_s receive no explanation in either place, leaving a 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?

States a specific verb (self-update) and resource (Embody on Convoy nodes) with clear scope ('one node or the whole fleet'). An agent can distinguish it from siblings like convoy_restart_node or convoy_start_node without opening any schema.

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

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

Clear context for when to use it: updating Embody to the latest release, scoped to one node or fleet, and it routes the agent to convoy_get_job for polling. It also names a prerequisite (Embody >= 6.0.257). However it doesn't state when-not to use it or contrast explicitly against alternative update paths.

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 no annotations, the description carries the full burden and does well: it discloses the auto ladder sequence (WM_CLOSE -> escape -> enter), that it stops when the window disappears, and the consequence that enter accepts a dialog's default (potentially committing something). It omits failure behavior (what happens if the dialog never closes) and any permission/instance-targeting caveats.

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 dense sentences, front-loaded with the action and the ladder behavior, then the sequencing guidance. No filler; every clause adds decision-relevant 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 no-annotation, no-output-schema tool the description is nearly complete: it covers the default behavior, the fallback ladder, the safety boundary, and the recommended pre-step. A minor gap is the absence of failure/timeout behavior when the dialog persists.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema by explaining the semantic effect of each action (close/escape decline vs enter accepts the default) rather than just restating the enum values.

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

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

States a specific verb+resource (dismiss a modal dialog) plus the scope (blocking a TouchDesigner instance) and the post-condition (verify it is gone). It also carves out a boundary the siblings don't cover, noting the main TouchDesigner window is never a 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?

Explicitly routes the agent to run list_dialogs (with screenshot=true) first, and gives decision guidance for the rungs: close/escape decline a question, enter accepts its default. This tells the agent not just when to call it but which action to choose.

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 no annotations, the description carries the full burden and does disclose key behavioral traits: it is a read-only, host-only operation that never wakes TouchDesigner, and it clarifies routing implications for other tools. It does not detail return format or side effects, but the safety and scope context is valuable and goes beyond what the schema provides.

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 dense sentences with no filler. It front-loads the primary purpose and then adds routing context. Every clause earns its place.

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

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

For a zero-parameter status tool with no output schema and no annotations, the description covers what it reports, that it's safe and passive, and how it relates to other tools' routing. It doesn't enumerate the exact fields returned, but given the absence of an output schema, the description is sufficiently complete 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?

The tool takes zero parameters, so per the rubric the baseline is 4. There are no parameters to describe, and the description appropriately focuses on output instead. No additional parameter semantics are needed.

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

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

The description clearly states a specific verb and resource — 'Report this machine's Convoy host presence and ... realm, peer, queue, and identity status.' The scope is distinct from siblings like convoy_list_nodes or get_td_status. However, it doesn't explicitly contrast with other status tools (e.g., get_td_status) to help the agent pick correctly.

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 it: to check this machine's Convoy host presence, noting it's a host-only read that never wakes TouchDesigner, and that explicit convoy_* tools use this host for remote routing. It implies usage but doesn't state exclusions or name an alternative status tool for comparison.

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 no annotations, the description carries the full burden and does well: it discloses the returned fields, that it remains callable when TouchDesigner is down, and that envoy_unresponsive / main_thread_stalled signal a live-but-frozen TD. It does not mention timeouts, latency, or whether the call is strictly read-only, which keeps it short of a 5.

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 short sentences, front-loaded with the core purpose and followed by return contents and the key edge-case flags. Every sentence adds information; 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?

No output schema exists, so the description must explain returns — and it does, listing connection state, crash detection, liveness, and config, plus the frozen-TD flag semantics. For a zero-parameter health-check tool this is fully adequate.

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

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

The tool takes zero parameters, so the schema carries nothing to interpret and the baseline is 4. The description correctly adds no parameter chatter.

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

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

States a specific verb and resource (check whether TouchDesigner is running and Envoy reachable) and enumerates the exact signals returned (connection state, crash detection, process liveness, project config). This is clearly distinguishable from sibling job/node tools like convoy_get_job or convoy_ping, which target Convoy rather than TD/Envoy health.

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?

"Works even when TD is down" implies a diagnostic/health-check use case and hints that this is the tool to reach for during outages, but no alternatives are named and no when-not condition is given (e.g., versus get_convoy_status or convoy_ping). Usage is implied rather than explicit.

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 no annotations, the description carries the full behavioral burden, and it usefully discloses that the call blocks until Envoy is reachable before returning. It does not cover other relevant traits such as behavior when an instance is already running, failure modes, or permissions.

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 tight sentences with the core action and scope front-loaded, and the blocking behavior positioned last as a useful caveat. The parenthetical '(unpinned: the registry default's)' is dense but still efficient overall.

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

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

For a zero-required-parameter launch tool with no output schema and no annotations, the description covers the essential scope logic and the readiness behavior. Absent is any note on return values or what happens on timeout failure, but the core is sufficient to call it correctly.

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

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

Schema description coverage is 100%, so both parameters (timeout, project_path) are already fully documented. The description reinforces the project_path default (pinned instance) but adds no syntax or format beyond what the schema 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?

The description gives a specific verb+resource (launch TouchDesigner) and precisely scopes which .toe it opens (this session's pinned instance, or registry default when unpinned). It partially differentiates from the sibling restart_td via 'start TD for the first time,' but never names restart_td, leaving the launch-vs-restart boundary slightly fuzzy.

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 supplies a clear when-to-use condition: 'start TD for the first time or restart after a crash.' However, it doesn't explicitly name or rule out the restart_td sibling, so the agent must infer which tool applies to a plain restart versus a crash recovery.

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

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

No annotations are provided, so the description carries the full burden and does so well: it discloses that it runs on the bridge and therefore works during a blocked main thread, that TD's dialogs are not OS-readable, and that a blocked=true signal is returned when a dialog is up. It omits permission/auth requirements and how the returned list is structured, but covers the non-obvious behavioral traits.

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 carrying distinct information (purpose, execution context, text-reading workaround, return signal), with the core purpose front-loaded. Dense and mostly waste-free, though the parenthetical dialog enumeration could be tightened.

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 an unusual execution scenario (working during a blocked main thread) with no annotations and no output schema, the description supplies the needed context: what it lists, when it works, how to read dialog text, and the blocked flag. It leaves the return structure of the dialog list undescribed, which is a minor gap without an output schema.

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

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

Schema coverage is 100%, so the baseline would be 3. The description adds real value beyond the schema by specifying the screenshot workflow — 'pass screenshot=true to save a PNG of each one and Read it' — which tells the agent what to do with the parameter's output, something the schema alone does not convey.

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

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

States a specific verb and resource ('List the modal dialogs a TouchDesigner instance currently shows') and enumerates concrete dialog types. However, it never names or differentiates from the obvious sibling dismiss_dialog, so an agent must infer that this is the read-only counterpart rather than being routed explicitly.

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

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

Gives clear context for when this is the tool to reach for: while TD's main thread is blocked and every other Envoy tool is timing out. It also tells the agent to pass screenshot=true and Read the PNG when text is needed. It stops short of naming the alternative action (dismiss_dialog) after a dialog is found.

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 no annotations, the description carries the full burden and does disclose real behavior: graceful quit, blocking wait for process exit before relaunch, and that other instances are never affected. It omits what happens to unsaved work in the project being killed, which is a meaningful gap for a restart/terminate tool, and says nothing about failure or partial-restart 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?

Four short sentences, front-loaded with the core action and scope before the sequencing detail and the when-to-use trigger. The parenthetical about unpinned behavior is slightly dense but every sentence earns its place; no filler.

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

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

For a two-param, zero-required tool with no output schema and no annotations, the description covers action, scope, sequencing and trigger condition adequately. The remaining hole is the fate of unsaved project state and behavior when TD is not actually running, which an agent would want before invoking.

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

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

Schema description coverage is 100%, so the schema already documents both parameters and the baseline is 3. The parenthetical '(unpinned: the registry default's)' adds modest resolution on project_path's default, but the description adds no formatting details (e.g. path syntax) 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?

States a precise verb+resource ('Quit this session's pinned TouchDesigner gracefully and relaunch its .toe') and scopes it tightly to one instance, so an agent can distinguish it from a plain launch. It stops short of naming the obvious sibling (launch_td) that an agent could confuse it with, so it is clear but not maximally differentiating.

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?

'Use when TD is running but needs a fresh start' gives explicit triggering context, and the scoping clauses ('unpinned: the registry default's', 'Other TD instances are never touched') tell the agent what state to be in. It never states the negative case (e.g. use launch_td when TD is not running) or names alternatives, so it is clear but lacks exclusions.

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

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

With no annotations, the description carries the full burden and does well: it discloses that only this session's bridge is re-pinned, that other sessions are untouched unless all_sessions=true, and that all_sessions writes the registry default and bumps active_epoch. It omits error behavior (e.g. unknown instance name) and any permission prerequisites.

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 tight sentences, front-loaded with the dual behavior and the listing mode before the switching mode. Minimal waste, though the instance/all_sessions wording partly duplicates the schema descriptions.

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 exists, and the description does state that listing returns instances with their status, which covers the main return expectation. Combined with the mutation-scope disclosure, it is nearly complete for a 2-param tool, missing only failure modes.

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

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

Schema description coverage is 100%, so the schema already documents both parameters including the toe-basename format and the all_sessions default. The description restates the same semantics without adding format, validation, or edge-case detail, so the 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 names a specific verb (switch) and resource (this session's TouchDesigner instance) and explicitly covers the dual mode (switch vs list). An agent can distinguish it from siblings like get_td_status, launch_td, and restart_td without opening any schema.

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

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

It gives clear conditional usage: omit 'instance' to list, supply a name to re-pin. That covers the when-to-use decision for both modes, but it does not name an alternative tool or state when a different sibling (e.g. get_td_status) would be preferable.

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