Compeller

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

The description adds valuable behavioral context beyond the sparse annotations: it states the operation is idempotent and records both the executor's decision (accepted/rejected) and the observer. This goes beyond the readOnlyHint=false and destructiveHint=false annotations, though it does not describe edge cases like duplicate calls or error behavior.

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

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

The description is two sentences long, front-loaded with the core purpose, and every word contributes meaning. It avoids redundancy and is highly scannable.

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 5-parameter tool with no output schema, the description covers the essential behavior (idempotent record of acceptance/rejection and observer). It does not explain return values or error conditions, but the absence of an output schema lowers the necessity; the description is complete enough for the core use case.

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

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

Schema description coverage is 100%, so all five parameters are already documented in the input schema. The description does not add any additional parameter-specific meaning beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states that this tool records an acknowledgement for a launch_id, specifying the verb 'records' and the resource 'acknowledgement for a launch_id'. It distinguishes itself from sibling tools like launch_lighting_cue (which initiates) and get_lighting_cue (which retrieves state).

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 it is used to acknowledge a cue but does not provide explicit when-to-use guidance or mention alternatives. There is no comparison to sibling tools like report_lighting_cue or launch_lighting_cue, and no exclusions or prerequisites are stated.

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

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

The description adds significant behavioral details beyond the destructiveHint annotation: it explains dequeuing behavior, cancellation of external AI tasks, state transition to CANCELLED, and idempotency. This level of transparency helps the agent understand side effects and safety, fully complementing 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 concise and well-structured: a clear statement of the action, technical details in the middle, and a practical use case at the end. Every sentence earns its place with no redundancy.

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

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

For a single-parameter cancellation tool, the description covers the essential behavior, idempotency, and usage rationale. However, it does not clarify behavior for a compel that is not in-progress (e.g., already COMPLETED), though the idempotency statement partially addresses this. Overall, it is complete but leaves minor edge cases unexplained.

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

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

The input schema already provides 100% coverage for the single parameter 'compel_id' with a clear description. The tool description does not add extra meaning beyond what the schema provides, so 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 clearly states the tool cancels an in-progress compel, specifying the resource and the resulting CANCELLED state. It distinctly differentiates from sibling tools like create_compel or get_compel, making the purpose unambiguous.

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

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

The description provides a clear use case: 'Use to stop a mis-prompted or runaway job before it consumes more render minutes.' It implies when to use the tool but does not explicitly state when not to use it or mention alternative tools, though the context is sufficient 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?

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the safety profile is clear. The description adds value by disclosing the return format (compel ID, status, tracking links), which is not in the annotations. However, the false claim about reference media slightly reduces trustworthiness.

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

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

The description is concise, consisting of one sentence that covers the action, inputs, and outputs. However, the 'optional reference media' phrase is unnecessary and potentially misleading, so not every element 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?

The description captures the core creation purpose and return information, which is important given the lack of an output schema. However, it omits the fact that style must be selected from list_styles and falsely claims reference media support, leaving the tool's full behavior only partially described.

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

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

All schema parameters have descriptions, so baseline is 3. However, the description introduces 'optional reference media' with no corresponding parameter, actively confusing parameter understanding. It adds no useful semantics for the actual parameters beyond what the schema already provides.

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

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

The description clearly states it creates a Compeller generation job from primary audio media, with a specific verb and resource. It distinguishes from sibling create_compel_from_music, but the mention of 'optional reference media' is not supported by the schema, slightly muddying the purpose.

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

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

It provides clear context that this is for creating a compel from uploaded audio, but does not mention alternatives or exclusion criteria. The unsupported 'optional reference media' reference could mislead an agent into thinking there is a parameter for it, harming usage guidance.

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

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

Annotations only provide readOnly=false, destructive=false, which are basic and do not cover side effects or prerequisites. The description adds a routing rule (audio file → use create_compel) but does not disclose what happens after creation, auth requirements, or other behavioral details. With sparse annotations, the description carries moderate burden but only partially fulfills 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, front-loaded with the action, and every word adds value. It states the core function and the key alternative without fluff, making it highly 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?

The tool has 6 parameters, 3 enums, and no output schema. The description explains the primary use case and the critical alternative, and the schema covers parameter details. It lacks return value information, but the creation action and clear parameter descriptions make it sufficiently complete for the domain 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%: all six parameters have detailed descriptions. The description itself adds no additional parameter semantics beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description clearly states the tool creates a compel from a selected Deezer preview track, using a specific verb and resource. It also distinguishes itself from the sibling tool create_compel by noting the alternative for audio files, making the purpose unambiguous.

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

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

