Upstream.so

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

Annotations already declare readOnlyHint=false, openWorldHint=true, and destructiveHint=true, so the safety profile is covered structurally. The description adds useful context (active vs scheduled output, mirroring POST /api/v1/streams/{stream}/destinations) but does not mention auth requirements, side effects on an existing stream, or what happens alongside remove_destination.

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 tightly packed sentences that front-load the core action and then the required fields and endpoint mapping. Dense but no filler; the key-format clause is long yet earns its place by disambiguating platform-specific input.

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 7 parameters, no output schema, and annotations already covering safety, the description covers the action, the required fields, and the non-obvious key formats. Minor gaps remain around optional params (status, url, include_in_schedule), but the schema documents those adequately.

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 value beyond the schema: the stream key format rules per platform (custom/instagram/rumble use rtmp:// or rtmps://, customsrt uses srt://) and the max-100 name constraint, which the schema does not encode. This is meaningful semantic enrichment.

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 a multistream destination to a stream') and clarifies the scope as multistream output to an external platform. This cleanly separates it from list_destinations, update_destination, and remove_destination 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?

The description explains what the destination does ('enable active or scheduled output to an external platform'), which implies when it applies, but gives no explicit when-to-use/when-not guidance or routing to siblings like update_destination or list_destinations. Usage is inferable but not stated.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true; the description adds the operationally important consequence that 'Queue changes can affect live output,' which is not derivable from the hints. It stops short of describing ordering behavior, duplicate handling, or what the response contains.

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 purpose, then the risk warning, then parameter guidance, then the mirrored endpoint. Four dense sentences with little waste, though the REST-endpoint sentence is the least essential for an agent.

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

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

Covers purpose, risk, and both payload variants for a destructive, no-output-schema mutation tool. Remaining gaps (return value, ordering guarantees, auth requirements) are modest given the annotations and full schema coverage.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema: the .mp4 URL constraint for external-videos and the concrete shape of items per queue type. It does not clarify whether items append at the end or their position semantics.

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

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

States a specific verb and resource ('Append items to a stream queue') and the per-queue-type payload semantics, which cleanly separates it from siblings like remove_from_stream_queue, reorder_stream_queue, and get_stream_queue. An agent can identify the operation without opening the schema.

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

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

It routes the caller by queue type (media UUIDs for video/audio/audio-secondary vs {url, name} for external-videos) and points to list_media as the way to obtain UUIDs. It gives clear context but does not state when not to use this tool (e.g., to reorder or remove, use the sibling tools).

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the agent knows this is a safe, non-destructive local write. The description adds only the API mapping ('Mirrors POST /api/v1/folders') and says nothing about duplicate-name behavior, ownership requirements, or what the call returns.

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

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

Two short sentences with zero filler, and the core action is front-loaded. The optional nesting behavior and API mapping follow in the natural order of importance.

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 two-parameter create with annotations covering the safety profile, the essentials are present. However, with no output schema, the description gives no hint of what a successful call returns (e.g., the new folder ID), which an agent would need to chain into subsequent calls.

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 'name' and 'parent_id' are fully documented in the schema, including the ownership note and the null-for-root behavior. The description adds no syntax or constraint 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?

The description states a specific verb and resource ('Create a media library folder'), scoping it to the media library rather than generic folders. It implicitly distinguishes itself from siblings like create_tag and create_stream by naming the resource, though it never contrasts itself with related folder tools such as update_folder or move_files_to_folder.

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?

'Optionally inside a parent folder' is the only usage signal, and it simply restates the parent_id parameter. There is no guidance on when to create a folder versus using an existing one, no mention of permissions or prerequisites, and no routing to alternatives.

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

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

Annotations already declare write, destructive, and open-world behavior, so the safety profile is carried. The description adds real behavioral context beyond that: optional setting groups (encoding, volumes, playback, transitions, video_fit, recording) and tags default sensibly, and a supplied schedule can itself start or stop broadcasting — a non-obvious side effect. It doesn't say what a failed platform/key combination returns, hence a 4 not a 5.

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

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

Front-loaded with the required fields, then platform-specific key rules, then optional groups, then lifecycle ownership. Dense but every sentence carries information; the trailing 'Mirrors POST /api/v1/streams' is arguably filler for an agent but harmless.

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 14-parameter creation tool with nested objects and no output schema, the description covers what must be supplied, how optional groups behave, and how the object interacts with the start/stop lifecycle. The omission of any guidance on failure/auth requirements or the returned object is minor given annotations cover the write/destructive profile.

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 all 14 parameters, including nested objects and the key-format constraints. The description restates the required fields and key prefix rules, which is useful reinforcement but not meaningfully additive. Baseline 3 applies when the schema does the heavy lifting.

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 opening sentence gives a specific verb+resource ('Create a stream'), and the follow-up about status being managed by start_stream/stop_stream cleanly separates this creation tool from the lifecycle siblings. An agent can distinguish it from update_stream and start_stream without opening any schema.

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

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

It states a clear when-not: status/broadcasting is controlled via start_stream/stop_stream and scheduling, so the agent knows not to try to go live through this tool. The key-requirement rules per platform (none vs custom/instagram/rumble vs customsrt) are also usage-relevant. It stops short of naming update_stream as the mutation path for existing streams, so it isn't a full 5.

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

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

Annotations already declare a non-destructive, closed-world write, so the safety profile is covered. The description's added value is the uniqueness validation rule, but that same fact is already in the schema's name description, and "Mirrors POST /api/v1/tags" is an implementation detail rather than agent-useful behavior. No mention of what is returned or what happens on name collision.

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, front-loaded sentences with no padding. The closing "Mirrors POST /api/v1/tags" sentence earns its place only marginally, since the REST mapping is not something an agent acting on this tool needs.

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 3-parameter create with annotations covering the safety profile, this is minimally adequate. It omits sibling differentiation (create vs update vs delete) and, with no output schema, says nothing about the created tag's identity or response shape.

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 schema documents all three parameters with types, lengths, and color format. The description adds no parameter syntax or format 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 specific verb and resource ("Create a tag"), which is immediately clear. However it does nothing to distinguish itself from siblings like update_tag, delete_tag, or list_tags, so an agent must infer the boundary on its own.

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

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

The uniqueness constraint ("Name must be unique within the account") implies this is for new tags and that existing tags should be edited via update_tag instead, but that alternative is never named. Usage is only implied, not stated.

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

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

Annotations only declare it is a non-read, non-destructive, closed-world write. The description adds the traits that actually matter here: the token lifetime (24h), that new tickets renew the account token family WITHOUT revoking in-flight uploads, and that tickets support batched reuse. That is non-obvious mutation semantics that no annotation conveys.

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

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

Three dense sentences with the core action front-loaded, followed by lifecycle/constraint details and the sibling route. No filler, no restatement of the title, and each sentence adds a distinct fact (what is minted, token-family behavior, revocation path).

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-optional-param write tool with no output schema, the description supplies everything an agent needs: what is returned in effect (endpoint + bearer token), how long it lives, how it interacts with existing uploads, and how to undo it. Nothing material 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?

Only one optional parameter (folder_id) and schema description coverage is 100%, so the schema already documents the UUID and the Folder-Id header requirement. The description adds no parameter-level 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+resource ('Start a media upload... mints an upload ticket') and immediately qualifies the output (TUS endpoint + 24h bearer token) and protocol (TUS 1.0.0 client). It also names the sibling it complements (revoke_upload_tickets) and maps to the underlying REST route, so an agent can distinguish it from create_folder/create_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?

Gives clear operational guidance: reuse one ticket for a batch when practical, and use revoke_upload_tickets to invalidate the token family immediately. It names the alternative tool and the condition that selects it, but never states when NOT to mint a ticket (e.g., if a valid unexpired ticket already exists) or any preconditions beyond folder ownership implied by the schema.

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, but the description goes well beyond them by spelling out exactly what is destroyed (the folder and its subfolders) and what is preserved (files move to the library root rather than being deleted). This is precisely the cascading-effect detail an agent needs before invoking a destructive operation.

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

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

Three short sentences, front-loaded with the destructive verb and scope, followed by the side effects and the API endpoint mapping. No filler, and each sentence adds distinct information.

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

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

For a single-parameter destructive tool with no output schema, the description covers the critical unknowns: permanence, cascading deletion, and file relocation. It stops short of covering permission requirements or error behavior (e.g., what happens if the UUID is invalid), which are minor gaps given the annotation-based safety profile.

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 'folder' property is documented as a UUID in the schema itself. The description adds no syntax, format, or lookup guidance beyond that, so the baseline 3 applies when the schema carries the parameter burden.

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 ('Permanently delete a folder') with the destructive intent made explicit by the word 'Permanently'. The resource (folder) cleanly separates it from sibling deleters like delete_media, delete_stream, and delete_tag without needing to inspect 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?

The description never says when to choose this tool over alternatives (e.g., move_files_to_folder to relocate contents rather than destroy structure) nor states any precondition for deletion. Usage is only inferable from the tool name, so no guidance is provided.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the cascade effect — the file also disappears from any queues that reference it — which is a non-obvious side effect not present in the annotations. It omits auth/permission requirements and error behavior, so it falls short of a 5.

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

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

Three short sentences with zero filler: the action, the irreversibility plus cascade consequence, and the API mapping. The most important constraint (permanent, irreversible) is front-loaded immediately after the verb.

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

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

For a single-parameter destructive tool with annotations covering the safety profile and no output schema, the definition supplies what an agent needs: the effect, the irreversibility, and the downstream consequence. Only permission requirements and failure modes are absent, which keeps it just short of 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% and the sole parameter's meaning ('Media (storage) UUID.') is fully documented there. The description adds only the informal phrase 'media file', which does not extend the schema's semantics; 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 ('Permanently delete a media file from the library') and pins the scope to media, which cleanly separates it from the many sibling delete_* tools that act on folders, streams, and tags. 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?

Usage is implied by the description and the resource name, and the irreversibility warning nudges the agent to confirm intent. However, it never names alternatives (e.g., update_media, move_files_to_folder) or states prerequisites, so the when-to-use routing 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 openWorldHint=true, so the safety profile is covered; the description still adds real value by declaring irreversibility and the live-broadcast interruption. It stops short of saying what happens to attached resources such as destinations or queued items, which is the remaining meaningful gap.

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

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

Three short sentences with the destructive nature front-loaded, followed by the irreversibility warning and endpoint mapping. No filler, nothing repeated from the schema.

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

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

For a one-parameter destructive tool with annotations and no output schema, the definition covers what is destroyed, that it is irreversible, and the API route it mirrors. Only the fate of dependent objects (destinations, queue entries) is left unstated.

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 parameter is fully documented as a 'Stream UUID', so the schema carries the load. The description adds no syntax, format, or lookup guidance beyond that, which lands on 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 pair and resource ('Stop any live broadcast and permanently delete the stream and its configuration'), plus the underlying endpoint, so the agent knows exactly what happens. It implicitly distinguishes itself from the sibling stop_stream (which stops but does not delete) and delete_media by naming the stream as the resource.

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

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

The description implies the usage condition (a full teardown rather than a mere stop), but never explicitly says when to choose it over stop_stream, delete_media, or update_stream, and lists no exclusions. Usage is inferable from the verb, which is the definition of a 3.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so safety is covered. The description adds genuinely non-redundant behavior: the deletion is permanent/irreversible and the blast radius is limited because streams keep working and merely lose the tag, plus the REST endpoint it mirrors.

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

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

Three short sentences, front-loaded with the irreversible action, then the side effect, then the API mapping. Every sentence earns its place 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 one-parameter destructive tool with no output schema and destructiveHint already set, the description covers irreversibility and side effects adequately. It stops short of stating permission requirements or behavior when the tag does not exist, which would make it fully complete.

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

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

Schema description coverage is 100% for the single 'tag' parameter, so the schema already carries the parameter documentation. The description adds no format, id-shape, or existence-requirement detail beyond it, which is the expected baseline when the schema does the work.

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 ('Permanently delete a tag') and the 'tag' resource plus 'delete' verb cleanly distinguishes it from delete_folder, delete_media, delete_stream, and from create_tag/update_tag. 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?

Usage is implied by the destructive verb and the note that streams survive, but there is no explicit when-to-use versus when-not guidance and no reference to sibling alternatives such as update_tag or list_tags. Adequate but leaves the routing decision 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds the underlying REST endpoint mapping but nothing further about behavior, auth requirements, or rate limits beyond what annotations supply.

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

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

Two short clauses with zero waste, front-loading the resource and hedging nothing. The endpoint mirror is appended as a compact second sentence that earns its place.

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

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

For a zero-parameter read tool with no output schema, the description supplies exactly the missing piece: the fields returned. Combined with annotations covering the safety profile, nothing an agent needs to call it correctly is absent.

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

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

The tool takes zero parameters, so the schema baseline of 4 applies; there is no parameter semantics to explain. The description's field list (id, name, email, plan, limits) describes the response, not inputs, which is a modest bonus here.

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

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

States a specific verb (Get) and resource (the authenticated Upstream account) and enumerates the returned fields: id, name, email, plan and limits. This clearly distinguishes it from the get_folder/get_media/get_stream siblings, which target content rather than the account itself.

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

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

The description makes the scope explicit ('the authenticated account') and notes it mirrors GET /api/v1/user, so an agent knows this is a self-scoped identity lookup with no parameters. It does not, however, state when to prefer it over any alternative or any exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered without the description. The only added context is the REST endpoint mapping, which is marginally useful for developers but says nothing about error behavior for a missing UUID or what a "not found" looks like.

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

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

Two short sentences with zero padding, and the core action is front-loaded before the endpoint reference. Nothing needs trimming.

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 one-parameter read tool with annotations covering safety, the definition is nearly sufficient, but with no output schema the description says nothing about the folder object returned (name, items, permissions), leaving the agent to guess at the payload.

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 parameter already documents itself as "Folder UUID." The description's "by UUID" simply restates that, adding no format, source, or validation detail beyond the schema.

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

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

States a specific verb and resource ("Get one folder") and constrains it to a single item via UUID, which implicitly separates it from the plural list_folders. It never names a sibling explicitly, so an agent must infer the singular/plural split from the tool names themselves.

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

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

There is no guidance on when to fetch a single folder versus listing folders, nor any mention of how the UUID is obtained (e.g., from list_folders or create_folder). The requirement to already hold a UUID is only implied by the phrase "by UUID."

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 this is a safe, non-destructive, closed read. The description adds genuinely non-obvious behavior: the need to poll, the is_processing flag semantics, and the dependency between processing and queue usability. It omits error behavior (e.g., unknown UUID) but the safety profile is already covered.

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, followed by the operational polling guidance, then a compact REST mapping. Every sentence carries information an agent can act on; 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 single-parameter read with no output schema, the description conveys the key returned field (processing state) and the workflow dependency. Only failure/not-found handling is left implicit, which is a minor gap for a low-complexity tool.

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

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

Schema description coverage is 100% with a single 'media' parameter already documented as the storage UUID, so the baseline is 3. The description restates 'by UUID' without adding format, constraint, or lookup guidance beyond the schema.

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

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

States a specific verb and resource ('Get one media file by UUID') and includes the scope detail that it returns processing state. This distinguishes it cleanly from list_media (many) and get_stream (different resource) 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 a concrete usage trigger and stopping condition: poll after an upload until is_processing is false, because the file is unusable in queues until processed. It does not name an alternative tool for the pre-upload or bulk case, so it falls just short of explicit when-not guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds the useful detail that it mirrors GET /api/v1/streams/{stream}, giving an integrating agent a concrete REST analogue, but says nothing about auth, rate limits, or error behavior (e.g. unknown UUID).

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?

One front-loaded functional sentence plus a short endpoint-mapping note. Every clause earns its place and nothing is 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?

With no output schema, the description compensates by listing the returned sections (settings, status, tags, destinations), which is genuinely helpful. A read-only single-fetch tool with full schema coverage needs little more, though noting error/not-found behavior would round it out.

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 'stream' parameter is documented as a UUID in the schema. The description's 'by UUID' reinforces but does not extend that; with one well-documented param, the schema carries the semantics.

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

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

States a specific verb and resource ('Get one stream by UUID') and enumerates the payload areas (settings, status, tags, destinations). The phrase 'one stream by UUID' implicitly separates it from list_streams/show_streams, though no sibling is named explicitly.

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

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

Usage is implied by the single-UUID scope: fetch one stream when you have its ID. There is no explicit when-to-use vs update_stream/get_stream_queue guidance and no stated prerequisites or exclusions.

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

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

Annotations declare readOnlyHint=false, which is unusual for a GET-shaped tool, and the description explains exactly why by disclosing that it assigns and saves stable IDs as a side effect. That is genuinely additive behavioral context beyond the annotation. It doesn't say whether that write is idempotent or whether it requires elevated permissions, so it is not a full 5.

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

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

Three tight sentences: purpose first, the non-obvious side effect second, and the mirrored REST endpoint last. Every sentence carries information, though the REST endpoint reference is of marginal value to an agent.

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 read tool with no output schema, the description covers what is returned ('ordered items') and the one surprising behavior (ID assignment). It leaves the returned item shape and ordering stability unstated, but the annotations plus schema fill most of the remaining gaps.

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

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

Schema description coverage is 100% and the enum values for 'type' are fully documented in the schema, so the description adds no parameter-level meaning. The description mentions 'legacy external-video items' but doesn't tie that to the external-videos enum value. 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 ('Get the ordered items of one of a stream's media queues') and scopes it to one queue type, which is precise enough to distinguish it from add_to_stream_queue and remove_from_stream_queue. It stops short of explicitly naming the siblings an agent should compare against, so it lands just under the top band.

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

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

