apivideo

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

The description adds behavioral context beyond the destructiveHint annotation by declaring it a WRITE operation and specifying that it returns a stream key and RTMP ingest URL. It does not contradict the annotations, though it could disclose more about side effects or prerequisites.

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

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

The description is a single front-loaded sentence that includes the action, resource, endpoint, and key return values. Every part is useful and there is no padding or repetition.

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

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

For a low-complexity creation tool with three documented parameters, the description plus schema is nearly sufficient. It names the critical returned artifacts (stream key and RTMP URL) even though there is no output schema, but it does not describe full response details or error behavior.

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

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

Schema coverage is 100%, so the schema already documents all three parameters. The description does not add additional meaning to the parameters themselves, but it does indicate the real-world output that follows from successful invocation.

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

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

The description states a specific action ('Create a new live stream') on a specific resource, making it distinct from siblings like apivideo_create_video or apivideo_get_live_stream. It also names the endpoint and the key outputs (stream key, RTMP ingest URL), fully clarifying the tool's purpose.

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

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

The description clearly implies this tool is for creating a live stream, but it does not explicitly say when to choose it over alternatives such as apivideo_create_video or apivideo_list_live_streams. It provides the endpoint and result, but no exclusion or comparison 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 signal a mutating operation via destructiveHint=true, and the description reinforces this with 'WRITE.' It adds meaningful behavioral context: when `source` is provided, api.video ingests from that URL, and raw file bytes cannot stream through MCP. This goes beyond the annotation without contradicting it.

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

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

Three sentences with no wasted words. The core purpose is front-loaded in 'WRITE. Create a new video object,' followed by the essential source guidance and the endpoint. 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?

The description is adequate for a creation tool but leaves gaps: it does not explain what happens when `source` is omitted, and with no output schema it does not indicate what response the agent should expect. Given 9 parameters and complexity around ingestion, slightly more detail on behavior and return value would improve completeness.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra semantics for `source`, explaining it as a public URL, recommending it for hosted use, and clarifying why raw bytes cannot be used. Other parameters are left to the schema, which fully documents them.

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

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

The description states a specific verb and resource: 'Create a new video object.' It clearly differentiates from siblings like apivideo_create_live_stream and apivideo_update_video by naming the object type and including the endpoint 'POST /videos.'

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 useful context for the `source` parameter, recommending it for hosted use, but it does not explicitly say when to choose this tool over alternatives or when not to use it. Usage is implied by 'Create a new video object,' but no exclusions or sibling routing are provided.

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

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

Beyond the destructiveHint annotation, the description explicitly warns 'This cannot be undone' and specifies that all assets are deleted, not just the video record. This gives the agent critical behavioral context for a high-impact call.

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

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

Four short, information-dense phrases: the verb, the endpoint, the permanence warning, and the scope of deletion. No filler words or redundant restatement of the schema or annotations.

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 DELETE operation, the description supplies everything needed to call it correctly: what it acts on, that it is permanent, and the HTTP endpoint. The absence of an output schema is not a real gap 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?

The input schema already provides 100% coverage for the single required parameter, videoId, with the description 'The video id to permanently delete.' The tool description adds little semantic detail beyond echoing the endpoint placeholder, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb and resource: 'Permanently DELETE a video and all its assets.' It also provides the HTTP endpoint 'DELETE /videos/{videoId}', making the operation unmistakable. It clearly stands apart from sibling tools like update_video or get_video as the only delete operation.

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

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

The description clearly establishes the tool's context: it is a write operation, it is destructive, and it permanently removes the entire video. It does not explicitly list alternatives or state 'use this instead of X', but the absence of any other delete tool in the sibling list makes the intended usage clear.

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

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

Annotations already declare readOnlyHint=true; the description corroborates 'Read-only' and adds the exact HTTP verb/path (GET /live-streams/{liveStreamId}) and a hint of response contents. It does not cover 404/error or auth behavior, but with the readOnly annotation this is reasonable.

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

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

One compact sentence plus endpoint, with each clause earning its place. 'Read-only' and the endpoint are short, front-loaded, and free of filler.

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

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

For a simple single-ID GET with a readOnly annotation, full schema coverage, and no output schema, the description provides enough: identification by id, operation type, endpoint, and key response fields. Error cases are not documented but are low-stakes for a read-only fetch.

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

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