The description explicitly provides usage guidance: use this tool when a Deezer track is selected, and if the user provides an audio file instead, upload and use create_compel. This directly addresses when to use this tool versus the alternative, fulfilling the criterion for explicit when/when-not guidance.

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

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

Annotations already include destructiveHint=true. The description adds context by stating it removes the registration and stops future deliveries, giving concrete behavioral details beyond the annotations. No contradiction.

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

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

Two short, direct sentences that front-load the action and effect. No unnecessary words 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?

For a single-parameter destructive tool with annotations and schema covering safety and parameter semantics, the description is sufficient. It explains the effect without needing to describe return values. Slight lack of detail on error cases or reversibility, but these are not essential given the annotations.

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 webhook_id and its origin (from register_webhook or list_webhooks). Schema description coverage is 100%, so the tool description adds little beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the action (Delete), the resource (webhook endpoint), and the method (by id). It also explains the consequence (removes registration, stops future deliveries), distinguishing it from sibling tools like update_webhook and test_webhook_delivery.

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 to permanently remove a webhook. It provides clear context but does not explicitly mention alternatives or when not to use, though sibling tools like update_webhook are available. This is clear but lacks explicit exclusion/alternative 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?

Given the readOnlyHint annotation already conveys the safe read-only nature, the description adds value by listing the returned data elements and the context of use. It doesn't describe every possible edge case, but for a parameterless getter, this is adequate behavioral disclosure 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 two sentences, front-loaded with the core purpose, followed by a practical usage directive. Every sentence earns its place, with no redundant or vague 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-parameter, read-only tool with no output schema, the description fully covers the purpose, return data, and usage context. It gives an agent enough information to decide when to call it and what to expect back.

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

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

The input schema has zero parameters, so the baseline is 4. The description adds no parameter information because none exist, but it compensates by explaining the return value in detail, which indirectly clarifies what the tool expects (nothing).

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: retrieving the authenticated account's render-minute balance and plan details. It enumerates specific data fields (minutes remaining, monthly allowance, plan code, quota exceeded) and uses the verb 'Get' with a specific resource, distinguishing it from sibling tools like get_pricing or get_capabilities.

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: 'Call before starting an expensive render so an agent can make cost-aware decisions.' It doesn't explicitly name alternatives or exclusions, but the context strongly implies the appropriate scenario, which is sufficient for a simple read operation.

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

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

Annotations already declare readOnlyHint=true, and the description adds that it returns capabilities, supported features, and API version. No additional behavioral context (e.g., caching, response format) is provided, but with annotation support this is adequate.

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

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

The description is a single, front-loaded sentence with no wasted words. It efficiently conveys the tool's purpose.

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

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

For a zero-parameter, read-only capability tool, the description is sufficient. It names the key outputs (platform capabilities, supported features, API version) and lacks an output schema, but this is acceptable for such a simple tool.

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

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

The tool has no parameters, and schema coverage is 100%, so the description does not need to compensate. Baseline of 4 for a zero-parameter tool is appropriate.

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

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

The description clearly states the tool retrieves Compeller platform capabilities, supported features, and API version. This distinguishes it from sibling get_* tools that target specific resources like credits, compels, or renderings.

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 a discovery/metadata use case but does not explicitly state when to prefer this over other tools or mention alternatives. For a simple introspection tool, the context is clear but guidance is minimal.

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

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

The readOnlyHint annotation already signals a safe read operation. The description adds that it returns status, progress, and details, but does not disclose any additional behavioral traits such as polling behavior or response format. This is acceptable given the annotation coverage.

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

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

The description is a single, front-loaded sentence with no unnecessary words. It efficiently conveys the tool's purpose.

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

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

For a simple get-by-ID tool with a read-only annotation and clear parameter schema, the description adequately covers what the agent needs to know. It states the type of information returned (status, progress, details) without needing to enumerate every field.

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 single parameter 'compel_id' with a description. The tool description does not add any further parameter semantics, which is acceptable given the 100% schema coverage.

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

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

The description uses the specific verb 'Get' and clearly identifies the resource as a 'Compeller generation job'. It mentions status, progress, and details, which distinguishes it from list/search operations, though it does not explicitly name sibling alternatives.

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

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

