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

Adds behavioral context beyond annotations: 'Takes effect immediately on the user's live stream' and the call-only condition. Annotations already indicate mutation (readOnlyHint=false) and idempotence (idempotentHint=true), which the description does not contradict.

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 main action. Each sentence adds distinct information: what, when, and how. No filler or redundant 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?

Covers the tool's purpose, usage condition, and parameter identification in a compact way. With no output schema, no return description is needed. Slightly incomplete in not explicitly stating that scene_id or scene_name should be provided, but this is implied by the wording.

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 already fully document all three parameters with 100% coverage. The description restates 'scene_id (preferred, from get_scenes)' and 'exact scene_name (case-insensitive)', adding minimal new meaning beyond the schema. No additional semantics like mutual exclusivity are provided.

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

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

Description opens with a specific verb and resource: 'Switch DualStream's live output to another scene.' This clearly differentiates from sibling tools like get_active_scene (read) and create_scene (new scene), and scopes the action to the live stream.

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?

States an explicit trigger: 'call only when the user asked for a scene change.' Also gives param preference: scene_id preferred from get_scenes, or exact scene_name. Does not explicitly name alternative tools for other operations, but the call-only condition serves as a clear exclusion.

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?

Even with annotations (readOnlyHint=false, destructiveHint=false), the description adds meaningful behavioral detail: the source appears live immediately if the scene is active, lands centered by default, and returns the new source_id. No contradictions 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?

Four tight sentences, each covering a necessary aspect: purpose, behavior, parameter guidance, follow-up actions, and return value. No redundant or filler content; the most important information appears first.

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 lacking an output schema, the description explicitly states the return value (new source_id). It covers default scene, live appearance, conditional parameter requirements, default positioning, and reference to related tools. The description is complete for a tool with moderate complexity and good schema coverage.

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 covers all parameters (100%), giving baseline 3. The description enriches by specifying that device_id and source_type must be passed verbatim from list_devices for cameras/displays/windows, clarifying the relationship between these parameters. This goes beyond the schema's individual 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 opens with 'Add a source to a scene', a specific verb+resource statement that clearly identifies the function. It further distinguishes itself from sibling tools by explaining the live behavior, default scene behavior, and post-add positioning via set_source_transform.

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 defaults to active scene, requires device_id and source_type from list_devices for camera/display/window sources, and directs users to set_source_transform or set_source_shape for further editing. It does not explicitly state when to use this tool over alternatives, but the guidance is sufficiently purposeful.

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, but the description adds critical behavioral context: the action 'takes effect immediately on the user's stream' and populates 'both canvases (H+V).' This reveals side effects beyond what annotations convey, making the tool's impact transparent.

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

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

The description is three sentences, with the main purpose front-loaded. Every sentence adds necessary detail: the default behavior, the explicit usage condition, and the alternative mode. No wasted words or redundancy with 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?

The tool has three parameters, no output schema, and minimal annotations. The description covers the key behavioral aspects: the two modes of operation, immediate effect on the stream, and the fact that both canvases are populated. This is sufficient for an agent to invoke the tool correctly in 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 descriptions cover 100% of parameters, so baseline is 3. The description adds value by explaining the relationship between recipe_id and target_scene_id: the default creates a new scene, while passing target_scene_id adds sources to an existing scene. This clarifies parameter interplay beyond the individual 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: 'Apply a recipe to the live stream.' It further distinguishes its behavior from siblings by explaining the default action (creates a new scene and switches to it) and the alternative (adds to an existing scene via target_scene_id). This specific verb+resource+scope fully clarifies what the tool does.

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

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

The description gives an explicit usage directive: 'call only when the user asked to build/switch a scene.' It also explains when to use target_scene_id as an alternative to the default behavior. While it doesn't name sibling tools like create_scene, the guidance is clear and actionable.

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 meaningfully to the annotations: annotations only declare readOnlyHint=false and destructiveHint=false, but the description explains the off-air vs. immediate activation behavior, that it returns a scene_id, and suggests populating before activating. This goes beyond the structured fields, even if it doesn't cover edge cases like duplicate names or failure 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?

Two sentences, no fluff, front-loaded with the core action. Every clause adds value: the first sentence states the verb and object; the second explains the activate option, the workflow, and the return value. Highly 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?

For a simple tool with 2 parameters and no output schema, the description covers creation, activation behavior, return value usage, and the recommended next step (add_source). It even references sibling tools to guide the overall workflow. Complete enough for an agent to select and invoke it correctly without further context.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra semantics for the activate parameter by explaining its timing and conditional use ('call only when...'), which enriches the schema's 'Switch the live output now' without being redundant. The name parameter is straightforward, so the added value is moderate.

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

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

