Flask

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

Annotations already declare the read-only, idempotent, non-destructive profile, and the description adds substantial context on top: the full status vocabulary, which states are terminal vs. non-terminal, and what transfer_progress and progress mean. This is exactly the behavioral detail annotations cannot carry.

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

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

Front-loaded with the core purpose, then id rules, then status meanings, then return fields. It is dense and runs as one long block with no formatting, but every clause earns its place by defining a status value or a return field.

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

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

No output schema exists, yet the description names all four return fields (asset_id, version_id, url, version_url) and fully enumerates the status outcomes with their handling. Nothing an agent needs to call and correctly interpret this tool 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%, so baseline is 3, but the description exceeds the schema by clarifying that asset_id may be a version id or an asset id, that it resolves to the current version, and that a folder id is refused. That is genuine meaning beyond the schema's one-line parameter note.

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

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

States a specific verb (check) and resource (processing status of an uploaded or imported video) and its readiness semantics. An agent can distinguish this polling tool from siblings like upload_video or wait_for_feedback purely from the description.

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 acceptance rules (version id or asset id, folder id refused) and conditional next actions per state: poll again for in-progress states, and read error_message / stop polling / re-upload on error. It doesn't route to any sibling alternative, so it stops short of a full 5.

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

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

Annotations already establish readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: 'Only items you can view are listed' (permission-scoped results), that version listings are not paged while root/folder listings are, and how next_offset signals more results. It does not contradict the annotations and adds real behavior, but does not describe rate limits or auth requirements.

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 dense paragraph, but it is front-loaded and grouped logically: mode selection first, then pagination, then the search alternative. Every clause carries information, though the asset-item field list could be trimmed against the schema.

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

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

With no output schema, the description correctly compensates by describing the returned item fields (asset_id, version_id, version_count, media fields, url, version_url) and the pagination envelope. For a five-param, zero-required tool its guidance is complete.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters, making 3 the baseline. The description reinforces the meaning of the three identifier modes and the limit/offset semantics, but mostly restates what the schema provides rather than adding syntax or edge-case detail.

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

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

States a specific verb (Browse) over specific resources (folders and assets) and enumerates the three entry modes (no id, folder_id, asset_id), which cleanly separates it from siblings like versions_add or tags. An agent can tell exactly what it returns per mode 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?

Explicitly distinguishes the modes and names the alternative: 'To find something by name without knowing its folder, use search.' It also warns 'Not with folder_id' for asset_id, giving both when-to-use and a constraint against misuse.

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

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