Usage is only implied: the description notes the returned IDs let items be 'targeted by playback and removal tools,' which hints that this is the discovery step before play/skip/remove. There is no explicit when-to-use statement or rule for choosing among the sibling queue tools.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered without description help. The description adds the definition of a destination and the REST endpoint it mirrors, but says nothing about pagination, ordering, or an empty-destination result.

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

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

Two short, front-loaded sentences with no padding; the resource and its scope come first. The trailing endpoint reference is mildly redundant but cheap and occasionally useful for API-familiar agents.

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

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

For a single-parameter read tool with full annotation coverage and no output schema, the description supplies enough to call it correctly. Missing only return-shape and pagination notes, which are minor here given the annotations.

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

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

Schema description coverage is 100% and the single 'stream' parameter is already documented as a Stream UUID, so the schema carries the load. The description only implicitly ties the parameter to a stream, adding no syntax or format detail beyond the schema baseline.

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

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

The description gives a specific verb+resource (list a stream's multistream destinations) and even parenthesizes what a destination is, which helps an agent distinguish it from list_streams, list_tags, and list_media. It does not explicitly name the create/update/delete destination siblings, but the read-vs-write split is obvious from the name.

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

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

There is no statement of when to use this tool versus alternatives, and no prerequisites (e.g., that a stream must exist or that destinations are only meaningful for restreaming setups). Usage is only weakly implied by the phrase 'a stream's destinations'.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, covering the safety profile. The description adds the REST endpoint mapping ('Mirrors GET /api/v1/folders'), which is minor context but discloses no additional behavior like pagination defaults or result ordering.

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

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

Two tight sentences with the core purpose front-loaded and the filter capability second. No filler.

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

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

For a simple paginated read tool with full schema coverage and annotations carrying the safety profile, the description is adequate. It could note pagination behavior, but the schema covers it and no output schema exists to require return-value explanation.

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 page, per_page, and parent_id (including the 'root' literal). The description's mention of parent filtering adds no syntax or meaning beyond what the schema provides.

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

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

States a specific verb ('List') and resource ('media library folders') plus the filtering capability. However, it doesn't differentiate itself from the sibling get_folder (single-folder retrieval) or explain why an agent would pick this over list_media.

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?

'optionally filtered by parent' implies the hierarchical browsing use case, but there is no explicit when-to-use guidance and no sibling alternatives (e.g., get_folder for a single folder) are named. Usage must be inferred.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that results are paginated and that it mirrors GET /api/v1/media, but says nothing about ordering, total counts, rate limits, or what each item contains; with annotations doing the heavy lifting this is an adequate but not rich 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?

Three short sentences, front-loaded with the core action, followed by filters and then the usage cue. The trailing 'Mirrors GET /api/v1/media' is low-value for an agent but cheap, so it is close to optimal without being perfectly trimmed.

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 list tool with full schema coverage and no output schema, the description covers purpose, filters, pagination and the downstream use case (finding UUIDs). It omits any hint of the response shape or result ordering, a minor gap given the absence of an output schema.

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

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

Schema description coverage is 100%, so every parameter (page, type, search, per_page, folder_id) is already documented, including defaults, ranges and the 'root' literal. The description restates three of the filters but adds no syntax or edge-case meaning beyond the schema, 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?

The description names a specific verb and resource ('List/search the account's media library') and states the paginated scope plus the filters available, which clearly separates it from the single-item get_media sibling. It stops short of explicitly contrasting itself with list_folders/list_tags/list_streams, so an agent must infer the sibling boundaries.

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

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

'Use this to find media UUIDs for queue tools' gives a concrete downstream context for when to call it, which is genuinely actionable routing guidance. There are no exclusions or named alternatives, so it falls short of a 5.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so safety is covered. The description adds genuinely new behavioral information beyond that: sort order ('newest first'), pagination behavior, and that the response carries meta/links — details an agent would otherwise have to discover empirically.

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

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

Three short sentences, front-loaded with the core action and scope, followed by response/pagination behavior and the underlying endpoint. Every sentence carries information an agent or developer can act on; nothing is 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 usefully compensates by noting that meta/links pagination data is returned. For a zero-required-parameter list tool this is close to complete; the only notable omission is routing guidance relative to the many list_*/get_*/show_* siblings.

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

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

Schema description coverage is 100%, with both page and per_page documented including ranges and defaults, so the schema carries the parameter burden. The description only implies pagination semantics ('paginated', meta/links) without adding syntax or format detail, 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 and resource ('List the streams') plus scope ('owned by the account') and ordering ('newest first'), which is more than a bare restatement. It does not, however, distinguish itself from siblings like get_stream or show_streams, which an agent could reasonably confuse with this one.

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

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

There is no when-to-use or when-not-to-use guidance. The phrase 'owned by the account' implicitly scopes the tool, but nothing tells the agent when to prefer list_streams over get_stream, show_streams, or the other list_* siblings, and no prerequisites are stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds useful context that this mirrors GET /api/v1/tags, but says nothing about pagination, result size, or ordering.

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

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

A single short sentence with a parenthetical and an API reference, front-loaded with the verb and resource. No filler, though the 'Mirrors GET /api/v1/tags' clause is marginally useful only to API-aware agents.

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

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

For a zero-parameter read-only list tool with no output schema, annotations carrying the safety profile and a clear resource statement, the description is nearly sufficient. It could note the return shape or pagination, but little is genuinely missing.

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

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

The tool takes zero parameters, so the schema baseline of 4 applies; nothing in the description is needed to explain inputs, and none is provided.

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

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

States a specific verb (List) and resource (tags), and the parenthetical clarifies what tags are for (organizing streams). It does not explicitly contrast itself with sibling list_* tools, but the resource name is unambiguous enough to distinguish it from list_folders, list_media, etc.

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

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

Usage is implied by the purpose: enumerate the account's tags. There is no statement of when to prefer this over create_tag/update_tag/delete_tag, nor any preconditions or exclusions. Adequate but with a clear gap.

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, idempotentHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description adds the meaningful precondition that the destination folder must be owned by the caller, plus an endpoint mapping, but says nothing about partial failure, overwrite semantics, or the effect on source folders.

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 compact sentences with the core operation and its key constraint front-loaded; nothing is padded or repeated for filler.

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

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

For a two-parameter mutation tool whose annotations carry the safety profile and whose schema fully documents inputs, the definition is essentially sufficient. It leaves only minor operational details (partial-failure behavior, whether files are removed from their previous folder) unstated, and there is no output schema to explain.

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

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

Schema description coverage is 100%, so both parameters are fully documented in the schema, including the root default and the maxItems=100 constraint. The description restates the same 'up to 100' and 'folder_id omitted' facts rather than adding new meaning, 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 ('move media files') plus scope constraints: the 100-file cap and the root-vs-folder destination behavior. No sibling tool performs a move, so the definition is unambiguously distinct without needing to name an alternative.

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

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

The 'or to the library root when folder_id is omitted' clause tells the agent which destination applies, which implies when to use it. However, there is no explicit when-not guidance, no mention of prerequisites beyond ownership, and no comparison to sibling tools like update_media or create_folder.

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

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

Annotations declare a destructive, non-read-only, open-world mutation, and the description adds real context beyond them: it 'requests a change to live output', repeating the command can restart the item, and the 202 'acknowledges an asynchronous request, not confirmed playback'. That async/non-confirmation nuance is exactly the kind of behavioral disclosure an agent needs and cannot get 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?

Purpose is front-loaded, followed by behavioral caveats, the prerequisite for item_id, and the underlying API semantics. Every sentence carries distinct information with no filler.

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

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

For a mutation tool with no output schema, the description is complete: it covers purpose, preconditions, live-output side effects, repeat behavior, and explicitly explains that the 202 is an async acknowledgment rather than confirmed playback. An agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds provenance for item_id ('Get item_id from get_stream_queue'), telling the agent where the identifier comes from rather than just that it exists. This is a meaningful addition over the schema text.

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

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

The description states a specific verb+resource: 'Jump to a playable item already in an active stream queue, starting it from the beginning without restarting the stream.' It clarifies the scope (must already be in an active queue) and the key behavioral distinction (playing from start vs restarting), which separates it from skip/reorder 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?

It implies the precondition (item must already be in an active stream queue) and points to get_stream_queue for obtaining item_id, giving usable context. However, it never explicitly contrasts with siblings like skip_stream_queue or reorder_stream_queue, so the 'when to use this vs alternatives' decision 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 destructiveHint=true and readOnlyHint=false, so permanence is expected; the description reinforces 'Permanently' and adds two non-obvious preconditions (stop live streams, disconnect connected destinations) that the annotations do not convey. It stops short of describing failure modes or whether the operation is recoverable.

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, each earning its place: action, precondition, and API mapping. The most important information (permanent removal plus prerequisites) is front-loaded.

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

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

For a two-param destructive tool with no output schema this is complete: what it does, what must happen before calling it, and which endpoint it mirrors. Nothing needed 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?

Schema coverage is 100% with both UUID parameters documented in-schema. The description only echoes them implicitly via the REST path '(streams/{stream}/destinations/{destination})', adding endpoint-mapping context but no new meaning about the identifiers.

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 ('Permanently remove'), a specific resource ('multistream destination'), and the containment scope ('from a stream'). This clearly distinguishes it from add_destination and update_destination 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 concrete preconditions: live destinations must be stopped first, and connected destinations must be disconnected in the dashboard. It does not name an alternative tool or explain when to prefer update_destination instead, but the operational gating 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 destructiveHint=true, openWorldHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real value beyond them: it scopes the destruction ('The media file itself is not deleted') and warns of a live side effect ('Queue changes can affect live output') that the annotations do not 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?

Three tight sentences, zero filler, with the identification semantics front-loaded before the caveats and the endpoint reference last. Every sentence carries distinct information.

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

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

For a 3-parameter mutation tool with full schema coverage, existing annotations and no output schema, nothing an agent needs is missing: the identifier ambiguity, the non-destructive-to-file guarantee, and the live-output risk are all stated.

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 and the schema already documents all three parameters. The description goes further by explaining that mediaId is a media UUID for storage queues but a queue item id for external-videos, adding meaning the schema description does not supply.

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 ('Remove one item from a stream queue by its id') and immediately disambiguates the ambiguous identifier semantics per queue type. It also names the underlying endpoint, so an agent can distinguish this from delete_media at a glance.

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

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

The line 'The media file itself is not deleted' implicitly routes the agent away from delete_media, and 'Queue changes can affect live output' signals the operational context. But it never explicitly states when to use this versus skip_stream_queue or play_stream_queue_item, nor any prerequisites, so usage is only implied.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is covered structurally. The description still adds real operational context beyond that: that changes can affect live output, and that the call replaces the entire existing order rather than merging into it.

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

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

Two sentences, purpose front-loaded, and the live-output warning follows immediately. The trailing 'Mirrors PATCH /api/v1/streams/{stream}/queues/{type}/reorder' is REST trivia that an MCP agent cannot act on, so it does not fully earn 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 3-required-param mutation with no output schema, the definition covers what is replaced and the live-output consequence, which is the essential context. It omits error behavior when ids are stale or the list is partial, and any permission requirements, but nothing critical for correct invocation 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%, including an enum breakdown of every queue 'type' value, so the schema does the heavy lifting. The description's only added nuance is 'full ordered list', which reinforces the replacement semantics of 'order' but adds no format, id-validity, or completeness rules beyond the schema.

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

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

States a specific verb and resource ('Replace a stream queue's playback order') and qualifies the input as a 'full ordered list of item ids', which implicitly separates it from the incremental add_to_stream_queue / remove_from_stream_queue siblings. An agent can tell replace-semantics from append/remove-semantics 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?

The description never says when to choose this tool over add_to_stream_queue, remove_from_stream_queue, or play_stream_queue_item, nor does it state prerequisites such as whether the queue or stream must be active. 'Queue changes can affect live output' is a caution, not usage 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?

Annotations already declare destructiveHint=true and readOnlyHint=false; the description goes further by specifying immediacy, bulk scope ('every active ticket'), the concrete failure mode for stale callers (401), and the recovery path. It omits whether in-flight uploads are cancelled or whether the revocation is reversible, which keeps it from a 5.

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

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

Three short sentences, front-loaded with the action and scope, then the consequence, then the remedy. Every sentence carries distinct information; nothing is redundant 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 zero-parameter, destructive, account-wide operation with annotations covering the safety profile and no output schema, the description supplies everything an agent needs: scope, effect timing, downstream consequence, and how to recover.

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?

Zero parameters, so per the rubric the baseline is 4. The description involves no parameter semantics to explain, and none are needed.

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

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

Specific verb (revoke) plus precise resource and scope (every active upload ticket for this account), which cleanly separates it from create_upload_ticket and delete_media. It even anchors to the REST endpoint it mirrors, so an agent knows exactly what operation this is.

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

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

Clear context: use this to invalidate all outstanding tickets, and 'create a new ticket to resume' points the agent to the create_upload_ticket sibling for the follow-up path. No explicit when-not-to-use or bulk-vs-single alternatives are given, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, covering the safety profile. The description adds useful context (interactive overview with statuses, pagination, and builder links), but discloses no auth requirements, return format beyond links, or navigation behavior.

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

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

Two tight sentences, the primary purpose front-loaded and the sibling relationship stated second. No filler, though the second sentence introduces slight tension with the first rather than fully resolving it.

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 tool with a full-coverage schema and annotations carrying the safety profile, the description covers purpose, content, and the sibling relationship adequately. It could clarify whether this is a UI-only view versus a data endpoint, but no critical invocation detail 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%, so page and per_page are already documented with defaults and range. The description only alludes to 'pagination' and adds no syntax or semantics beyond the schema; baseline 3 is appropriate.

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

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

The description names a specific verb and resource ('Open an interactive overview of your Upstream streams') and lists what the view contains (statuses, pagination, links). It also relates itself to a sibling by noting it returns 'the same account-scoped data as list_streams.' The split between 'open an overview' (UI-like) and 'returns data' leaves the exact nature slightly ambiguous, so it falls short of a clean 5.

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

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

It references list_streams as an equivalent-data alternative, which hints at a routing decision, but never states when to prefer this tool over that one or over get_stream. Usage is implied rather than instructed.

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 openWorldHint=true, so the bar is lower, yet the description still adds real value: it explains the 202 means an asynchronous request was accepted, not confirmed playback, and that repetition advances again. It stops short of saying what happens to the currently playing item or whether auth/permission is needed.

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 compact sentences, front-loaded with the behavior before the API-level detail. The endpoint-mirroring clause is marginally incidental for an agent, but the async/202 sentence that follows it is high value.

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

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

With no output schema, the description correctly carries the async semantics and ordering behavior. It is nearly complete for a 2-parameter tool, leaving only error/precondition behavior on a non-active stream unspecified.

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 genuine meaning for the 'type' enum by noting that 'video' and 'external-videos' share the video player, which is not captured by the schema's flat enum list.

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 (skip) and resource (item on an active stream) plus the key constraint 'without restarting it'. This clearly separates it from siblings like get_stream_queue and add_to_stream_queue/remove_from_stream_queue, which manipulate the queue rather than advancing playback.

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?

'On an active stream' establishes the precondition, and 'repeating the command can skip another item' tells the agent it is re-invokable to advance multiple times. It does not name an alternative (e.g. play_stream_queue_item for jumping to a specific item) or state what to do when the stream is inactive, so it stops short of explicit alternatives.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and openWorldHint=true, so the mutating/outbound nature is covered. The description adds value beyond that by disclosing the plan/trial authorization gate and the specific 403 rejection behavior, though it does not say whether an already-live stream errors or is idempotent.

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

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

Two short sentences, fully front-loaded with the action first, then the constraint and endpoint reference. No filler or redundancy.

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

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

For a single-parameter action with no output schema, the description covers the action, the authorization constraint, and the underlying endpoint, with annotations carrying the safety profile. Slightly incomplete on success semantics and idempotency 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?

Only one parameter ('stream') and the schema already documents it at 100% coverage as 'Stream UUID.' The description adds no format, sourcing, or lookup guidance for that identifier, 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 ('Start') and resource ('broadcasting a stream to its platform'), making it immediately distinguishable from siblings like stop_stream, create_stream, or update_stream. The REST endpoint mirror (POST /api/v1/streams/{stream}/start) further pins down the exact operation.

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 precondition and failure mode: rejection with 403 when the plan/trial does not permit streaming. This tells the agent when the call will fail, but it does not explicitly contrast with stop_stream or state when a stream must already exist/is in a stoppable state.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered; the description goes further by disclosing the user-visible consequence (live viewers are interrupted) and a required confirmation step. It does not cover reversibility or any state side effects, so not a 5.

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

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

Two short sentences, zero padding, with the action and its impact front-loaded before the caution and the REST mapping. Every sentence earns its place.

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

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

For a one-parameter mutation with annotations and no output schema, the description supplies the essentials: what it does, the blast radius, and the confirmation caveat. Missing only return/status behavior, which is a minor omission here.

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% for the single 'stream' parameter, so the schema already documents it fully and the baseline is 3. The description only echoes the parameter via the REST path template and adds no format or lookup detail beyond UUID naming.

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 ('Stop a running stream') and adds the meaningful qualifier that it interrupts a live broadcast, which distinguishes it from the neighboring delete_stream and start_stream. It does not name those siblings explicitly, so it falls short of a 5.

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

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

Gives one genuine usage constraint — confirm with the user before stopping a live stream — which is real guidance. However, it never says when to choose stop_stream versus delete_stream or how it relates to stream lifecycle/start_stream, so the alternative-selection guidance is only implied.

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

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

With annotations already declaring destructiveHint=true, idempotentHint=true, and openWorldHint=true, the bar is lower, yet the description still adds real value: it clarifies that only provided fields change (partial PATCH, not full replace) and that certain live and lifecycle changes are rejected by the API. It stops short of saying what is destroyed or what permissions are needed, so it is not a 5.

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

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

Three tight sentences, front-loaded with the core PATCH semantics before the capability list and the API restriction. Slightly dense, but no sentence is wasted and the endpoint reference is placed last where it belongs.

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

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

For an 8-parameter mutation tool with no output schema but full annotation coverage, the description supplies the key behavioral context an agent needs: partial-update behavior, side effects, and API-imposed restrictions. It omits any indication of the response shape or error behavior, which is the only notable hole.

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 every parameter is already documented in the schema and the baseline is 3. The description contributes only the general 'only provided fields change' rule plus a hint that 'name' can be synced from a connected platform; it adds no per-parameter meaning beyond the schema.

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

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

The description names a specific verb and resource ('Partially update a multistream destination') and even cites the underlying operation ('Mirrors PATCH /api/v1/streams/{stream}/destinations/{destination}'), which makes the read-modify semantics unambiguous. The word 'partially' implicitly separates it from add_destination and remove_destination, but no sibling is named outright.

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 lists what the tool can do ('overwrite settings, change scheduled output, pause a destination or sync a connected platform's title') but never states when to prefer this over add_destination, remove_destination, or update_stream. The note that live configuration and connected-destination lifecycle changes are API-restricted is a useful constraint, but it is a limitation rather than routing guidance.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is carried structurally. The description only adds the root-move semantics and an endpoint pointer, and it never explains why the operation is flagged destructive (e.g., effect on contained files/subfolders) – a meaningful gap for a flagged-destructive mutation.

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

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

A single front-loaded sentence covers both behaviors efficiently. The trailing 'Mirrors PATCH /api/v1/folders/{folder}' is mildly redundant but short and provides an API mapping for agents that reason over REST endpoints.

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 three-parameter mutation with full schema coverage and complete annotations, the description covers the essential operations and the null-parent case. It is nearly complete, with the only real omission being the downstream effect of moving a folder (children/contents), which matters given destructiveHint=true.

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

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

Schema description coverage is 100%, so all three parameters (name, folder, parent_id) are already documented with types and constraints. The description's note that parent_id null moves to root duplicates the schema text 'New parent folder UUID, or null for the root', adding no new semantics.

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

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

States two specific operations on a specific resource: rename and move a folder. The 'move it under another parent' phrasing implicitly separates it from move_files_to_folder (which relocates files) and update_media/update_stream siblings, though no sibling is named explicitly.

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

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

Use is implied by the rename/move verbs, and the parent_id=null-to-root rule is stated, but there is no explicit when-to-use/when-not guidance and no mention of prerequisites (e.g., needing the target parent to exist or permissions).

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, idempotentHint=true, and readOnly=false, so the safety profile is covered. The description adds the partial-update semantic ('Only provided fields change') and mirrors PATCH /api/v1/media/{media}, which is genuinely useful, but it does not explain what is destructive (e.g. tag clearing) or any auth/permission 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?

Two tight sentences: purpose and field scope first, then the update semantic and the underlying endpoint. Every clause carries 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 mutation tool with no output schema, the annotations plus 100% param coverage plus the PATCH mirror leave little missing. It could mention effects on dependent resources or permission requirements, but an agent has enough to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents each field including the null-to-clear behavior and max lengths. The description only restates the field grouping as audio tags, adding little beyond what the schema provides — 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?

States a specific verb and resource ('Update a media file's metadata') and enumerates the editable fields (name plus audio tags). This implicitly separates it from siblings like update_tag and update_stream, though it never names those alternatives explicitly.

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

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

No when-to-use guidance, no prerequisites, and no routing to or away from the many sibling update_* tools. The only usable cue is 'Only provided fields change', which clarifies the update mode but not when to choose this tool.

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

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

Annotations already flag destructiveHint and idempotentHint, so the bar is lower. The description still adds real value: PATCH semantics (only supplied fields change) and explicit warnings that it may overwrite settings/tags and affect live output or scheduled start/stop behavior.

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

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

Single compact paragraph, front-loaded with the core verb and PATCH semantics, then warnings. Every clause carries weight; not padded, though the create_stream cross-reference requires the reader to know that sibling.

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 14-param destructive mutation with nested objects and no output schema, the description covers semantics, side-effect scope, and endpoint parity. It omits auth/permission requirements and return behavior, but annotations plus rich schema cover most of the remaining need.

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

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

With 100% schema description coverage the schema already documents all 14 parameters, so baseline 3 applies. The description adds only a cross-reference ('same fields as create_stream except type'), which gives some semantics but no per-parameter detail.

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 (partially update), resource (a stream), and defines the update style via PATCH semantics. It distinguishes itself from create_stream by noting type is creation-only, but does not differentiate from other update_* 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?

Implies use for modifying an existing stream and cross-references create_stream for the field set, giving useful context. However it never states when to prefer this over alternatives or any prerequisites (e.g., permissions, live-state conditions).

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, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds non-obvious behavioral detail beyond that: it is a PATCH-style partial update where unspecified fields are preserved. It does not explain what makes the call destructive (nulling fields), though the schema covers that.

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

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

Three short, front-loaded sentences with no filler: purpose, update semantics, and API mapping. Every sentence earns its place and the key information (what changes) comes first.

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

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

For a four-parameter mutation tool with full schema coverage and annotations covering the safety profile, no output schema is needed and the description is nearly sufficient. It could mention the uniqueness conflict on name or that null clears fields, but those are already in the 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% (formats for color, max length for name/icon, null-clearing semantics), so the schema carries the parameter burden. The description names three of the four parameters but adds no syntax or constraints beyond what the schema already states.

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

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

The description gives a specific verb (update) plus resource (tag) and enumerates the mutable fields (name, color, icon), so an agent can distinguish it from create_tag and delete_tag. It stops short of explicitly contrasting itself with the sibling update_* tools, but the resource is unambiguous.

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

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

"Only provided fields change" implies partial-update usage, which is genuinely useful guidance, but there is no explicit when-to-use versus delete_tag/create_tag routing or prerequisite information. Usage is implied rather than stated.

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