The description opens with a clear action: 'Create a new empty scene.' It distinguishes itself from sibling tools like activate_scene (switch to an existing scene) and get_scenes (list) by specifying it creates a new scene, and by referencing activate_scene for later activation. This leaves no ambiguity about the tool's 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?

The description explicitly states when to use activate:true ('call only when the user wants to build/switch to it now') and when not to ('otherwise it's created off-air... then activate_scene when ready'). It also names the alternative tool (activate_scene) and provides a clear workflow, satisfying the 'when-to-use vs alternatives' 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?

Annotations already indicate destructive intent, and the description adds the operational consequence that 'events stop relaying immediately'. This provides useful context beyond the annotations, though it does not mention irreversibility or permission requirements.

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, concise sentence that states the action and a key behavioral consequence. It is front-loaded and every word earns its place, with no 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 simple destructive tool with one parameter and no output schema, the description covers the core action and a notable effect. It lacks details about return values or explicit irreversibility, but those are either implied or covered by annotations, making it sufficiently 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?

The input schema fully documents the only parameter (automation_id) with a clear description referencing list_automations. The tool description adds no additional parameter semantics beyond reinforcing the 'by id' mechanism, so it meets the baseline for 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 verb 'Delete' and the resource 'stored automation', specifying the identifier-based operation. It distinguishes from siblings like list_automations and save_automation by emphasizing deletion and the immediate effect on event relaying.

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 need for an automation id ('by id') and the effect (events stop relaying), but does not explicitly state when to use this tool versus alternatives or provide exclusions. The sibling tools provide context, but the description itself lacks direct usage guidance.

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

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

The readOnlyHint annotation already indicates this is a read-only operation. The description adds beyond that by disclosing the exact return structure ({scene_id, scene_name}) and the null-when-none behavior. This is useful context for a simple getter, though it does not need to go deeper given the trivial nature.

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 includes the action, the resource, the output shape, and the edge case (null). Every word earns its place; there is 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?

For a parameterless, read-only getter with no output schema, the description fully specifies the return value and the null condition. There are no missing pieces that would hinder an AI agent from selecting and invoking this tool correctly.

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

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

The tool has zero parameters, so the baseline is 4. The description does not need to explain parameter semantics because there are none, and the input schema is empty. No further value could be added here.

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 'Return' and the specific resource 'currently active scene', and it distinguishes itself from siblings like get_scenes (which likely lists all) and activate_scene (which sets the active scene) by focusing on the current state. The output format and null case are explicitly described.

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

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

The description implies usage (when you need the current active scene), but it does not explicitly mention when to prefer this over get_scenes or activate_scene. There are no exclusions or alternatives named, so it falls short of providing explicit guidance.

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

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

Annotations declare readOnlyHint=true, and the description does not contradict this. It adds meaningful behavioral context beyond the annotation, such as the meaning of consent state ('pending' means the streamer must approve the client) and the recommendation to use it as a first troubleshooting step. This enriches the agent's understanding of the tool's role and dependencies.

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

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

The description is exactly two sentences: the first states the core purpose and output details, the second gives usage guidance. Every word earns its place, with no redundancy or filler.

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

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

For a no-input diagnostic tool, this description is complete. It covers what the tool reports, the meaning of consent state, and when to invoke it. Even without an output schema, it gives enough information about the expected response to guide 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?

The tool has zero parameters, so the baseline is 4. The description adds no parameter details (none are needed) but compensates by describing what the report includes (version, port, auth mode, consent state), which is helpful given the absence of an output schema.

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

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

The description uses the specific verb 'Report' and clearly identifies the resource (DualStream desktop app's control server reachability). It lists the exact information provided (app version, port, auth mode, consent state), making it distinct from sibling tools that manipulate scenes or triggers.

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

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

It explicitly instructs to 'Call this first when other DualStream tools fail' and explains the diagnostic value: distinguishing 'app not running' from real errors. This is a clear when-to-use directive, and although no alternative tools are named, the tool's unique role makes this 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 mark the tool as read-only, but the description adds substantial behavioral context: buffered events, eviction semantics with truncated flag, server-side receipt timestamps, and the meaning of stream_event entries. This goes well beyond the annotation without contradicting it.

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?

In just three sentences, the description packs the event list, ordering, parameter usage, truncation handling, timestamp origin, and use case distinction. It is front-loaded and every sentence 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?

Despite lacking an output schema, the description explains event types, ordering, truncation semantics, and timestamp provenance, and cross-references get_state_snapshot for resync. It misses explicit response structure but is sufficiently complete for a polling 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?

The schema already describes both parameters (100% coverage), but the description adds practical usage context, especially for since_seq (polling pattern) and the implication of truncated=true. This enriches the schema's basic definitions.

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

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

The description opens with a specific verb ('Poll') and resource ('buffered control events'), enumerates the event types covered, and clarifies ordering ('oldest first'). It also distinguishes itself from wait_for_event by positioning itself for catch-up versus live reaction, fully differentiating from siblings.

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

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

Explicit usage guidance is provided: pass since_seq to get only new events, resync via get_state_snapshot when truncated=true, and use wait_for_event for live reaction instead. It also mentions the intended catch-up use case, giving clear when-to-use versus 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?

Beyond the readOnlyHint annotation, the description adds valuable behavioral context: scene_id stability across rename/reorder, invalidation on collection switch, and the emitted event.scenes_changed with reason 'collection_switched'. This discloses important side effects and data behavior not apparent 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?

Two sentences with no fluff. The first sentence states the primary function and output format; the second adds essential behavioral nuance. Both sentences earn their place, and the description is front-loaded with the action.

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

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

For a no-parameter, read-only list tool, the description is complete: it covers scope (active collection), output structure, and the key caveat about id stability and collection switches. No output schema exists, so the description correctly fills the gap by specifying the return format.

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 has no parameters, so schema coverage is trivially 100%. The baseline for zero parameters is 4, and the description doesn't need to add parameter semantics. It focuses on return format and behavior instead, which 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 'List all scenes in DualStream's active collection' with a specific verb and resource, and specifies the return format. It distinguishes itself from siblings like get_active_scene and create_scene by emphasizing 'all scenes' and the active collection 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 context is clear: use this to list all scenes in the active collection. While it doesn't explicitly mention alternatives or exclusions, the 'all scenes' phrasing implies a contrast with targeted tools like get_active_scene. The scope is well-defined, but no explicit 'when not to use' is given.

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 readOnlyHint annotation already declares this is a safe read operation. The description adds value by disclosing the authoritative nature of the snapshot and its complete scope (all scenes + active id), as well as its role in resynchronization after connection or scene-change events.

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

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

The description is two concise sentences that front-load the purpose and follow with explicit usage guidance. 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?

Despite having no output schema, the description fully specifies the return content (scene ids, names, active id). Combined with the usage context and read-only annotation, this provides a complete picture for an agent to select and invoke the 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?

The tool has zero parameters, and the input schema is empty, meaning there is nothing to explain. The description makes this clear by not mentioning any inputs, aligning with the 0-param baseline.

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

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

The description clearly states the tool returns an authoritative snapshot of all scenes (scene_id + scene_name) and the active scene id, using a specific action ('snapshot') and resource ('scene state'). This differentiates it from sibling tools like get_scenes and get_active_scene by combining both into a single output.

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

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

It explicitly states to call this to (re)sync after connecting or after specific events ('event.resync_required' and 'event.scenes_changed'). This provides clear context for when to use it, though it does not explicitly mention alternatives 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?

The annotations already declare readOnlyHint=true, so the read-only nature is known. The description adds valuable behavioral details beyond that: the exact shape matches update_widget_settings, the widget_not_found error condition, and the guarantee that alerts always exist. This provides meaningful context not derivable from annotations alone, though it doesn't cover every possible edge case.

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 long, front-loaded with the primary action, and every sentence adds essential information (purpose, usage pattern, error behavior). There is no fluff or redundant repetition of schema fields, making it concise 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 simple tool with only 2 parameters and no output schema, the description is complete: it states what the tool reads, in what context (active scene), which widget types are supported, how the result relates to a sibling tool, and the known error condition. No additional context is needed for an agent 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?

Both parameters (widget_type and format) are fully described in the schema with enums and comments, achieving 100% schema description coverage. The tool description does not add extra parameter-level detail beyond what the schema provides, so it doesn't improve on the baseline. However, it does clarify the overall context of 'active scene' which indirectly helps parameter understanding.

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

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

The description clearly states the tool reads the current settings JSON for a widget in the active scene, specifies the widget types (alert, chat, goal, prediction), and distinguishes it from the sibling update_widget_settings by noting the returned shape is exactly what that tool accepts. This makes the purpose and scope 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 gives clear usage context: it's the read step before making changes to widget settings, and it references the sibling update_widget_settings as the companion write tool. It also explains the widget_not_found error and that alerts always exist, which helps the agent decide when this tool is applicable. It doesn't explicitly state when NOT to use it, but the context is strong 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?

The readOnlyHint annotation already indicates a safe read operation. The description adds useful behavioral detail: disabled automations are listed but 'never relay events', which is an important nuance. It also explains the semantics of the prompt, providing context beyond the 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 a single well-structured sentence that packs all necessary information without waste. It begins with the action, defines the core concept, and adds a caveat about disabled automations. 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, read-only list tool with no output schema, the description is complete. It explains what an automation is, what data it contains, and the edge case of disabled automations. An agent would have no unanswered questions about invoking 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?

The tool has zero parameters, which gives a baseline of 4. The description goes further by describing the structure of the returned automations (event trigger with optional platform/min_amount, and a prompt), which effectively documents the output shape. This adds significant meaning beyond the empty 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: 'List the streamer's stored automations'. It uses a specific verb and resource, and the additional explanation of what automations are (trigger + prompt) distinguishes it from sibling tools like list_recipes. The title and description align without redundancy.

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 use case: to see the streamer's standing instructions for handling events. It does not explicitly mention alternatives or exclusions, but the context is clear enough that an agent would know when to call it. The mention of 'Disabled automations are included' also alerts the user to a nuance in the result set.

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

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

The readOnlyHint annotation already establishes safe read behavior. The description adds non-obvious behavioral details: each entry supplies a device_id and source_type for direct use in add_source, and displays include is_primary and resolution. This goes beyond the schema to explain output shape, though it doesn't discuss potential edge cases or errors.

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, then output details, then an example use case. No redundant phrases; every sentence adds value. The categories in the first sentence align with the enum without being wasteful.

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

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

For a simple read-only listing tool with one optional param and no output schema, the description fully covers the purpose, the returned fields, and the intended workflow (call first, pass to add_source). The readOnlyHint annotation handles safety, and the tool's simplicity doesn't require more.

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

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

The schema already has 100% coverage of the single 'kind' parameter, with a description 'Filter to one device kind.' The description enumerates the kinds in its opening sentence but doesn't explicitly connect them to the parameter's filtering role beyond that. This matches the baseline of 3 for 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 opens with 'Enumerate capture devices available to add as sources' – a specific verb+resource that clearly differs from sibling list_sources (which likely lists existing sources). It enumerates the device categories and notes the output feeds add_source, anchoring its purpose in the tool ecosystem.

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: 'Call this first to find, e.g., the user's webcam or primary monitor' and notes the results are 'ready to pass straight to add_source.' However, it doesn't explicitly state when not to use it or name alternatives like list_sources, so it falls short of a 5.

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

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

Annotations provide readOnlyHint=true, so the safe read nature is established. The description adds domain context about recipe structure but does not disclose additional behavioral traits such as rate limits, error conditions, or response format. It does not contradict annotations.

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

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

The description is two sentences, front-loaded with the core purpose, and every clause adds value. 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 simple read-only list tool, the description covers purpose, recipe concept, usage timing, and optional filtering. With complete schema coverage and annotations, nothing essential is missing.

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

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

The schema describes the only parameter (mode) with an enum and full explanation ('Filter to one scene mode; omit for all recipes'), achieving 100% coverage. The description merely echoes this by saying 'Optionally filter by mode', adding no extra 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 explicitly states the tool lists DualStream's installed recipes and explains what a recipe is, distinguishing it from apply/save actions. The verb 'List' plus resource 'recipes' is specific, and the mention of 'use before apply_recipe' clarifies its role among siblings.

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 direct usage guidance: 'Use before apply_recipe to discover recipe ids, or before authoring to avoid duplicate names.' This clearly indicates when to use the tool and implies alternatives (apply/save recipes). It also notes optional mode filtering.

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, so the safety profile is known. The description adds behavioral context by noting the default to the active scene and specifying the exact output fields (e.g., per-canvas transform, crop/shape/effects applied). This goes beyond the annotation without contradicting it.

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

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

The description is two sentences with no filler. The first sentence delivers the main action and output; the second provides usage. Every phrase earns its place, making it a model of concise clarity.

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 tool with one optional parameter, the description covers the output fields and typical use cases. It doesn't mention error conditions or pagination, but these are not critical for a read-only list operation. The sibling tool set further contextualizes its role.

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 fully describes the single parameter scene_id with its default behavior (100% coverage). The description merely restates 'defaults to the active scene,' adding no new information about parameter syntax or behavior 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 opens with a specific verb and resource: 'List the sources in a scene.' It enumerates the exact output fields (ids, types, visibility, per-canvas transform, crop/shape/effects), making it distinct from sibling tools like get_scenes. It also connects to set_source_* calls, clarifying 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?

The description explicitly says 'Use to find source_ids for set_source_* calls, or to see the current layout,' providing concrete usage scenarios. It doesn't mention alternatives or when not to use it, so it earns a 4 rather than a 5.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description reveals that the card renders with preconfigured styling (not controlled by the caller), that a prerequisite is that the AI Card alert type must be enabled, and that a specific error (card_disabled) occurs if not. It also notes that the AI Card type is OFF by default, which is valuable behavioral context.

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

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

The description is three sentences long, front-loaded with the core purpose, then includes usage guidance and an important error condition. Every sentence adds value with no redundancy or filler.

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

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

For a simple tool with two parameters and no output schema, the description covers what the tool does, how to use it, when to use it, and a common failure mode. It is complete enough for an agent to select and invoke the tool correctly without needing additional 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?

The input schema already fully describes both parameters (title and message) with detailed meaning, so schema coverage is 100%. The description adds only a high-level note that 'You supply only the text,' which does not materially enhance the parameter-specific understanding already provided by 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 specifies the action ('Post a card onto the live stream via DualStream's alert system'), the target (AI Card alert type), and the rendered outcome (both canvases with streamer-configured styling, position, sound, duration). It distinguishes this from sibling tools like trigger_clip by focusing on the card alert type and the fact that the user only supplies text.

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

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

Explicit usage guidance is provided: 'Use for short, timely, viewer-facing moments' and 'only when the user asked for it or set up an automation.' This sets both positive contexts and a clear restriction. It also explains the card_disabled error and how to resolve it, which helps the agent decide when this tool is 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 already declare destructiveHint=true, so the destructive nature is conveyed. The description adds the default-scene behavior and source_id requirement, but does not elaborate on irreversibility or permissions—acceptable given annotation coverage.

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

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

The description is a single concise sentence that front-loads the verb and resource, with no unnecessary words. It is easy to parse and comprehend 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?

Given the tool's simplicity (two parameters, no output schema) and full schema coverage, the description is sufficient to understand purpose and usage. The missing discussion of return values is not critical.

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 clear descriptions for both parameters. The tool description reiterates the default active scene but adds minimal new meaning beyond what the schema 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 ('Remove'), the resource ('a source from a scene'), and the default behavior (defaults to the active scene). It unambiguously distinguishes itself from sibling tools like add_source and set_source_transform.

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 useful context by specifying the default active scene and allowing scene_id for other scenes. It does not explicitly mention alternatives, but no other removal tool exists among siblings, making the intended use clear.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses key behavioral nuances: every match wakes the AI session, matching events start relaying immediately, and id is derived from name when omitted. It also clarifies the per-type meaning of min_amount. This goes well 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 compact yet dense, with each sentence providing essential information: the create/update operation, the policy, the doc format details, and the behavioral consequences. It is efficiently packed without 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 a single nested parameter and no output schema, the description covers the necessary context: how to construct the doc, what triggers are valid, how min_amount works, and what happens after saving. It also includes a usage policy. The only minor omission is not explicitly directing users to list_automations, but overall 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?

Although the schema already describes the doc parameter, the description adds substantial meaning: canonical event names, per-type amount comparisons, id derivation, and the policy to only create streamer-requested automations. This clarifies the structure far beyond the schema's terse summary.

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

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

The description opens with 'Create or update an automation', clearly stating the verb and resource. It also explains the id matching behavior, which distinguishes it from sibling tools like list_automations and delete_automation. The purpose is unambiguous and specific.

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

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

The description gives explicit when-not guidance: 'Only create automations the streamer asked for.' It also advises 'Prefer rare, high-signal events' to limit AI session wakes. However, it does not explicitly name alternatives such as list_automations for finding existing automations, so it is not a 5.

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

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

Annotations already indicate this is a non-read-only, non-destructive operation, but the description adds key behavioral context: 'does NOT change the live stream' and 'id/version/thumbnail are filled in automatically.' This informs the agent about side effects and auto-populated fields beyond what annotations convey.

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

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

The description is long, but it is well-structured with a clear lead sentence, an explicit pointer to a field reference, and bullet-point breakdowns for background and sources. Every section serves a purpose and supports the complex nested parameter. It is appropriately sized for the complexity, though it could be slightly trimmed without losing essential guidance.

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

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

Given the complex nested schema and lack of output schema, the description thoroughly explains the manifest structure, provides examples, and clarifies side-effect behavior. However, it does not describe any return values, error conditions, or validation behavior, which would help the agent understand the outcome beyond auto-filled 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?

The schema only describes the 'manifest' parameter as 'The recipe manifest to author,' leaving nested fields undocumented. The description compensates with a full field reference, concrete examples for background and sources, and detailed Text source settings. This dramatically improves the agent's understanding of what the manifest should contain.

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

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

The description opens with a specific verb and resource: 'Author a new recipe from a manifest and save it to the user's recipe library.' It clearly distinguishes from the sibling apply_recipe by explicitly stating it does NOT change the live stream. This makes the tool's purpose unambiguous and differentiates it from the closest alternative.

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

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

The description explicitly names the alternative for live-stream changes: 'use apply_recipe for that.' It also clarifies the primary use case (saving a recipe without affecting the live stream) and gives guidance on constructing a minimal valid manifest. This goes beyond simple context and provides 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?

Description adds behavior beyond annotations: omitting 'enabled' toggles, errors list configured effects, and the tool returns the new state. Annotations only state readOnlyHint=false and destructiveHint=false, so this contextualizes the mutation and error handling 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?

Three sentences, front-loaded with purpose, and no filler. The second and third sentences add crucial usage and behavioral details in minimal words, making this extremely concise while remaining 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?

With high schema coverage and no output schema, the description adds return state and error behavior, which are essential. It does not explicitly repeat parameter defaults or source_id guidance, but the schema covers those. Overall complete for a moderate single-purpose 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 already covers all 5 parameters (100% coverage). Description adds an example for the effect parameter and reinforces that 'enabled' can be omitted to toggle, though the schema also says 'Omit to toggle.' The error-listing detail adds semantic value for effect 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?

Description clearly states 'Enable, disable, or toggle an effect already configured on a source' with an example ('shader-style filters like a black-and-white look'), distinguishing it from sibling tools like set_source_effects. The phrase 'already configured' emphasizes it acts on existing effects, not adding new ones.

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

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

Provides clear context: 'already configured' and 'Only effects the streamer already applied can be toggled' indicate when to use. Also explains toggle behavior via 'Omit enabled to toggle.' However, it does not explicitly name alternative tools or exclusions, so it falls short of full 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=false and destructiveHint=false, so the description adds useful context by clarifying that crop pixel values are absolute to the source's native resolution (not the canvas) and that format omitted applies to both canvases. However, it does not disclose whether the crop replaces existing crop settings, if the operation is reversible, or any side effects beyond the parameter semantics.

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

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

The description is two sentences, front-loaded with the core action, and packs all essential parameter semantics compactly. Every sentence contributes meaningful information without redundancy or filler.

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

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

Given 8 parameters, no output schema, and rich parameter interactions, the description covers the main parameters and important contexts (native resolution, canvas formats). It misses scene_id context and does not explain expected return behavior, but the core invocation criteria are sufficiently covered for a mutation 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?

With schema description coverage at 0%, the description compensates well for six of eight parameters: left/right/top/bottom (absolute pixels of source native resolution), anchor (placement of retained region), and format (canvas scope). It omits scene_id and source_id, but source_id is self-evident and scene_id is optional and likely contextual. The explanation of pixel space and canvas scope adds critical meaning beyond the 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 action: 'Crop pixels off a source's edges.' It names the specific resource (source) and the operation (cropping), which is distinct from sibling tools like set_source_transform or set_source_shape. No ambiguity about what the tool does.

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

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

The description does not provide any guidance on when to use this tool versus alternatives. It lacks explicit context like 'Use this when you need to remove edges' or exclusions/recommendations. The only usage-related hint is the parameter semantics for 'format', but that does not address 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 only state readOnlyHint=false and destructiveHint=false, so the description adds useful context like color encoding, example shapes, and format applying to both canvases. However, it does not disclose whether effects are additive or replace existing ones, or the response behavior, which would be valuable 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 a bit long but front-loaded with the main purpose. The examples are useful and make the nested object semantics clear. Some redundancy exists with 'each an object' repeated, but overall it earns its length.

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 and complex nested parameters, the description provides enough to call the tool in basic scenarios but lacks details on glow structure, interaction when multiple effects are set, and how effects combine with existing state. It is minimally viable but not comprehensive.

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

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

Schema coverage is 0%, so the description must compensate. It explains the effect objects with concrete examples for border, shadow, and blur, and clarifies color format and format scope. It omits detailed structure for glow and does not explain scene_id/source_id, but those are self-evident from schema names.

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 visual effects (border, shadow, glow, blur) to a source. This distinguishes it from sibling tools like set_effect_enabled, which toggles effects, and other set_source_* tools that handle transform, crop, etc.

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 which parameters to provide (any of border, shadow, glow, blur) and notes format behavior, but it does not explicitly state when to use this tool versus alternatives like set_effect_enabled, nor does it mention prerequisites or when not to use it.

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

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

With only minimal annotations (readOnlyHint=false, destructiveHint=false), the description adds substantial behavioral detail: global application across scenes, preservation of saved volume, toggle behavior when 'muted' is omitted, and the return value. This goes well beyond the annotations and paints a clear picture of the tool's side effects.

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

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

The description is two sentences long, front-loaded with the core purpose, and every clause adds value: global scope, toggle behavior, volume preservation, and return state. No fluff 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?

Given the tool's simplicity (2 parameters, no output schema), the description covers all essential aspects: what it does, global behavior, toggle semantics, preserved volume, and return value. It is complete enough for an agent to invoke the tool confidently.

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

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

The input schema already documents both parameters fully, including the 'Omit to toggle' hint for 'muted'. The description reinforces this but adds little new parameter-level information. The mention of volume preservation is behavioral, not parameter semantics. Since schema coverage is 100%, the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource ('Mute, unmute, or toggle an audio-carrying source'), clearly distinguishing it from sibling tools like set_source_visibility or set_source_transform. It also clarifies the scope (applies to every scene containing the source), preventing confusion with scene-local mute operations.

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

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

The description provides clear context on when to use this tool: for controlling mute state on an audio source across all scenes. It explains the global behavior and survival across scene switches, but does not explicitly mention alternatives or when not to use it. Still, the context is strong enough to guide proper 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 indicate mutation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds meaningful behavioral detail beyond that, such as how 'back' places behind everything, 'front' respects reserved top layers, and the general rule that new sources are added on top. This helps the agent predict effects.

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

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

The description is front-loaded with the core action, then efficiently explains the position options and includes practical examples. Each of the four sentences contributes distinct value, with no wasted words or 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?

For a simple reorder tool with no output schema, the description fully covers the tool's purpose, parameter behaviors, and typical usage scenarios. It provides enough context for an agent to select and invoke it correctly, including the default scene 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 67% with position lacking a description. The description compensates by explaining the semantic meaning of each enum value ('up', 'down', 'front', 'back') and how they affect z-order. It also clarifies that scene_id defaults to the active scene, adding 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 uses a specific verb ('Change') with a clear resource ('source's layer order'), and the title reinforces it as 'Reorder a source (z-order)'. It clearly distinguishes from sibling set_source_* tools by focusing on ordering, not transforms, cropping, or visibility.

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

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

The description provides clear when-to-use guidance with concrete examples: using 'back' for backgrounds added after a camera, and notes that alert overlays have a reserved top layer. While it doesn't explicitly name alternative tools for exclusions, the context strongly implies this tool is for z-order manipulation only.

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

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

Annotations are sparse (readOnlyHint=false, destructiveHint=false). The description adds behavioral details beyond annotations, such as the default behavior for omitted format ('applies to both canvases') and clear semantics for 'None'. This enhances 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 two sentences, front-loaded with the core verb and resource, and every detail earns its place. It is concise yet packs meaningful information about shapes and defaults.

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 parameters and no output schema, the description is fairly complete: it explains the two most complex parameters (shape and format) and their defaults. However, it omits any mention of 'Squircle' and does not fully define 'format' beyond the default behavior, leaving minor gaps.

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

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

Schema description coverage is only 20% (only radius has a description). The description compensates by explaining the meaning of shape enum values (Circle, RoundedRectangle, RoundedRectangle9x16, None) and the impact of omitting format. However, it does not clarify source_id or scene_id, but those are less ambiguous.

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

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

The description clearly states the tool's function with a specific verb ('mask') and resource ('source'), and elaborates on shape-specific behaviors (e.g., 'Circle inscribes a circle'). This distinguishes it from sibling tools like set_source_crop and set_source_transform.

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 practical usage context, such as 'great for round webcam cams' and notes that 'None clears the mask', but it does not explicitly mention alternatives or when not to use this tool. This is clear context without exclusions.

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

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

Beyond the sparse annotations (readOnlyHint:false, destructiveHint:false), the description discloses that omitted keys remain unchanged, that desktop layouts never map to mobile, and gives exact canvas dimensions and recommended patterns. This is valuable behavioral context that guides invocation.

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

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

The description is long but well-structured, with the core purpose up front, then coordinates, then directives, then examples. While some layout guidance is verbose, each section adds practical value and no sentence 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 7-parameter tool with no output schema and only 14% schema coverage, the description covers the essential parameters and provides concrete usage patterns. It omits only self-explanatory identifiers like source_id and scene_id, making it complete enough 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?

Schema coverage is only 14% (format described). The description explains x, y, width, height with examples and clarifies that coordinates are absolute pixels, and discusses format usage. It also notes that omitted keys are unchanged, adding significant 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 opens with 'Set a source's position and/or size on a canvas', using a specific verb and resource. It clearly distinguishes from sibling tools like set_source_crop or set_source_effects by focusing solely on position/size.

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 for when to use the tool (positioning/resizing) and explicit mandates such as 'ALWAYS set the two canvases SEPARATELY' with layout patterns for different scenarios. It does not explicitly compare against alternatives, but the usage context is well-defined.

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

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

Annotations only indicate non-read-only and non-destructive behavior. The description adds valuable context: toggle behavior via omitted 'visible', dual canvas application, cross-scene source resolution, and return of the new state. This goes beyond the minimal annotation coverage.

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

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

Three concise sentences with no filler. The description is front-loaded with the primary action, and every sentence contributes unique information about behavior, defaults, or edge cases.

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

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

For a simple visibility toggle with no output schema, the description fully covers behavior, defaults, cross-scene resolution, and return value. No significant gaps remain, making it complete for an AI agent to select and invoke correctly.

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

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

Schema description coverage is 100%, but the description enriches parameter meaning: clarifies toggle via omitted 'visible', the 'format' parameter's effect on canvas scope, and source_id resolution across scenes. This adds edge-case guidance not evident from 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 shows, hides, or toggles a source in a scene, using a specific verb and resource. It distinguishes itself from sibling tools like set_source_transform or set_source_mute by focusing solely on visibility.

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: use this when you need to show/hide/toggle a source, with notes on canvas scope and cross-scene resolution. It does not name alternatives explicitly, but the context is clear enough for 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 the annotations (readOnlyHint=false, destructiveHint=false), the description discloses important behavioral details: it saves two native files (horizontal+vertical), the duration_sec default behavior, and the retryable error scenario with waiting for user approval. This adds significant value 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 three sentences, each earning its place: the first states the core action, the second explains the optional parameter, and the third covers error handling. It is front-loaded with the verb and resource, and there is no wasteful repetition or filler.

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

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

Given the tool's simplicity—one optional parameter, no output schema—the description is complete. It explains what the tool does, parameter behavior, and error handling. The agent has all necessary information to invoke it correctly, including the retry condition.

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 describes duration_sec as 'Clip length in seconds; omit for the configured default' with 100% coverage. The description merely restates this same information ('duration_sec is optional; omitted uses the user's configured default'), adding no new meaning. Thus the baseline of 3 is appropriate.

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

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

The description uses a specific verb 'Save' and identifies the resource as 'the stream' with output as 'a clip pair (horizontal + vertical files)'. This clearly distinguishes it from all sibling tools, which are about scenes, automations, widgets, etc., so there is no ambiguity about what it does.

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

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

The description gives clear context: it is used to save a replay clip, with the optional duration_sec behavior explained. It also provides guidance on retryable errors ('If the replay buffer is warming up... wait for the user's go-ahead and try again'). However, it does not explicitly mention alternative tools or when not to use it, though no sibling tool overlaps in function.

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

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

Annotations indicate readOnly=false and destructive=false, and the description complements this by disclosing immediate effect on the stream and durable template changes for alerts. This adds behavioral context beyond the annotations, though it doesn't detail error handling or reversibility.

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

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

Three concise sentences, front-loaded with the primary action and immediate effect. The round-trip pattern and alert-specific note add necessary detail without waste. Every sentence contributes substantive 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 three parameters, two required, and no output schema, the description covers purpose, usage pattern, and side effects. It mentions active scene, format behavior, and alert durability. Missing details like error behavior or validation are minor for a well-scoped mutation 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%, but the description enriches parameter semantics by explaining the settings object should be a full round-trip copy and that format omission applies to both canvases. This goes beyond the schema's basic property 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 explicitly states 'Apply new settings to a widget in the active scene', using a specific verb (apply) with a clear resource (widget settings) and scope (active scene). It distinguishes from sibling tools like get_widget_settings (retrieval) and source-level setters by focusing on widget-level restyling.

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 concrete usage guidance via the round-trip pattern: 'Pass the full settings object from get_widget_settings with your changes applied (round-trip: get, modify, update).' Also clarifies format omission defaults to both canvases and alerts update the canonical template. Lacks explicit 'when not to use' or alternative tool comparisons, but gives strong contextual direction.

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 readOnlyHint annotation, the description discloses that the whole session is held, there is no server-side timeout, and the call fails retryably if the DualStream connection drops. These are critical behavioral traits that an agent must know to avoid blocking the user unexpectedly.

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?

Although longer than typical, every sentence earns its place: the block behavior, the session warning, explicit usage rules, the reaction loop, and failure mode. It is front-loaded with the core behavior and structured for quick comprehension.

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 blocking, session-holding tool with no output schema, the description covers all necessary operational context: return semantics, connection loss handling, retryability, and interaction pattern. An agent has enough to invoke it safely and correctly.

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

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

Schema already covers both parameters at 100%, so baseline is 3. The description adds meaningful nuance by explaining since_seq as a cursor from the previous call ('pass the last_seq from your previous call') and providing a concrete events filter example. This enriches, but does not radically change, schema semantics.

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

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

The description opens with a clear verb+resource+behavior: 'Block until a control event arrives (or return immediately if matching events are already buffered past since_seq).' This distinguishes it from non-blocking sibling tools like get_recent_events and leaves no ambiguity about what the tool does.

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

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

Provides explicit when-to-use ('Only call it when the user has EXPLICITLY asked you to listen for events') and when-not-to-use ('Never use it to wait for consent approval or as a convenience between steps... tell the user what to do, end your turn, and retry'). It also outlines the live-reaction loop pattern, cementing usage context.

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