No guidance is provided on when to use this tool versus alternatives like list_compels or search_compels. The description simply states what it does, leaving the agent to infer the appropriate use case.

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

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

Annotations already indicate readOnlyHint=true, covering safety. The description adds useful context about the response contents (resolved variables, launch_contract, REACT feedback), which 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 a single, front-loaded sentence that efficiently conveys the tool's purpose and key details without 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 tool with one parameter, read-only annotation, and no output schema, the description sufficiently indicates what is returned and how to identify the target. The context is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema covers 100% of the parameter with a clear description of launch_id's source. The tool description doesn't add extra semantics beyond what the schema already provides, aligning with the baseline score.

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: 'Fetch a single live lighting cue by its launch_id', specifying the resource and identifier. It distinguishes from siblings like list_lighting_cues by explicitly narrowing to a single cue.

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

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

The description implies usage by specifying the launch_id and the parameter description states it comes from launch_lighting_cue or list_lighting_cues, giving clear context. However, it doesn't explicitly state when not to use this tool versus alternatives like list_lighting_cues.

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 covers the safe-read aspect, but the description adds no further behavioral context such as caching behavior, whether pricing is static, or any limitations. It does not contradict annotations but provides minimal extra value.

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

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

The description is a single, front-loaded sentence that is concise and directly states the tool's purpose with no unnecessary words.

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

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

For a zero-parameter, read-only tool with no output schema, the description is complete enough. It states what the tool returns (subscription plans and pricing) and lacks any necessary information.

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

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

There are no parameters, so the description does not need to explain any. The baseline for zero parameters is 4, and the description is sufficient.

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

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

The description clearly identifies the action ('Get') and the specific resource ('current Compeller subscription plans and pricing'). It distinguishes from sibling tools like get_account_credits or get_compel because it focuses on pricing information.

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

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

There is no explicit guidance on when to use this tool versus alternatives. The usage is only implied by the description itself, with no exclusions or alternative tool suggestions.

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 no behavioral information beyond the annotation readOnlyHint=true. It does not disclose possible errors, response format, or any side effects. It merely restates the safe read nature already covered by annotations.

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

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

The description is a single, concise sentence with no redundant words. It is front-loaded with the verb and resource, making it easy to parse.

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

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

Given the simplicity of the tool (single-parameter read operation) and the presence of annotations and schema, the description is sufficient. It could arguably mention what 'details' includes, but for a get-by-ID tool this is often understood.

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 covers the single parameter rendering_id with a clear description, achieving 100% coverage. The tool description adds no additional semantic meaning beyond the schema, so 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 clearly states the action ('Get details') and the resource ('specific video rendering'), distinguishing it from sibling tools like list_renderings and start_render. It is specific and 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?

No guidance is provided on when to use this tool versus alternatives (e.g., list_renderings for searching, get_compel for compels). The context is implied by the name but not explicitly stated.

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

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

Discloses several behaviors beyond the sparse annotations: loud validation failures, return of the active cue for REACT, per-frame execution, and the authoritative strobe slider. This gives the agent a strong sense of side effects and error handling.

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

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

Four dense sentences, each adding value: purpose, parameter guidance, validation behavior, and return/execution details. No filler; front-loaded with the core 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 tool with 4 params, nested objects, and no output schema, the description fully explains return values, execution model, and edge cases, making it sufficient for an agent to invoke confidently.

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

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

Schema coverage is 100%, so baseline is 3. The description repeats schema info (effect_id from list_lighting_effects, variables override defaults) but adds no new parameter details beyond the example 'speed 0.5'.

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: launching a starter lighting effect onto a stage as a live cue, with a concrete example. It distinguishes from siblings like list_lighting_cues (listing) and stop_lighting_cue (stopping) by emphasizing the live launch action.

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

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

Provides clear context: use effect_id from list_lighting_effects and optional variables to override defaults. It implies a prerequisite (list effects first) but does not explicitly mention when not to use this tool or name alternative tools beyond the implied one.

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 readOnlyHint=true in annotations, the description adds useful context: it is scoped to the authenticated account and returns results newest first. It does not mention pagination behavior, but the schema parameters cover that, and the read-only nature is confirmed.

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

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

The description is a single, front-loaded sentence with no filler. Every word contributes meaning: 'List all', 'for authenticated account', and 'newest 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?

