LiveReacting

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

Goes beyond the annotations by disclosing the actual side effect: activating deactivates the previous scene (the real meaning of destructiveHint). It also describes the streaming/autoSynch interaction and names the 'synced' response field, which annotations cannot express.

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

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

Front-loads the core action, then layers the exclusivity rule, idempotency, streaming behavior and id source in compact sentences. Every sentence carries distinct information with no padding.

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

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

For a two-parameter mutation with no output schema, the description covers the mutation's effect, its safety profile, the dependent state (streaming/autoSynch) and the response field. Nothing an agent needs to call it correctly 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?

Schema coverage is 100%, and the schema already documents both parameters including their id origins. The description restates that scene ids come from livereacting_get_scenes but adds no syntax or format detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('make one scene the active scene') and immediately defines the on-air effect, which separates it from the many read/list siblings. The exactly-one-active semantics make the tool's scope unmistakable.

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

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

Explains the condition for use (putting a scene's content on air) and notes idempotency, so an agent knows repeat calls are harmless. It does not point to a sibling alternative (e.g. livereacting_manage_scene), leaving a small gap in 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?

Adds substantial context beyond the annotations: settings are read strictly by type and mismatched fields are silently dropped, files being omitted creates an empty playlist, autoSynch can copy the saved project over the running stream and overwrite live-only changes, and calls are not idempotent with a timeout-recovery path via get_scenes. This is far richer than the destructive/idempotent hints 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?

Front-loaded with purpose and type enumeration, and nearly every sentence carries operational value. It is on the long side for a single tool, and the set_playlist guidance appears twice in different phrasings, which is mild 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?

With no output schema, the description supplies what an agent still needs: default behaviors, silent-drop failure modes, stream-overwrite side effects, and the correct recovery step after a timeout. For a nested, type-discriminated mutation this is complete.

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

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

Schema description coverage is 100%, so a baseline of 3 is warranted, but the description adds type-dependent semantics the schema only implies: playlists ignore fileId, video ignores files, and loop defaults to true for playlists with loop:false needed for a play-once clip. It stops short of covering name/volume/adPoints behavior, so it is not a full doubling of the schema.

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

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

States a specific verb and resource ('Add one layer to a scene that already exists') and immediately enumerates the three creatable types, noting which layer types must be made in the Studio instead. It explicitly separates itself from livereacting_create_scene_with_playlist and livereacting_set_playlist, so an agent can route without opening any schema.

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

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

Gives explicit when-to-use cases (scene with no playlist, background music alongside a video playlist) and names the alternatives with the condition that selects them: create_scene_with_playlist for a new scene, set_playlist to modify a playlist afterwards, get_scenes to verify after a timeout. Nothing is left to inference.

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

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

Annotations already carry destructiveHint=true and idempotentHint=true, but the description adds the consequences those hints do not: cancellation is irreversible and the schedule must be recreated via livereacting_schedule_stream. It also scopes the operation to SCHEDULED streams only, which is the key behavioral boundary an agent cannot infer from 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?

Front-loaded with the core action, then the two modes, then consequences, then the two sibling routings. Every sentence carries a distinct fact; nothing is repeated from the title or schema verbatim.

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

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

For a two-parameter destructive mutation with no output schema, the definition covers what it does, what it will not touch, irreversibility, recovery, and preconditions. An agent has everything needed to call it correctly and safely.

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

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

Schema coverage is 100% and the schema already documents each parameter's effect and the 'required unless liveId is given' constraint, so the baseline is 3. The description adds the branching logic in prose (one id vs every schedule on a project) and points to livereacting_get_project as the id source, though it does not state what happens if neither parameter is supplied despite required=0.

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

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

States a specific verb+resource (cancel scheduled streams) and immediately disambiguates its two operating modes by parameter: liveId cancels one, projectId cancels all. It also names the sibling it is not (livereacting_stop_stream) and the sibling it complements (livereacting_schedule_stream), so an agent can place it among the 29 tools without opening a schema.

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

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

Explicit when-to-use and when-not-to-use: running streams are out of scope and routed to livereacting_stop_stream, and the agent is told to call this before livereacting_schedule_stream when schedules already exist because scheduling refuses to coexist. Both alternatives and the precondition are named rather than implied.

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

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

Annotations cover the safety profile (idempotent, non-destructive), and the description adds substantial context beyond them: the observable outcome (file appears in the media library and is returned), a named error code and recovery loop, and the post-upload encoding requirement for video. That is exactly the behavioral detail structured fields don't carry.

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

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

Front-loads the core action, then the success outcome, then the error recovery, then the video caveat. Every sentence carries information, though the sentences are dense and the encoding sentence packs several clauses, slightly reducing readability.

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

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

With no output schema, the description compensates by explaining what is returned (the media file) and what the error response looks like (UPLOAD_INCOMPLETE naming parts, issues.errors). An agent has everything needed to call it correctly and handle both outcomes.

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?

Only one parameter with 100% schema description coverage, so the schema already documents uploadToken fully. The description adds marginal value by noting the token is reused on retry ('same token'), but no format or syntax 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?

States a specific verb (finish) and resource (upload), and explicitly ties itself to the lifecycle step 'started with livereacting_upload_file, after every part has been sent'. This distinguishes it immediately from livereacting_upload_file and the other media 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?

Gives the when ('after every part has been sent'), the failure path (missing/wrong-size part returns UPLOAD_INCOMPLETE and names the parts, re-send then call again with the same token), and routes to an alternative (livereacting_encode_media or a running encode) when issues.errors is non-empty.

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 declare the generic write profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description carries real added weight: it discloses the hidden one-hour default if duration is omitted, plan-tier constraints on 1080p/4K formats, and the hard 8-hour cap for Facebook-only streams. These are non-obvious operational limits an agent could not infer from structured fields.

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

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

Purpose and next steps are front-loaded, and the dense guidance sentences all carry distinct information. It is on the long side and restates the one-hour default that already appears in the duration schema, which is minor redundancy rather than padding.

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

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

For an 8-parameter creation tool with no output schema, the description covers intent, sequencing, and the major limits well. The one gap is that it never indicates what is returned (presumably a project id needed for the chained calls), leaving the agent to discover the handle for subsequent tools on its own.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds decision-level meaning: it explains which duration shape to send for each streaming scenario and that autoSynch should be paired with the manual 24/7 case. It also reiterates that destinationIds come from livereacting_list_destinations and cannot be created here, reinforcing the cross-tool constraint.

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

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

The description opens with a specific verb+resource ('Create an empty LiveReacting project') and immediately frames it as 'the first step of building a stream' with 'no scenes and no content', which cleanly separates it from sibling tools like livereacting_create_scene_with_playlist or livereacting_update_project.

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 sequences the workflow: 'call livereacting_create_scene_with_playlist next... then livereacting_start_stream or livereacting_schedule_stream'. It also branches on intent, telling the agent exactly what to pass for a 24/7 looping channel versus a self-terminating stream, and notes what cannot be done here (privacy settings, advanced YouTube options, destination creation).

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 cover the mutation profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false, openWorldHint=true), and the description adds substantial behavior beyond that: state-dependent branching (first scene vs. chained scene), the activation side effect a stream requires, the auto-switch wiring that chains a 24/7 channel, and a hard refusal condition (previous scene must already contain a video playlist layer). It also discloses a silent failure mode — audio files produce a video playlist holding audio and are not reported as an error — which is exactly the kind of non-obvious trait an agent needs.

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

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