Schema coverage is 100% and the single parameter already includes a name and example ('li400mYKSgQ6xs7taUeSaEup'). The description adds no additional parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb ('Get'), a single resource ('single live stream object'), an identifier ('by id'), and even lists contained fields (stream key, RTMP ingest, player URL). The endpoint line further disambiguates from list/analytics siblings.

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

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

Clearly indicates this is for fetching one live stream when the id is known ('by id'), which contrasts usefully with list and analytics siblings. It does not explicitly say 'use list_live_streams when you don't have an id' or name alternatives, so some inference is required.

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

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

The readOnlyHint annotation already covers safety, so the description adds useful behavioral context: the endpoint path, the aggregation nature, and the grouping/dimension behavior. It does not mention any side effects or rate limits, but for a read-only analytics query this is acceptable.

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

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

The description is short and front-loaded with the core purpose. The 'Read-only.' sentence repeats the annotation, which is slightly redundant, but the endpoint suffix adds useful specificity without bloat.

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 moderately complex read-only analytics tool with full schema coverage, the description is complete enough: it states the resource, grouping, date range, and endpoint. The absence of an output schema is mitigated by the clear 'plays' analytics scope, though a brief note on response format would have been ideal.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the meaning of date range and dimension, but does not add anything beyond what the schema already documents for each 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?

The description uses a specific verb-resource pairing: 'aggregated play analytics for live streams' with explicit grouping by dimension and date range. This clearly distinguishes it from sibling tools like apivideo_get_video_analytics, which targets on-demand video analytics.

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 use: it is for live stream play analytics over a date range, grouped by a dimension. It does not explicitly name alternatives or exclusion criteria, but the scope is unambiguous enough for an agent to select it appropriately among siblings.

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

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

Annotations already mark readOnlyHint=true and the description echoes 'Read-only,' but it also adds the REST endpoint and the returned object fields (title, assets, player URL, status flags). This gives useful expectations beyond the annotation, though it omits error/404 behavior.

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

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

The description is compact and front-loaded with the core verb and resource. The endpoint and field list add value without 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 one-parameter read-only GET, the description is nearly complete: it identifies the input ID, the endpoint, and the fields returned, while the readOnlyHint covers safety. It does not document errors or auth, but the operation is simple enough that this is a minor gap.

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

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

Schema coverage is 100% and the videoId parameter already has a clear example and description. The description adds no new parameter-level meaning beyond saying 'by id,' 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 ('Get a single video object by id') and lists the returned fields, which clearly separates it from list_videos and the status/analytics siblings. The by-id scope is explicit enough that an agent can select this tool 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 gives no guidance about when to use this tool versus apivideo_list_videos, apivideo_get_video_status, or apivideo_get_video_analytics. It only notes that the operation is read-only, which conveys safety 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?

Beyond the readOnlyHint annotation, the description adds that results are aggregated, date-range constrained, and grouped by a dimension. It also identifies the HTTP GET method via the endpoint path. It does not mention response shape or pagination, but the aggregation semantics are meaningful additional context.

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

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

The description is compact and front-loaded with the core operation before stating the method. The 'Read-only' clause is somewhat redundant with the readOnlyHint annotation but does not meaningfully bloat the text.

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

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

For a 6-parameter GET endpoint with no output schema, the description conveys the essential aggregation concept needed to understand what the tool returns. The remaining invocation details are well covered by the fully documented schema; minor gaps such as response shape and pagination behavior remain.

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

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

The schema already documents all six parameters with formats, defaults, constraints, and the dimension enum. The description's date-range and grouped-by language largely restates the schema's from/to and dimension descriptions, adding no new parameter-level meaning.

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

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

States a specific operation: aggregated play analytics for videos, with a date range and grouping dimension. The mention of 'videos' and the GET /analytics/videos/plays endpoint clearly distinguishes it from the live-stream analytics sibling. There is no ambiguity about the target resource.

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

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

The description clearly indicates this tool is for video play analytics over a date range, which provides enough context to route an agent correctly. It does not explicitly name alternatives or exclusions, but the video-vs-live-stream distinction is obvious from the scope and endpoint.

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

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

The description repeats the read-only behavior already declared by readOnlyHint=true, which adds no new information. It does add some behavioral context by listing what status categories are included (upload progress, encoding qualities, playability), but it does not disclose error cases, response shape, or any side effects beyond what annotations already cover.

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

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

The description is compact and front-loads the core purpose, with concrete examples of status contents. The 'Read-only.' clause is redundant given the annotation, and the endpoint string is slightly redundant with the tool's REST style, but the overall size is appropriate and no word is wasted.

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

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