For a simple list tool with two optional parameters and read-only annotation, the description conveys the essential scope, ordering, and account binding. No output schema exists, but the return type (list of jobs) is implicit and acceptable.

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 (limit, offset) are fully described in the schema with coverage 100%. The description adds no additional meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool lists Compeller generation jobs for the authenticated account, with a specific ordering (newest first). This distinguishes it from siblings like get_compel (single item) and search_compels (search/filter).

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 want all jobs for your account), but it does not explicitly contrast with search_compels or other alternatives. No clear 'when to use instead' guidance is provided.

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

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

Annotations already indicate readOnlyHint: true, so the safety profile is covered. The description adds value by disclosing the return contents (launch_id, resolved variables, launch_contract, feedback) and clarifying that it lists only live cues, which is useful behavioral 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, front-loaded sentence that conveys the purpose, scope, and return fields without redundancy. Every phrase earns its place, and there is no filler.

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

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

The tool is simple (one optional parameter, no output schema, read-only), and the description adequately covers what it returns and when it applies. No pagination or additional behavior is needed for this straightforward listing operation.

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

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

Schema coverage is 100% for the single optional stage_id parameter, which already has a clear description. The description only restates this as 'Optionally scope to one stage,' adding no new syntax or format details. Baseline 3 is appropriate since the schema carries the parameter 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 clearly states the tool lists live (non-stopped) lighting cues, with a specific verb ('List') and resource ('lighting cues'). It distinguishes from the singular get_lighting_cue and from list_lighting_effects by specifying 'live (non-stopped)' cues and including the fields returned.

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: use this to see cues REACT is actively executing, and optionally scope by stage. It doesn't explicitly mention alternatives like get_lighting_cue for a single cue, but the live/non-stopped framing and optional stage filter imply appropriate use cases.

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

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

With readOnlyHint=true, the description adds value by disclosing what each effect carries (id, capabilities, launch_contract template) and that these are a specific starter set. 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?

Two sentences, front-loaded with the core action and examples, followed by the return-value structure and a direct usage pointer. Every sentence earns its place with no redundancy.

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

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

For a simple list tool with no parameters and no output schema, the description completely covers what it returns (effects with ids, capabilities, contract template) and how to use the result. No gaps remain.

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

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

The tool has zero parameters, and the schema is an empty object, so the description naturally doesn't need to explain any. The baseline for zero parameters is 4, and no further semantic detail is required.

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

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

The description clearly states the verb ('List') and resource ('COM-497 starter lighting effects') with concrete examples. It also distinguishes this from sibling tool 'list_lighting_cues' by specifying these are effects for launching cues, not existing cues.

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 guidance on when to use the tool: to obtain effect IDs for launching cues, and instructs to 'Use the returned id as effect_id for launch_lighting_cue.' While it doesn't explicitly contrast with alternatives, the intended use case is clear.

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

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

The readOnlyHint annotation already declares this is a safe read operation, and the description aligns with that by saying 'list'. The description adds the scope (specific compel) and the 'all' qualifier but does not disclose return format, pagination, or ordering behavior. Since annotations cover the safety profile, a score of 3 is appropriate.

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

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

The description is a single, front-loaded sentence with no unnecessary words. It directly states the action and scope, making it highly 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?

This is a simple filtered-list tool with good annotations and a fully documented parameter. The description adequately conveys the tool's purpose and scope, but it lacks details about return structure, pagination, or ordering. Given the tool's simplicity, the description is sufficient but not exhaustive, so a score of 4 is appropriate.

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

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

The input schema has 100% coverage for the single parameter compel_id, with a clear description. The tool description's phrase 'for a specific compel' merely reinforces the schema meaning without adding extra syntax, formatting, or behavioral details. Baseline 3 is correct given the schema carries the full param 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 uses a specific verb 'list' with a clear resource 'video renderings' and scopes it to a specific compel. This clearly distinguishes it from sibling tools like list_compels (which lists compels) and get_rendering (which retrieves a single rendering).

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: when you need all renderings for a particular compel. It does not explicitly mention alternatives or exclusions, but the 'for a specific compel' phrasing provides clear contextual guidance on when to use this tool.

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

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

The readOnlyHint annotation already establishes this is a safe read operation. The description adds context that the tool returns 'available' styles for 'Compeller video generation', implying it provides a set of valid options for use in generation workflows, which is useful beyond the annotation alone.

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

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

The description is a single sentence that is front-loaded with the action ('List') and resource ('visual styles'), followed by a scope. It contains no filler and every word adds value.

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

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

