Upstream.so

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

Annotations only declare destructiveHint=false, so the description must carry the rest. It adds genuinely useful platform-specific key format rules (rtmp://, rtmps://, srt://) and the required-parameter set, but says nothing about auth requirements, idempotency, error behavior, or what happens on failure.

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 purpose then requirements, with no filler. Slightly dense in the parenthetical format clause but every sentence carries information.

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

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

For a 7-param mutation tool with minimal annotations and no output schema, the description covers the required parameters and the non-obvious key format constraint well. The optional params (url, status, include_in_schedule) are left to the schema, which is acceptable given 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 the baseline is 3, but the description adds real meaning beyond the schema: the conditional key prefix rules keyed to platform values (custom/instagram/rumble vs customsrt). The 'max 100' note duplicates the schema but the format rules do not.

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 ('Add') and resource ('multistream destination to a stream'), which clearly separates it from siblings like list_destinations, update_destination, and remove_destination. 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?

No when-to-use or when-not guidance, and no alternatives named. It implies creation context via 'Required:' and the mirrored POST endpoint, but an agent gets no help choosing between this and update_destination or when adding a destination is appropriate.

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

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

The only annotation is destructiveHint=false, so the description usefully adds that this is an append operation mirroring POST /api/v1/streams/{stream}/queues/{type}, plus a hard validation rule (url must end in .mp4). It does not cover idempotency, ordering, limits, or auth requirements, but it adds real behavior beyond the annotation.

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

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

Three tight sentences, front-loaded with the core action, then the format branching, then the endpoint reference. Every sentence carries information an agent needs to construct a correct call.

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 doesn't say what the call returns, which is a minor gap for a mutation tool. Everything else needed to invoke it correctly — type-to-format mapping, validation, UUID source — is present.

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

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely adds meaning: the items format is conditional on type (UUID array vs {url, name} objects), the .mp4 constraint, and the list_media pointer. These go beyond the schema's terse property descriptions.

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

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

States a specific verb+resource ('Append items to a stream queue') and immediately differentiates itself from siblings by spelling out per-queue-type item shapes. An agent can distinguish this from remove_from_stream_queue and reorder_stream_queue 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 conditional guidance: which item format applies to which queue type, and routes the agent to list_media to obtain UUIDs. It stops short of explicit when-not-to-use or naming the alternative siblings (remove_from_stream_queue, get_stream_queue).

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 destructiveHint=false, so the description carries the behavioral burden and largely fails it: no mention of ownership requirements, duplicate-name behavior, idempotency, or side effects. 'Mirrors POST /api/v1/folders' adds an endpoint mapping but no runtime 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 short sentences, front-loaded with the core action and no filler. Every clause earns its place.

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

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

For a simple two-parameter creation tool with a fully documented schema and no output schema, the description covers the essential scope and the parent-nesting option. It is only slightly thin on failure modes and permission requirements, which the schema partially covers via 'must be a folder you own'.

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

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

Schema description coverage is 100% — both name and parent_id are fully documented in the schema, including the ownership constraint and null/omit semantics. The description adds nothing beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (create) and resource (media library folder) plus the optional nesting behavior, so it is clearly distinct from delete_folder, update_folder, get_folder and list_folders. It stops short of naming any sibling explicitly, which keeps it from a 5.

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

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

The description says what the tool does but gives no when-to-use guidance, no prerequisites (e.g. auth/ownership needed to create), and no routing to alternatives. The only usage signal is the incidental note that nesting is optional.

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

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

With only destructiveHint=false in annotations, the description carries real weight and delivers: it specifies required inputs, key-format constraints per platform (rtmp/rtmps/srt), that optional setting groups default sensibly, and that status is externally managed. It stops short of describing return shape or error behavior, but adds substantial context beyond the annotation.

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

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

Requirements and the request-mapping are front-loaded, and the sentences are dense but purposeful. Some key-format detail duplicates the schema, which costs a bit of efficiency, but it is well organized overall.

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

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

For a 14-parameter tool with nested objects and no output schema, the description covers the critical creation constraints, default behavior of optional groups, and lifecycle separation. It does not enumerate every optional group (schedule, url, type), but the schema covers those, so nothing decisive 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 the schema already documents every parameter in detail. The description largely restates schema content (key format rules, platform values) rather than adding new meaning, so the baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource ('Create a stream') and grounds it against the API surface ('Mirrors POST /api/v1/streams'). It also delineates the lifecycle boundary by noting status is managed by start_stream/stop_stream, which separates it from those siblings, though it does not explicitly contrast with update_stream vs this creation path.

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

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

Gives clear operative context: name and platform are required, a key is needed unless platform is none, and status is handled elsewhere. It also hints that platform 'none' exists to add a destination later. It stops short of explicit when-not-to-use or a direct alternative tool name for creation scenarios.

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 destructiveHint=false, so the description carries most of the burden. It does disclose a genuine behavioral constraint (name uniqueness within the account) and maps the operation to POST /api/v1/tags, but says nothing about what happens on duplicate names, required auth/permissions, or the response.

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, zero filler, with the action stated first and the key constraint immediately after. Every sentence carries information.

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

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

For a simple three-parameter create tool with no output schema and full schema coverage, the description plus schema gives an agent enough to call it correctly. The main omission is failure behavior on duplicate names and required permissions.

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% (icon, name, color all documented with formats and maxLength), so the baseline is 3. The description restates the name uniqueness rule already present in the schema, adding no new parameter meaning.

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

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

States a specific verb and resource ('Create a tag'), which cleanly separates it from update_tag, delete_tag, and list_tags in the sibling set. It does not explicitly name those siblings, but the verb makes the intent unambiguous.

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

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

No guidance on when to create a tag versus reusing an existing one, no prerequisites, and no reference to alternatives such as list_tags for checking existing names. The uniqueness rule hints at a workflow but is not framed as usage guidance.

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

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

Annotations only declare destructiveHint=false, so the description carries the real burden here. It discloses the 24h token lifetime, that new tickets renew the token family without revoking in-flight uploads, and the revoke path. Missing only details like rate limits or token scope boundaries, but the key behavioral traits are well 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?

Tight, front-loaded sentences: purpose first, then ticket semantics, then lifecycle routing to revoke_upload_tickets and the API mirror. 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 single-param creation tool with no output schema, the description covers what it produces, ticket lifetime, batch reuse, and the companion revoke tool. Adequate and well-rounded; would need only minor additions like auth requirements to reach the top tier.

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 folder_id param is fully documented in the schema, including the Folder-Id header re-send requirement. The description adds no param detail but the schema does the work; slightly above baseline for the header hint being surfaced in 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+resource ('Start a media upload: mints an upload ticket') and specifies the concrete artifact produced (TUS endpoint + 24h bearer token). Distinguishes clearly from siblings and cites the mirrored API endpoint.

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

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

Explicit guidance: use any TUS 1.0.0 client, reuse one ticket for a batch when practical, and calls out revoke_upload_tickets for immediate invalidation. The token-family renewal behavior when creating new tickets is clearly stated, which routes the agent appropriately.

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

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

Annotations only supply destructiveHint=true, so the description carries real added weight: it discloses that subfolders are deleted recursively while contained files survive by moving to the library root, plus permanence. It omits permission requirements and whether confirmation/recovery is possible, keeping it short of a 5.

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

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

Three tight sentences: the destructive action is front-loaded, the cascade consequence follows, and the API mapping is a useful trailing detail. No filler.

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

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

With no output schema and a single well-documented parameter, the description covers the essential semantics of a destructive recursive operation. Missing auth/permission notes and any indication of failure modes prevent a 5.

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

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

There is a single parameter ('folder') with 100% schema description coverage ('Folder UUID.'), so the schema already does the work. The description adds no format or identification detail beyond the schema, making the baseline 3 correct.

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') and distinguishes itself from the many sibling delete_* tools by naming the exact object type. The cascade semantics make the scope unambiguous.

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

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

Usage is implied rather than stated: the word 'Permanently' signals irreversibility, but there is no explicit when-to-use/when-not guidance and no pointer to alternatives such as update_folder, move_files_to_folder, or get_folder. An agent must infer that this is the terminal removal path.

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

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

Annotations already declare destructiveHint=true, so the safety profile is covered. The description adds genuinely new behavioral context: the deletion is permanent and the file vanishes from any queues that reference it, which an agent could not infer from the annotation alone. It stops short of stating auth requirements or response behavior.

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

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

Three short sentences, front-loaded with the action and its permanence, then the cascade effect, then the API mapping. Nothing is redundant 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?

For a one-parameter destructive tool with no output schema, the description covers the key risk (irreversibility) and the side effect (removal from referencing queues). It omits permission/auth requirements and confirmation expectations, which are the remaining gaps for a delete operation.

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

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

Schema description coverage is 100% and the single 'media' parameter is documented as a storage UUID in the schema. The description adds no format, sourcing, or lookup guidance 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 ('Permanently delete') and resource ('a media file from the library'), and the resource noun cleanly separates it from sibling deletes like delete_folder, delete_stream, and delete_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 framing ('Permanently', 'Irreversible'), which signals caution, but there is no explicit when-to-use guidance, no prerequisites, and no named alternative (e.g., update_media to modify metadata instead of deleting).

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

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

Annotations already declare destructiveHint=true, so the safety profile is partly covered. The description adds real value on top: 'Permanently', 'Irreversible', and the fact that the stream's configuration is destroyed alongside it — details an agent needs before calling and that the annotation alone does not convey.

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

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

Three short sentences, zero waste, with the destructive/permanent nature front-loaded right after the purpose statement. Nothing is padded or repeated.

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, the description covers purpose, irreversibility, and the underlying REST semantics. It is essentially complete; the only gap is the absence of guidance on alternatives such as stop_stream.

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 a single documented 'stream' UUID parameter, so the schema does the heavy lifting. The description adds nothing about the parameter (e.g., format, whether it accepts names or IDs only), 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 (delete) and resource (stream), and scopes it further as 'and its configuration', which distinguishes it from sibling deletions like delete_media, delete_folder, and delete_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?

The description implies usage (permanent removal of a stream) but never states when to choose this over alternatives such as stop_stream, update_stream, or the other delete_* tools, nor does it name any prerequisite. Usage is inferable from the verb, which is the minimum viable level.

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 the description goes beyond that by spelling out the blast radius: deletion is permanent, streams continue functioning but lose the tag association. It also maps to the underlying DELETE endpoint. It stops short of stating required permissions or whether the tag can be re-created.

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, zero filler, with the permanence/destructiveness front-loaded before the reassuring side-effect note and the endpoint 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 destructive tool with no output schema, the description covers what is destroyed, what survives, and the API contract. Missing only the error/permission behavior an agent might want before committing to an irreversible call.

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% ('Tag id.'), so the single parameter is already documented. The description adds only the mirrored REST path /api/v1/tags/{tag}, which subtly confirms the value is a tag identifier rather than a name. 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 ('Permanently delete a tag') and the resource name uniquely separates it from the many other delete_* siblings (delete_folder, delete_media, delete_stream). An agent needs no schema inspection to know what it does.

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

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

Usage is implied by the destructive verb, but the description never states when to use this versus update_tag (modify) or list_tags, and offers no prerequisites or exclusions. Adequate but with a clear gap in 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 readOnlyHint and idempotentHint, so safety is covered. The description adds the set of returned fields, which is useful since no output schema exists, but says nothing about auth requirements or what 'limits' means. With annotations carrying the safety profile, this is adequate but thin.

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 waste, with the resource and returned fields front-loaded. Nothing is redundant or 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?

For a zero-param read tool with no output schema, the field enumeration gives an agent enough to know what comes back. Minor gap: it doesn't clarify the shape/type of 'limits' or the plan representation, but nothing blocking.

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 the baseline is 4. The description correctly implies the account is selected implicitly by the caller's credentials rather than by an argument, which is the only semantic an agent needs 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 (authenticated account) and enumerates the returned fields (id, name, email, plan, limits). No sibling tool covers accounts, so it is unambiguously distinct from the folder/stream/media/tag tools.

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: 'authenticated account' signals the current user's own record and there are no alternatives to disambiguate against. It never states when an agent should call this versus, say, listing streams, though the purpose is self-evident.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description's only addition is mapping to the REST endpoint GET /api/v1/folders/{folder}. It says nothing about what happens on a missing/invalid UUID or what the folder payload 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?

Two short sentences, front-loaded with the core action. The REST-endpoint mirror sentence is low-value filler but costs little.

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 single-parameter read, this is nearly adequate, but with no output schema the description omits any hint of the returned folder shape or failure behavior. Adequate, with visible 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% for the single parameter (folder UUID), and the description's 'by UUID' merely restates that. Baseline 3 applies when the schema already documents the parameter.

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 (folder) with a clear singular scope, which implicitly separates it from the sibling list_folders. It does not explicitly name that sibling or any differentiating condition, so it lands just 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?

No guidance on when to use this versus list_folders or the other get_* siblings, and no prerequisites or error conditions mentioned. The only usage signal is the implicit single-vs-many distinction.

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 readOnlyHint=true, so the description adds real behavioral value: it discloses that the field is_processing gates downstream queue usability and describes a polling pattern. It surfaces that processing state is part of the return, which the agent couldn't infer from annotations alone.

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

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

Three tight sentences: identity of the resource, the polling workflow, and the endpoint mapping. The most actionable constraint (polling until processed) is front-loaded, and nothing is redundant.

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

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

For a one-parameter read with no output schema, the description covers the key return field (processing state) and the operational trigger for calling it. There is no gap an agent needs filled to call this correctly.

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

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

Schema description coverage is 100% and the single parameter is already documented as the storage UUID, so the schema does the heavy lifting. The description's 'by UUID' reinforces but adds no syntax or format detail beyond it, matching the baseline of 3.

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

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

States a specific verb and resource ('Get one media file by UUID') and names the returned scope ('including its processing state'), which cleanly separates it from sibling list_media. 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?

Gives explicit workflow guidance ('After an upload, poll this until is_processing is false') and a precondition for downstream use ('only usable in queues once processed'). It doesn't name list_media as the alternative for enumerating media, so it stops short of full 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 readOnlyHint=true and idempotentHint=true, so the safety profile is covered without description help. The description adds the REST endpoint equivalence (GET /api/v1/streams/{stream}) and the set of fields returned, which is modest supplementary context but discloses no error behavior, auth requirements, or lookup-failure semantics.

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

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

A single compact sentence front-loads the action and identifier, then lists the payload contents before the endpoint mapping. No filler or redundancy; every clause carries information.

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

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

With no output schema, the description compensates by naming the fields the response carries (settings, status, tags, destinations), and the annotations cover the read-only/idempotent profile. For a one-parameter read tool this is sufficient for correct invocation.

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

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

Schema description coverage is 100% and the single parameter is documented as 'Stream UUID.' The description reinforces the UUID-based lookup, adding a little meaning over the schema, but contributes no format, validation, or sourcing details. Baseline 3 is appropriate 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?

States a specific verb and resource ('Get one stream by UUID') and enumerates the returned fields (settings, status, tags, destinations), so the agent knows exactly what this retrieves. It does not explicitly name the contrasting sibling (list_streams, get_stream_queue), but 'one stream by UUID' implicitly distinguishes it from listing tools.

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: use it when you have a single stream UUID and need its details, rather than list_streams for enumeration. However, the description gives no explicit when-to-use guidance, no prerequisites, and does not name alternatives such as get_stream_queue, so the agent must infer the routing decision.

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?

readOnlyHint=true in annotations already establishes this as a safe read, so the description only needs to add context. It adds one useful behavioral detail ('ordered items'), implying return ordering, but says nothing about pagination, queue size limits, or what happens for an empty queue. Some added value over the annotation, but thin.

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 no filler, and the core purpose is front-loaded before the REST endpoint mapping. The endpoint reference is marginally redundant with the tool name but useful for agents cross-referencing API docs.

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

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

This is a simple two-parameter read with full schema coverage, so little is required. However, with no output schema, the description never indicates what a queue item looks like (id, position, media reference), which is the main missing piece for an agent consuming the result.

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

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

Schema description coverage is 100%, with the enum values and the stream UUID fully documented in the schema. The description adds no format, constraint, or default information beyond what the schema already provides, so the baseline of 3 applies.

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

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

States a specific verb and resource: 'Get the ordered items of one of a stream's media queues', which is clearly distinct from the sibling write operations (add_to_stream_queue, remove_from_stream_queue, reorder_stream_queue). It does not explicitly contrast against read siblings like get_stream or list_media, but the scope 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?

Usage is implied by the name and the endpoint mapping ('Mirrors GET /api/v1/streams/{stream}/queues/{type}'), but there is no explicit statement of when to prefer this over get_stream or list_media, and no preconditions or exclusions. Adequate but leaves selection to inference.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered structurally. The description adds no behavioral context beyond that — no pagination, no ordering, no scope limits (e.g., whether inactive streams return anything) — so it earns little credit for 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?

Two compact sentences with the core purpose front-loaded and no filler. The endpoint-mirroring sentence is arguably redundant for an agent, keeping it just below a 5.

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

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

For a simple one-required-param read tool this is minimally adequate. Since there is no output schema, the description could have described the returned destination shape or list behavior, which it does not.

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% (the single 'stream' param is documented as a Stream UUID), so the schema carries parameter meaning. The description implies the stream parameter but adds no format or constraint detail beyond it. 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 (List) and resource (a stream's multistream destinations), and the parenthetical clarifies what a 'destination' is, disambiguating it from unrelated list_* siblings. It stops short of naming the sibling it complements (add_destination/remove_destination), so a 4 rather than 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?

No when-to-use guidance or alternatives are given. The only positional cue is 'Mirrors GET /api/v1/streams/{stream}/destinations', which is an implementation mapping, not selection guidance. Given three sibling destination-mutating tools, an agent gets no explicit routing help.

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

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

The readOnlyHint annotation already establishes that this is a safe read, so the description's burden is lower. It adds that results can be scoped by parent and maps to GET /api/v1/folders, but says nothing about pagination behavior or what a result set 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?

Two short clauses, front-loaded with the purpose and zero filler. The trailing REST-endpoint mapping is marginally useful for parity checks but not essential.

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?

Read-only safety is covered by annotations and all three params are schema-documented, so the core is intact. With no output schema, a note on the shape of the returned folder list and how pagination interacts with parent filtering would have closed the remaining gap.

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

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

Schema description coverage is 100%, so page, per_page, and parent_id are all documented in the schema, including the 'root' literal. The description adds only the 'optionally' qualifier on parent filtering, meeting the baseline for schema-covered parameters.

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

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

States a specific verb and resource ('List media library folders') plus the filtering capability, which is enough to distinguish it from create_folder/delete_folder/update_folder. It stops short of explicitly contrasting with the closely related get_folder (single item) sibling.

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 browse-vs-drill-down use case, and the REST endpoint mapping hints at read semantics. However, there is no explicit when-to-use guidance or statement of when get_folder would be preferred over this list call.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds the paginated listing behavior and the filter semantics on top. It still doesn't disclose ordering of results or the shape of returned media entries, which matters since no output schema exists.

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

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

Three tight sentences that front-load the core action and end with a useful API mapping. Every sentence carries information, though the REST-endpoint mirror line is slightly lower value than the rest.

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 five-parameter read-only listing tool with full schema coverage and no output schema, the description covers filters, pagination, and the downstream use case. It stops short of describing returned fields or ordering, which is the only meaningful gap.

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

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

Schema description coverage is 100%, so page, per_page, type, search, and folder_id are already documented in the schema. The description restates the type/search/folder filters without adding format details or defaults beyond what the schema 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 ('List/search the account's media library') plus the paginated scope, which cleanly separates it from the get_media sibling that fetches a single item. The closing note that it 'Mirrors GET /api/v1/media' removes any ambiguity about what the tool wraps.

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

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

Gives an explicit purpose: 'Use this to find media UUIDs for queue tools,' which tells the agent exactly when this tool is the right entry point. It lacks an explicit when-not or a named alternative (e.g., versus get_media or list_folders), so it falls just 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 and idempotentHint, so the safety profile is covered. The description adds real context beyond them: ordering (newest first), pagination via meta/links in the response, and a note that it mirrors GET /api/v1/streams, which helps an agent reason about parity with the REST API.

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, zero filler, with the core action and ordering front-loaded before the pagination and endpoint-parity notes. Every sentence carries information.

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

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

For a simple two-param read tool with annotations covering the safety profile, the description covers ordering, pagination behavior, and response shape (meta/links), so no output schema is necessary. Minor gap: no guidance on what happens with out-of-range page values or total count, but nothing essential is missing.

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

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

Schema coverage is 100% and both parameters (page, per_page) are documented with defaults and ranges in the schema itself. The description only references pagination generically, adding nothing about parameter syntax or values beyond what the schema 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 names a specific verb and resource ('List the streams'), plus scope ('owned by the account') and ordering ('newest first'). The resource noun cleanly distinguishes it from sibling list tools like list_media, list_tags, and list_folders, and from get_stream.

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

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

Usage is implied by the description's enumerative framing, but there is no explicit statement of when to prefer this over get_stream or the other list_* tools, and no exclusions or prerequisites given. Minimum viable 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 readOnlyHint and idempotentHint, so the safe-read profile is covered. The description adds the useful REST mapping (GET /api/v1/tags) but says nothing about pagination, ordering, or result size, which is the kind of extra context that would raise this score.

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 plus a REST mapping note; every clause carries information and there is 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 no-parameter, read-only list tool with annotations covering safety, this is nearly complete. The only missing element is any indication of return shape or pagination, which matters slightly more since no output schema exists.

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 baseline of 4 applies. There is nothing for the description to clarify beyond what the empty schema already conveys.

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). Siblings like list_streams/list_folders are distinct by resource, but the description never explicitly differentiates itself from them, so it stops short of a 5.

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

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

No when-to-use or when-not-to-use guidance. It never says whether this is the right call for enumerating tags versus looking up a single tag, nor does it mention any prerequisites. Usage is only implied by the verb.

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 idempotentHint=true and destructiveHint=false, so safety is covered. The description adds real value beyond them: the 100-file batch limit, the ownership requirement on both the folder and the moved media, and the mapping to POST /api/v1/folders/move-files. It stops short of describing failure behavior for a non-existent or unowned folder_id.

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

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

Two sentences, front-loaded with the action and its limit, with the root-folder fallback immediately after. Every clause carries information an agent needs; 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?

For a two-parameter mutation tool with no output schema and annotations covering idempotency and non-destructiveness, the description is nearly complete. It could say more about how an invalid or unowned folder_id is handled, but the ownership and batch constraints are already spelled 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 description coverage is 100%, so both parameters are already documented, and the description's statement about omitting folder_id essentially restates the schema text. Baseline 3 is appropriate; it adds no syntax or format detail the schema lacks.

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 (Move), resource (media files), destination target (folder owned or library root), and a hard cap (up to 100). No sibling tool performs a move operation, so the agent can immediately distinguish it from create_folder, update_media, or update_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?

The description gives the conditional rule for the optional parameter: omit folder_id (or pass null) to move to the library root. It also signals the ownership precondition on the destination. It does not name an alternative tool, but no sibling competes for this action.

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

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

The destructiveHint annotation already declares this is a destructive operation, so the description's added value is the word 'Permanently', which signals irreversibility beyond the annotation. However, it says nothing about permissions, cascading effects on stream state, or error behavior for missing UUIDs.

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, front-loaded with the action and outcome, with no filler. The REST endpoint mapping is slightly redundant metadata but still useful for orienting 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 simple two-parameter destructive tool with full schema coverage, no output schema, and a destructiveHint annotation, the description covers what is removed, from where, and that it is permanent. Only auth and post-removal state are left unaddressed.

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 'stream' and 'destination' documented as UUIDs, so the schema already carries the parameter burden. The description adds no format or constraint detail beyond that, 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 ('remove') plus resource ('multistream destination') and scope ('from a stream'), which cleanly separates it from siblings like remove_from_stream_queue, delete_stream, and update_destination. The REST endpoint mapping pins down exactly which operation is performed.

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 purpose implies usage, but there is no explicit guidance on when to choose this over update_destination (e.g., removing vs disabling) or any stated prerequisites. An agent can infer the intent from the name, but the description does not route it against 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 only declare destructiveHint=false, so the description carries most of the burden and does well: it clarifies that removal is non-destructive to the media asset and pins the behavior to a concrete REST endpoint (DELETE /api/v1/streams/{stream}/queues/{type}/{mediaId}). It stops short of describing return values or queue-position side effects, but for a single-item removal that is a minor 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?

Two sentences, front-loaded with the action and identifier semantics, followed by the non-deletion clarification and endpoint mapping. No filler.

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

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

With no output schema, the description still covers the key call-time facts: identifier semantics, queue-type meaning, non-destructive scope, and endpoint mapping. Only the response shape and any ordering side effects on the remaining queue are unaddressed, which is acceptable for this operation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine disambiguation beyond the schema by explaining that mediaId is a media UUID for storage queues but an item id for external-videos. That resolves the one ambiguity an agent would otherwise hit when the type enum is 'external-videos'.

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 (remove), resource (item from a stream queue), and the identifier semantics, and explicitly separates itself from deletion of the underlying media file. That distinction is what distinguishes it from sibling delete_media, and the add_to_stream_queue / reorder_stream_queue siblings are implicitly excluded by 'remove one item'.

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

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

The description gives clear context for when the tool applies (removing a single queue entry) and explicitly notes what it does NOT do ('The media file itself is not deleted'), which steers an agent away from delete_media. It does not, however, spell out when to prefer this over reorder_stream_queue or how it interacts with queue 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 idempotentHint=true and destructiveHint=false, so the description need not restate safety. It adds real value by clarifying replace semantics (the supplied list becomes the queue order, and it must be complete) and by mapping to the underlying PATCH endpoint, though it does not say what happens to items omitted from the list.

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 zero filler; the core replacement semantics are front-loaded and the API mapping is secondary. Nothing extraneous.

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, no-output-schema mutation tool with full schema coverage and safety annotations, the description covers purpose and semantics adequately. A brief note on what happens to queue items omitted from the new order would make it 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%, with each parameter (stream, type enum, order) documented in the schema itself. The description only reinforces that 'order' must be the complete ordered list of ids, adding marginal meaning over the schema, so the baseline 3 applies.

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

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

States a specific verb (Replace) and resource (a stream queue's playback order) with the input shape ('full ordered list of item ids'), which clearly separates it from add_to_stream_queue and remove_from_stream_queue. It does not name those siblings explicitly, so it falls just short of a 5.

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

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

The phrase 'full ordered list' implies this is the tool for wholesale reordering rather than incremental add/remove, but there is no explicit when-to-use statement, no when-not-to-use, and no named alternative. 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 only declare destructiveHint=true. The description adds substantial behavioral context: immediate revocation, all active tickets affected, subsequent requests receiving 401, the need to create a new ticket to resume, and that it mirrors DELETE /api/v1/media/uploads. This goes well beyond the annotation.

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

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

Three tightly written sentences, front-loaded with the core action, followed by the effect and the REST equivalent. Every sentence earns its place with no wasted words.

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

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

With no output schema and a simple zero-parameter operation, the description fully covers what the tool does, its immediate effect, and the follow-up action. Nothing an agent needs in order to call it correctly is missing.

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

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

The tool has zero parameters, and schema coverage is trivially 100%. Per the rules, a 0-parameter tool gets a baseline of 4; there are no parameter semantics for the description to add.

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 ('revoke'), resource ('upload tickets'), and scope ('every active upload ticket for this account'). It implicitly contrasts with the sibling create_upload_ticket by saying 'create a new ticket to resume', so an agent can distinguish the two without opening schemas.

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

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

Provides clear context for use: invalidating all active tickets immediately, and that a new ticket is needed to resume. However, it does not explicitly state when to choose this over other deletion tools like delete_media or remove_destination, and offers no 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 only give openWorldHint and destructiveHint=false, so the description's disclosure that the call may be rejected with 403 when the plan/trial disallows streaming is real added value for predicting failure. It stops short of covering idempotency, what happens if the stream is already live, or the response shape.

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, action-first, no filler. Each sentence carries distinct information: what it does, the failure mode, and the API mapping.

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 action tool with no output schema, purpose, failure mode, and endpoint mapping are all present. Only the state transition semantics (already-streaming behavior, return value) are left implicit.

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

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

The schema documents the single 'stream' parameter at 100% coverage (Stream UUID), so the description need not restate it. It adds no format or identifiability detail beyond the schema, matching the baseline for fully-covered params.

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 with scope ('Start broadcasting a stream to its platform'), which cleanly separates it from create_stream, stop_stream, and get_stream. The endpoint mirror (POST /api/v1/streams/{stream}/start) reinforces exactly which 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?

Usage is implied by the verb and the sibling set (start vs stop_stream), and the 403/plan nuance hints when calls fail, but there is no explicit statement of when to pick this over alternatives or any preconditions (e.g. must a stream be configured with destinations first).

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 openWorldHint=true, so the safety profile is covered. The description adds real value beyond that by disclosing the user-visible impact (viewers lose the live broadcast) and the required confirmation step, which annotations cannot convey.

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

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

Three short sentences, each earning its place: the operation, the impact/caution, and the REST endpoint mapping. The critical caution is front-loaded before the API metadata.

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, no-output-schema tool with safety annotations already present, the description covers operation, impact, and the confirmation requirement. It leaves unstated what state the stream enters after stopping (ended vs. resumable) or how it relates to delete_stream, which are minor but real 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?

Only one parameter ('stream', a Stream UUID) and schema description coverage is 100%, so the schema fully documents it. The description adds no syntax or format detail beyond restating the path template /streams/{stream}/stop, which matches the baseline 3 when the schema carries the load.

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 (stop) plus resource (running stream) and adds the state qualifier 'running,' which separates it from start_stream. It doesn't explicitly contrast with the adjacent delete_stream sibling, so an agent must infer that stopping is not deletion, but the operation itself 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?

Provides clear contextual guidance: this interrupts a live broadcast for viewers, and the agent should confirm with the user before stopping a live stream. It stops short of naming alternatives (e.g., delete_stream) or stating when not to call it, but the pre-condition context is genuinely actionable.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, covering the safety profile. The description adds meaningful PATCH semantics ('only provided fields change'), which tells the agent that omitted fields are preserved – a non-obvious behavioral trait. It omits permission requirements and error behavior.

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

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

Two short sentences, front-loaded with the core action and the key partial-update constraint, plus the underlying endpoint. Nothing is wasted.

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

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

With no output schema and full schema coverage, the description is nearly complete for a partial-update mutation. It covers the partial-update contract and safety annotations carry idempotency; only edge cases like null handling (e.g., clearing url) and error behavior are unaddressed.

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 8 parameters are already documented in the schema with types and constraints. The description adds no per-parameter detail beyond the general 'only provided fields change' rule, so the baseline of 3 applies.

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

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

States a specific verb ('partially update') and resource ('multistream destination'), and clarifies the PATCH semantics that only provided fields change. It implicitly distinguishes itself from the add_destination/remove_destination siblings, though it doesn't name them 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 verb – use this to modify an existing destination rather than add or remove one – but there is no explicit when-to-use guidance, prerequisites, or named alternative among the many siblings. Adequate but with clear gaps.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds the partial-update implication (either field can be changed) and the root-move behavior, but says nothing about required permissions or side effects on contained media.

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, front-loaded with the mutating operations and followed by the clarifying root case and API mapping. Every clause carries information; nothing is redundant padding.

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

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

For a simple partial-update tool with full schema coverage and no output schema, the description covers the core behaviors adequately. It only stops short of permissions/effects context that annotations partly compensate for.

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 are already documented in the schema, including the parent_id null-for-root behavior. The description restates that behavior but adds no syntax or format detail beyond structured fields, 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 specific verbs (rename, move) and the exact resource (a folder), and clarifies it operates on the folder itself rather than its contents, which separates it from the sibling move_files_to_folder. 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 operations described, but there is no explicit guidance on when to prefer this over create_folder or delete_folder, and no prerequisites or permission notes. The PATCH endpoint reference gives useful API context but not selection criteria.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing the partial-update contract ('Only provided fields change') and mapping to PATCH /api/v1/media/{media}, though it says nothing about permissions 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?

Two short sentences, zero filler. The subject (what gets updated) is front-loaded and the partial-update qualifier and API mapping follow immediately.

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

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

For a low-risk partial-update tool with full schema coverage and no output schema, the description covers purpose, mutability semantics, and API parity. Return behavior and authorization requirements are the only meaningful gaps, and both are minor for a PATCH-style field updater.

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 already carries its own description, max length, and null-clears semantics. The description lists the same field names without adding format, validation, or clearing rules beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('Update') and resource ('a media file's metadata') and enumerates the affected fields (name plus audio tags title/artist/album/year/genre). The resource scoping clearly separates it from siblings like update_folder, update_stream, and update_tag.

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

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

The description gives clear partial-update context ('Only provided fields change') and the PATCH endpoint it mirrors, which implies usage for incremental edits. However it never states when to prefer this over siblings such as update_tag or update_stream, leaving alternative selection to inference.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context the annotations do not: partial-update semantics (untouched fields are preserved) and the fact that 'type' cannot be modified after creation.

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 compact clauses, front-loaded with the operation and its semantics before the cross-reference and endpoint mirror. 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 14-parameter nested mutation tool with rich schema coverage and no output schema, the description covers operation semantics and field scope adequately. It stops short of permissions, error behavior, or constraints around editing a live stream, though some of those live in the schema (e.g. preserve_state).

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 14 parameters are fully documented and the baseline is 3. The description adds cross-tool meaning the schema cannot convey by mapping the accepted field set to create_stream minus the creation-only 'type', which helps an agent reason about what it may send.

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) and resource (a stream), with PATCH semantics spelled out as 'only provided fields change'. It also explicitly distinguishes itself from create_stream by noting the shared field set minus the creation-only 'type' field, and anchors the operation to the underlying REST endpoint.

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 rather than stated: the create_stream cross-reference tells the agent this is the edit path for an existing stream, but there is no explicit when-to-use versus get_stream/delete_stream/update_media, and no prerequisites or conditions (e.g. live-stream state) are called out.

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

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

No annotations are present, so the description carries the full burden. It discloses the partial-update behavior ('Only provided fields change') and references PATCH semantics, which tells the agent that missing fields are untouched. It does not state auth requirements or whether the operation is reversible, but the idempotence implicit in PATCH is a useful behavioral signal.

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. First sentence states the purpose, second states the partial-update contract, third maps to the API endpoint. Front-loaded and zero waste.

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

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

A mutation tool with no annotations and no output schema. The description covers the action, what changes, and the endpoint, which is complete enough for correct invocation. It lacks auth or permission notes and does not discuss response behavior, but no output schema exists so that omission is acceptable.

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

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

Schema coverage is 100%, so the schema documents all four parameters with descriptions including max lengths, formats, and clearing semantics (null clears). The description's 'name, color or icon' maps one-to-one to the three optional parameters, adding mild routing value. Baseline is 3, plus credit for the clear enumeration.

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 (Update) and resource (tag's name, color or icon) with a precise edit contract. It maps to a known HTTP endpoint, giving the agent strong resource recall. Distinguishes itself from create_tag, delete_tag, and list_tags by naming the mutation scope.

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

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

The description implies usage via 'Only provided fields change' – a partial-update/PATCH semantic. However, it doesn't explicitly say when to prefer this tool over create_tag or delete_tag, nor does it state whether it can create or only mutate. Sibling routing is implied, not explicit.

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