For a simple one-parameter read-only status endpoint, the description provides enough context to understand what data is returned (upload progress, encoding qualities, playability). Since there is no output schema, the description partially covers return semantics, though it could mention specific response fields or error conditions to be fully complete.

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

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

With schema description coverage at 100%, the parameter videoId is already documented as 'The video id.' The description does not add further semantic detail about the parameter, such as expected format, requiredness context, or relation to other parameters. It meets the baseline but does not exceed it.

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

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

The description clearly states the specific action ('Get encoding and ingest status for a video') and distinguishes it from sibling tools like apivideo_get_video or apivideo_get_video_analytics by naming the exact domain (status, upload progress, encoding qualities, playability). The REST endpoint is also included, reinforcing what resource is being addressed.

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

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

The description implies when to use the tool (when you need encoding/ingest status) but does not explicitly state when not to use it or name alternatives. With many sibling video-related tools, such explicit routing would improve clarity. Currently, usage context is only implied by the scope of the returned data.

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?

Annotation readOnlyHint=true already marks the operation as read-only; the description reinforces this with 'Read-only' and specifies the GET endpoint. It adds the returned fields (language, source URL, default flag), which is useful context. It does not go into edge cases like empty results, but for a non-destructive GET this is adequate.

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

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

The entire description is one short sentence plus the endpoint and 'Read-only'. Every fragment earns its place and the key action is front-loaded.

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

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

For a list operation with three well-documented parameters and no output schema, the description tells the agent what is returned (language, source URL, default flag), the endpoint, and the read-only nature. Missing details like pagination behavior are already in the schema. No critical information for selecting and invoking the tool is absent.

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

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

Schema description coverage is 100%; videoId, pageSize, and currentPage each have descriptions. The tool description adds only the semantic context of what a caption track contains, which is helpful but does not change the 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?

The description opens with 'List caption tracks for a video', naming a specific verb, resource, and scope, and adds the fields returned in parentheses. This distinguishes it cleanly from sibling list tools such as list_chapters or list_videos.

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

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

The description implies the tool is for retrieving caption tracks for a given video, but it does not explicitly state when to prefer it over alternatives or when not to use it. No exclusions or references to sibling tools are provided.

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

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

Annotations already declare readOnlyHint=true, and the description repeats that. It adds the HTTP endpoint, which provides some operational context, but does not describe pagination behavior, response format, or edge cases. With annotations covering the safety profile, the added value is modest.

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

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

The description is two short sentences with no filler. It front-loads the core action and then adds the HTTP method and endpoint, which is efficient and easy to scan.

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

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

For a simple read-only list operation with fully documented parameters, the description is nearly complete. The only minor gap is that it does not describe the response shape or pagination metadata, but the schema covers paging inputs and the operation is straightforward.

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 fully documents videoId, pageSize, and currentPage. The description adds no parameter-level detail beyond what the schema already provides, meriting the baseline score 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: 'List chapter tracks for a video.' This distinguishes it from sibling list tools like list_captions and list_videos. The endpoint GET /videos/{videoId}/chapters further pins down the operation.

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

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

The description gives clear context (chapters scoped to a video) but does not explicitly say when to use this tool over alternatives such as list_captions. Usage is implied by the resource name rather than stated with exclusions or alternative conditions.

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

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

Annotations already declare readOnlyHint: true, and the description's 'Read-only' restates that. It adds the endpoint and account scope, but no further behavioral details such as pagination behavior, rate limits, or response shape. There is no contradiction.

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

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

The description is compact, front-loads the core operation, and includes the endpoint in a single short sentence. Every phrase earns its place with no redundant filler.

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

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

Optional params are fully documented in the schema, the safety profile is covered by the readOnlyHint annotation, and the description explains scope, filters, sorting, and endpoint. A minor gap is the absence of any indication of what a successful response contains, though 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?

Schema description coverage is 100%, so the input schema fully documents all six parameters. The description merely summarizes the filter and sorting categories without adding new parameter-level meaning, so the baseline 3 applies.

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

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

The description states a specific verb ('List'), a clear resource ('live streams'), and an account scope, while also naming the optional filters and sorting. It is readily distinguishable from the sibling get_live_stream (plural resource vs singular) and create_live_stream.

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

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

The description implies use for collection-style listing in the account and is read-only, but it gives no explicit guidance about when to use this tool over get_live_stream or how to choose between listing and fetching a specific stream. The context is clear enough only through 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?