For a simple list tool with no parameters, no output schema, and a readOnly annotation, the description provides sufficient context: it identifies the domain (Compeller video generation) and the nature of the result (available styles). A more detailed return format is not necessary for such a trivial operation.

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 zero parameters, the baseline is 4. The description does not need to explain parameters, and the empty schema is fully self-explanatory.

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

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

The description specifies a clear verb ('List') and resource ('visual styles'), and scopes it to 'Compeller video generation', distinguishing it from sibling tools like list_lighting_effects or list_compels. It immediately conveys 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 implies the tool is used when you need to know which visual styles are available for video generation, but it does not explicitly state when to use it over alternatives or mention any exclusions. For a simple list tool, this is acceptable but not fully explicit.

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

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

The annotation readOnlyHint already declares safe read behavior, but the description adds valuable context: 'Secrets are never returned by this tool.' This discloses a security-relevant trait that is not in the annotations or schema, helping agents avoid expecting secret values. No contradiction with annotations.

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

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

Two sentences, front-loaded with action ('List all webhook endpoints'), followed by a crucial caveat about secrets. Every word earns its place, with no filler or repetition of schema data.

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

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

For a simple list operation with no parameters and no output schema, the description covers the purpose and a key behavioral note. It could mention pagination or response format, but the absence of an output schema and presence of readOnlyHint reduce the need. Given the low complexity, the description is 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 tool has zero parameters, and the schema coverage is 100% (empty properties). Per the baseline for no-parameter tools, the description does not need to add parameter details. The score reflects that the description adequately addresses the parameter space by not pretending otherwise.

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 lists all webhook endpoints for the authenticated account. The verb 'List' and resource 'webhook endpoints' make the purpose explicit, and it distinguishes from sibling tools like register_webhook and delete_webhook which perform different actions.

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

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

The description implies use for viewing registered webhooks but does not explicitly state when to prefer this over alternatives. With many webhook-related siblings, providing a direct contrast (e.g., 'to view a single webhook, use get_webhook') would strengthen guidance.

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

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

The description goes well beyond annotations by disclosing critical behavioral traits: the signing secret is returned exactly once and must be stored immediately, deliveries are signed and at-least-once with up to 6 retries, and the same event ID is used for deduplication. This is rich context that an agent needs to handle deliveries correctly. 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?

The description is dense but every sentence earns its place: purpose, return value warning, delivery signature, and retry/dedupe behavior. It is front-loaded with the core action, and the length is appropriate for the complexity of webhook registration.

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 covers the essential context: what events are available, what is returned (webhook_id and secret), and how delivery behaves (signing, retries, dedupe). This is complete for a registration tool with only 2 parameters, and the agent can proceed confidently.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by clarifying the 'events' parameter semantics: it explains that 'compel.ready' means 'renderable - call start_render' and that omitting events or passing ['*'] subscribes to all. This goes beyond the schema's enum list and enhances the agent's understanding of parameter usage.

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

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

The description starts with a specific verb+resource: 'Register an HTTPS endpoint to receive signed push notifications'. It clearly distinguishes this from other webhook tools (delete, list, rotate, update, test) by focusing on initial registration. The event types are also enumerated, making the tool's purpose unambiguous.

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

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

The description implies when to use this tool (when setting up a new webhook) and provides context about event subscription and delivery. However, it does not explicitly mention alternatives or exclusions, such as using update_webhook to modify an existing webhook. Still, the context is sufficiently clear for an agent to select this tool appropriately.

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=false and destructiveHint=false, and the description does not contradict these. The description adds context by enumerating the fields reported, but it does not disclose side effects (e.g., whether this overwrites prior state), authentication requirements, or idempotency. This meets the baseline with annotations but lacks rich behavioral detail.

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

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

The description is a single sentence, front-loaded with the core action and then a concise enumeration of the report's contents. Every word contributes to describing the tool's purpose and payload, with no redundant or irrelevant text.

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

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

For a tool with 8 parameters, nested objects, and no output schema, the description gives the essential idea and data fields but lacks important operational context: it does not mention the required launch_id, how the report is delivered, or when it should be called. It is adequate for a basic understanding but not fully complete.

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

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

