Playbook

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

Goes far beyond the annotations: it discloses the public-exposure consequence (a sensitive file becomes public), the sandboxing of HTML, the background copy with a ~20s wait and a `pending` class, quota caps per plan with whole-batch 422 refusal, partial-failure `remaining` semantics, write-scope and per-asset permission requirements, and the rule that one unknown token fails everything. Annotations only give readOnly/destructive/openWorld/idempotent hints; this description supplies the operational reality.

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 single dense paragraph is well front-loaded: purpose, then public-URL warning, then serving limits, then async/return-shape semantics, then edge cases and quota. Nearly every sentence carries decision-relevant information, but the wall-of-text form makes it harder to scan than it needs to be for the volume of distinct edge cases packed in.

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 carries the full burden of return semantics and does so completely: it enumerates `created`, `pending`, `already_had_permalink`, `no_file_to_publish`, `failed_to_publish`, `remaining`, and `quota`, and explains what each means and what the agent should do next. For a batch mutation with async completion and partial failure, this is the required level of detail.

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 both parameters, giving a baseline of 3. The description adds genuine semantics beyond it: the whole set must be sent in one call (not fanned out), the max-200 limit, that tokens already permalinked are skipped, and that a retry must use exactly the `remaining` token list. It also explains when to pass `organization` versus omitting it.

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

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

States a specific verb+resource ('give assets a permalink') and immediately defines what a permalink is and how it differs from the signed display_url. It also carves out what it is NOT for (hosting pages/apps) and names the sibling that handles that case. An agent can distinguish it from get_asset_permalinks, deploy_app, and share_asset from the first two sentences.

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 ('when a URL has to keep working — external site, deck, doc, hand-off') and explicit when-not-to-use ('never use it to host a page or app — deploy_app is for that'). It routes the agent to the correct follow-up (get_asset_permalinks to read URLs) and the correct pre-check (list_organizations for quota) rather than re-publishing.

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 far beyond the annotations, which only give readOnly/destructive/openWorld hints. It discloses the idempotency contract (same id + same content converges; same id + different content is 409 element_exists), the compare-and-swap semantics of expected_version_token, which 409s are safe to repeat, the converged/materialized response keys and their absence-when-false convention, and a one-hour public-page staleness window.

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 scope, then layered into error, concurrency, and response semantics; virtually every sentence carries operational weight. It is long and dense, but the length is justified by the tool's complexity rather than padding.

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

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

With no output schema, the description still explains the return payload (the slot as it now stands, element_id, the new version_token, converged/materialized flags), plus auth failures, concurrency conflicts, and caching delays. Nothing an agent needs to call it correctly is absent.

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

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

Schema coverage is already 91%, so the schema carries most parameter meaning, but the description adds real value: element.id as an idempotency token, props carrying HTML/URL must be strings, asset_token is copied into the page library, and expected_version_token is an echoed compare-and-swap value. The column_id vs column_index distinction is covered in the schema rather than the prose, leaving little to add.

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

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

Opens with a specific verb+resource+scope: insert one element into a slot of a published page, or into a section column when parent_element_id is given. It also names the sibling it differs from (update_page_element for changes, apply_page_operations for batches), so the agent can distinguish it without opening any schema.

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

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

Explicit routing: use update_page_element when the same id carries different content, and prefer apply_page_operations for several elements or a section plus contents (atomic). It also states the permission precondition (modify + page-layout API writes) and which errors are safe to retry versus which are not.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered; the description still adds substantial non-obvious behavior: unscoped searches span the whole workspace, nested_assets is required for parent boards or the search returns nothing, subtree matching can lag a board move whereas list_assets reads the database, and putting a person's name in `query` does not match the uploader. These are genuine gotchas not derivable from structured fields.

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

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

Front-loaded with purpose, then usage, then scoping, then the uploader pitfall — a sensible priority order with no filler sentences. It runs long for a description, but for a 13-parameter tool every paragraph carries operative guidance rather than restating schema fields.

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 13 parameters, no output schema, and rich annotations, the description covers calling correctly: scope, nesting, uploader resolution, date-field defaults, and payload retrieval. It stops short of describing the result shape or pagination flow (parent_id/after_cursor are left to the schema), which is the only meaningful gap for a tool of this complexity.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema does not: collection_token is framed as the scoping lever with a stated consequence, nested_assets is tied to parent-board tokens, and uploaded_by is tied to a list_members resolution step. The name-in-query pitfall is a semantic warning absent from the schema itself.

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

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