The readOnlyHint annotation already covers safety, and the description adds 'Read-only' and 'GET /players' as confirmation. However, it does not add deeper behavioral context such as pagination behavior or account-scope details beyond the schema fields.

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

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

The description is compact and front-loaded: resource, scope, safety, and HTTP method are conveyed in one short sentence 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?

For a simple read-only list operation with fully documented optional parameters and no required inputs, the description is complete. The return value is inferable from the resource name, and no output schema is needed.

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 four parameters are already documented. The description adds no extra meaning to sortBy, pageSize, sortOrder, or currentPage, matching the baseline for full schema coverage.

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

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

States a specific verb ('List') and resource ('customized player themes'), scoped to the account. This clearly distinguishes it from sibling list tools like apivideo_list_videos or apivideo_list_live_streams.

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

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

The description makes the use case obvious: call this when the agent needs the account's custom player themes. There is no competing sibling for listing players, so no exclusion is needed, but explicit 'when to use' wording is absent.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the HTTP method (GET /videos) and the account scope, which is useful context. However, it does not disclose pagination behavior, response envelope, or other runtime traits, matching the same limitations seen in the calibration example.

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

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

The description is a single concise sentence with no filler. The action and resource are front-loaded, and the read-only note plus endpoint are efficient, valuable additions.

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

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

For a read-only list operation, the description combined with the fully documented schema gives an agent the endpoint, filters, sorting, and pagination controls needed to invoke the tool correctly. The return shape is not specified, but with no output schema and a standard list endpoint, that omission is minor.

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 all 9 parameters documented. The description names the filterable fields and mentions sorting, but it adds no semantic nuance beyond what the schema already provides, 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 uses a specific verb ('List') and resource ('videos in the account'), enumerates optional filters and sorting, and explicitly marks the operation as read-only with the GET endpoint. This clearly differentiates it from sibling tools such as apivideo_get_video (single video) and apivideo_list_live_streams (different resource type).

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

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

The context is clear: this tool lists account videos with optional filters and sorting. It does not explicitly state when not to use it or name alternatives like apivideo_get_video, but the resource and verb make the boundary obvious. Missing explicit exclusion keeps it from 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?

The readOnlyHint annotation already establishes the safety profile, and the description reinforces it with 'Read-only' and adds the endpoint 'GET /webhooks'. It does not disclose response format, pagination behavior, or any additional side effects, but this is a simple read operation with annotations covering the main safety concern.

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

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

The description is compact and front-loaded, with each sentence contributing useful information: the operation, the account scope, optional filtering, read-only nature, and endpoint. There is no redundancy or wasted text.

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

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

For a simple, read-only list operation with three optional, fully documented parameters and no output schema, the description is complete enough for an agent to invoke it correctly. It supplies the endpoint, scoping, filtering option, and safety profile without requiring additional context.

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

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

Schema description coverage is 100%, and all three parameters are already clearly described in the schema, including defaults and examples. The description only mentions event-name filtering without adding meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly identifies the verb ('List') and the resource ('webhooks configured in the account'), and distinguishes it from sibling list tools by resource type. It also mentions optional event filtering, making the purpose specific and unambiguous.

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

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

The description gives clear context for when to use the tool—listing account webhooks, optionally filtered by event—but does not explicitly state when not to use it or mention alternative tools. Since all siblings target different resources, the context is sufficient without exclusions.

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

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

Annotations mark destructiveHint=true, and the description adds valuable behavioral context: it is a WRITE operation, uses PATCH semantics, and only the provided fields are changed. This prevents the assumption that the request performs a full replacement.

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 WRITE flag, the core purpose, the partial-update behavior, and the endpoint. No filler or redundancy, and the most important constraint is front-loaded.

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

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

For an update tool with 100% schema coverage and destructiveHint annotation, the description covers the essential operation, partial-update behavior, and endpoint. It does not describe response format, but no output schema is provided and the description is otherwise 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 coverage is 100%, so parameters are already documented. The description adds the key semantic that only provided fields are changed, which clarifies how optional parameters behave during an update—beyond what the individual field descriptions offer.

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

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

The description uses a specific verb ('Update') and resource ('an existing video'), clearly distinguishing this from sibling create/delete/get/list tools. The endpoint PATCH /videos/{videoId} reinforces the operation without ambiguity.

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 'existing video' clearly indicates this tool is for modifying already-created videos, which excludes creation, deletion, or retrieval. It lacks explicit alternatives or when-not-to-use statements, but the context is unambiguous among the sibling tools.

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