Schema coverage is only 38%, and the description compensates by naming several parameters (status, active_variables, skipped_bindings, capability_misses, last_frame_at, errors), giving semantic meaning to those without schema descriptions. However, it omits launch_id and executor_id, so compensation is partial.

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 names the action ('report-back'), the resource ('lighting cue'), and the specific data payload (status, active variables, skipped bindings, capability misses, last_frame_at, errors), making it clear this tool is for reporting execution results. This distinguishes it from siblings like ack_lighting_cue (acknowledgement) and get_lighting_cue (retrieval).

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 (REACT/BAE report-back) but gives no explicit guidance on when to invoke this tool versus alternatives, no prerequisites, and no mention of how it relates to launch_lighting_cue or stop_lighting_cue. Users must infer the intended workflow.

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 destructiveHint annotation, the description discloses critical behavior: 'The previous secret is invalidated immediately,' 'integrators must update their receiver before the next compel terminal event fires,' and 'Returns the new secret exactly once; store it on receipt.' These details are essential for safe use and go well beyond what annotations provide.

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

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

The description is two sentences, front-loaded with the primary purpose, and every clause adds value. It explains the action, the consequence (immediate invalidation), the urgency (update before next event), and the return behavior (one-time secret) with no redundant words.

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

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

Given the tool's simple one-parameter schema, the destructiveHint annotation, and the absence of an output schema, the description is complete. It covers what happens, when to use it, what to expect in the return, and a critical warning. No additional context is needed for an agent to correctly 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 input schema fully documents the webhook_id parameter with a clear description ('The webhook id to rotate the secret on'), so schema coverage is 100%. The description adds the context 'for a registered webhook endpoint,' which slightly reinforces that the ID must refer to an existing registered webhook, but it does not add significant new parameter-level meaning.

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

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

The description starts with 'Mint a new HMAC-SHA256 signing secret for a registered webhook endpoint,' which clearly states the action (mint/rotate), resource (webhook endpoint), and scope (signing secret). This distinguishes it from siblings like register_webhook, update_webhook, and delete_webhook by focusing specifically on secret rotation.

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

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

The description implies the tool is used to rotate a webhook's signing secret, and it provides clear context about the immediate invalidation and the need to update receivers. However, it does not explicitly state when not to use it or compare it to alternatives like update_webhook, so it lacks explicit exclusions.

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

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

Annotations include readOnlyHint=true, which already indicates a safe read operation. The description adds minimal context ('for the authenticated account') but does not disclose behavior such as return format, pagination, rate limits, or whether the search is case-insensitive or partial matching.

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

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

The description is a single focused sentence with no unnecessary words. It is concise and front-loaded with the action, though the ambiguous 'Compeller generation jobs' could be tightened.

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

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

The tool is simple with only two parameters and a readOnlyHint, but the description lacks context about return values, how it differs from 'list_compels', and the exact matching behavior. It is sufficient for basic invocation but leaves gaps for an agent to select it correctly among siblings.

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%: both 'query' and 'limit' have clear descriptions. The description adds no significant semantic detail beyond the schema; it only restates that search is by title, which is already in the query parameter description.

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 (Search) and the resource (Compeller generation jobs), with an explicit scope (by title, for the authenticated account). However, the term 'Compeller generation jobs' is slightly ambiguous and it does not explicitly differentiate from the sibling tool 'list_compels', which likely returns all compels.

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

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

No guidance is given on when to use this tool versus the alternative 'list_compels' or other search tools. The description does not mention any prerequisites, exclusions, or situations where this tool is preferred.

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

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

Annotations declare readOnlyHint=true, and the description is consistent with a read-only search operation. The description adds a useful behavioral constraint that results are limited to the authenticated account's uploaded media. However, it does not disclose other behaviors such as return format, pagination details beyond schema, or any side effects. With the annotation covering safety, the description provides minimal added value beyond that.

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

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

The description is a single sentence, front-loaded with the action ('Search and list'), and contains no redundant or unnecessary information. It is 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?

The tool is simple with three optional parameters, full schema coverage, and a read-only annotation. The description adequately conveys the scope and purpose. Without an output schema, the return structure is unspecified, but pagination is inferable from the limit/offset parameters. Overall, the description is sufficient for the tool's complexity, though it could mention that results are paginated.

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 covers all three parameters (type, limit, offset) with descriptions, achieving 100% schema description coverage. The description adds no additional parameter semantics, so the baseline score of 3 is appropriate.

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

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

The description clearly states a specific verb+resource ('Search and list uploaded media files') and scope ('for the authenticated account'). However, it does not explicitly distinguish itself from overlapping siblings like search_music or search_compels, even though the schema's type filter includes audio (which could also be handled by search_music). Thus, it is clear but lacks sibling differentiation.

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

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