States a specific verb and resource ('AI-powered visual search for assets') and immediately qualifies what makes it distinct: it understands depicted content (colors, subjects, scenes, objects, compositions) rather than filenames or tags. It explicitly names the sibling it displaces ('Prefer this over search_assets'), so an agent can route correctly 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 concrete when-to-use examples ('ocean waves in blue', 'product shots on white background'), an explicit alternative and the condition that selects it (content-descriptive queries vs search_assets), plus a scoping recommendation with the failure mode for not scoping (moodboard/pitch reel returns other projects' assets). It also spells out the correct multi-tool workflow for uploader queries via list_members.

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?

Far exceeds the annotations (destructive, non-idempotent, open-world) by disclosing atomic rollback, the operation_index on failure, id-minting constraints, permission prerequisites (403 page_layout_api_disabled), compare-and-swap staleness behavior (409 stale_document applies nothing), which 409s are safe to retry, and the up-to-one-hour public propagation delay.

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 atomic batch purpose before the operational detail, and nearly every sentence carries a distinct operational fact. It is nonetheless a dense wall of text that could be tightened, which keeps it short of a 5.

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

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

For a complex, destructive, non-idempotent batch mutation with no output schema, the description covers error semantics, concurrency, permissions, and the exact shape of the response (slots, per-operation summaries, converged, materialized) — nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it points to get_page_elements_catalog as the authoritative argument map, notes unknown keys are refused, and explains the compare-and-swap role of expected_version_token and the new token returned after a successful write.

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

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

States a precise verb and resource — applying up to 50 page edits to a board's published page — plus the defining trait (ordered, atomic). It clearly differentiates itself from the single-operation siblings (add_page_element, update_page_element) by being the batched equivalent.

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 extensive operational context: each operation takes the arguments of the matching single tool, batch-level params are excluded, and one batch edits exactly one document. However, it never states plainly when an agent should prefer this batch tool over looping the single-tool siblings, leaving that routing decision to inference.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so safety is covered. The description adds meaningful merge semantics: tags not in either list are left untouched, which tells the agent that unrelated tags are preserved. It still omits auth/permission requirements and error behavior.

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

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

Three short sentences, front-loaded with the operation and scope, then parameter mechanics, then the key preservation guarantee. Every sentence earns its place.

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

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

With a fully documented schema, rich safety annotations, and no output schema, the description supplies the critical merge behavior and scope. It leaves minor gaps, such as overlap between add_tags and remove_tags, but is largely complete for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description only restates that add_tags and remove_tags are string arrays, adding no syntax, validation, or case-handling detail beyond the schema.

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

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

The description states a specific verb+resource (add/remove tags) and scope (single asset), which clearly separates it from generic asset-mutation siblings like update_asset. It does not explicitly name or compare against any sibling tool, so it falls short of the top-tier sibling-differentiation bar.

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 explains how to pass add_tags/remove_tags but never says when to use this tool instead of update_asset or any other tag-related operation. There is no context, prerequisite, or exclusion 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 mutation profile (readOnly=false, destructive=false, idempotent=false). The description adds meaningful context beyond them: the 202 Accepted asynchronous behavior, the delay before assets appear, and the required write scope. It stops short of explaining duplicate-call behavior or what asset properties are copied.

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

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

Three tightly written sentences with zero waste. The core action is front-loaded, followed by the async behavior and the auth requirement, in a logical order an agent can act on.

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 non-idempotent mutation tool with no output schema, the description covers the critical async return behavior and scope requirement. It leaves some gaps around failure modes, partial success, and exactly what gets copied, but the rich schema and annotations carry much of the remaining burden.

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

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

Schema description coverage is 100%, and the schema itself provides detailed parameter descriptions (including the nuanced organization parameter). The description only restates the two main parameters, adding no semantic detail beyond what the schema already provides, so baseline 3 applies.

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

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

States a specific verb ('Copy'), resource ('assets'), and scope ('into a target board'), with the one-or-more plurality. The verb 'copy' inherently distinguishes it from the sibling 'move_assets' without ambiguity.

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

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

Usage is implied by the operation described (copying assets), but there is no explicit guidance on when to choose this tool over alternatives like move_assets or create_asset_version. The write-scope requirement is a prerequisite, not a usage condition.

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 destructive/non-idempotent, but the description adds substantial context beyond them: live bytes are replaced while the current head is snapshotted, a write-scope token and versioning-enabled plan are required, private/loopback/metadata URLs are refused, and the comment lands on the replaced head's snapshot. This is rich disclosure of side effects and constraints.

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 in the first clause, then layers constraints, failure modes, and retry guidance in dense, non-redundant sentences. Despite its length, every sentence carries distinct decision-relevant 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?

No output schema exists, yet the description covers mutation semantics, auth/plan prerequisites, URL validation, size/multipart failure behavior, and the retry-vs-check procedure. An agent has everything needed to call it correctly and handle failure.

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

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

Schema coverage is 100%, so the schema already documents all 8 parameters and the baseline would be 3. The description adds operational meaning beyond the schema: it clarifies the uri constraint (public https, private hosts refused) and explains the comment's placement relative to revert semantics, though most param detail duplicates 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: uploading a file from a public URL as a NEW VERSION of an EXISTING asset, and explicitly contrasts with creating fresh assets by noting the asset keeps its token, boards, and links. An agent can distinguish this from siblings like upload_from_url or create_upload_url immediately.

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 (existing asset + versioning enabled) and when-not (files needing multipart or over the cap are refused and redirected to the Playbook web/desktop app). It names list_asset_versions as the recovery step after a timeout and forbids blind retry, which is exactly the alternative-selection guidance a caller needs.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the agent knows this is a non-destructive, non-idempotent write. The description adds the useful default behavior that omitting parent_collection_token creates at the workspace root, but says nothing about permissions, side effects, or failure modes beyond that.

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

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

Two short sentences, front-loaded with the core action and then the optional variant. Every clause carries information and nothing is padded.

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

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

For a simple create tool with full schema coverage and annotations covering the safety profile, the definition is nearly sufficient. The only minor gap is that with no output schema, the description does not hint at what the created board returns (e.g. a token), which an agent may need for follow-up calls.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema, including the org-resolution rules and the parent token default. The description's mention of parent_collection_token largely restates what the schema already says, 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?

Specific verb+resource (create a board) with scope stated (in a workspace) and a distinguishing capability (nesting under a parent board). An agent can separate it from update_board, get_board, and the many other create_* siblings without opening a schema.

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

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

The description implies when the optional nesting parameter applies, but gives no explicit when-to-use vs alternatives guidance (e.g. when to create a root board vs. a nested one) and no prerequisites. Usage is inferable from the schema's organization parameter notes rather than the description itself.

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

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

Adds substantial behavior beyond the annotations: atomic failure semantics ('An unrecognized value fails the whole call with 406 — nothing is created'), no upload or polling step, merge-into-group behavior for multi-code calls, null `group` for single-code calls, and the silent anonymous-board fallback. The description is consistent with destructiveHint=true and 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?

The purpose is front-loaded and each sentence carries operational weight (formats, error behavior, auth scope, validation tip). It is dense rather than padded, though the colour-format enumeration partially duplicates the schema and makes the paragraph long.

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 five parameters, no output schema, and a mutation with destructive semantics, the description covers return shape (`group` vs null), error behavior, auth scope, and a critical pre-validation step. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: the group/palette merge behavior tied to color_codes cardinality, the exact Pantone prefix convention ('185 C' not 'PANTONE 185 C'), and the rationale for omitting/passing `organization`. It does not fully explain `parent_token` beyond a brief gloss.

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

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

States a specific verb and resource ('Add colour swatches to a Playbook board') and immediately scopes the concept ('building blocks of a palette or a brand's colour spec'). This clearly separates it from siblings like create_board, create_note, or create_asset_version.

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

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

Gives concrete preconditions and routing advice: send one code vs two or more (different return semantics), requires a `write` scope token, and explicitly recommends validating `collection_token` with get_board first because unknown tokens silently fall back to a default board. It lacks an explicit 'do not use this when...' statement, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds the "top-level only" scoping rule, which is real behavioral context, but says nothing about permissions, duplicate handling, or visibility on the target.

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

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

Two sentences, the core action front-loaded and the hard constraint immediately after. No filler, no restating the title.

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

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

The tool is a simple non-idempotent create with no output schema, and annotations plus the fully documented schema cover most of what an agent needs. The mutual-exclusion and top-level rules are surfaced; only error/failure behavior is left implicit.

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

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

Schema description coverage is 100%, including the mutual-exclusion notes on asset_token/board_token and a detailed organization explanation, so the schema carries the burden and baseline 3 applies. The description's restatement of the xor constraint is accurate but adds nothing beyond the schema.

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

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

States a specific verb ("Post") and resource ("top-level comment") plus the two target types ("asset or board"). The "top-level" qualifier distinguishes it from nested/reply comment operations, so an agent can place it against siblings like get_comments and edit_asset_version_comment 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?

Usage is implied rather than stated: the description establishes the create-comment intent and the mutual-exclusion requirement, but never names when to choose this over get_comments (reading) or edit_asset_version_comment (editing), nor any prerequisites. Adequate but with a clear gap.

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

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

Annotations flag destructiveHint=true and idempotentHint=true, and the description richly corroborates beyond them: it discloses exactly what is destroyed (options omitted are deleted, removing the value from every asset holding it), the plan quota on new fields, auth requirements (write scope + owner/admin), and exact-name matching with error behavior on unknown names. No contradiction with the annotations.

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

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

Front-loads the primary create/replace behavior, then caveats, quota, and auth. It is dense and long, and a couple of statements (Status-field protection, options replacement) partially restate the schema, but nearly every sentence carries actionable information, so the length is largely earned.

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

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

Given four params, one mutation with destructive side effects, no output schema, and a large sibling set, the description covers creation, overwrite semantics, quota limits, auth, sibling routing, and value-setting. An agent has everything needed to call it correctly; the absent output schema is not a gap since nothing about the response is required to invoke 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 per-parameter detail largely duplicates schema text, but the description adds cross-parameter semantics: the field_type/options dependency (select needs non-empty options; date/person/url pass field_type and omit options), the unchanged return for a same name+type field, and refusal when the name belongs to another type. That is genuine meaning beyond the schema, though much overlaps.

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

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

The opening sentence gives a specific verb (Create / REPLACE) and resource (custom field on a workspace), and immediately distinguishes the dual create-or-overwrite behavior. It differentiates itself from siblings by naming delete_custom_field's counterpart (list_custom_fields), update_asset_status, and update_asset explicitly, so an agent can route without opening another schema.

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

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

Explicit when-to-use and when-not guidance: check list_custom_fields first if the field may exist, do NOT use this for the built-in 'Status' field (use update_asset_status), and set a field's VALUE via update_asset's `fields` argument because no separate tool exists. The alternatives are named with the conditions that select 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?

Adds substantial context beyond the annotations: confirms the note returns synchronously with no upload/polling step, states the required `write` scope, and discloses the critical silent-failure mode where an unknown collection_token falls back to an anonymous default board. It also explains the color omission consequence (average_color: null is not a failed write). These are exactly the traps an agent needs flagged.

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, then usage, behavior, auth requirement, and the get_board tip in a logical order. Every sentence carries information, though the density makes it longer than strictly minimal for a 10-param 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?

Covers creation semantics, sync return behavior, auth scope, the silent-fallback risk, and the no-output-schema case by stating what is returned. For a mutation with 10 parameters and no output schema, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the schema descriptions are unusually detailed (color palette, organization resolution, collection_token fallback), so the schema does the heavy lifting. The description largely restates the collection_token warning rather than adding new per-parameter meaning, so baseline 3 is correct.

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

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

States a specific verb and resource ('Add a note to a Playbook board') and immediately differentiates it from file-based siblings by defining it as 'a sticky-note asset that holds text rather than a file.' An agent can distinguish it from create_comment, add_page_element, and upload_* 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 use contexts ('a brief, a caption, a to-do, context for the assets around it') and a specific prerequisite workflow: validate collection_token with get_board first. It does not name an alternative tool for cases where the agent wanted a file asset, but the usage condition is otherwise clear.

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

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

Adds substantial context beyond the annotations: requires a token with the `write` scope, requires a caller capable of making HTTP requests, returns a one-time address, and enforces a hard 104857600-byte ceiling with an explanation (single-request transfer). It also contrasts Playbook's five-minute streaming fetcher budget against this path's lack of it. This is rich, non-obvious behavioral disclosure.

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

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

Purpose is front-loaded ('Step 1 of 2...'), then the preference and fallback routing follow. It is long and dense, but nearly every clause carries routing or constraint information, so little is wasted; a slightly tighter phrasing would reach 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 still explains what comes back (a one-time address plus exact HTTP requests to make) and how the two-call flow completes. Combined with full schema coverage and 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 coverage is 100%, so the schema already documents all four parameters, setting the baseline at 3. The description adds the 104857600-byte ceiling that constrains the `size` parameter and reinforces the cross-call state (title must be re-passed to finish_upload), giving modest value beyond the schema.

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

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

States a specific verb+resource and frames it as 'Step 1 of 2 for uploading a file you already HOLD', immediately distinguishing it from the fetch-based sibling upload_from_url and from finish_upload. An agent can tell exactly what this produces: a one-time address plus the HTTP requests to send.

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: 'Prefer upload_from_url whenever the file is already at a URL', then enumerates the exact conditions that select this tool instead (no URL, URL behind a login, expired signed URL, blocked host, failed ingest), and names share_board with enable_uploads as the fallback when neither route is available. When-to-use, when-not, and alternatives are all covered.

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

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

Annotations declare a non-read-only, non-idempotent, non-destructive mutation, but the description adds substance beyond them: the returned batch_id holds a reservation against the workspace quota until completion, and the call is all-or-nothing ('if any single file cannot be handled the whole call is refused'). The uuid echo behavior is also disclosed. Lacks return-shape detail, which is minor.

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, mechanics, the uuid rationale, the batch_id/quota warning, and the alternative are all front-loaded into one dense paragraph with no filler sentences. Slightly long, but every clause carries operational weight.

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

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

For a mutation tool with no output schema, the description covers the return value (batch_id), the cross-call dependency (finish_uploads), the quota/cost implication, and the failure mode. An agent has everything needed to call it correctly without opening other tools.

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

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

Schema coverage is 100% so the baseline is 3, but the description genuinely adds rationale the schema lacks: why a caller-supplied uuid matters ('with several similar files it is the only reliable way to tell which address belongs to which file') and why the batch_id must be passed back. It also reinforces the 'measure, do not estimate' size 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?

States a specific verb and resource ('request upload addresses for up to 100 files in one call') and explicitly frames itself as the batch form of create_upload_url. The agent can immediately distinguish it from the singular sibling and from upload_from_urls.

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 ('prepare a batch only when you are ready to finish it'), a named alternative with the condition that selects it ('Use upload_from_urls instead when the files are already at URLs Playbook can fetch'), and the required follow-up call (finish_uploads). Nothing is left to inference.

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

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

Annotations already declare destructive=true, idempotent=false, openWorld=true, but the description goes well beyond them: exact timing of address failure (within a minute), slug redistribution to any workspace, permanent file loss, the fact that board and assets are unaffected, and a specific error code path with an escalation instruction.

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

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

Four front-loaded sentences with no filler: the action, the irreversible consequence, the blast radius, and the permission/error prerequisites. Each sentence carries distinct information an agent needs before invoking.

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

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

For a destructive, non-idempotent tool with no output schema, the description covers reversibility, side effects, scope boundaries, required permissions, and the unhandlable error case. Nothing material to correct invocation is missing.

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

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

Schema description coverage is 100% and both parameters are documented in the schema itself, including the slug pattern and the single-vs-multi-workspace resolution rule for organization. The description adds nothing parameter-specific, so the baseline 3 applies.

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

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

States a specific verb+resource ('Take a hosted app offline and delete it') with a clear scope statement about what happens to the app's address and slug. An agent can distinguish this from delete_asset and delete_board immediately, and the description reinforces that the board and its assets are untouched.

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 frames the tool as non-reversible and names deploy_app as the alternative path to bring the app back, plus states the prerequisites (write scope, board-edit permission, hosted apps enabled). The hosted_apps_disabled 403 case and the instruction to tell the user to contact support give the agent a concrete fallback behavior.

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 supply destructiveHint=true and idempotentHint=false, and the description adds genuinely new behavior: the deletion is soft and recoverable from the Playbook trash for a limited time. That materially changes an agent's risk calculus. It stops short of a 5 because it says nothing about permissions or what happens once the trash window lapses.

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

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

Two short sentences, no filler, and the critical reversibility caveat is stated immediately after the action. Every sentence earns its place.

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

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

For a two-parameter, fully documented delete operation with strong annotations, the description covers the essentials an agent needs. Nothing about return values is required since no output schema exists, though a note on the recovery window duration would make it complete.

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

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

Schema coverage is 100%, with both token and organization fully documented in the schema (including when to omit the workspace slug). The description adds no parameter meaning of its own, so the baseline 3 applies.

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

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

States a specific verb (soft-delete) and resource (asset), and the 'soft' qualifier meaningfully distinguishes it from a hard destroy or from revert_asset. It does not explicitly name a sibling, so it stops short of a 5.

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

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

Implies usage through 'soft-delete an asset' and notes the reversibility window, which hints at when it is safe to call, but it never states when to prefer this over alternatives such as revert_asset, or any prerequisite conditions. Guidance is implied rather than explicit.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds one genuinely new fact — that all board contents are deleted along with the board (cascade) — but says nothing about irreversibility, recovery, or required permissions. 'Destructive.' merely restates 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?

Two short sentences, front-loaded with the action and scope. The second sentence ('Destructive.') largely duplicates the destructiveHint annotation rather than earning its place, but the overall text is tight and waste-free.

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 irreversible cascading deletion with no output schema, the description covers the minimum: what is removed. It omits recovery expectations, permission requirements, and how to obtain the token, which an agent would benefit from before invoking a destructive operation.

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

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

Schema description coverage is 100%, and the organization parameter has a thorough inline description explaining when to pass or omit it. The tool description adds no parameter meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (delete) and resource (board), plus the scope of the operation — 'and all of its contents' — which signals a cascading delete. It does not distinguish itself from sibling delete_* tools, but the name and verb make the target unambiguous.

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

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

No guidance on when to use this versus update_board, or on prerequisites such as needing a board token obtained from list_boards/get_board. There is no mention of alternatives or conditions under which deletion is appropriate.

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

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

Annotations already declare destructiveHint=true, but the description adds substantial beyond-annotation context: values are stripped from every asset, the action is not reversible, the Status field is protected, and it requires a write-scope token plus owner/admin permission. Auth and irreversibility are exactly the extra disclosure the annotations don't carry.

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

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

Front-loads the destructive effect and irreversibility in the first two sentences, then appends the protection and auth constraints. Every sentence carries distinct, actionable information with no padding.

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

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

For a destructive 2-parameter tool with no output schema, the description covers impact, irreversibility, protected resources, parameter source, and auth requirements. An agent has everything needed to call it correctly and safely.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a meaningful clarification that the token must be the identifier from list_custom_fields and explicitly not the field's name — a real semantic guard beyond the schema text.

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

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

States a specific verb (Delete) and resource (custom field), plus scope ('of any type, with all of its options'). It is clearly distinguishable from sibling create_custom_field and read-only list_custom_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 concrete context for use: it names the source of the token (list_custom_fields) and explicitly excludes the built-in 'Status' field, which cannot be deleted. It does not name an alternative sibling, but the when/when-not conditions are present.

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

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

Adds substantial behavioral detail beyond the annotations: cascade semantics for sections, permission and workspace-enabled requirements, exact error codes (403 page_layout_api_disabled, 409 stale_document), version token handling, idempotency via converged/materialized flags, and a one-hour propagation delay for the public page. This is exactly the kind of context 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 dense but all sentences earn their place; the core action is front-loaded and edge cases follow logically. Nothing is redundant, and each sentence adds critical operational detail.

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?

Despite having no output schema, the description explains return semantics (converged, materialized, version_token) and covers permissions, concurrency, error handling, and propagation delay. An agent has everything needed to invoke and interpret results correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning: it clarifies that element_id must match slot_id (else 404) and explains how to use expected_version_token from get_page_layout for compare-and-swap. That is useful semantic guidance beyond the schema.

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

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

States a specific verb+resource ('Remove an element from a board's published page') and clarifies it returns the slot as it now stands. An agent can distinguish this from siblings like update_page_element or move_page_element 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?

Provides rich context about when the call succeeds (id nowhere on page) and when it fails (id in a different slot returns 404, missing permissions return 403), plus concurrency behavior with version tokens. It does not explicitly name an alternative tool, but for a delete operation the when-to-use conditions are thoroughly covered.

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

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

Annotations declare destructive/idempotent/openWorld, and the description goes well beyond them: the app is public with no login, files must never contain secrets, the only write is visitor uploads under stated share-link conditions, plus hard limits (index.html required, 50 files/1 MB, 10 apps/workspace), write scope requirement, and the 403 `hosted_apps_disabled` failure mode that no tool can fix.

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

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

Purpose is front-loaded and each block (contract, public exposure warning, limits, failure modes) earns its place, but the description is very long and dense for a single tool, with some packaging detail that could be delegated to the referenced `hosted_apps` topic.

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, open-world deploy with a nested `files` object and no output schema, the description supplies everything needed: return value (`url`), prerequisites, constraints, idempotency behavior, and the un-actionable 403 case with user-facing guidance.

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: a deploy replaces the whole file set so every file must be re-sent, files are public, and board_token scope is limited to the board and its sub-boards. It stops short of restating per-parameter syntax, which the schema already handles.

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 gives a concrete verb and resource ('put a small web app... live at a public address, or replace the files of the app...') and defines what a hosted app is (static files, one board and its sub-boards). It is clearly distinguishable from delete_app and list_apps, which appear in the sibling list.

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 routing: read the `hosted_apps` topic with read_documentation BEFORE writing files, confirm the board with the user because the app is public, and check list_apps first if the call times out instead of re-deploying blindly. When-to-use-vs-alternatives is fully covered.

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

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

Goes well beyond the annotations (readOnly=false, idempotent=true, destructive=true) by disclosing the required scope, the versioning-enabled precondition, the exact blast radius (does not change bytes or head), the clear-with-empty-string behavior, and the not-found error for unknown/out-of-range versions.

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 address key, then preconditions, then the side-effect exclusions. Every sentence carries information, though the trailing head_version_number arithmetic adds density that could be split or trimmed.

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

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

No output schema exists, yet the description covers auth scope, preconditions, side effects, edge cases (empty string, unknown version), and failure mode. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuinely non-obvious meaning: empty string clears the comment, and the newest stored version is `head_version_number − 1` rather than the head value itself. That resolves a real ambiguity an agent would otherwise hit.

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 ('Edit the comment/note on an existing asset version') and pins the addressing key (`version_number`). It also explicitly differentiates from the nearest siblings by declaring it does NOT create a version, which separates it from create_asset_version.

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

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

Gives a clear prerequisite path ('Use `list_asset_versions` to find the `version_number`') and states the conditions required (write-scope token, versioning enabled). It does not name the alternative tool to use when you actually want a new version, so it stops short of full when/when-not routing.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: this call 'does not transfer anything, it records what landed', which corrects the likely assumption that finish_upload moves bytes, and it implies the retry semantics by requiring a fresh create_upload_url on failure. It stops short of stating explicitly what happens to a partially-recorded asset.

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

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

Three sentences, front-loaded with the workflow position and purpose, then the precondition, then the failure exclusion. Every sentence earns its place and nothing is repeated.

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

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

For a non-idempotent mutation with 11 params, a nested object and no output schema, the description supplies the crucial orchestration context (two-step flow, ordering precondition, failure handling) that the schema cannot express. It is nearly complete; the only thin patch is what the caller gets back or how to confirm the asset landed, which is arguably outside description scope given the sibling get_asset exists.

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

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

Schema description coverage is 100%, so all 11 parameters are already documented in-schema, including the signed_gcs_id and media_type 'pass it back unchanged' constraints. The description re-states the signed_gcs_id rule but adds no syntax or format detail the schema lacks. Baseline 3 applies when the schema carries the load.

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

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

States a specific verb and resource ('turn bytes you have already sent to storage into a Playbook asset') and frames itself as 'Step 2 of 2', which cleanly distinguishes it from the sibling create_upload_url that precedes it. An agent can place it in the upload workflow without opening any schema.

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

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

Gives explicit when-to-use ('only after every step returned by create_upload_url has succeeded') and an explicit when-NOT-to, with the alternative action spelled out ('If a step failed, do NOT call this; start over with a fresh create_upload_url'). 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?

Discloses traits the annotations cannot express: the call is NOT atomic, creates assets one at a time, does not roll back, and a partial failure leaves earlier assets created while reporting an error. The no-retry rule is a behavioral constraint beyond idempotentHint=false and does not contradict 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?

Three sentences, front-loaded with purpose, then the inclusion rule, then the failure warning. Every sentence carries a distinct operational constraint and nothing is repeated from the schema.

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

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

For a non-atomic mutation tool with no output schema, the description covers the failure and recovery model well, and the schema covers the per-item fields and the echoed uuid. It stops short of describing the success response shape or partial-success reporting, which is the one gap an agent calling a non-atomic batch would want.

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 batch_id, assets and collection_token semantics are already fully documented in the schema, including the quota-release role of batch_id and the silent default-board routing. The description adds no parameter-level detail of its own, so the baseline 3 applies.

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

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

States a specific verb and resource ('turn bytes already sent to storage into assets') and immediately scopes it as the batch counterpart of finish_upload, letting an agent separate it from that sibling without opening either schema. The 'all on the same board' clause adds the batch-level constraint that distinguishes the two.

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 which items to include ('only the items whose byte transfers actually succeeded') and gives a hard prohibition with a pointer to the alternative path ('Never retry it after a failure; see the recovery steps in the error itself'). The relationship to finish_upload is stated, so selection between the two is unambiguous.

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 readOnly/non-destructive/non-open-world, and the description layers on substantial extra behavior: signed display URLs expire in ~24h while permalink does not, colors is empty for anything with no rendered preview (meaning 'not analysed', not 'colourless'), stream_url stays null until HLS encoding finishes, and reading never triggers an encode. These are real operational traits an agent needs and none are in the annotations.

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

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

Front-loads purpose, then the sibling routing rule, then return-field semantics — a logical order with no filler sentences. It is dense for a single-token getter, but each clause (expiry, colors emptiness, stream_url) carries distinct information rather than restating 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 carries the return-value burden and does so thoroughly: enumerates the metadata returned, explains URL expiry, colors ordering and edge case, and the video stream_url precondition. Nothing an agent needs to call and interpret 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 description coverage is 100% and the organization parameter already carries rich usage guidance in the schema itself. The description reinforces 'ask for an asset by token' but adds no new syntax, format, or meaning for either parameter, so the baseline 3 is appropriate.

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

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

States a specific verb+resource ('Get full details of a specific asset by its token') and explicitly distinguishes itself from the sibling get_assets, including the behavioral difference (this one always returns ai_agent_payload; get_assets makes it opt-in). An agent can route between the two 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 guidance: use get_assets for more than one asset (up to 100 per call) and avoid looping this tool, plus 'ask for an asset by token' because list/search results don't carry colors. It names the alternative and the condition that selects it, and points to retry_video_processing for the stream_url case.

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/non-destructive, and the description adds substantial non-obvious behaviour: the URL is unauthenticated, expires in about a day, file contents do not pass through the server, each asset read consumes one API request against quota, and download permission is required per asset. It also enumerates response buckets (no_file, not_found, failed) which an agent needs to interpret outcomes.

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?

Dense but well ordered: the core purpose comes first, then edge-case handling, then permissions and quota limits. Every sentence carries distinct operational information with no filler or repetition of the title.

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

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

With no output schema, the description compensates fully by explaining the returned URL properties (unauthenticated, ~1-day expiry) and the failure/skip categories an agent will encounter. Permission, quota and batch-size constraints are all covered, leaving nothing essential unstated.

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

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

Schema description coverage is 100%, so both parameters are already documented, including the max-25 constraint and the workspace-resolution rule for `organization`. The description adds no syntax or format detail beyond the schema, so the baseline 3 applies; its token-level semantics (link assets returning a null size) describe results rather than inputs.

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 signed URL of the ORIGINAL file of one or more assets') and immediately disambiguates from near neighbours by contrasting the original bytes with `display_url`, previews and image permalinks. An agent can distinguish it from get_asset_previews, get_asset_permalinks, and get_asset without opening a schema.

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

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

Gives explicit when-to-use guidance ('hand a full-quality video, PDF, font or source image to another system, or fetch it yourself') and an explicit exclusion plus alternative: if the URL must keep working longer, use `add_asset_permalinks` instead. The requirement of download permission and the 25-asset limit are also stated up front.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial context beyond them: it never publishes, assets without a permalink appear under `not_published`, and `pending` assets withhold the URL until the file is in place. These status behaviors are not derivable from the annotations or schema.

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

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

Front-loaded with the core purpose before the status edge cases and the sibling alternative. It is dense and long, but nearly every sentence earns its place; only the use-case list ('a document, a deck, a web page...') is slightly padded.

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

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

No output schema exists, yet the description explains the meaningful return states (`not_published`, `pending`) and the resize semantics, which is what an agent needs to interpret results. Complete for a read tool whose safety profile is already carried by annotations.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real semantics: width/height resize IMAGES only, supplying one keeps the aspect ratio, and PDFs/video/other types ignore both. It does not elaborate on asset_tokens or organization, but those are fully covered by 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 ('Read the permanent public URL of one or more assets') plus an optional rendering behavior, and explicitly differentiates itself from get_asset_previews. An agent can distinguish it from 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?

Explicit routing rules: run add_asset_permalinks first for assets under `not_published`, re-read rather than re-publish for `pending`, and use get_asset_previews instead for a throwaway image. Names the alternatives and the exact conditions that select 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 only declare the safety profile (readOnly, non-destructive, not open-world). The description adds rich behavior beyond that: URLs are short-lived (~1-2 hours), a size is mandatory or you get the full render back, non-image assets return URLs that won't load, no-file assets land in no_file_to_render, unknown/invisible tokens land in not_found, and one render per token per call.

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

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

Front-loads the core purpose, then the size requirement and image-only constraint, so the agent hits the critical rules early. It is long and heavy on caps emphasis, with a couple of sentences that could be tightened, but nearly every line carries a distinct constraint.

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-param tool with no output schema, the description compensates by naming the response buckets (no_file_to_render, not_found, URL-per-asset) and the size/format/media constraints. An agent has enough to call it correctly and interpret the result without an output schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema cannot: why width/height must be supplied (otherwise the same full-size render), and the token-visibility semantics behind not_found. It stops short of adding format or organization guidance beyond what the schema already carries.

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 ('Render one or more assets as images... get a URL per asset') and explicitly distinguishes itself from the full-size display_url render and from get_asset_permalinks. An agent can tell it apart from get_asset and get_asset_permalinks without opening any schema.

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

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

Gives explicit when-to-use ('This is how you LOOK at Playbook assets'), when-not ('wasteful to fetch and too large for most vision models'), and the alternative for durable links ('anything that must keep working later... needs get_asset_permalinks'). It also states the pre-condition (check media_type starts with image/).

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 establish readOnly/non-destructive/openWorld=false, but the description adds substantial behavioral detail beyond them: partial-failure semantics for unknown or invisible tokens in not_found, the contrast with list_assets regarding grouped children, and the return-field scope. It also warns that get_ai_payload defaults differently here than in get_asset and that payload responses can be very large.

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 batch purpose and the get_asset alternative are front-loaded, and each subsequent sentence carries a distinct constraint (return fields, loop avoidance, not_found handling, grouped children). No sentence is redundant with the title, annotations, or schema prose.

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

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

With no output schema, the description compensates by naming the fields returned, explaining the not_found bucket, and calling out the get_ai_payload size/default difference. For a 3-parameter read tool with annotations covering safety, this is complete enough for correct invocation.

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

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

Schema description coverage is 100%, so each parameter already has its own detailed description; the baseline is 3. The description reinforces the 1-100 bound and the not_found behavior but adds little parameter-level meaning beyond the schema for organization or get_ai_payload.

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 ('Get full details for up to 100 assets'), identifies the tool as 'the batch form of get_asset,' and explicitly contrasts it with list_assets and get_asset. An agent can distinguish it from every relevant sibling 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 a concrete usage sequence ('after list_assets or a search'), an explicit preference rule ('Prefer it over calling get_asset in a loop'), and a scoping contrast with list_assets ('Grouped child assets ARE returned here, unlike in list_assets'). It also explains when not to expect success for individual tokens via the not_found bucket.

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

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

Annotations already declare readOnlyHint, non-destructive and closed-world, so the safety profile is covered. The description goes beyond that by disclosing semantics an agent could not infer: asset_count includes nested boards (each group/stack counted once), published_page url is null unless live, and template can be set on a non-live page. That is real added behavioral context.

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

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

Front-loaded with the core purpose, then the return-field semantics in a compact block. Every sentence carries information, though the asset_count/list_assets sentence is dense and slightly long-winded.

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 must describe the return shape — and it does, naming title, description, asset_count, parent board, child board count and published_page sub-fields. Complete enough for a two-parameter read tool; only the child/parent field formats remain unspecified.

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

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

Schema description coverage is 100%, so token and organization are already fully documented (including the token-vs-share-link trap and workspace omission rule). The description only repeats 'by its token' and adds no format or edge-case guidance beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource ('Get details of a specific board by its token') and enumerates exactly which fields come back. This distinguishes it from list_boards/list_board_children, though it never names an alternative explicitly.

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

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

Usage is implied rather than stated: there is no 'use this when you already have a token' or 'to enumerate boards use list_boards instead'. It does give one actionable comparison rule (asset_count vs list_assets without nested_assets), but no when/when-not framing against the many sibling read tools.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds no behavioral context beyond the implied read (no pagination behavior, ordering, or result scope), so it earns little credit even against the lower annotated bar.

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

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

Two short sentences with no filler and the core action front-loaded. The second sentence is somewhat redundant with schema content, which keeps it just short of a 5.

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

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

For a read-only list tool with annotations and full schema coverage this is minimally complete, but with no output schema the description could have said something about pagination (the page parameter) or what the returned comments contain. Those omissions leave a gap.

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

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

Schema description coverage is 100%, so all four parameters (including the organization workspace nuance and page) are already fully documented in the schema. The description's restatement of entity_type values adds nothing beyond the enum, so the baseline 3 applies.

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

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

States a specific verb (List) and resource (comments) plus the scope (asset or board), so an agent can tell what the tool does. It does not, however, explicitly contrast itself with the closely related create_comment or edit_asset_version_comment siblings.

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

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

There is no when-to-use or when-not-to-use guidance; the second sentence merely restates the required parameters already present in the schema. Nothing tells the agent to prefer this over create_comment or edit_asset_version_comment.

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 read-only safety profile, and the description goes well beyond them by documenting a rate limit, the meaning of `skipped`, and the full semantics of every `cancel_reason` value (including that nothing past an overlimit point was stored). This is exactly the operational context an agent needs and cannot get from structured fields.

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

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

Front-loaded with the core purpose, and the dense enumeration of status/cancel_reason values is justified because no output schema exists to carry that information. The backtick-heavy value list is slightly unwieldy but every clause carries meaning.

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 shoulders the burden of explaining the return payload, and it does so thoroughly, including terminal-state interpretation. Combined with annotations covering safety, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100%, so both `token` and `organization` are already fully documented in the schema, and the description adds no further parameter guidance. The mention of `board_token` and `files` describes returned fields, not inputs, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('Read an import run's progress') and immediately enumerates the fields it returns, so the agent knows exactly what this retrieves. The `token` semantics tie it to import_from_google_drive/import_from_dropbox, distinguishing it from the tools that start imports rather than report on them.

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

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

Clear context is given: this is the polling tool for an in-progress import, with an explicit cadence constraint ('Poll no more than every 15-30 seconds'). It does not name an alternative or state when not to use it, so it stops short of full routing guidance, but the intended usage is unambiguous.

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 readOnly/openWorld=false, and the description adds substantial operational context beyond them: the ~40 KB props payload is only returned for types named in the argument, dead props are stored but not rendered, and the catalog is identical for every workspace. It also discloses a design constraint (no carousel element; use sections or a grid with horizontalView/autoScroll).

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?

It is dense and long, but front-loaded with the core purpose and downstream consumers before the return-value detail; nearly every sentence carries actionable information, though the style/carousel guidance could be trimmed slightly.

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 carries the burden of explaining return structure, the conditional props behavior, and the element taxonomy (sections, columns, banner, notes/assets, style prop), leaving nothing essential for correct invocation unstated.

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

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

Schema coverage is 100% and the schema description already explains the element_types argument's effect and unknown-type refusal, so baseline is 3. The description adds the ~40 KB size hint that matters for request planning, which is a genuine incremental detail over the schema.

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

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

The description defines the tool as 'the vocabulary for designing a board's published page' and then enumerates exactly what it returns (templates, element_types, enum_sets, background_colors, typographies, operations, limits), making its distinct role unmistakable against siblings like get_page_layout or publish_board.

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

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

It states an explicit imperative timing rule — 'read it BEFORE publishing with a template or writing any page element' — and ties its outputs to the sibling tools that consume them (publish_board, update_page_settings, apply_page_operations), so an agent knows precisely when this must be called.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial context beyond them: the verbatim return contract (ids/camelCase keys match the element tools), the meaning of slots:null, the first-write-stores-defaults lifecycle, the 404 error code semantics, and that reads bypass the page-layout write flag.

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 dense but well-ordered block that front-loads the purpose and return contents before edge cases. It is somewhat long, and given there is no output schema the extra detail on lifecycle and errors mostly earns its place, though minor compression would help.

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 compensates by explaining every returned field, the null/inheritance semantics, and the 404 path. An agent has everything needed to call it correctly and interpret the result.

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

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

Schema coverage is 100%, so both token and organization are fully documented in the schema itself, including the organization-omission guidance. The description adds no parameter-specific syntax or format detail, so baseline 3 is appropriate.

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

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

Names a specific verb+resource: reading the stored design of a board's published page, and enumerates exactly the fields returned (template, background_color, typography, slots, subboards_settings, version_token). An agent can immediately distinguish this from sibling page tools like get_page_elements_catalog which return element catalogs.

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 conditions: use publish_board with a template when 404 page_layout_not_found occurs, address unedited pages by slot name via get_page_elements_catalog, and notes reads aren't gated by the write flag. It lacks an explicit 'use X instead when...' comparison against sibling element-read tools, but the contextual routing is strong.

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

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

Annotations already flag destructiveHint=true and readOnly=false, and the description goes well beyond them: it discloses the required write scope, the two 422 rejection conditions, that children move to the parent's board, and that a group has no file and derives its preview from its first displayable child. This is exactly the extra context annotations cannot carry.

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

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

Front-loaded with the core action and concept, and the operational warnings are grouped near the end. It is dense but nearly every sentence adds distinct value; slight length is justified by the non-obvious data model.

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

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

For a destructive, non-idempotent mutation with no output schema, the description covers purpose, auth scope, failure modes, and side effects (children moving boards). An agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so baseline is 3, but the description adds meaningful semantics beyond the schema: it clarifies that parent_asset_token may be an existing group or spawns a new one, and warns to pass the group's own token rather than a member's.

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 ('Merge assets into a group') and then defines what a group actually is, which is essential given the unusual data model. It clearly distinguishes this from siblings like ungroup_assets and move_assets by explaining the container/member relationship.

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 conditions for use: pass the target asset as parent_asset_token, add to an existing group by passing the GROUP's token, and ungroup a child first if it belongs to another group. It does not explicitly name alternative sibling tools (e.g. move_assets, ungroup_assets) for adjacent tasks, so it stops short of a 5.

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

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

Goes well beyond the annotations: discloses async execution (returns pending, poll get_import until completed/canceled), the re-sync skip logic and the duplicate-asset risk for changed/renamed folders, one-active-import-per-workspace limits, storage-overage refusal, rate-limit retry delay, and the required write-scope + owner/admin auth. The idempotentHint=false annotation is consistent with the described partial-skip-but-adds-second-asset behavior.

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

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

Front-loaded with purpose, then structured under clear FOLDERS / RE-SYNC / WHERE FILES LAND headings that make it scannable. It is verbose (~450 words) but the density is warranted by the tool's async, re-sync and duplicate-handling complexity; little is pure 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, and the description fills that gap by explaining what the call returns (a run in pending, polled via get_import) and where imported files land (a named sub-board found via list_board_children or list_assets). Auth, failure modes, and connection prerequisites are all covered.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema, including folder URL/path/id formats, the refused shared-link/root cases, board_token re-sync semantics, and organization resolution. The description largely reinforces rather than extends these, so the baseline 3 applies.

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

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

States a specific verb+resource ('Import Dropbox folders into a board') and immediately distinguishes itself from the closest sibling: 'upload_from_url cannot reach those' for private/team Dropbox folders. An agent can route between this, import_from_google_drive, and upload_from_url 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?

Explicit when-to-use with the alternative named ('files that live in the user's Dropbox... upload_from_url cannot reach those'), plus guidance for the no-source case ('when list_import_sources has no source... its connect_url is where a person connects'). Re-sync guidance tells the agent when to reuse board_token vs create a new board.

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 (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true) only sketch the safety profile; the description adds substantial non-obvious behavior: asynchronous run in `pending`, per-folder validation against the connected account, re-sync dedup but duplicate-on-change and full re-import on rename, storage-overage refusal/cancel, rate-limit retry delay, and write-scope plus owner/admin 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?

Long but front-loaded and organized with ALL-CAPS section markers (RE-SYNC, WHERE FILES LAND) so an agent can scan it. Nearly every sentence carries distinct operational information, though a few clauses (storage overage detail) could be tightened.

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

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

No output schema exists, and the description compensates by explaining the return (a run in `pending` with get_import polling to completed/canceled) and failure modes. For a complex, async, externally-dependent import tool, nothing essential is missing.

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

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

Schema coverage is 100%, so the schema carries the field docs (baseline 3). The description adds meaning beyond it, notably the board_token reuse pattern for re-sync and where imported folders land as sub-boards, which an agent needs to pick board_token correctly.

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 ('Import Google Drive folders into a board') and immediately scopes it against the sibling it is not ('upload_from_url cannot reach those' private folders). An agent can distinguish it from upload_from_url and import_from_dropbox without opening a schema.

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

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

Explicitly routes: use this for user's Drive files including private folders; connects are done by a person in the web app via list_import_sources connect_url; reuse the board_token for recurring sync. It also names the async follow-up (poll get_import) and the one-active-import constraint with the alternative (poll the named token).

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 read-only annotations by disclosing that enabled:false means the address 404s and no tool re-enables it, that app source files cannot be read back, and that a disabled workspace answers 403 hosted_apps_disabled with no in-tool remedy (escalate to support). These are exactly the behavioral traps an agent needs.

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

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

Front-loaded with the core purpose and scannable; the return fields and failure modes are ordered sensibly. It runs slightly long, and the 'keep the source' aside is tangential for a pure list operation.

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 contract itself (slug, name, url, board_token, enabled) and covers prerequisites and failure behavior, leaving nothing an agent needs to call it correctly.

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

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

Schema coverage is 100%, so the sole `organization` parameter is already fully documented in the schema. The description adds no format or edge-case meaning beyond it, so the baseline 3 applies.

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

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

States a specific verb (list) and resource (hosted apps of a workspace) and defines what an app is: a small public web app showing one board, deployed with deploy_app. An agent can distinguish this from deploy_app/delete_app without opening a schema.

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

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

Gives clear context: it lists apps produced by deploy_app and names the prerequisite (hosted apps enabled for the workspace) plus the failure mode if not. It stops short of explicitly routing to delete_app or naming when not to call it, but for a listing tool the usage context is unambiguous.

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 read-only/no-destroy, so the description is free to add the non-obvious behaviors: cursor pagination is not a change feed and does not report deletions, signed display URLs expire in ~24h so permalink should be stored, `ai_agent_payload` is absent rather than null when not requested, and `created_after` ignores later edits/retags/moves. These are exactly the traits an agent cannot infer from schema or annotations.

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

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

Front-loaded with purpose and then organized by task (filtering, pagination, freshness, URLs, per-uploader). It is dense and slightly long at roughly six sentences, but each one carries distinct operational guidance 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 read-only listing tool with no output schema, the description covers the gaps that matter: pagination model and its limitations, URL expiry, absence-vs-null semantics, failure modes for bad tokens/names, and how to select the right alternative tool. Nothing an agent needs to call it correctly appears to be missing.

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

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

Schema coverage is 100% and the per-field descriptions already carry most parameter detail, so the baseline is 3. The description adds integrative meaning beyond individual fields by binding parameters into workflows — 'for what is new in this board since X, pass created_after with collection_token and nested_assets' — and by reiterating the complete-list rationale for uploaded_by.

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

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

Opens with a specific verb+resource+scope: 'List assets in a Playbook workspace, optionally filtered to a specific board.' It also distinguishes the tool from siblings by noting it should be preferred over the search tools when a complete list is needed, since it walks the database directly rather than going through the search index.

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 recipes: cursor pagination for a stable crawl/reconcile, `created_after` + `collection_token` + `nested_assets` for 'what is new since X', and `uploaded_by` for a complete per-person list with the alternative (search_assets/ai_search) named for multi-person filtering. It also states prerequisites (resolve the person with list_members, resolve share links via resolve_share_link).

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/destructive annotations, it discloses plan-dependent gating (Free/Pro: primary_gcs_id null and thumbnails empty for versions older than the revert window), that reads are always available regardless of plan, and that md5 may be a storage-placeholder for async uploads.

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 'entry point' statement and otherwise dense with useful facts, though it is on the long side and packs a wall of field names into one sentence. Nearly every clause earns its place, but the field enumeration could be trimmed.

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

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

With no output schema, the description carries the full burden of describing the return shape and does so thoroughly (version_number, md5, size, media_type, source, comment, created_at, created_by_token, revertable, thumbnails, head_version_number), plus the plan-gating caveat and a pointer to display_url for current content.

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

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

Schema description coverage is 100%, so page, per_page, token and organization are already documented in the schema; the description adds no pagination or parameter guidance. Its detail is instead directed at return fields, which is not what this dimension measures, so the baseline 3 applies.

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

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

The description states a specific verb and resource ('Lists the version history of an asset, newest first') and scopes it broadly as 'the entry point for anything about an asset's earlier states'. It explicitly names the sibling tools it feeds into (revert_asset, edit_asset_version_comment), so an agent can place it relative to alternatives without opening any schema.

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

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

It tells the agent exactly when to reach for this tool (version history, previous/older versions, what changed and when, choosing a version to restore) and names the downstream alternatives with their purpose. The follow-on routing to revert_asset for rollback and edit_asset_version_comment for annotation is explicit rather than 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 cover the safety profile (readOnlyHint, non-destructive, closed-world), but the description adds a genuinely non-obvious semantic: asset_count includes nested boards, each group/stack counted once, and must be compared against list_assets only with nested_assets: true. It stops short of disclosing ordering, pagination, or permission requirements, so it is strong but not exhaustive.

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

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

Three sentences, each doing distinct work: purpose first, routing second, semantic caveat last. No restatement of the title or name, and the most decision-relevant information is front-loaded.

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

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

With no output schema, the description carries return-value burden, and it does explain the key count field's semantics well. It does not describe the shape of the returned child-board records or ordering, leaving a modest gap for a no-output-schema tool.

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

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

Schema description coverage is 100%, and the schema itself already carries the meaningful param guidance (token naming caveat, when to omit organization). The description adds no additional parameter-level meaning, so the baseline 3 applies.

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

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

States a specific verb and resource — 'List the direct child boards of a given board' — with the scope word 'direct' making the boundary explicit. It is immediately distinguishable from list_boards (which can traverse depth) and list_board_descendants (deeper traversal) named in the sibling set.

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: navigating the hierarchy one level at a time, and names the alternative it beats ('more efficient than list_boards with depth when you only need one node's immediate children'). The condition that selects this tool over the depth-based sibling is spelled out, 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 readOnlyHint=true, openWorldHint=false, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context beyond annotations: it specifies that results are paginated, that each board carries an absolute tree_depth, and that asset_count aggregates the entire subtree—details not present in the annotations or schema. It does not mention rate limits or auth, but the required token parameter is clear from the schema.

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

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

The description is a single, well-structured paragraph front-loaded with the core purpose. Every sentence earns its place by adding distinct information: subtree scope, tree_depth, asset_count semantics, and the list_assets contrast. No redundancy or 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 must carry the burden of explaining return values. It does so by describing tree_depth and asset_count semantics, including how asset_count relates to list_assets' default behavior. For a paginated list tool with readOnly annotations, this is complete enough for correct invocation and interpretation.

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

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

Schema description coverage is 100%, so the input schema already fully documents all four parameters (token, page, per_page, organization). The description adds no parameter-level guidance beyond what the schema provides; it focuses on output semantics and sibling comparison. Baseline 3 is appropriate.

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

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

The description states a specific verb (list) and resource (board descendants) with explicit scope: 'EVERY board nested under a given board — children, their children, and so on — in one paginated call.' It directly contrasts with the sibling list_board_children, making the tool's distinct purpose unmistakable.

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

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

It explicitly names the alternative (list_board_children) and explains that this tool avoids walking that sibling level by level. It further clarifies how to interpret asset_count versus plain list_assets and the nested_assets parameter, providing clear when-to-use and when-to-choose-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?

Annotations already declare readOnlyHint/destructiveHint/openWorldHint, so the safety profile is covered. The description adds genuinely non-obvious behavior: results are paginated, and `asset_count` is recursive (counts the board plus every nested board) while list_assets counts only direct assets unless `nested_assets: true`. That is valuable disclosure beyond 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?

Four sentences, front-loaded with purpose then parameter behavior. Dense but each sentence carries real information (search, depth, pagination, count semantics). Slightly long and the last sentence is clause-heavy, but nothing is filler.

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

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

No output schema, so the description must carry return semantics, and it does explain pagination and the meaning of `asset_count`. It stops short of describing the board object fields or total-count metadata, leaving minor gaps for a list tool.

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

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

Schema description coverage is 100%, so the schema already documents page, depth, query, per_page, and organization. The description restates the depth values and pagination, adding no syntax or format details the schema lacks; baseline 3 applies.

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

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

States a specific verb+resource ('List boards (collections) in a Playbook workspace') and clarifies the hierarchy scope via `depth`, which implicitly separates it from list_board_children / list_board_descendants. It does not name those siblings directly, so it falls short of full sibling differentiation.

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 context for each relevant mode: title search via `query`, tree breadth via `depth` ('1' vs 'all'), and pagination via `page`. The closing sentence even tells the agent how to reconcile `asset_count` against list_assets output. No explicit when-not-to-use or named alternative tool, so not a 5.

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

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

Annotations already cover the safety profile (readOnlyHint, non-destructive, closed world), and the description layers on non-obvious behavior: exact-match semantics for field and option names, the downstream error behavior of update_asset, the presence of a built-in Status field, and the fact that the endpoint is not paginated and returns everything in one call.

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

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

Dense but front-loaded: the core purpose and the call-first instruction lead, and follow-on caveats (Status field, no separate set-value tool, matching rules, no pagination) each carry distinct information. Slightly redundant in restating that 'list_custom_fields has the spelling' after already stating exact matching, which keeps it just short of 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 does the work of describing the return shape — fields carry a `field_type` and allowed options, `select` holds one option while `date`/`person`/`url` hold a free value — and it points to update_asset's `fields` parameter for value formats. Nothing an agent needs to call and then use this result 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% for the single `organization` parameter, so the schema already carries the slug format, the omit-when-single-workspace rule, and when to pass it. The description adds only implicit workspace scoping ('a workspace's custom fields') and no syntax detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('List a workspace's custom fields') and immediately defines what those are ('the structured metadata vocabulary its assets use') with concrete examples (Priority, Season, Usage Rights). An agent can distinguish it from create_custom_field and delete_custom_field 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 ordering instruction ('Call this FIRST before setting or filtering a field value'), names the alternative paths (update_asset's `fields` argument, update_asset_status for the built-in Status field), and states there is no separate set-value tool. When-to-use and which-sibling-to-use are both fully resolved.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuine value beyond that by describing the return content ('catalog of guides and references') and how the returned slug is consumed, though it says nothing about pagination or output format specifics.

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

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

Three short sentences, front-loaded with the action and resource, then the return, then the follow-up workflow. Every sentence carries distinct information with no filler.

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

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

For a zero-param, read-only catalog tool with readOnly annotations, the description covers purpose, return content, and downstream usage, which is sufficient to invoke it correctly. It could be slightly richer on the shape of the returned catalog, but no critical gap remains.

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

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

There are zero parameters, so the schema-side burden is nil and the baseline for a no-param tool is 4. Nothing in the description is needed to clarify inputs, and it correctly implies no arguments are required.

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 ('List all available Playbook documentation topics') and clarifies the output is a catalog of guides and references. This lets an agent distinguish it from read_documentation, which reads a single topic's full content.

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

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

The description explicitly routes the agent: use the topic slug here with read_documentation to get full content, establishing the list-then-read workflow and naming the relevant sibling. It stops short of stating when NOT to use this tool, so it's clear context rather than a complete when/when-not rule.

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 safety profile (readOnlyHint=true, openWorldHint=false, destructiveHint=false), yet the description still adds real behavioral detail: results are paginated and ordered newest first, non-group tokens are refused outright, and the group itself has no file and borrows its preview from its first displayable child. Auth/permission requirements are not mentioned, which keeps it short of a 5.

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

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

Purpose and the sibling distinction are front-loaded in the first two sentences, which is the right ordering. It runs longer than strictly necessary — the palette/preview aside is contextual colour rather than call-critical information — but no sentence is filler.

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

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

For a read-only, no-output-schema list tool with fully documented parameters, the description covers the concept of a group, the routing decision, pagination ordering, and the error case. Only auth/permission scope and any rate-limit behavior are left unstated.

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

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

Schema coverage is 100%, so the schema already documents page, per_page, fields, and organization, establishing a baseline of 3. The description goes beyond that by defining what a valid `token` is (`is_group` true in get_asset/get_assets) and what happens otherwise — meaning the schema does not carry.

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

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

The description opens with a specific verb+resource ('List the assets inside a group') and immediately differentiates itself from siblings by noting that list_assets and the search tools return only top-level rows. An agent can route to this tool without opening any schema.

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

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

It explicitly states the alternative tools (list_assets, search tools) and the condition that selects this one over them. It also names a hard precondition for the required argument — `token` must be a group asset — so misuse is prevented rather than merely discouraged.

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/non-destructive/closed-world, but the description adds substantial context: connections are scoped to the signed-in Playbook account only, the email field is briefly null right after connecting, and the connect_url is only populated once a connection exists. These are behavioral traits an agent could not infer from the schema.

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

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

Front-loaded with the core payload description, then the operational caveats. It is dense but every sentence carries needed information; slight length and packing of multiple concepts into single sentences keep it from 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 full burden and does so: it explains every returned field, the null-email edge case, and the connect_url fallback. 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?

Only one optional parameter (organization) with 100% schema description coverage, so the schema fully documents it. The description adds no meaning about the parameter itself, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb and resource ('List the storage accounts connected for import') and enumerates the exact fields returned per entry (provider, token, email). It also names the sibling tools that consume the output (import_from_google_drive / import_from_dropbox), so an agent can place it precisely in the workflow.

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

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

Explicitly routes the agent: use a source of the matching provider for the import_* tools, connections are made by a person in the web app (no connecting tool exists), and when no source of the needed provider is present the connect_url is the next step. It also states the owner/admin permission 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 already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds real behavior: the query match is fuzzy (with a misspelling example), a single name can return several members, and each carries its own token. It doesn't discuss pagination or the shape of each member record beyond the token.

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

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

Front-loads the core purpose, then layers query behavior, the token return, and the routing guidance in a logical order. It is dense but every sentence carries distinct, actionable information with no filler.

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

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

Although there is no output schema, the description explains what comes back (a token per member) and why it matters. Combined with full schema coverage and annotations, an agent has everything needed to call and use 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%, so the schema already documents all four parameters, including query's fuzzy/typo tolerance. The description reinforces query's fuzzy behavior with an example and clarifies the token's downstream use, but adds little syntax or format detail beyond the schema. 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 (List) and resource (people in a Playbook workspace), plus the secondary find-by-name mode. It also distinguishes itself from siblings by explaining the token output feeds ai_search, search_assets, and list_assets, so an agent can place it in the workflow without opening other schemas.

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

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

Explicitly says to call this FIRST whenever a request names a person, with concrete examples ('what did Max upload', 'files from Sarah'), and warns that a name typed into a search query does NOT match the uploader. That is a clear when-to-use plus the failure mode of the alternative.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. Beyond that, the description discloses the response shape, the meaning of permalink_quota as left-of-total, and the downstream failure mode where exceeding the cap rejects the entire add_asset_permalinks batch — real context an agent cannot get from the empty schema.

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

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

Three sentences, front-loaded with what it returns, then the quota caveat. Every sentence earns its place, though the final clause about the refused batch is slightly long-winded for the value it carries.

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

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

With no output schema, the description carries the return-value burden and does so fully: fields, the slug's role as cross-tool identifier, and the quota structure. 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?

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to compensate for. It adds no param detail because none exists to add.

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

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

States a specific verb and resource (list workspaces/organizations) and immediately disambiguates the term 'organizations' against 'workspaces'. It also enumerates the returned fields (slug, name, role), which no sibling list_* tool claims, so an agent can tell it apart.

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

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

Gives a concrete when-to-use: call this before a large add_asset_permalinks batch to check remaining permanent-URL quota, explaining the overage consequence. It also notes the slug is the identifier other tools expect. It does not, however, position itself against the other list_* siblings (list_boards, list_members), so no exclusion guidance.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the mutation/safety profile is covered. The description adds value the annotations do not carry: the required `write` scope and the per-asset update permission on every source asset, which is exactly the kind of auth precondition an agent needs. It does not explain what happens to the source board listing, but that is largely implied by 'move'.

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

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

Three short sentences, purpose front-loaded, then parameters, then permission constraints — well structured. The middle sentence partially duplicates what the 100%-covered schema already states, so it is not perfectly waste-free.

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

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

For a 3-parameter tool with full schema coverage, no output schema, and annotations covering safety, the description supplies the missing auth/permission layer. An agent has enough to invoke correctly; only return/error behavior is unspecified, which is acceptable given no output schema.

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

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

Schema description coverage is 100%, including a detailed note on the optional `organization` parameter, so the schema carries the semantic load. The description restates the asset-token array and destination board token without adding format, ordering, or limit details beyond the schema.

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

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

States a specific verb ('Move') and resource ('assets') plus the destination ('target board'). It is clearly distinguishable from copy_assets and move_page_element by verb alone, though it does not explicitly name those siblings.

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

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

It gives real prerequisites (write scope token, update permission on every source asset) which implies when the call will succeed. However it offers no guidance on when to prefer this over copy_assets or how it differs from moving a page element — the alternative-selection dimension 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?

Far exceeds the annotation bar: it names the 403 error code and states that only Playbook can enable it (retrying is futile), explains that a 409 `stale_document` applies NOTHING, describes version-token rotation on success and the resulting staleness of the caller's own token, distinguishes retry-safe from non-retry-safe 409s, and discloses the up-to-one-hour public-page lag. It also clarifies that `converged`/`materialized` keys are ABSENT when 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?

Eight dense sentences with the core purpose front-loaded and no filler, but the token/concurrency block is packed tightly and could be split for readability. Given the complexity and the absence of an output schema, nearly every sentence carries weight.

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 12-parameter mutating tool with no output schema, the description supplies the missing pieces an agent needs: auth requirements, all relevant error codes and their remedies, concurrency protocol, and the meaning of the response keys (including when they are absent). Nothing material is left unstated.

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

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

Schema coverage is 100%, so the schema already documents all 12 parameters including the column_id vs column_index trap and expected_version_token's compare-and-swap role. The description adds behavioral meaning to the version token round-trip but no parameter-level detail the schema lacks, which is the baseline-3 case.

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

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

The opening sentence states a specific verb (move), resource (page element), and the three distinct move targets: position, slot, or into/out of a section column. It also announces the return shape ('Returns both affected slots'), which cleanly separates it from siblings like reorder_page_slot and update_page_element.

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 preconditions ('Requires `modify` on the board and page-layout API writes enabled') and a precise recovery protocol for 409s, including which two are safe to retry. What it lacks is any explicit comparison to adjacent siblings (reorder_page_slot, update_page_element), so the agent must infer when a move is the right call from the move semantics alone.

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 (destructiveHint, openWorldHint, idempotentHint) only sketch the profile; the description adds the substantive behavior: public internet exposure of the board and its assets, the 409 refusal code and its scope, that a template publish replaces page settings but not stored element edits, and that `template_applied` is absent when the design was untouched. Nothing here contradicts the annotations.

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

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

The critical scoping and the sibling differentiation are front-loaded, and the dense template semantics are genuinely load-bearing for correct invocation. It is still a long, paragraph-heavy block with some repetition around template handling that could be tightened, so it falls short of ideal conciseness.

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 high-complexity, destructive, open-world mutation tool with no output schema, the description covers the mutation surface, the return values (public URL, `template_applied`), the failure mode (409) and its remedy, and the exposure consequence. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining the conditional meaning of `template` (implicit `standard` on a non-live board, workspace-specific template override, refusal when edits exist) and the resolution rules around `organization`. The remaining parameters are covered adequately by the schema itself.

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

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

The first sentence gives a specific verb+resource (create/update a board's public page) plus the mutation surface (expiry, download restriction, password) and the return value (public URL). It then explicitly contrasts itself with the sibling `share_board`, so an agent can route between them without opening either schema.

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

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

It states when to pass `template`, when to omit it, when an implicit `standard` applies, and the recovery path when a 409 `page_design_exists` is returned (republish without `template` and use the page element tools). The share_board vs publish_board distinction and the 'live page or existing design is never given a template implicitly' rule are explicit exclusion criteria.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description adds value by disclosing what comes back (docs text, code examples, endpoints) and that the content is a public developer-docs page. It does not mention rate limits or whether content is cached, keeping it at a 4.

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

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

Three short sentences, front-loaded with the action and scoping, then the prerequisite, then the return value. Nothing is redundant and nothing is missing.

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

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

For a single-parameter read tool with no output schema, the description supplies exactly what is needed: how to pick a topic, what the call returns, and where the content comes from. No material gap remains.

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

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

Schema coverage is 100% and the schema already documents the single 'topic' parameter with slug examples and a pointer to list_documentation. The description adds no syntax or format detail beyond that, so the baseline of 3 is appropriate.

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

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

States a specific verb (read) and resource (a specific Playbook documentation page), and distinguishes itself from the sibling list_documentation by scope (one page vs. the topic index). 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?

Explicitly tells the agent to call list_documentation first to discover available topics, which is a clear prerequisite and names the sibling alternative. There is no explicit 'when not to use' guidance, so it falls just short of a 5.

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

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

Goes well beyond the annotations (destructiveHint/idempotentHint) by disclosing irreversibility specifics (re-adding mints a DIFFERENT URL, old embeds stay broken), the real-world scope of the takedown (public copy stays fetchable ~1 week), auth requirements (write scope plus update permission on every asset), and all-or-nothing failure on an unknown token.

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?

Seven sentences, but each carries distinct operational information (irreversibility, takedown limits, skip semantics, error code, permissions) and the destructive warning is front-loaded. Slightly dense, though nothing is padding.

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

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

No output schema exists, and the description compensates by describing the response (freed `quota`, absent skipped assets, 406 when nothing had a permalink) and the full permission model. An agent has everything needed to call this safely.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds semantics the schema does not: a single unknown token fails the whole call, and the response reports the freed `quota`. The `organization` parameter's resolution behavior is left entirely 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 ('Revoke assets' permalinks') and immediately frames the outcome ('freeing the plan's permalink allowance'). It is trivially distinguishable from the sibling add_asset_permalinks/get_asset_permalinks by direction of operation.

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

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

Explicitly carves out when NOT to use it ('NOT an emergency takedown', with the week-long purge delay explained), and states the edge-case behavior (assets without permalinks skipped, 406 if none). It does not name a competing alternative tool for takedown scenarios (e.g. delete_asset), so it stops short of full routing guidance.

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

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

With annotations present (readOnlyHint=false, destructiveHint=true, idempotentHint=true, openWorldHint=true), the bar for extra behavioral disclosure is lower, yet the description goes far beyond them. It explains the 422 reorder_id_mismatch error path, 403 page_layout_api_disabled, 409 stale_document semantics, which 409s are safe to retry, that the write is compare-and-swap via expected_version_token, that a successful write rotates the token, and that the public page can lag up to an hour. This is exactly the kind of write-behavior context annotations cannot 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?

Front-loaded with the core action and constraint, then organized into paragraphs for errors, concurrency, and response flags. It is dense but every clause carries operational weight; it is slightly over-detailed with dual error-path and token-protocol sections, keeping it just below the high bar for conciseness.

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

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

For a 6-parameter, three-required write tool with no output schema, the description covers everything an agent needs: required input semantics, exact error codes, idempotency/retry rules, version-token handling, and response flag behavior. Nothing material is missing, and it correctly does not attempt to explain a return value that has no schema.

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

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

Schema description coverage is 100%, so all six parameters are already documented in the schema, including token, slot_id, ordered_ids, organization, subboard_token, and expected_version_token. The description adds operational meaning for ordered_ids (exact match required, nested ids count as extra) and the token semantics, but the schema already covers the basics. 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 (Set the order) and resource (a slot's top-level elements on a board's published page), introspected from the very first sentence. It also names the simpler sibling move_page_element for a single-element move, so it is clearly distinguishable from alternatives.

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

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

Explicitly says to use move_page_element when moving one element, and lays out the concurrency protocol. It also states the exact requirement (modify on board and page-layout API writes enabled) and what to do when they're missing, so the agent knows when and when-not to use this tool.

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