Annotations already cover readOnly/idempotent/non-destructive, and the description layers on substantive behavior the annotations cannot convey: the full return shape, that pipeline_status means the transcript is final only once complete, and the Markdown conventions (#t=S for video seconds, #rt=S for spoken phrases) that an agent must parse.

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

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

Purpose and usage are front-loaded before the long return-value enumeration, and with no output schema that enumeration earns its space. The single dense paragraph and the redundant restatement of element_id provenance are the only 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?

No output schema exists, so the description must carry the return contract — and it does, enumerating text, tags, author, recording fields, transcript status, visual_references, visuals and replies. It also closes the loop by telling the agent when a follow-up get_annotated_frames call is required.

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

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

Schema coverage is 100% and the schema description already says element_id comes from an item in feedback_list, recent_activity, search or wait_for_feedback. The description restates that same provenance rather than adding new meaning (e.g. format, edge cases for cross-asset ids), so the schema does the heavy lifting and baseline 3 applies.

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

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

States a specific verb and resource — 'Get a single feedback item with its full reply thread' — which immediately separates it from feedback_list (which lists) and from feedback_post. The distinction is reinforced later by naming feedback_list as the listing alternative.

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

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

Gives explicit when-to-use conditions: 'Use it when an item has replies (feedback_list gives reply_count, not the replies) or to read one item again', plus an explicit when-not with the alternative ('to list an asset's feedback use feedback_list'). It also prescribes the follow-up call to get_annotated_frames for items carrying visuals.

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

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

Annotations cover only the safety profile (readOnly, idempotent), and the description adds substantial behavior beyond them: the default OPEN filter, the counts object, the exact response fields, recording-item cardinality (one comment per recording), the Markdown #t=/#rt= link semantics, and an explicit untrusted-content warning keyed to author_is_team_member.

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

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

Front-loaded with purpose and routing, then defaults, then response shape, then recording/Markdown details, then the security caveat — a sensible ordering where each block is doing work. It is dense and long-form for a list tool, and the #t=/#rt= explanation is somewhat reiterated via visual_references, but there is no filler.

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

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

With no output schema, the description carries the return-shape burden itself and does so: version_id, container_id, title, per-item body/tags/status/author/timestamp/reply_count/posted_by_agent, plus the recording sub-object. For a 4-param read tool with rich nested returns, an agent has everything needed to call it and interpret results.

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 semantics beyond the schema: that asset_id accepts either an asset id or a version id and that folder ids are rejected with a redirect. The status default and 'in-progress included under open' merely restate the schema enum.

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 top-level feedback on an asset') and immediately disambiguates scope: asset id → current version, version id → that exact version, folder id → refused. It also explicitly routes away from siblings, naming recent_activity(folder_id) and feedback_get for reply threads.

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

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

Explicit when-to-use and when-not rules are given: folder ids are rejected with a named alternative, default is OPEN-only with status=all to widen, and get_annotated_frames(id) should be called once per item that carries visuals. Nothing about tool selection is left to inference.

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

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

Annotations cover only safety hints (readOnly=false, idempotent=false, destructive=false), and the description goes well beyond them: it explains that a reply lands on the thread's version even after a newer version is uploaded, that tags/timestamp are refused on replies, that recordings and drawings cannot be added, that images must already exist in Flask, and that @mentions notify. This is exactly the extra behavioral context annotations cannot carry.

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

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

Front-loads the core action and then stays dense but useful; the timestamp-preference and reply semantics are stated early. It is a long single block with some overlap against the already-rich content schema description, which costs it a point.

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

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

For a 5-parameter mutation tool with no output schema, the description covers threading, version targeting, tag requirements, mention syntax, attachment limits, and reply constraints. An agent has everything needed to invoke it correctly and to know what it cannot do.

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: asset_id-vs-version_id semantics ('current version' vs exact version), the timestamp seconds-conversion heuristic, and the cross-parameter constraint that tags/timestamp are refused with reply_to. It does lean on the schema for content Markdown details, which caps this below 5.

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

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

States a specific verb and resource ('Create a feedback comment on an asset') plus the actor scope ('as the connected user'), which cleanly separates it from siblings like feedback_update, feedback_get, and feedback_list. An agent can identify this as the write/create path for feedback without opening any schema.

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

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

Gives concrete when-to-use guidance: prefer timestamp when source material has one (with a conversion example), omit for a general note, and use reply_to to join an existing thread. However, it never explicitly names feedback_update as the alternative for editing existing comments, so routing between write tools is left partly 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 cover the safety profile (readOnly, idempotent, non-destructive), so the description is free to add behavioral detail — and it does: sort order (by feedback count, most first), silent omission of zero-feedback assets unless include_empty, pagination semantics with next_offset, and the per-item shape (asset_id plus versions[].version_id). That is substantive disclosure beyond what annotations provide.

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

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

The scoping options and routing guidance are front-loaded and every sentence carries information, but the single dense paragraph is long, and a few clauses (limit defaults, offset) restate the schema. Slightly tighter structure would help, though nothing is egregiously wasted.

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

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

With no output schema, the description carries the return-shape burden and does so: it specifies the item structure, sorting, pagination fields, and empty-asset behavior. An agent can form the expected response and call it correctly without further context.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine nuance the schema lacks: asset_id accepts an asset id or any of its version ids and the whole asset is reported version by version, and folder_id scopes to the subtree. Most other parameter details (defaults, mutual exclusivity, include_empty) are restatements of the schema, so it lands just above baseline.

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

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

The description states a specific verb and resource ('Aggregate feedback statistics across many assets in ONE call') and immediately enumerates the aggregate dimensions (counts per asset/version, split by type, tag, author, timestamps). It is clearly differentiated from siblings feedback_list and recent_activity, which it names 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?

It gives concrete routing rules: use this for trend questions like 'are v1 notes going down across this client's recent videos' instead of calling feedback_list per asset, and 'For reading the feedback text itself across assets, use recent_activity.' Both when-to-use and the alternative tool are named with the condition that selects them.

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 destructive/idempotent/not-read-only, and the description adds material context beyond that: content is a full body replacement (with advice to start from current content to preserve mentions/formatting), tags are collaborative by NAME and must already exist, replies cannot carry tags, and the return shape matches feedback_get without replies. That is unusually rich behavioral disclosure including the return contract, which no output schema provides.

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

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

Front-loaded with the action, then dense conditional detail. It is longer than one sentence but nearly every clause carries a distinct constraint; the parenthetical about starting from current content is actionable rather than filler.

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

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

For a mutation tool with annotations and no output schema, the description covers permissions boundaries, partial-update semantics, the replies exception, and even the return value shape. An agent has everything needed to call it correctly without further inference.

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 3 is the baseline, but the description adds cross-parameter semantics the schema cannot express: the 'at least one of content, timestamp, add_tags, remove_tags' requirement, the whole-body replacement behavior of content, and the tag-by-NAME / must-exist constraint.

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

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

Opens with a specific verb+resource ("Edit an existing feedback item") and immediately scopes what is editable. It is clearly distinguishable from feedback_post (create) and feedback_get (read) without opening any schema, and it enumerates the mutable fields.

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 conditions: content/timestamp only on the connected user's OWN comments, tags on ANY item you can comment on but never on replies (tag the root instead), and requires at least one of content/timestamp/add_tags/remove_tags. It does not name a sibling tool as an alternative, which is why this falls short of a 5.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and the description adds real context beyond them: no duplicate-name checking (which explains the non-idempotent hint), the required edit access on the parent, and an explicit 'additive: nothing existing changes' guarantee that reinforces destructiveHint=false.

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

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

Front-loaded with the core action and then the optional parent behavior, followed by duplicate-handling, return value, follow-up tools, and permissions. Every sentence carries a distinct operational fact with no filler.

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

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

No output schema exists, but the description covers the return shape (folder_id and url), the permission prerequisite, duplicate behavior, and the hand-off tools for populating the folder. For a 3-parameter creation tool, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning about parent_folder_id (optional, omit for root, values come from contents or search results) and names the returned folder_id. team_id and title semantics remain schema-only, so it stops short of a 5.

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

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

States a specific verb+resource ('Create a folder') and immediately clarifies the nesting model, distinguishing it from sibling tools like contents, items_update, and the upload tools. An agent can tell what this does and how it relates to siblings without opening any schema.

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

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

Explicitly routes the agent: call contents first if the folder may already exist (duplicates allowed), and use items_update or the upload tools to put assets inside the new folder. It also names when parent_folder_id should be omitted (root) versus supplied (nested), leaving nothing 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?

With readOnly/idempotent/non-destructive already in annotations, the description adds substantial context beyond them: the 12-image cap, which links get dropped and named for get_frame, what each frame contains (drawing rendered in, pointing links, shared screen), the exclusion of webcam frames, and that returned links are unauthenticated and expire after 'some hours'. These are operational traits annotations cannot express.

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

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

The critical routing instruction is front-loaded, but the body is two sprawling run-on sentences packed with parenthetical asides that are hard to parse. The content is mostly relevant, yet density and length work against quick comprehension.

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

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

There is no output schema, so the description carries the burden of explaining returns — and it does: frame contents, labelling, the [FRAME N] transcript marking, image cap, and the two link forms (Link vs Media only) with their fetchability and expiry. An agent can act correctly without further information.

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

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

Only one parameter, and the schema description (100% coverage) already states it is the id field from feedback_list, feedback_get, recent_activity, search or wait_for_feedback. The description repeats that sourcing information rather than adding new meaning, so baseline 3 applies.

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

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

The description opens with a concrete verb+resource: 'The visuals of a feedback item, in one call', and immediately specifies which items qualify ('any item with a visuals field'). It also distinguishes itself from the closest sibling by stating 'Use get_frame only for a moment this did not show.'

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

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

Explicit when-to-use ('call it before acting on any item with a visuals field'), when-not/alternative ('Use get_frame only for a moment this did not show'), and what is out of scope ('webcam frames are NOT included'). The agent has no inference left to make about tool selection.

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

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

Annotations already carry readOnly/idempotent/destructive=false, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond that: links are fetchable without login, expire after 'some hours' (call again for fresh ones), and come in two variants (Link as shown vs Media only). It stops short of error/rate-limit behavior, but this is rich for an annotation-covered read tool.

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?

Efficiently front-loads the fallback rule and the two selection modes, with no wasted preamble. The nested parentheticals make it dense, but every sentence carries information about selection or return behavior.

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 fully covers what comes back (asset frame, active shared screen, transcript snippet, drawing-included vs media-only links, ephemeral access) and how to re-obtain links. An agent has everything needed to call and consume the result correctly.

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

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

Schema coverage is 100% and the schema descriptions for at/word/source already explain each field. The description's wording ('at' = recording time, 'word' = spoken phrase, asset vs shared-screen) largely restates that, adding scenario context rather than new syntax. 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+resource ('the exact frame at a recording time (at) or when a word/phrase was spoken (word)') and explicitly positions itself against the sibling get_annotated_frames as the fallback. An agent can distinguish the two tools without opening either schema.

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

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

Gives an explicit ordering rule ('call get_annotated_frames first; use this for a moment the comment doesn't link') plus the exact conditions that select this tool: a transcript-mentioned moment or a link named as not shown. Nothing is left to inference.

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

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

Beyond the readOnly/idempotent annotations, it discloses that the content is static prose identical for every user, carries no team data, and is roughly 14 KB for the main topic — which lets an agent budget context and skip redundant fetches. It also flags the redundancy relationship between topics, a behavioral trait not expressed anywhere in the structured fields.

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

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

Front-loads the core statement and the read-before-acting rule before the topic catalogue, and every sentence carries information. The per-topic parentheticals are dense but slightly list-heavy, costing a little economy versus a single tight sentence.

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?

One enum parameter, full schema coverage, no output schema — and the description still establishes content type, size, invariance, redundancy rules and the sibling to use for live permission data. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is already 100% with an enum, but the description adds real meaning by summarizing what each of the five topics actually contains, so the agent can pick the right one without trial and error. It also designates "instructions" as the playbook, a priority signal the enum alone does not convey.

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 ("Returns one of Flask's usage guides as Markdown") and immediately scopes the content as fixed, user-invariant reference text with no team data. This clearly separates it from data-bearing siblings like permission_get, feedback_get and contents.

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

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

Gives explicit when-to-use ("Read it before acting on feedback or making your first write in a session"), explicit when-not-to-fetch ("it already contains display and concepts, so do not fetch those after it"), and names the alternative for a different need ("for one folder's or asset's actual access, use permission_get").

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

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

Beyond the annotations (destructive=true, idempotent=true), the description discloses partial-failure semantics ('applied on its own and is not undone if another fails'), idempotency behavior ('an item already in the requested state reports changed: {}'), revert guidance via [from, to] pairs, the required edit access on item and target folder, and the Flask tab refresh side effect.

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

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

The purpose is front-loaded and every clause carries information, but the body is a dense semicolon-chained run-on that would benefit from grouping into shorter statements. Size is justified by the tool's complexity, so only structure loses a point.

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

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

With no output schema, the description compensates by explaining the result shape (per-item results, changed fields as [from, to], changed: {}), and it covers constraints, permissions, and side effects. An agent has everything needed to invoke and interpret it.

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?

Although schema coverage is 100%, the description adds real semantic meaning the schema does not: a version id renames/moves its whole asset, folder_id accepts 'root', folders are restricted to view/none for link and full_access/view/none for team, and link_access can never be full_access.

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 set of verbs (rename, move, share) over a specific resource (folders and assets), and immediately bounds the scope (up to 20 items per call). It is clearly distinguishable from siblings like versions_add or upload_file_complete, which it names directly.

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

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

It gives explicit exclusions and alternatives: 'Change sharing only when the user asks', 'to make media a version use versions_add, or upload with version_of'. It also names the routing rule for version ids, folder moves, and cross-team limits, leaving little 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 the tool as read-only, idempotent, and non-destructive, but the description adds material context beyond them: the available return fields, the absence of email addresses, the team field in the result, and what happens when query has no match. It also clarifies that the mention link notifies the person when used in feedback content and that this tool does not expose who can open an item.

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 front-loaded with what the tool lists and the returned fields, then moves to practical usage and scope exclusions. Despite being dense, every sentence carries useful information; the long mention URL is actionable rather than 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?

There is no output schema, so the description carries the burden of explaining return values, and it does: user_id, name, role, avatar_url, mention link, and the team field. It also covers privacy behavior, query edge cases, and the sibling alternative for access settings. Nothing material is missing for correct selection and 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%, so both parameters are already documented. The description adds meaningful query semantics (names containing the query are kept; no match yields an empty list) and reinforces team context, though it does not add much beyond the schema for team_id.

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: it lists the people on the team and names the fields returned, including user_id, name, role, avatar_url, and mention link. It also distinguishes this team-wide listing from permission_get, which covers item access settings. 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?

It explicitly says to use this tool for mentioning someone in feedback_post / feedback_update content and provides the exact mention-link pattern. It also states query behavior and the empty-list outcome, and directs item-access use cases to permission_get. This is clear when-to-use and when-to-use-something-else 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 read-only, idempotent, non-destructive, so the safety profile is covered; the description adds substantive context by enumerating the returned access levels, note-visibility rules, creator/member status, and default link/team levels. It does not say what happens if neither param is supplied or if both are passed, which is the remaining 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?

Front-loaded with the operation and then the alternative-routing; every sentence carries information. The return-value enumeration is long, but it is justified because no output schema exists, so it is density rather than padding.

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

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

With no output schema, the description takes on the burden of describing return values and does so thoroughly (access levels, version-note visibility, creator info, defaults, member count). Combined with the sibling routing, an agent has what it needs to call this correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema: folder_id for folders, asset_id for assets, and the non-obvious rule that version ids resolve via their asset's settings.

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

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

Opens with a specific verb + resource: 'Read the access settings of a folder or an asset.' This is clearly distinct from siblings like members (people listing) and items_update (mutating access), both of which are named.

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

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

Explicitly routes the agent: 'It does NOT list individual people - use members', 'To change the link or team access, use items_update ... only when the user asks.' When-to-use, when-not-to-use, and the alternative are all stated.

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

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

Annotations already cover the safe-read profile (readOnly, non-destructive, idempotent), so the bar is lower; the description nonetheless discloses ordering (newest first), visibility filtering (only assets you can view), and pagination behavior including the caveat that a page can hold fewer than `limit` items and next_offset signals remaining pages. It stops short of auth/rate-limit context, but the pagination disclosure is real added value.

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

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

Front-loaded with purpose and scope before routing and pagination detail, and every sentence carries information. The single dense paragraph packed with parenthetical asides and the enumerated return fields is slightly heavy to scan, keeping it off 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?

With no output schema, the description compensates by enumerating each returned item's fields (type, author, timestamp, link, container_id/container_title, asset_id as version id), along with pagination, scoping, and sibling routing. An agent can call this correctly and interpret the result without further documentation.

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

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

Schema coverage is 100% so baseline is 3, but the description adds semantics beyond the schema: team_id resolves a team named by an earlier result versus the app's currently selected team, folder_id scopes to a client/project subtree, offset consumes the previous next_offset, and since/until narrow the window. It also clarifies that asset_id is a version id, which the schema never states.

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

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

States a specific verb+resource (get latest feedback) with explicit scope (whole team or one folder's subtree) and ordering (newest first), plus the content type (text and recording comments on assets you can view). This clearly distinguishes it from the asset-scoped feedback_list and the aggregate feedback_stats.

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

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

Names three alternatives with the exact condition selecting each: feedback_list for one asset's feedback, wait_for_feedback to wait for new feedback, feedback_stats for counts and trends. It also states when to use folder_id (one client's/project's feedback) and the window params, leaving nothing 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial beyond-that context: it always returns all three categories most-recent-first, each capped at limit and not paged, and only items the caller can view. It also discloses the shape of each hit type, which an agent needs to interpret results correctly.

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

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

The purpose and sibling routing are front-loaded, and the dense clause-heavy style wastes few words given how much return-shape and scoping detail it must convey without an output schema. The single-sentence wall of field lists is slightly harder to parse than it needs to be, keeping it off 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?

With no output schema, the description carries the burden of describing returns and does so thoroughly across all three hit categories, plus scoping limits (view-permitted, non-paged, capped). Everything an agent needs to invoke and interpret this tool 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 adds real meaning by clarifying that limit caps each category independently and that results are not paged. It also ties team_id to which 'team' the results describe. These nuances go beyond the field descriptions without contradicting 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 names a specific verb ('Search') and three resources (folders by name/description, assets by title, feedback by text) in one shot, and immediately distinguishes itself from siblings contents, feedback_list and recent_activity. An agent can tell exactly what this does and what it does not do without opening a schema.

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

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

It gives an explicit trigger ('when you don't know where something is') and routes the agent to the correct alternative for each narrower case (contents for a known folder, feedback_list for one asset, recent_activity for latest feedback). This is textbook when/when-not/alternatives guidance.

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

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

The annotations already declare this is a non-destructive, non-read-only, idempotent create operation. The description adds useful specifics beyond the annotations: idempotency is case-insensitive, an existing tag is returned unchanged with created: false, and tags are shared across the team.

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 front-loaded with the purpose and usage guidance, then adds idempotency and team-sharing details without waste. It is appropriately sized for a simple three-parameter creation tool.

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

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

Given the simple schema, full parameter descriptions, and absence of an output schema, the description covers what the tool does, when to use it, and key behavioral details like idempotency and shared team scope. Nothing critical is missing 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 the schema already documents name, color, and team_id. The description reinforces the optional color format and the role of name, but does not add meaningful semantics beyond the schema for team_id, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: create a team tag/label. It also explains the downstream purpose, tagging feedback by name in feedback_post and feedback_update, and distinguishes this from reusing existing labels via tags().

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

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

It explicitly says to reuse the team's labels when one fits and to create a new tag only when the user wants a new label. It also directs the agent to call tags() first to check for existing tags, giving clear when-to-use and when-not-to-use 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 the safe-read profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the description's job is to add context beyond that. It does so usefully by defining the share metric (count_with_tag / total_elements) and warning that shares do not sum to 100% because elements carry multiple tags, plus the version-id widening behavior. It stops short of describing ordering or result size, but is strong overall.

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 compact block that front-loads the core action and return shape before the scoping options and the caveat. The share-formula sentence is dense but earns its place by preventing a misreading of the output; no filler sentences are present.

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

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

With no output schema, the description carries the return-value burden and discharges it: it names the tag shares, the untagged bucket, and the formula with the non-summation caveat. Scope behavior and fallbacks are fully covered, so an agent has everything needed to call and interpret it.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: folder_id covers the entire subtree, asset_id aggregates across every version of the asset, and team_id omission falls back to the app-selected team. Mutual exclusivity is stated in both, so it adds no new value there.

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

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

States a specific verb and resource ('List the team's tags') plus the distinctive output ('share of each tag plus an untagged bucket'), which separates it from tag_create among siblings. An agent can identify the tool's function without reading 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?

Explicitly defines the default scope ('whole team') and the two narrowing alternatives with their exact semantics: folder_id narrows to the folder's whole subtree, asset_id counts feedback across all its versions, and a version id widens to its asset. It also notes the mutual exclusivity condition, leaving nothing 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?

Goes well beyond the annotations by describing branch-specific behavior: for a video it verifies every part landed and starts processing, for a zip it checks for a playable page and reports what to fix, and for an image/zip it creates the asset at a chosen location. 'Safe to retry: a repeat returns the same asset' reinforces idempotentHint=true with a concrete return behavior, though it partly overlaps 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?

Front-loaded with the action and precondition, then the discriminating parameter rule, then per-branch behavior. Dense but every clause carries information; a few long parentheticals make it slightly harder to scan than an ideal definition.

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

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

For a 9-parameter, no-output-schema finalize step, it covers the workflow position, the three mutually exclusive entry modes, asset placement (top level, folder_id, version_of), title handling, and retry semantics. It does not spell out failure recovery for a partial video upload or permission requirements, which are the remaining gaps.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a genuinely non-schema constraint: 'Pass exactly one of: asset_id ... image_url ... or upload_id'. That mutual-exclusion rule is not expressed by any required/oneOf constraint (0 required params), so the description carries real semantic weight.

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 ('Finalize a local file upload') and immediately anchors it to the sibling it completes, upload_file_start. An agent can distinguish it from upload_file_start and upload_video 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 an explicit precondition ('Call this only AFTER the upload command ... has finished successfully') and an explicit alternative for the preceding step (upload_file_start). It further routes by media type, telling the agent which of asset_id / image_url / upload_id applies to a video, image, or live animation zip.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description meaningfully adds beyond them: free-plan asset limits, that version_of is always free, refusal behavior when quota is exhausted, resume-on-retry, and critically that re-calling upload_file_start creates and counts another asset. This last point is essential given idempotentHint=false.

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?

Content largely earns its place given three distinct upload modes, but it is delivered as one dense run-on paragraph. The capitalized mode labels (VIDEO:, IMAGE, LIVE ANIMATION) help navigation, yet the sheer density and lack of line separation make it hard to scan; it is close to over-long for a single description.

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

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

For an 8-parameter, multi-mode tool with no output schema, the description covers all branches (video/immediate asset, image/deferred, zip/animation), the required follow-ups, quota and size limits, and error behavior. Nothing an agent needs to invoke it correctly across modes 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%, so the baseline is 3, but the description adds cross-parameter conditional semantics the schema does not: which params apply per content_type (image/zip params go to upload_file_complete instead), the files/notes 'video only' constraint, and that folder_id is ignored when version_of is set. That meaningfully exceeds the schema's per-field docs.

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

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

The first sentence states a specific verb and resource ('Start uploading a LOCAL video or image file from the user's machine into Flask') and immediately distinguishes it from upload_video for public links. It also routes to upload_file_complete as the continuation, so an agent can place it in the workflow without reading sibling 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?

Explicit when-to-use (needs a shell running curl) and when-not (a chat app without a shell -> use upload_video), plus per-mode routing (video vs image vs zip) and follow-up calls. It even states the live-animation precondition ('ONLY when the user asks to play an HTML/JS animation live') and the default it overrides (render the MP4).

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 cover the safety profile (readOnly=false, destructive=false, openWorld=true, idempotent=false); the description adds substantial context beyond them: the download/store/process pipeline, free-plan asset limits (new assets limited, new versions free), refusal behavior with an explanatory message, and the requirement for edit access when folder_id is supplied. This is exactly the extra behavioral detail the 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?

The description is long but front-loaded: identity of the tool, then mechanics, then the version_of branch, then constraints, then the alternative tool and the code/files case. Every sentence carries a distinct operational fact, though the density approaches a wall of text that could be broken into clearer stanzas.

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

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

With no output schema, the description takes on return-value duty and discharges it: it names what is created (container_id + url, asset_id/version_id), what to hand back (the asset URL), and how to detect completion (poll asset_status until 'ready'). Combined with plan limits, access prerequisites and the sibling alternative, nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the prose adds meaning on top of the schema: folder_id defaults to the team root when omitted and is ignored when version_of is set, version_of accepts either the asset container id or any version id, and team_id falls back to the app-selected team. Marginal added value over the already-detailed schema, but genuinely useful for the version_of/folder_id interaction.

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 ('Upload a video from a public URL') and explicitly delineates both the source types (direct file link or Google Drive share link) and the two outcomes (new asset vs new version). It also names the sibling it is NOT (upload_file_start) for local files, so an agent can route without opening either schema.

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

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

Gives explicit when-to-use (public URL, code/files with notes+source.zip) and when-not (local file on disk -> upload_file_start). It also prescribes the operational sequence: share the returned asset URL while processing, then poll asset_status(version_id) until status is 'ready'. Alternatives and conditions are stated, not inferred.

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

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

Annotations already declare a safe, idempotent read, but the description adds substantive context the agent could not infer: retention windows (14 days on Free/Pro, expiry permanent), that a video returns the original upload, that images are kept indefinitely, and that download links are tokenless and expire after one hour. That is exactly the kind of operational detail annotations cannot carry.

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

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

Front-loaded with purpose and parameter rules before the detail, and every sentence carries real information. It is dense and parenthetical-heavy, though, and the trailing list of return fields reads as a run-on; slight restructuring would improve scanability without losing content.

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

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

No output schema exists, so the description must document return values, and it enumerates all of them (asset_id, version_id, url, version_url, kind, filename, size, download_url, available_until) including null semantics for images. Combined with retention, expiry, and permission guidance, an agent has everything needed to call and interpret this tool correctly.

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

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

Schema coverage is 100% and the schema already explains version-id-vs-asset-id, but the description adds the meaningful constraint that folder IDs are rejected and clarifies the polymorphic behavior of the single parameter. Good value beyond the schema, though for a one-parameter tool it is close to what a well-written schema field 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 and resource ('Get a download link for a version's file') and immediately frames the intent ('to work on it locally'). It also distinguishes itself from version_notes_get for live code versions, so an agent can pick it out of a large sibling list 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?

Explicitly says what ID to pass, that a folder id is refused, that view access is required, and routes to version_notes_get for a live version's source zip. It also gives fallback guidance (call again after an hour, hand download_url to the user when no shell is available), leaving little 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 only say non-readonly/non-idempotent/non-destructive; the description adds substantial context: returns a presigned URL for exactly file_size bytes, no complete call needed, files are immutable (a name used once), requires full_access and team membership, 30 MB/20 files limits, and a convention for source.zip including what to exclude from the zip. This is far beyond annotation coverage.

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

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

Front-loaded with the core action and the key alternative, but the run-on parentheticals and stacked clauses (curl, markdown line, zip convention, limits, permissions, immutability) make it dense and hard to scan. Every sentence carries content, but structure is convoluted.

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

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

Covers the full contract: presigned URL return, upload mechanism, no complete step, visibility in notes, limits, permissions, and immutability policy. No output schema, but the description explicitly explains what is returned ('presigned upload URL') and how to consume it, so nothing an agent needs 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 already 100%, so baseline is 3; the description adds real semantics (file_size must match exactly and is enforced, name uniqueness per version, asset_id can be asset or version id, content_type implied by application/zip convention). Marginal but meaningful value above 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 action and resource ('add a file to a version that already exists') and explicitly distinguishes from the new-upload path (upload_file_start/upload_file_complete via 'pass files with the upload call instead'). An agent can tell it apart from siblings 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?

Explicit when-to-use (version already exists) vs when-not (new upload), names the alternative workflow, and gives the exact next action ('upload with the curl command from next_step') and follow-up (put returned markdown line in version_notes_update). Covers the only sane sequence.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: required access level (full_access or comment_and_notes), that comment/view access is insufficient, that download_url works tokenless for one hour, that only team members can add files, and a prompt-injection warning to treat notes as data.

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

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

Front-loaded with purpose and usage before permissions and security caveats, and nearly every sentence carries operational value (curl invocation, token expiry, access tiers). It is dense but the length is justified by the safety and workflow 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 still describes the return shape (name, size, download_url), the null-markdown case, and end-to-end usage. An agent has everything needed to authenticate, fetch, and safely use 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 coverage is 100%, so the single asset_id parameter is already documented, including that it accepts an asset id resolving to the current version. The description adds the return-side nuance that markdown is null when no notes exist, which goes slightly beyond the schema 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+resource ('Read a version's notes (Markdown) and its files') and immediately explains what each part is. It is clearly distinguishable from siblings like version_download (files only) and version_notes_update (writes notes).

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

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

Explicitly prescribes when to use it: 'Call this before continuing work someone else uploaded: read the current version's notes, download its files, then make the changes the feedback asks for.' That is a concrete trigger plus a follow-on workflow that rules out ambiguity.

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

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

Goes well beyond the annotations (destructiveHint/idempotentHint) by disclosing replace-not-merge semantics, the 20,000 character cap, the full_access requirement, that access extends to any version and not just your own uploads, and the return payload (stored markdown plus warnings about dropped references). Missing only pagination-style operational edge cases, which are irrelevant here.

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

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

Front-loads the core action and semantics before branching into the new-upload alternative and the guidance block. Dense and mostly earned, though the style guidance ('what changed and why ... how to continue') is advisory padding that a shorter pointer would have covered.

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

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

No output schema, yet the description still names the return value and its warning case. With permissions, character limits, the alternative upload flow, and access scope all covered, an agent has everything needed to call this correctly on the first try.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: the 20,000-character limit on markdown is a constraint absent from the schema, null/empty both clear, and Flask links are converted to references. It also explains that asset_id may be a version id or an asset id (its current version).

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 (replace a version's notes) plus the exact replace semantics ('the whole text; null or empty clears them'). It is immediately distinguishable from version_notes_get (read) and from the upload_* siblings it explicitly routes away from.

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

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

Gives an explicit when-not plus the alternative: 'For a NEW upload, pass notes with the upload call instead (upload_file_start, upload_file_complete, upload_video)'. It also states the standing condition for use ('Write notes on every revision you upload') and the access prerequisite.

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 flag destructive/not-idempotent; the description goes well beyond: it states the source asset ceases to exist along with its title and link, that sharing is taken from asset_id, that no media or feedback is deleted, that ordering determines the current version, and that failures are per-source without rollback. These are exactly the consequences an agent needs before invoking a destructive tool.

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

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

Front-loaded with the core action and metaphor, and virtually every sentence carries information an agent needs for a destructive multi-source operation. It is dense and would benefit from light structuring, but there is no filler to cut.

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

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

For a destructive, multi-source tool with no output schema, the description covers ordering, per-source results, refusal conditions, and side effects on the source asset and feedback. Nothing material an agent would need to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: asset_id is 'the asset that keeps its title, link and sharing', and source_ids behave differently depending on whether an asset id (all versions) or a version id (single version) is passed.

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 ('Make other assets or versions the NEWEST versions of asset_id') and grounds it in a familiar mental model ('as dragging one onto another does in the Flask app'). It also explicitly distinguishes itself from siblings by routing new-media creation to 'the upload tools with version_of'.

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

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

Gives an explicit when-to-use ('Use it when a revision was uploaded as a separate asset') and an explicit when-not/alternative ('To add NEW media as a version, use the upload tools with version_of'). It also enumerates the refusal conditions (still uploading, another team, more narrowly shared), leaving little to inference.

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

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

Annotations already flag non-readonly, idempotent, non-destructive, but the description adds the consequences annotations cannot express: the top version becomes the current one, version numbers follow the order, and no media or feedback is deleted (feedback stays on its version). This is exactly the extra context needed for a mutation tool.

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 dense, front-loaded sentences with no filler; the operation, its consequences, and the undo path all appear before the pointer to contents.

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

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

For a two-parameter mutation with no output schema, the description covers semantics, side effects, and reversibility well. It omits failure behavior (e.g. what happens if order is missing an id or contains an invalid one) and any permission requirements, which are the remaining gaps.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds meaning beyond the schema: order must contain every version id of asset_id exactly once (a complete permutation, not a subset), top-first, and it states the behavioral effect of that ordering.

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 ('Set the order of an asset's versions') and immediately clarifies the effect, distinguishing it from siblings like contents (listing), versions_add, and versions_split. An agent can tell what it does 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 clear context for use and an explicit undo path ('Reorder again to undo'), plus points to contents(asset_id) as the way to obtain the version ids. It does not contrast against other ordering-adjacent siblings (e.g. versions_split), so it stops short of explicit alternatives.

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

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

Adds real context beyond the annotations: no media or feedback is deleted, feedback stays attached to its version, new assets inherit folder and sharing, and partial failures are not rolled back ('earlier ones are not undone if a later one fails'). The annotations cover non-destructive/idempotent, and the description confirms rather than contradicts them, though it doesn't state auth/permission requirements for a mutating tool.

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

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

Front-loads the mutation and its result, then packs invariants, undo path, and failure semantics into short declarative clauses with zero filler. Every sentence carries a distinct fact an agent needs.

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

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

No output schema exists, and the description compensates by naming the already_separate status and explaining per-version, non-transactional results. Combined with the annotations, an agent has everything needed to invoke 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% for the single parameter, so the schema already documents version_ids; the baseline of 3 applies. The description adds per-version result semantics and the already_separate outcome, which is useful but behavioral rather than parameter-level detail (e.g. the 10-item cap is left to 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 pair ('Move each version ... out of its asset into a new asset of its own') and fully specifies the outcome (same folder, named after the version, same sharing). It is clearly distinguishable from siblings like versions_add (its undo) and contents (which lists versions).

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?

Routes the agent explicitly: 'Undo it with versions_add' and 'contents(asset_id) lists an asset's versions' tell the agent when to reach for a sibling instead. The constraint that an asset always keeps at least one version and that already-alone versions return already_separate defines when the call is meaningful at all.

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 cover safety metadata, but the description adds rich behavior: blocking up to timeout_seconds, returning as soon as feedback arrives or empty on timeout, ordering rules for recordings and newer feedback, pending recordings, and the fact that the caller's own posts are excluded.

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

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

The description is dense but front-loads the core purpose and then layers in timeout behavior, pending handling, continuous listening, and alternative routing. It repeats some schema details like the default timeout, but most sentences carry distinct behavioral 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 blocking wait tool with no output schema, the description covers the essential agent decisions: what triggers a return, what empty means, how to continue listening, how pending items are handled, and which sibling to use instead. Nothing critical 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%, so the schema already documents asset_id, since, and timeout_seconds in detail. The description adds useful operational context beyond the schema, such as passing next_since from the previous response and refusing folder ids, though much of the parameter guidance is already present 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 and resource: waiting for NEW feedback on an asset. It clearly scopes the result to comments and replies by others, excluding the caller's own posts, and distinguishes itself from siblings like feedback_list, feedback_get, and recent_activity.

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

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

Explicitly routes usage: use after uploading a video instead of repeatedly calling feedback_list, use feedback_get for pending items, call again with next_since to listen continuously, and use recent_activity(folder_id) when a folder id is refused. Alternatives and when-not conditions are directly stated.

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