Roughly six dense sentences, but the highest-value information (what it does, that it is the normal path, the state-dependent behavior) is front-loaded, and the sibling routing notes are consolidated in the back half. It is longer than strictly necessary — the overlay/Studio sentence could be trimmed — but nearly every sentence carries actionable 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?

For a 7-parameter mutation tool with no output schema, the description covers purpose, branching behavior, prerequisites and refusal conditions thoroughly, which is more than enough to invoke it correctly. The one remaining gap is that it does not hint at what comes back (e.g. the new scene id), which matters slightly given there is no output schema.

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

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

Schema description coverage is 100%, so the schema already documents every parameter, and the baseline is 3. The description still adds meaning the schema lacks: the provenance and encoding prerequisite for file ids, and the note that loop is ignored when the scene auto-switches into another one. It stops short of adding format or aggregation detail for the remaining 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 first sentence states a specific verb and resource ('Add a scene to a project and fill it with a video playlist') and frames it as the canonical way to add content. It explicitly distinguishes itself from siblings livereacting_set_playlist (for changes afterwards) and livereacting_add_layer (for audio playlists), so an agent can route correctly without opening other schemas.

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

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

Gives explicit when-to-use context ('the normal way to put content into a project, because a new project is created empty'), prerequisites (file ids from livereacting_list_media or livereacting_import_media, files must have finished importing and encoding), and named alternatives for adjacent needs (livereacting_set_playlist for edits, livereacting_add_layer for audio). It even states what cannot be done here (text/image/interactive overlays, Studio 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?

Goes well beyond the annotations by disclosing that encoding is asynchronous and returns immediately, that the response lists both queued and skipped files with skip reasons (not found, not a video, already queued/encoding), and critically that already-encoded files will be re-encoded if sent again. That last point corroborates the non-idempotent, destructive annotation with concrete operational 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 purpose is front-loaded in the first clause and nearly every sentence carries operational value. The final clause about checking status after a timeout partially repeats the earlier polling guidance, and the middle sentence is dense with parenthetical skip reasons, so it is not maximally tight.

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

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

With no output schema, the description still explains what the call returns (queued and skipped files with reasons) and how to determine completion. For a single-parameter async queue operation, nothing an agent needs to invoke it correctly 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?

There is a single parameter (fileIds) with 100% schema description coverage, including the pattern, min/max items, and the source listing tool, so the schema carries the burden. The description does not add syntax or format detail beyond what the schema states, 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?

States a specific verb and resource ('Queue video files for encoding so they can be streamed') and explains the reason encoding is needed, which cleanly separates it from siblings like livereacting_get_media_file and livereacting_get_encode_status that it explicitly names.

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

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

Gives explicit when-to-use criteria (resolution or frame rate above the account limit), tells the agent how to identify candidates (livereacting_get_media_file with includeMetadata), and names the follow-up tool to poll. It also adds a caution: do not re-send already-encoded files, and check livereacting_get_encode_status after a timeout before retrying.

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 readOnly/idempotent/non-destructive, and the description adds context they cannot carry: a 150 requests-per-minute account-wide limit, a 15-second minimum poll interval, the pollAfterSeconds return field, and the meaning of an empty result. That is exactly the operational context an agent needs to avoid hammering the endpoint.

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 what is returned and followed by polling cadence and termination condition. The 'minutes, not seconds' clause is short and directly supports the polling guidance rather than padding.

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

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

With no output schema, the description still surfaces the critical return field (pollAfterSeconds) and the empty-list terminal state, plus rate limits and scope. An agent can poll correctly and know when to stop without further documentation.

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% (limit defaults to 50; offset references nextOffset), so the schema carries the parameter burden. The description adds nothing about limit/offset, which is acceptable at this coverage level but earns only the 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?

Names a specific verb (list) and a tightly scoped resource: files queued for encoding or currently encoding, with progress. The scope wording ('right now', 'with its progress') separates it from siblings like livereacting_list_media or livereacting_get_import_status without needing to name them.

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

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

Gives concrete usage conditions: poll no more often than every 15 seconds, use pollAfterSeconds, and stop when the list is empty ('nothing left to wait for'). It does not explicitly name an alternative tool for non-encoding status checks (e.g. get_import_status), so it falls short of a full when/when-not/alternatives statement.

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 readOnly/idempotent/non-destructive, and the description goes well beyond them: per-account rate limit, minimum poll interval, the semantic gap between transfer completion and encodability, playlist refusal behavior, fileId persistence after completion, and the fact that `files` reflects live state and can shrink. None of this is derivable from the annotations.

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

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

Three short paragraphs, each with a distinct job: return fields first, then the done-vs-usable caveat and rate limit, then the YouTube playlist/folder special case. No sentence is decorative, and the most important output field names are front-loaded.

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

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

There is no output schema, so the description carries the full burden of describing return values, and it does: status, progress percentage, pollAfterSeconds, usable, nextStep, isFolder, and files. It also closes the obvious follow-up gap by noting that `files` names videos without ids and pointing at livereacting_list_media.

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 is only one parameter and schema coverage is 100%, so the schema already documents the fileId pattern and origin. The description nonetheless adds lifecycle meaning the schema lacks: the fileId remains valid and pollable after the import finishes, which tells the agent it can re-invoke rather than cache a one-shot token.

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

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

The description opens with a specific verb+resource ('Check how far an import ... has got') and names the exact sibling tools that produce the fileId (livereacting_import_media, livereacting_import_from_url). It also enumerates what the call returns (status, progress percentage, pollAfterSeconds), so an agent can distinguish it from livereacting_get_encode_status without opening a schema.

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

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

It states the trigger condition (after an import started by one of the two import tools), the polling cadence (no more often than once every 10 seconds), the reason (150 req/min account budget), and where to go next via `nextStep` when `usable` is false. The distinction between `done` and `usable` is explicitly flagged as a usage trap, which is exactly the kind of when/when-not guidance this dimension rewards.

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

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

Goes well beyond the readOnly/idempotent annotations by disclosing pagination behavior (50 items per response, up to 600 items, use itemTotal for real length and nextOffset to page), the requirement to exhaust pages, and the scope fact that all layer types including Studio-only ones are readable here.

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

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

Front-loads the return shape before the pagination caveat, and every sentence carries information the agent needs (id provenance, page size, total count, page-exhaustion rule, readable scope). No filler.

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

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

With no output schema, the description carries the full burden and does so: it describes the returned fields, the playlist item structure, truncation semantics, and the pagination contract needed to retrieve a full playlist correctly.

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

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

Schema coverage is 100%, so baseline is 3; the description adds meaning by tying offset to the 50-item page size and the nextOffset field, plus reinforcing where layerId and projectId originate. That is a genuine increment over the schema's own parameter descriptions.

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

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

States a specific verb and resource ('Read one layer in full') and immediately enumerates what is returned: type, name, position, settings, and playlist items plus which is playing. This is clearly distinguishable from siblings like livereacting_add_layer, livereacting_set_playlist, and livereacting_get_scenes.

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?

Points the agent at the prerequisite source of ids ('Layer ids come from livereacting_get_scenes') and gives operational guidance to read every page before judging playlist contents. It does not explicitly state when NOT to use this tool versus alternatives such as get_scenes, but the context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description still adds value by disclosing the shape of the returned data (name, type, duration, size, folder, encoding state) and noting that metadata is opt-in, which matters because there is no output schema.

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, zero filler, with the core purpose front-loaded and the conditional metadata guidance placed in the second sentence. Nothing here could be dropped without losing 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?

With no output schema, the description compensates by listing the returned fields, and it explains the optional metadata expansion. Minor gaps remain around error behavior for an invalid or missing id, but the essentials for calling it correctly are present.

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

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

Schema description coverage is 100%, so both fileId and includeMetadata are already well documented, including the id pattern and the default of false. The description's mention of resolution, frame rate and codecs largely restates the schema text, so it adds little beyond the 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?

States a specific verb and resource ('Read one file from the media library by id') and enumerates the returned fields, which cleanly separates it from the list-oriented sibling livereacting_list_media. An agent can tell instantly that this is the single-item fetcher.

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

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

Gives concrete guidance for the includeMetadata flag ('when you need the technical detail') and ties it to a downstream decision (whether livereacting_encode_media is required). It does not state when to prefer this tool over alternatives, but the encode_media workflow context is genuinely useful.

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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: scenes are omitted by default and that omission exists because scene lists can be long, which explains the default rather than merely restating 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?

Three sentences, front-loaded with what is returned, then the use case, then the parameter caveat. The field enumeration is long but it is load-bearing given there is no output schema; nothing is obviously redundant.

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

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

With no output schema, the description takes on the burden of describing return values and does so by naming the returned fields. Combined with the default-omission behavior and the sibling routing for scenes, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100% and every parameter already carries its own description, so the baseline is 3. The description largely mirrors the schema ('prefer livereacting_get_scenes, which pages'; 'off by default') and only adds the 'scenes can be long' rationale, which is marginal.

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?

Specific verb (read) plus resource (one project) with an enumeration of exactly what comes back: name, video format, audio quality, duration, destinations, stream status, pending schedule count. This distinguishes it from livereacting_list_projects (plural) and from livereacting_get_scenes (explicitly routed away).

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

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

Gives a concrete use case ('check a project is set up the way the customer expects before starting a stream') and names the alternative for scene data (livereacting_get_scenes, which pages). It does not address overlap with livereacting_get_stream_status for the 'current stream status' field it advertises, so the routing guidance is not complete.

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 readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds real value beyond them: the active-scene/on-air semantics and the response caps ('20 scenes at a time and at most 50 layer summaries per scene'). It's slightly redundant with the limit/offset schema docs on the 20-scene cap.

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

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

Four short sentences, front-loaded with what the tool does, then the domain concept, then the read/list rule, then downstream routing. 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?

With no output schema, the description carries the return-value burden and does so reasonably: it says scenes come back with layer summaries, states the pagination caps, and warns that layer summaries are truncated at 50. It stops short of describing the fields in a scene or layer summary, a minor gap.

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

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

Schema description coverage is 100% — limit, offset, sceneId and projectId are all documented, including the nextOffset pagination hint and the 24-hex pattern. The description restates the sceneId presence/absence behavior but adds no format or syntax detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Read the scenes of a project') and adds domain definition: 'A scene is one arrangement of content; exactly one scene is active at a time.' This distinguishes it from siblings like livereacting_get_layer and livereacting_activate_scene that operate on adjacent concepts.

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 branching rule: 'Give a sceneId to read a single scene, or leave it out to list them all.' It also names the precise downstream workflows — find a layer id before livereacting_get_layer / livereacting_set_playlist, and a scene id before livereacting_activate_scene.

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuine context beyond them: the YouTube channel must have granted analytics access, `playlists` can fail with FEATURE_NOT_AVAILABLE on a healthy account, row-shaped sections are paginated 50 at a time, and no CSV export is available here. That is exactly the extra behavioral detail the annotations do not carry.

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

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

Front-loaded with the core action and organized into one paragraph per concern (prerequisite, plan availability, youtube returns, playlists returns, section paging). Slightly repetitive, since `playlists` availability is stated twice, but every paragraph carries 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?

With no output schema, the description carries the return-value burden and does so for both modes, enumerating the metric families and the row shape. All 8 parameters are documented and the two required ones are explained 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 coverage is 100%, so the baseline is 3, but the description adds real meaning for `type`: per-plan availability, the error it can produce, and what each mode returns. It also reinforces the opt-in nature of `sections` and the row-at-a-time paging behavior, though the 28-day range and default limits mostly restate 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?

Opens with a specific verb+resource ('Read the analytics of one broadcast') and immediately scopes it to a single broadcast, distinguishing it from list-level siblings. The two `type` modes are each described in concrete terms (YouTube-reported metrics vs LiveReacting-recorded playback rows).

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?

Names the prerequisite source for the id (livereacting_list_broadcasts), explains when each `type` value applies, and states what to do when `playlists` returns FEATURE_NOT_AVAILABLE (tell the customer to email hello@livereacting.com). It also tells the agent to use the REST API instead when CSV export is needed.

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

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

Despite readOnly/idempotent annotations, the description adds substantial behavior the structured fields cannot: the 150 req/min account-wide rate limit, the 5-second polling floor, the diagnostic precedence for error fields, the precise meaning and limits of tokenExpired (only Instagram reports it; absence is not health), the no-login reality of Custom RTMP/HLS/SRT, and the caveat that LIVE is not proof of delivery. This is unusually rich behavioral disclosure.

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

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

Front-loaded correctly: what it reads, then error semantics, then polling, then a closing caveat. It is dense and long for a one-parameter read tool, but every paragraph carries non-redundant operational value, so little is wasted.

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

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

There is no output schema, so the description carries the return-value burden and does so fully, naming the status enum, per-destination fields, and derived signals like destinationsNeedingReconnect and notice. Nothing an agent needs to call or interpret it 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?

Schema description coverage is 100% and the single projectId param already documents its format and points to livereacting_list_projects. The prose adds nothing further about the parameter, so the baseline 3 applies.

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

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

States a specific verb+resource ('Read what a project's stream is doing right now') and enumerates the exact payload (overall status enum, live id, runtime, per-destination status/viewers/peak/times/duration/error). The 'right now' live-state framing implicitly separates it from the sibling analytics tool. An agent can select it without opening the schema.

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

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

Gives actionable when-guidance for diagnosing failures ('When a destination is failing, read its error field first') and polling cadence ('no more often than every 5 seconds'). It stops short of explicitly routing to or excluding siblings such as get_stream_analytics or validate_destinations, so it is clear context rather than full alternative routing.

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 it discloses the async contract (runs in background, returns a fileId immediately, poll livereacting_get_import_status), the concurrency limit (one import per account), quota behavior (video counts against storage), and the specific URL_NOT_ALLOWED error for disallowed addresses. This is materially more than readOnlyHint/openWorldHint 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?

Purpose, constraints, alternatives and async behavior are all front-loaded in roughly that order, and every sentence carries unique information. It is on the long side, and the content-type sentence partially overlaps the schema's `type` documentation, but there is no filler.

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

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

With no output schema, the description still explains the return value (a fileId) and the follow-up step needed to learn when the file is ready. Combined with the error and quota notes, an agent has everything needed to call this correctly and handle the result.

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, but the description adds real semantics: the content type of the fetched file decides the media type and must match `type`, which constrains how the enum parameter must be set. It does not add detail on folderId 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 first sentence states a specific verb and resource ('bring a file into the media library from a direct http or https link') plus the accepted media kinds and hosts. It explicitly separates itself from livereacting_import_media for Google Drive/Dropbox/YouTube links, so an agent can route without opening either schema.

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

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

It gives explicit when-to-use (direct file link on a public host, CDN or bucket URL), when-not (web pages, private/internal addresses, Drive/Dropbox/YouTube links, which route to livereacting_import_media), and prerequisite constraints (content type must match `type`, must fit plan max size, one import at a time). Alternative tools and exclusions are named outright.

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

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

Goes well beyond the annotations by disclosing that the import is asynchronous, returns a fileId immediately, requires polling, is serialized to one import per account, and that YouTube playlists/channels are refused with VALIDATION_ERROR. This is exactly the runtime behavior an agent needs to avoid promising an impossible playlist import.

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

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

Front-loaded with the core purpose followed by alternatives, async behavior, and constraints. Every sentence carries useful information; it is somewhat long, but nothing reads as filler given the failure modes it warns about.

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

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

With no output schema, the description compensates by explaining the return value (fileId) and the follow-up call needed to check readiness. Combined with the error case and concurrency limit, an agent has everything required to invoke and route correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real meaning by reinforcing the single-URL-per-call rule and the single-video (not playlist) constraint on the url parameter. It does not add anything about the folderId or type enum beyond what the schema already documents.

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

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

States a specific verb and resource ('Bring a file into the media library') and immediately scopes the accepted sources (Google Drive, Dropbox, YouTube). It explicitly names the two sibling tools that cover adjacent cases, so an agent can distinguish it without opening any schema.

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

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

Gives explicit alternatives with their selection conditions: 'direct link ... use livereacting_import_from_url' and 'file on the customer's own computer, use livereacting_upload_file'. It also states the downstream workflow (poll get_import_status) and the one-import-at-a-time constraint.

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 the safe-read profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the description is not burdened with safety disclosure. It still adds genuine behavioral context beyond the annotations: newest-first ordering, exclusion of running broadcasts, and the per-destination breakdown including peak viewers and error. Pagination behavior (limit/offset interaction, nextOffset) is left to the schema.

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 clauses, each load-bearing: what it returns, how to use a returned live id, and what it excludes. The scope constraint and sibling routing are front-loaded with no filler or restated name/title.

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

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

There is no output schema, so the description carries the return-value burden and discharges it by naming the per-broadcast fields (live id, start/end, duration, peak viewers, error, per destination). Combined with the sibling routing and the 100%-covered schema, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100%, so limit, offset and projectId are fully documented in the schema, and the pattern for projectId is even cross-referenced to livereacting_list_projects. The description adds no parameter-level syntax or defaults, so baseline 3 applies.

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

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

States a specific verb and resource ('List a project's finished broadcasts') plus ordering ('newest first') and enumerates the returned fields. It is immediately distinguishable from siblings like livereacting_get_stream_status and livereacting_get_stream_analytics, which it explicitly names.

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

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

Gives explicit routing in both directions: finished broadcasts only, with livereacting_get_stream_analytics consuming a live id from this result, and livereacting_get_stream_status named for running broadcasts. The when-not condition ('Only finished broadcasts appear') is stated outright.

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, idempotentHint, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: the returned ids feed into project creation, and destinations must be pre-connected in the Studio with no add capability here.

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 core action and platform scope, followed by actionable usage guidance and a clear limitation. Every sentence contributes without redundancy.

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

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

For a simple read-only list tool with fully described parameters and annotations covering safety, the description is complete enough: it states what is listed, how to use the result, and the prerequisite. No output schema exists, but the description sufficiently implies returned destination ids.

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

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

Schema description coverage is 100%, so both limit and offset are fully documented in the input schema. The description adds no parameter-level meaning beyond what the schema provides, making the baseline 3 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?

States a specific verb (List) and resource (streaming destinations), enumerates the supported platforms, and clarifies that destinations cannot be added from this tool. An agent can distinguish this from sibling tools like create_project or validate_destinations without opening schemas.

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

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

Explicitly says to use the returned ids when creating a project and states a key prerequisite (destination must be connected in LiveReacting Studio first; you cannot add one here). It does not name alternative tools such as validate_destinations, so it falls short of a full when/when-not/alternatives guide.

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 readOnly/idempotent/non-destructive, so safety is covered. The description adds real behavioral context beyond them: files and folders paginate on independent cursors, includeFolders requires type, and files with non-empty issues.errors are blocked from playlists until encoded. It stops short of describing response shape or truncation behavior in 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?

Front-loaded with the core purpose, then pagination rules, then the sibling routing. Dense and mostly waste-free, though the final sentence enumerating three import alternatives is long enough that it 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?

With 8 optional params, no output schema, and annotations covering safety, the description supplies the missing pieces an agent needs: what is returned (file ids, issues.errors), how to paginate, and where to go next. Complete enough to call correctly, with only minor gaps around response shape and empty-result 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 description coverage is 100%, so the schema already explains every parameter including the includeFolders/type dependency and folderOffset independence. The description largely restates those relationships (dual pagination, includeFolders requiring type) rather than adding new syntax or format meaning, so the 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?

Opens with a specific verb+resource+scope: 'List the video, audio and image files in this LiveReacting account's media library, and optionally the folders'. This clearly separates it from get_media_file (single file), upload_file/import_* (writes), and the list_* siblings (broadcasts, projects, destinations).

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

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

Explicitly routes the agent to alternatives: upload_file for local files, import_from_url for direct links, import_media for Drive/Dropbox/YouTube, and livereacting_encode_media when a file has errors. It also states the downstream use case (file ids feed playlists). When-to-use is fully covered.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description correctly focuses on behavior: the return shape (id, name, live state, future schedule count) and the page size of 20. With no output schema, that return context is genuinely additive, though it omits what happens on a truncated page beyond the offset parameter's own note.

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?

Six sentences, but front-loaded with purpose and the operational cue, and each sentence carries either scope, entry condition, return shape, or the alternative tool. The template definition of 'project' is the only sentence that could be trimmed for a reader already versed in the domain.

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 read-only 3-parameter list tool with no output schema, the description supplies ordering, page size, entry fields, an entry condition, and the sibling to use for detail work. An agent has everything needed to call it and interpret the result.

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 limit, offset, and the status enum are already fully documented in the schema. The description only echoes the ordering ('newest first') and the 20-per-page default, adding little beyond the structured fields; baseline 3 applies.

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

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

States a specific verb and resource ('List the LiveReacting projects on this account, newest first'), defines what a project is, and explicitly names livereacting_get_project as the single-item alternative. An agent can distinguish it from all siblings without opening a schema.

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

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

Gives an explicit entry condition ('Start here when the customer names a stream but you do not have its id') and routes to the alternative tool for detail retrieval. Nothing about when to pick this versus livereacting_get_project is left to inference.

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

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

Annotations already flag destructiveHint=true and non-idempotent, but the description goes well beyond them: permanent removal of the scene and all non-pinned layers including playlists, no undo, auto-switch links being silently cleared with a 24/7 chain warning, the response listing changed layers, and the active-scene reassignment rule. This is exactly the context annotations cannot carry.

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

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

Front-loaded with the verb+resource and organized per action value. Dense but nearly every sentence carries non-obvious operational consequence (no undo, link clearing, active-scene fallback); marginally long but not padded.

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

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

No output schema exists, and the description compensates by telling the agent the response lists layers whose auto-switch links were changed. Combined with the delete side-effect disclosures and the create/update scope limits, an agent has everything needed to call this safely.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning per action value: "update" renames and changes nothing else, "delete" removes layers for good, "create" yields an empty scene. It does not elaborate on setActive behavior beyond the schema's own note.

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

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

States specific verbs (create, rename, delete) and resource (scene), and immediately differentiates itself from the sibling livereacting_create_scene_with_playlist by explaining that create adds an *empty* scene. An agent can disambiguate from activate_scene, add_layer, etc. without opening schemas.

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

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

Explicitly routes the agent: use this for empty scenes, prefer livereacting_create_scene_with_playlist when the scene is meant to play video. Also states when NOT to delete (last remaining scene) and instructs to confirm with the customer before deleting.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description goes beyond them by naming the ACTIVE_SCHEDULES_EXIST failure, exposing the 3-minute/28-day window, the fixed-duration requirement, the gap rule, and the Facebook-only 8-hour stop. It stops short of describing the return payload or scheduling limits beyond a single set.

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

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

Front-loaded with the purpose, then four numbered rules that each carry non-obvious operational content. Slightly long for a 2-parameter tool and rules 2 and 4 partly restate the schema's dates description, but no sentence is filler.

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

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

For a mutation tool with annotations covering the safety profile and no output schema, the description closes the important gaps: prerequisites, error code, timing windows, and duration coupling. An agent has everything needed to invoke it without first discovering failures by trial.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns extra by explaining *why* the multi-date constraint exists (the platform cannot detect overlap with a manual duration) and by cross-linking duration setup to livereacting_update_project – reasoning absent from the schema itself.

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

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

States a specific verb ('Schedule') and resource ('a project to go live') with scope ('one or more future times'), and immediately distinguishes itself from the start-now path via 'Nothing starts now,' which separates it from livereacting_start_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?

Gives explicit when/when-not plus named alternatives: it warns that a project with existing schedules must call livereacting_cancel_schedules first, and that a manual-duration project must use livereacting_update_project or schedule one date at a time. This routes the agent to the correct sibling before it makes a failing call.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description goes well beyond: it explains the destructive mechanism (omitted items are removed), that playback restarts, that it is non-idempotent because playlistItemIds regenerate, the 600-item cap, the import/encode precondition, and last-write-wins behavior under concurrency. It also discloses the response signals (removedItemCount, shorter-playlist warning) with no output schema present.

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 core replace semantics are front-loaded in the first two sentences, and nearly every sentence carries a distinct operational rule (concurrency, limits, preconditions, recovery). It is long by absolute standards and repeats the deletion consequence twice ('anything already in it that you do not send again is removed' and 'Sending only the new video deletes everything else'), so a small deduction for 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?

With no output schema, the description carries the return-value burden and does so (removedItemCount, warning when the playlist shortens). For a destructive, non-idempotent, concurrent-write-prone operation it covers limits, preconditions, race conditions, and failure recovery — everything needed to invoke it safely.

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, and loop/volume/autoSwitchToSceneId are not discussed in prose. However, the description adds operational meaning around the dominant 'files' parameter — that the array becomes the whole playlist, that omission means deletion, that playback restarts from item one — which the schema states more terseley. This is meaningful reinforcement beyond structured data.

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

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

The description names a precise verb+resource: 'Replace the entire contents of a video or audio playlist layer,' and immediately scopes it down ('videoPlaylist and audioPlaylist layers only'). It distinguishes itself from any append-style operation ('There is no way to append with this tool'), which is exactly the distinction an agent needs against siblings like livereacting_create_scene_with_playlist.

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 when-and-how: read the full list first via livereacting_get_layer and page until nextOffset is null, apply the change, send the complete list back. It warns against the naive alternative ('Sending only the new video deletes everything else'), states the concurrency rule (no parallel edits against one playlist), and covers the Studio co-editing case and post-timeout recovery. Nothing is left to inference.

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

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

Annotations already declare idempotentHint=false and destructiveHint=true, and the description goes well beyond them: duplicate-broadcast risk on retry, the already-running/already-scheduled short-circuit that returns the existing live id, and platform-level limits (max stream length, 8-hour Facebook-only cap, unsupported thumbnails/announcements).

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 critical constraint (non-idempotent, do not retry on timeout) is front-loaded in the second paragraph, and the limits are separated into scannable bullets. Slightly verbose in framing ('Honest limits, so you do not promise the customer...') but no sentence is redundant.

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

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

No output schema exists, and the description only implicitly signals the return value ('returns the existing live id'), so an agent lacks the full success-response shape. Everything else an agent needs to invoke it safely is present, including the retry and status-check protocol.

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 there is a single required parameter, so the schema already documents projectId and its source tool. The description adds no format or constraint detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Start streaming a project to its destinations immediately') and explicitly enumerates the project shapes it applies to. An agent can distinguish it from livereacting_schedule_stream and livereacting_stop_stream without opening a schema.

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

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

Explicitly covers when to use it, when NOT to retry after a timeout, the exact alternative to consult (livereacting_get_stream_status), and how to interpret that status (PREPARING/LIVE vs OFFLINE) before re-calling. This is a complete routing and retry policy.

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 destructive=true and idempotent=false, but the description adds concrete consequences: every viewer stops immediately, the broadcast is unresumable, and a later start creates a new broadcast rather than resuming. That is real behavioral context beyond the flags, including the important non-idempotency warning on timeout.

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

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

Three tight sentences, front-loaded with the destructive consequence, then exclusions, then failure handling. Every sentence carries distinct information; nothing is redundant padding.

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 destructive, non-idempotent, single-parameter tool with no output schema, the description covers effect on viewers, irreversibility, sibling routing, and error recovery. An agent has everything needed to call it correctly and safely.

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?

Only one parameter (projectId) and schema description coverage is 100%, with the schema itself pointing to livereacting_list_projects for the id. The description adds no format or sourcing detail beyond what the schema already provides, so the baseline 3 applies.

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

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

States a precise verb+resource+scope: 'End the stream that is currently running for a project.' It explicitly distinguishes itself from livereacting_cancel_schedules (scheduled streams) and livereacting_start_stream, so an agent can disambiguate without opening schemas.

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

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

Gives explicit when-to-use context (running stream), when-not-to-use (scheduled streams are out of scope), a social precondition (confirm with the customer if you did not start it), and timeout recovery guidance (call get_stream_status rather than retrying). Nothing is left to inference.

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

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

Annotations already declare idempotentHint=true, destructiveHint=true, openWorldHint=true, and readOnlyHint=false, so the description's redundancy on idempotency is minor. It does add real value beyond the annotations: the NO_ACTIVE_LIVE failure mode and the copy-at-start mental model. It stops short of explaining why the operation is flagged destructive (e.g., overwriting the on-air state).

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

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

Four tight sentences, front-loaded with the action, then the rationale, the when-to-use condition, and finally the idempotency/error notes. No filler; each 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?

For a single-param tool with no output schema, the description covers the conceptual model, the autoSynch dependency, idempotency, and the key error condition. An agent has everything needed to decide when to call it and interpret a failure.

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?

Only one parameter (projectId) with 100% schema description coverage, so the schema already documents it. The description implies the project whose setup is pushed but adds no syntax, formatting, or sourcing detail beyond what the schema provides. Baseline 3 is appropriate.

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

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

States a specific verb and resource: pushing the project's current setup to the currently-running stream. The added mental model ('a running stream uses the copy of the project it was started with') makes the operation's intent unambiguous and clearly distinct from siblings like start_stream, stop_stream, or update_project.

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

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

Gives an explicit when-to-use condition ('only needed when the project has autoSynch off') and the inverse exclusion ('with autoSynch on, edits reach the stream by themselves'). Though it doesn't name an alternative sibling tool, the condition-based routing is 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?

Annotations already flag a destructive, idempotent, non-read-only mutation, but the description adds real behavioral context beyond them: partial-update semantics ('only the fields you send are changed'), a state gate that extends beyond 'on air' to PREPARING and SCHEDULED, and the side effect that title/description edits propagate to destination platforms. That is exactly the kind of state-dependent refusal behavior an agent cannot infer from 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?

Front-loaded with the core semantics (partial update) before the state constraints, then alternatives. Every sentence carries a distinct rule; nothing is restated from the schema verbatim.

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

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

For a 9-parameter mutation tool with nested objects and no output schema, the description covers partial updates, state-gated fields, side effects and sibling alternatives well. It does not mention auth/permission requirements or the failure mode for an invalid projectId, which keeps it short of perfect.

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

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

Schema coverage is 100% and the schema itself already labels several fields as refused while live or scheduled, so the baseline is 3. The description still adds value by widening the refusal window to PREPARING/SCHEDULED and by naming youtubeAdvancedSettings, which does not appear in the schema properties at all.

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

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

States a specific verb+resource (change the settings of an existing project) that cleanly separates it from livereacting_create_project, livereacting_get_project and livereacting_set_playlist. An agent can route to it without opening any schema.

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

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

Explicitly names alternatives and the conditions that select them: stop with livereacting_stop_stream or cancel with livereacting_cancel_schedules before touching the five refused fields, and use livereacting_set_playlist for playlist changes. It also states which fields are safe to change at any time.

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 tell the agent this is a non-idempotent, non-read-only operation; the description goes far beyond that with the 3-step protocol, the 403 refusal when a part's byte count is wrong, the 256 MiB single-part threshold, plan max-size and full-storage refusals for video, and a 3-day expiry on part URLs and the token. This is behaviorally rich context the schema cannot carry.

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

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

Front-loaded with the decisive constraint, and the numbered three-step flow is scannable. It is long, but nearly every clause carries a constraint (sizes, expiry, extension/type matching) rather than padding, so the length is largely earned.

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 4-parameter tool with no output schema, the description covers the complete lifecycle: precondition (file metadata), execution (HTTP PUT to part URLs), completion (token handoff), failure modes (403, storage full, plan limits), and expiry. An agent has everything needed to call it correctly or decide not to.

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, but the description adds real meaning: it supplies the full extension lists per type (e.g. video: .mp4 .m4v .mov ...) that the schema enum alone does not contain, and reinforces that size must be exact bytes and must fit the plan limit. It stops short of explaining folderId placement beyond what the schema says.

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

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

States a specific verb and resource ('start uploading a file into the media library') and immediately delimits scope with the key constraint that the server cannot read local files. It clearly distinguishes itself from livereacting_complete_upload (next step) and livereacting_import_from_url (alternate path).

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

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

Gives explicit when-to-use and when-not-to-use guidance: if you cannot run commands or make HTTP PUTs, 'ask for a public link and use livereacting_import_from_url instead.' It also names the required follow-up tool and the exact sequencing across all three steps.

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

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

Adds rich behavior beyond the annotations: token renewal for expired YouTube tokens, that failure forces the customer to reconnect in the Studio, and crucially that for custom RTMP/HLS/SRT (incl. LinkedIn and X) nothing is actually checked. This also reconciles with readOnlyHint=false, since renewal is a write side effect. It could note the idempotency/rate-limit angle, but the disclosure is strong.

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

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

Front-loads the core purpose and return contract, then layers the platform caveats. Dense but every sentence carries decision-relevant information (especially the custom-destination warning). Slightly long, but nothing 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?

With no output schema, the description carries the return-value burden and does so fully: 'valid true or false per destination, with a reason when it is false', plus a per-platform definition of what true means. An agent has everything needed to interpret results and call correctly.

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

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

Schema coverage is 100% and the single destinationIds parameter is fully documented in the schema (including its source, livereacting_list_destinations). The description adds no syntax or format detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('check that the given destinations still have a working login') and names the exact sibling it must precede ('Call this before livereacting_start_stream'). It also disambiguates what 'valid: true' means platform by platform, so the agent understands the check's true 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?

Gives explicit when-to-use ('Call this before livereacting_start_stream so a failure is explained up front rather than mid-broadcast') and an implicit alternative framing: use it pre-flight rather than discovering failure mid-stream. The sibling ordering constraint is unambiguous.

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