The description provides clear context for when to use the tool: to search and list uploaded media for the authenticated account. It does not mention alternatives or exclusions, but the context is sufficiently clear that an agent can infer this is the general media search tool. No explicit 'when-not' guidance 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?

Annotations already declare readOnlyHint: true, covering the safety profile. The description adds that results are 'Deezer preview tracks,' which clarifies the content scope but does not disclose response format, error behavior, or rate limits. This is moderate value beyond annotations.

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

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

The description is two sentences, front-loaded with the action and scope. It is concise, has zero waste, and earns its place.

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

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

For a simple search tool with two well-documented parameters and no output schema, the description adequately covers purpose and usage. It lacks explicit detail about the return payload, but that is not critical given the low complexity and existing 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?

Schema description coverage is 100%, and the description's mention of 'by song, artist, or album' simply mirrors the query parameter's existing description. No additional semantic value is added for the parameters.

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

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

The description clearly states the tool searches Deezer preview tracks by song, artist, or album. It distinguishes itself from sibling search tools like search_media by specifying 'Deezer preview tracks' and the file-absence use case.

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

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

The description provides a clear usage condition: 'when the user provides a song string but no MP3/WAV/FLAC file.' This implies an alternative path for file uploads, but it does not explicitly name alternatives or state when-not conditions, 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?

With readOnlyHint=false and destructiveHint=false, the description adds valuable behavioral context: only passed variables change (others keep current values) and stopped cues are rejected. This goes beyond the annotations and informs the agent about partial updates and input validation.

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, all essential: the action with example, the partial-update behavior, and the rejection condition. No filler or redundancy.

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

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

For a targeted update tool with two well-described parameters, the description covers the key behavioral aspects (live cue requirement, partial update, stopped cue rejection). It doesn't mention return values, but no output schema exists and this is not critical for tool selection or invocation. The description is sufficiently complete for reliable use.

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

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

Schema coverage is 100%, giving a baseline of 3. The description adds meaning by explaining that variables is a partial update (only passed variables change) and provides an example format (e.g., {"speed": 0.75}), which clarifies the expected object structure beyond the schema's generic 'name -> value' description.

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 'Update variables on a live cue' with specific examples (cycle speed or intensity), using a specific verb and resource. It distinguishes this tool from sibling tools like launch_lighting_cue and stop_lighting_cue by focusing on modifying an already-running cue.

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 for live cues mid-show, and explicitly states 'Stopped cues are rejected,' which is a key exclusion. It doesn't explicitly name alternative tools, but the context makes it clear when to use this tool versus launching or stopping a cue.

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 establish readOnlyHint=false and destructiveHint=false, so the description doesn't need to restate those. It adds context about READY status and default configuration, but does not mention side effects like asynchronous job start, credit consumption, or how to track rendering progress. With no output schema, more behavioral detail would be beneficial.

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 conveys the core action, precondition, and purpose. Every phrase adds value with no redundancy.

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

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

For a simple 1-parameter tool, the description covers the essential context: what to start, on what object, with defaults, and the intended outcome. It could mention the response format or link to get_rendering for progress tracking, but given the simplicity and schema coverage, it is reasonably complete.

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

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

Schema coverage is 100%: compel_id is described as 'The READY compel ID to render'. The description adds no new parameter-level meaning beyond echoing the READY qualifier. Baseline 3 is appropriate because the schema already documents the parameter fully.

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

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

The description clearly identifies the action ('Start rendering'), the target resource ('a READY compel'), and the intended purpose ('continue to final MP4 without opening browser UI'). It distinguishes from sibling tools like get_compel or cancel_compel by specifying the READY state requirement.

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 implies when to use: when a compel is READY and the agent wants to render with defaults without browser UI. However, it doesn't explicitly state alternatives or exclusion conditions (e.g., when to use cancel_compel or get_rendering), so it falls slightly 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?

The description reveals that the operation is idempotent and explains the internal mechanism (marks the cue as stop-requested so REACT drops it on next refresh). This adds valuable behavioral context beyond the annotations, which only indicate readOnlyHint=false and destructiveHint=true.

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

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

The description is two sentences, directly states the action and the idempotent behavior, with no filler.

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

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

For a simple one-parameter stop action, the description explains the effect and side-effect. It doesn't require an output schema, and the mention of 'live cue' implies the precondition that the cue must be running. This is sufficient for an agent to select and invoke.

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 fully documents launch_id with a clear description (100% coverage). The tool description adds no additional parameter semantics beyond the schema, so it meets the baseline of 3.

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

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

The description uses the specific verb 'stop' and identifies the resource as a live cue identified by launch_id. This clearly distinguishes it from siblings like launch_lighting_cue, ack_lighting_cue, and report_lighting_cue.

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 clearly states it stops a live cue, providing context for when to use it. It does not explicitly mention alternatives or exclusions, but the context is clear.

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

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

The description enriches the sparse annotations by disclosing the synchronous execution, use of HMAC-SHA256 signature, standard URL safety check, returned fields including an error placeholder, and that test delivery is always on-demand regardless of subscription. This goes far beyond the annotations (readOnlyHint: false, destructiveHint: false) and provides essential behavioral detail.

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 every clause adds value: the signature mechanism, the safety check, the return signature, and the subscription behavior. No filler or repetition.

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

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

Given the single parameter, no output schema, and sparse annotations, the description fully covers the tool's behavior, return shape, and usage context. It explains the synchronous nature, signature, safety check, and exactly what fields are returned, making it self-contained for an agent.

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

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

The input schema already fully documents the only parameter (webhook_id) with a description including the authenticated-account constraint. The tool description adds no extra parameter semantics beyond what the schema provides, so 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 clearly states the action: 'Synchronously POST a synthetic webhook.test event to a registered endpoint.' This identifies a specific verb (POST), resource (registered endpoint), and the synthetic event type, distinguishing it from sibling webhook management tools like register_webhook, update_webhook, and delete_webhook.

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: 'Use this to verify your integration before relying on compel.completed / compel.failed events.' It explains the tool's purpose relative to real events and notes it ignores the endpoint's events subscription, indicating it is for on-demand testing. However, it does not explicitly mention alternatives or when not to use, so it stops short of a full 5.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses validation specifics (https-only, <=2048 chars, URL safety blocklist), the return payload ('Returns the updated endpoint'), and that the secret is never returned. These details provide meaningful behavioral context beyond what annotations offer.

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 concise sentences, each earning its place: the first states the core action and fields, the second states the constraint and validation, and the third states the return value and points to an alternative. No redundant words.

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

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

Given the tool's complexity (4 parameters, one required) and existing annotations, the description covers all essential aspects: which fields can be updated, the at-least-one constraint, validation rules, return behavior, and the secret alternative. With no output schema, this is sufficient for correct invocation.

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

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

The input schema already provides 100% coverage with detailed descriptions for all parameters. The description adds critical semantics not present in the schema: the rule that at least one of url/events/active must be provided, and that validation mirrors register_webhook. This elevates it beyond the schema 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 starts with 'Update one or more mutable fields on a registered webhook endpoint: url, events, active.' This clearly specifies the action (update) and the resource (webhook endpoint). It also distinguishes from siblings by noting 'secret is never returned by this tool - use rotate_webhook_secret for that' and implying register_webhook validation context.

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

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

Provides the critical constraint 'At least one of these must be provided' and references register_webhook for validation rules, which helps the agent decide when to apply this tool. It explicitly points to rotate_webhook_secret for secret rotation. However, it does not contrast with delete_webhook or test_webhook_delivery, so the when-not-to-use guidance is incomplete.

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?

Given the readOnlyHint annotation, the description adds useful context by clarifying that this tool returns upload instructions (URL and headers) rather than performing the upload itself, and that authentication is required. This goes beyond the annotation without contradiction, though it omits rate limits or error behavior.

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

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

The description is three concise sentences, each adding distinct value: purpose, return value, and authentication. No filler or repetition of the tool name.

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

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

For a tool with no output schema, the description covers the core return value and auth, but lacks detail on possible error responses, URL expiration, or other edge cases. It also omits the 'text' media type from the schema, leaving a minor gap. Adequate but not fully 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 already documents all three parameters with 100% coverage. The description adds marginal context by listing example media types (audio, images, video) but omits 'text' and does not enhance parameter understanding beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function—getting upload instructions for media files and returning the upload URL and headers—with a specific verb and resource. However, it does not explicitly distinguish from sibling tools by naming alternatives, which prevents a perfect score.

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 only mentions API token authentication as a prerequisite, but offers no guidance on when to use this tool versus alternatives or when not to use it. The intended usage is only implied by the purpose statement.

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