LivePage · 活页

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), so the bar is lower, and the description still adds non-obvious behavior: visibility=internal hides the note from clients while the default all is client-visible, plus a pointer to the field/status documentation. It omits duplicate-handling and what the call returns, but the visibility/privacy semantics are genuine added value.

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

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

Four short sentences, front-loaded with what is saved and from where, then visibility semantics, then the exclusion, then the doc link. Nothing is padded, though the trailing documentation URL is a mild deferral of content that could have been inlined.

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 mutation with a nested anchor object, low schema coverage, and no output schema, the description covers visibility and anchor optionality but says nothing about what the tool returns (e.g., the created feedback id) or about body/version_id behavior. Adequate to call it correctly in the common case, incomplete for the full surface.

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 only 17%, so the description must compensate, and it does partially: it explains the visibility enum semantics and flags that page/text anchors are optional. It leaves body length limits, the source enum values (only implied by the channel list), version_id semantics, and sectionId unexplained, so roughly half the parameters remain undocumented anywhere.

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

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

The description names a specific verb and resource ('Save feedback ... to the relevant page and version') and enumerates the intake channels (meeting, WeChat, call, email), so an agent knows exactly what gets created and where it lands. It does not explicitly contrast itself with the feedback siblings (reply_feedback, list_feedback, set_feedback_status), so differentiation is only implicit.

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 the trigger condition ('feedback the user explicitly supplies') and an explicit exclusion ('Do not collect unrelated conversation history'), which is a real when-not rule. However, it never names the alternative tools an agent should reach for instead (e.g., reply_feedback for responses, list_feedback for retrieval), so routing is left partly to inference.

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

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

Annotations correctly declare this as a non-destructive, non-idempotent write (readOnlyHint: false, destructiveHint: false, idempotentHint: false). The description adds critical behavioral context not in annotations: it requires owner privileges and describes role capabilities. However, it does not mention the 26-character constraint or side effects like notifications.

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 most critical constraint (Owner only) is front-loaded, followed by role semantics and the fallback path.

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

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

Given two parameters, no output schema, and explicit annotations, the description covers purpose, permissions, role meanings, and an alternative tool. It is complete for invocation, though it omits expected outcome (e.g., success response or errors).

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 0%, so the description must supply parameter meaning. It clarifies that 'user_id' must be a known 26-character ID and defines the 'role' enum values (owner, editor, viewer). This compensates well for the schema's lack of descriptions.

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

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

States a specific verb (add) and resource (member) with scope ('this workspace') and references the required user_id. It is clearly distinguishable from siblings like remove_member, set_member_role, and invite_teammate.

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 states 'Owner only', describes the permission scope subject to role, and names the alternative for unknown user IDs ('use invite_teammate instead'). It explains the role meanings to help select the correct role parameter.

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

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

Annotations only declare readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description adds substantial context beyond that: no funds move, only a timestamp is written, moderation status and amount are untouched, the confirmation is visible only on the viewer's own row, and the 'I have paid' button is not a payment result. That is exactly the behavioral detail an agent needs for a payment-adjacent mutation.

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

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

It is front-loaded with a long anti-fraud disclaimer rather than the operation itself, and the 'records a timestamp only' point is restated near the end. Most sentences do earn their place, but the length and repetition cost it.

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

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

No output schema exists and the tool is a small two-parameter mutation, and the description covers side effects, visibility, and the meaning of the confirmation well. The main gap is proposal_id's semantics and any warning about repeated confirmation (idempotentHint=false), which it never addresses.

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 50%: row_id is documented in the schema, proposal_id is not. The description compensates for row_id by directing the agent to list_data_rows, but says nothing about proposal_id's meaning or source. Partial compensation only, so the baseline 3 is right.

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: it records a 'payment confirmed by the publisher' timestamp on one row, and explicitly distinguishes itself from set_data_row_status and set_form. An agent can tell exactly what this does and does not do 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?

Explicit about when to use it (after checking the money in your own WeChat Pay/Alipay statement), where to get the identifier (list_data_rows), and clarifies that the viewer need not press 'I have paid' first. It also names the alternative tool for a different job (set_data_row_status for moderation).

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 annotations: discloses the copy is an unpublished draft, that it is independent from the source thereafter, that it counts toward storage quota, and that copying requires allow_copy and an unlocked link. These are behavioral traits the structured fields do not 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 primary trigger and followed by bulleted consequences, so structure is strong; however the description is fairly long and some quota/moderation detail is secondary for the immediate call.

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

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

For a mutation tool with no output schema, the description covers what is created, its visibility, error outcomes and the entire downstream workflow, so an agent has everything needed to call it and proceed.

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 applies: the schema already documents link, title (with '(copy)' default) and folder_id. The description mentions link only implicitly ('the user pastes a LivePage link') and adds no format or syntax detail beyond the schema.

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

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

States a specific verb and resource ('copies the version readers currently see into a new page in your own workspace') and names the trigger context, distinguishing it from create_proposal and publish_file 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?

Explicitly says when to use it (user pastes a LivePage link and asks to copy/edit/rewrite), enumerates exact error conditions (403 copy_not_allowed, 410 revoked/expired) and instructs not to work around them, and routes the agent to read_version/publish_file/finalize_upload as follow-ups.

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

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

Annotations only cover safety flags (readOnlyHint=false, destructiveHint=false, idempotentHint=false); the description goes well beyond them with lifetime rules ('expires within 30 minutes and never outlives the parent token'), a handling constraint ('pass it to the CLI process environment, never a file, log, user-facing message or unrelated service'), and revocation semantics ('revoking the parent does not cascade'). This is exactly the behavioral disclosure a token tool 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?

The output is front-loaded with the core action and every sentence carries distinct information (lifetime, handling, exclusions, revocation). It is slightly denser than necessary, with the terminal caveat restated across two sentences, but there is no filler.

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

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

With no output schema, zero parameters, and only safety annotations, the description carries the full burden and does so: what it creates, its lifetime, where it may be placed, when not to call it, and its revocation behavior are all covered. 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?

The tool takes zero parameters, so there is no parameter surface for the description to compensate for; baseline 4 applies. The description instead clarifies the implicit inputs (host terminal capability, user upload intent) that govern whether the call is valid.

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

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

States a specific verb and resource ('Create a workspace-scoped credential for the SPACE CLI'), scoping the artifact precisely enough to separate it from siblings like create_upload_link and create_upload_session. An agent can tell what is produced 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 preconditions ('only when the host supports a local terminal and the user requests an upload') and exclusions ('This is not needed for browsing or feedback, and does not give a chat-only host a terminal'). This names the when, the when-not, and the anti-pattern in one place.

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 full safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false). The description adds that a folder can be shared through a single link, which is useful behavioral context, but says nothing about duplicate-name handling, permission requirements, or whether the share link is returned.

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

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

Three short sentences, front-loaded with purpose before the optionality and duplicate-check guidance. Every sentence carries information, though the folder_id reference is slightly off-target for this tool's own parameter set.

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

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

For a two-parameter mutation tool with no output schema, the description covers purpose, sharing behavior, and duplicate avoidance. It leaves gaps on permissions, idempotency expectations, and what the created folder/link looks like, so it is adequate rather than complete.

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

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

Schema description coverage is only 50% (name is undocumented; intro is documented), so the description should compensate but does not — it never explains what name or intro accept or their constraints. Worse, it references folder_id, which is not a parameter of this tool at all, adding potential confusion.

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

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

States a specific verb and resource ("Create a folder") plus its organizing purpose, and immediately frames the scope against siblings by naming list_folders and the create_proposal folder_id path. An agent can distinguish this from set_folder or list_folders without further inspection.

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

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

Gives an explicit precondition ("Check list_folders first to avoid duplicates") and clarifies that folders are optional by describing the alternative path (omit folder_id in create_proposal). It stops short of stating when not to create a folder at all, but the routing guidance is clear.

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

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

Annotations declare non-readOnly, non-destructive, non-idempotent. The description adds value beyond them by disclosing that it returns a proposal_id and that uploads become versions of this page, which is important lifecycle context absent 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 two leading sentences are well front-loaded and information-dense, but the trailing keyword list (~12 terms) is retrieval padding that dilutes the definition and is not operational guidance.

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

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

With no output schema, the description usefully states the return value (proposal_id) and version behavior, and annotations carry the safety profile. Missing only secondary details like permission or sharing prerequisites.

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 75%, so the schema already documents internal, folder_id, and allow_copy. The description only restates that folders are optional, adding no new syntax or meaning beyond what the schema provides; baseline 3 applies.

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

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

States a specific verb (create) and resource (page/proposal) and enumerates the artifacts it covers (report, proposal, deck, interactive page). It also distinguishes itself from list_proposals for updates, so an agent can route correctly without opening schemas.

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

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

Gives a clear conditional: use list_proposals first when updating existing pages to avoid duplicates, and notes folders are optional. It does not name all relevant neighbors (e.g. create_folder, copy_proposal), but the primary when/when-not is 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 (readOnly=false, idempotent=false, destructive=false, openWorld=false) only cover the safety profile; the description adds substantial behavior: link valid 2 hours, succeeds only once, uploads into this one page only, no login required, hold defaults to true so release waits on publish_version, and the required polling loop via get_version with state semantics (preview_ready/approved/converting/review).

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 and informative, but the routing rule is stated twice (the 'no terminal / 2 MB' condition appears both in the routing list and again in the 'Use this when' sentence), and the post-call follow-up procedure is long. Content is useful but not tightly edited.

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: it explains what is returned (a url plus a page-details link), how long it lives, what the agent must do with it (hand over unchanged, specify the file, wait for 'uploaded'), and the full polling/confirmation workflow through get_version and publish_version.

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 beyond the schema: proposal_id targets an existing page (find via list_proposals) and is mutually exclusive with title, title creates a new page, folder_id is optional, and hold=true blocks release until publish_version. Only the note parameter's role is left to the schema.

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

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

States a specific verb+resource: creates an upload page link that the user opens to pick files (PDF/PPTX/images/large files). It explicitly names the siblings it is not (create_cli_token, publish_file) and the routing conditions, so an 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?

Gives an explicit decision tree: terminal ⇒ SPACE CLI (create_cli_token first); no terminal + text files ≤2 MB ⇒ publish_file; anything else or unsure ⇒ create_upload_link. Also names the alternative for single HTML/Markdown with content in hand (publish_file). When-to-use and when-not-to-use are both 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 only declare the generic non-readonly/non-idempotent profile; the description adds the real behavior: URLs are PUT-only (not an upload route on their own, or the version stays stuck in 'uploading'), 15-minute URL validity, the required finalize_upload step, PPTX→page-image conversion with possible font substitution, and that quota errors carry recovery guidance.

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, then routing rules, caveats, mechanics. Dense and mostly waste-free, though the trailing keyword block is boilerplate rather than information.

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

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

For a non-idempotent mutation tool with no output schema, the description covers the full lifecycle (create version → get PUT URLs → upload bytes → finalize_upload), timing constraints, conversion side effects, and error recovery. 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 only 33%, and the description mainly restates the required file triple ('relative path, byte size and SHA-256') — though 'relative' does add a nuance beyond the schema. It says nothing about the required proposal_id or the optional note/mime fields, so it only partially compensates for the coverage gap.

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 ('Open a direct upload session') plus its mechanism ('a presigned URL per file'), and explicitly distinguishes itself from the sibling routes publish_file and create_upload_link. An agent can tell what it does and what it is not without opening the schema.

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

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

Gives an explicit decision tree: terminal ⇒ SPACE CLI (create_cli_token first); no terminal + text files ≤2MB ⇒ publish_file; otherwise/unsure ⇒ create_upload_link, plus a hard exclusion ('without a terminal do not open one'). This is exactly the when/when-not/alternatives guidance the dimension asks for.

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?

Although annotations already flag destructiveHint=true and idempotentHint=false, the description goes well beyond them: it names what ceases to exist (content, versions, page images, reading records, viewer-appended rows), the 30-day reversibility window, the point of no return, and the report-blocking constraint. This is exactly the extra context a destructive tool 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?

Consequences are front-loaded and nearly every clause carries information. It is a single dense paragraph, and the web-console digression is slightly tangential, 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 destructive mutation tool with no output schema, the definition covers consequences, reversibility window, irreversibility, blocking preconditions, the confirmation guard, and the alternative recovery tool. An agent has everything needed to call it 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 only 50%, so the description must carry meaning for the undocumented parameter — and it does for confirm, explaining the exact-title-repeat guard and its purpose (avoid deleting the wrong page), plus routing to list_proposals. proposal_id itself is still left to inference from its name and the referenced lookup tool.

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 ("Delete a page") and immediately enumerates the exact effects: link breaks, removal from page list/analytics/folders, reader-facing 404. This clearly separates it from siblings like restore_proposal (the inverse) and list_proposals (the lookup step).

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 names alternatives and conditions: use restore_proposal within 30 days, use the web console for immediate erasure, and check with list_proposals before calling. It also states a hard prerequisite — pages with unresolved reports cannot be deleted until the report is 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 readOnly/idempotent/non-destructive, but the description adds substantial extra context: workspace scoping, independence of tables from versions, the fact that reader-appended rows are omitted from `rows`, and the revision-fetch prerequisite for writes. These are behaviors the annotations cannot convey.

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

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

Front-loaded with purpose and mode-switching behavior, and dense with useful detail rather than filler. It is quite packed into one paragraph, but nearly every clause carries information; little could be cut without losing routing or behavioral guidance.

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 explicitly enumerates return contents for both modes (name, revision, columns, row count, size, write-back switch, limits; and columns/rows/revision with csv). Combined with scoping and prerequisite notes, 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?

Adds real meaning beyond the schema: `table` omitted lists every table, present returns the full table, and `format=csv` 'adds CSV text' rather than replacing JSON. `proposal_id` is undocumented in both schema and description, a minor gap, but the two behavior-defining params are well covered.

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 data tables attached to a page') and immediately distinguishes itself from siblings by naming set_data (must precede it) and list_data_rows (for reader-appended rows). An agent can tell it apart from other read tools 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 routes usage: omit `table` to list all tables, pass `table` to read one full table, and 'always call this before set_data to obtain the current revision'. It also names the alternative for reader-appended rows (list_data_rows) and clarifies that viewer-page reads do not go through this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety and idempotency are covered. The description adds the useful workflow context that the revision must be passed unchanged to set_downloads, but doesn't mention pagination, permissions, or output shape.

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

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

A single dense sentence enumerating outputs, plus a short second sentence on the revision handoff. Front-loaded and no fluff, though the field enumeration is 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?

For a simple read with one param, annotations, and no output schema, the description adequately explains what data is returned and the revision workflow. The only gap is version_id's meaning/format.

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 0% with only one parameter (version_id), which has no description. The description implies version-related context but never defines version_id or its format. Baseline for 1 undocumented param is 3.

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

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

The description specifies a clear verb (Read) and enumerates the exact resource fields it returns (download switch, attachments, labels, formats, sizes, candidates). This distinguishes it from siblings like get_replay_settings or read_version. However, it doesn't explicitly contrast with set_downloads/preview_downloads beyond the revision hint.

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 clearly states to use this before set_downloads by passing the revision back unchanged, which is actionable guidance. It doesn't explicitly rule out other tools or say when not to use it, and doesn't mention preview_downloads as an 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 the safe read-only/idempotent profile, but the description adds substantial non-obvious context: activity is 'observations, not intent scores or verified identities,' 'three devices do not establish three people,' the evidence level (none/thin/usable) must be read before concluding, and WeChat names are never exposed (row number is the only identifier). This is exactly the interpretive and privacy context the schema 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 text is long and splits into two loosely related blocks, with an extended subscriber-listing section appended after the engagement summary. The subscriber detail (grouping, reachability states, identifier rules) reads like a second tool's documentation and is not front-loaded, so several sentences do not earn their place in this tool's description.

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

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

For a two-parameter read tool with no output schema, the description supplies strong interpretive caveats and privacy rules, which is valuable. But it omits any explanation of the required proposal_id, gives no sense of return shape, and conflates the engagement and subscriber functions, leaving gaps for an agent to fill.

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 only 50%: 'days' documents its default but 'proposal_id' has no description at all. The description never explains what proposal_id is or what the days window scopes, so it fails to compensate for the uncovered parameter.

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

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

The description states a specific verb and resource: it reads recent device activity (pages reached/skipped, time, downloads, demos, comments, forwarding) and also lists page subscribers. The dual scope (engagement + subscriber listing) muddies the single purpose a bit, and it never contrasts itself against nearby siblings like get_session_timeline or get_downloads, so it falls short of a 5.

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

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

It gives explicit routing for a related task ('To remove someone or revoke a code, use remove_subscriber / revoke_subscribe_code on set_publish_notify'), which is genuine when-to-use guidance. However, it offers no guidance on when to call this tool versus the many overlapping read siblings (get_session_timeline, get_downloads, get_folder_analytics), so the core selection decision is left implicit.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive). The description adds genuinely non-obvious behavioral rules: 30-minute session gap, device-vs-person attribution, and exclusion of visits not arriving via the folder link. This is real behavioral disclosure beyond 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?

Four short sentences, front-loaded with what the tool returns and followed by the caveats that govern interpretation. No filler, though the sentence fragments are terse to the point of being cryptic.

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 and 0% schema coverage, so the description should define the return shape and parameter semantics. It instead spends its budget on sessionization rules, covering behavior but leaving the response shape and parameter meaning 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 0%, so the description must compensate. It does not explain days (1-90 window), folder_id (required scope key), or include_internal (whether internal viewers are counted), leaving all three parameters semantically unexplained.

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 (folder analytics: order, time spent, interactions) and distinguishes from get_session_timeline/get_engagement_summary by focusing on shared-folder page flow. Lacks explicit sibling naming but the scope is clear.

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 statement of when to use this vs get_engagement_summary, get_session_timeline, or list_sessions, and no mention of the required folder_id prerequisite. The description implies it is a folder-scoped read but gives no routing guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. Beyond that, the description adds a genuinely non-obvious behavioral fact: basic reading activity operates independently of the recording switch. It omits auth requirements and return formatting, but against strong annotations this is solid added 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?

Two short sentences with no filler. The core enumeration is front-loaded and the independence caveat follows as the one piece of qualifying context that earns its place.

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

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

With no output schema and no parameters, the description carries the burden of telling the agent what comes back, and it does so by listing the five settings. It lacks detail on units, types, or structure (e.g., whether retention is a period or a flag), which keeps it just short of full completeness.

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

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

The tool takes zero parameters, so there is no parameter semantics to document and the baseline of 4 applies. The description's enumeration of settings is about return content, not inputs, so it neither helps nor hurts here.

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

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

States a specific verb (Read) and resource (workspace recording settings), then enumerates exactly what is read: switch, used storage, separate capacity, per-visit limit, retention. The read verb also implicitly contrasts with the write sibling set_replay_settings, so an agent can route correctly 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 (use this to inspect current recording configuration) but there is no explicit when/when-not guidance or named alternative. The final sentence gives a useful decision fact — that reading activity is independent of this switch — but it does not tell the agent when to prefer this tool over others in the large sibling set.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior, so the safety profile is covered. The description adds a genuinely useful conditional: replay_url is returned only when an HTML recording or usable PDF/PPTX page replay exists, otherwise the event timeline is still available. It does not mention limits, pagination, or retention, which keeps it from a 5.

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

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

Two sentences, front-loaded with the resource and its contents, followed by the prerequisite and the conditional return behavior. Every sentence carries information, though the closing clause about the timeline remaining available is slightly redundant padding.

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

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

For a single-parameter read tool with full annotation coverage and no output schema, the description covers what the resource is, where the ID comes from, and the one non-obvious return nuance (conditional replay_url). Ordering/pagination or volume expectations are not addressed, leaving a minor gap.

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

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

There is one parameter with 0% schema description coverage, so the schema itself explains nothing. The description partially compensates by naming the source of session_id (list_sessions), but adds no format, length, or validity guidance beyond that.

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 visit's ordered events') and then enumerates the event types returned (opening, page changes, time spent, scrolling, clicks, QR codes, downloads, comments). This clearly distinguishes it from siblings such as list_sessions, get_engagement_summary, or get_replay_settings.

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 tells the agent where the required input comes from ('Get session_id from list_sessions'), which routes to the correct prerequisite tool. It stops short of stating when *not* to use this tool or how it differs in scope from get_engagement_summary, so it's clear context without exclusions.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the burden is lower. The description nonetheless adds real behavioral value: the polling cadence after conversion, the fact that content may be in a 'converting' state, and how artifacts are shaped (entry file, downloadability). It does not describe pagination or error behavior, so not a 5.

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

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

Front-loads the return contents, then operational guidance, then the sibling route-out — a sensible order. The parenthetical artifact field list is dense but each item earns its place; overall a touch long but no wasted sentences.

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 explaining the return shape (status, pages, issues, artifact fields), which is the key content an agent needs. The only real gap is the version_id parameter, which is omitted entirely from an otherwise thorough definition.

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 0% and the description never explains the version_id parameter's format or where to obtain it. It implies the tool operates on a single version, but with one undocumented required parameter and no field-level guidance, this is minimum-viable rather than compensating for the coverage gap.

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) plus resource (a version) and enumerates exactly what it returns: status, page count, validation/review issues, and contained artifacts with their fields. It is clearly distinguishable from siblings like read_version (rendered body), preview_version, and list_versions.

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

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

Gives an explicit trigger (after finalize_upload returns 'converting'), an explicit constraint (poll no faster than every 15–30 seconds), a follow-up action (show the preview once ready), and a named alternative for a different need (read_version for rendered body).

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

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

Adds real context beyond the annotations: an ownership/auth precondition, the role-granting boundary, the return payload (URL, QR URL, share_text), and the non-obvious fact that it does NOT message anyone. This clarifies the side-effect surface that the readOnly/destructive hints alone don't 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 precondition 'Owner only' is front-loaded, and each of the following sentences carries distinct, non-redundant information (constraint, return values, side-effect clarification, revocation pointer). 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 two-parameter, no-output-schema tool, the description supplies the preconditions, the grant boundary, the return artifacts, and the follow-up path, so an agent has everything needed to call it and explain 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 description coverage is 100%, so both the days validity window and the editor/viewer role are already documented in the schema. The description reinforces the editor/viewer concept and the time limit but adds no syntax or constraints beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('Create a time-limited link for a teammate to join this workspace') plus the exact access mechanism (WeChat sign-in). The link-based mechanism implicitly distinguishes it from a direct add_member, so an agent can tell what it produces without opening the schema.

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

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

Gives the precondition ('Owner only') and a clear exclusion ('Cannot grant owner'), and points to where existing invites are revoked (Members). It stops short of explicitly contrasting with the sibling add_member, leaving the choice between link-invite and direct-add 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 readOnly/idempotent/non-destructive, but the description adds substantial behavioral context beyond them: the visibility rule tied to ownership ('someone has to be able to clean up after a member leaves'), the hard guarantee that the secret and its hash are never returned, that the plaintext appears only once at creation, and that the prefix is safe to read out. This is exactly the kind of disclosure 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?

Well front-loaded: scope first, then returned fields, then the security caveat, then routing. Every sentence carries unique information, though the parenthetical justification and the retrieval warning are slightly long for a read-only list 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?

There is no output schema, so the description carries the return-value burden and does so thoroughly, enumerating the fields each entry provides. Combined with the scoping rules and cross-tool routing, 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 include_revoked is already documented in the schema (in Chinese). The description mentions that entries report revocation status but does not add syntax or semantics for the parameter itself, so the baseline of 3 applies.

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

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

The description states a specific verb (List) and resource (credentials/api tokens), then immediately scopes it: own credentials plus everything in the workspace if owner. The enumerated entry fields and the explicit routing to revoke_api_token and create_cli_token clearly distinguish it from 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 explicitly names the follow-up action ('Stop one with revoke_api_token; token_id comes from here and nowhere else'), states a deliberate boundary ('Creating a new long-lived token is only possible on the web console'), and points to create_cli_token for one-off SPACE CLI credentials. When-to-use and when-not are both 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?

Adds real context beyond the annotations: workspace independence ('independent of the current workspace'), the exact return shape per mode (catalogue fields, manifest + README + entry source), and a fictional-content warning that prevents an agent from copying names, figures or prices. The read-only reaffirmation ('creates nothing, uploads nothing') largely restates readOnlyHint/destructiveHint, which keeps it from a 5.

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

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

Front-loaded with the core purpose and the BEFORE instruction, then layered by mode. The long middle sentence enumerating use cases and platform features is dense but earns its place as scope-setting; a slightly tighter list would improve it.

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

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

No output schema exists, so the description carries the return-value burden and does so fully — it names the catalogue fields, what the key-mode manifest/README/entry source contain, and what the README covers. Combined with the fictional-data caveat, an agent has everything needed to call it correctly and interpret results.

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

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

Schema description coverage is 100%, so baseline is 3; the description exceeds that by explaining the interaction between the two parameters and the mode transitions (omit everything = catalogue, add key = package detail, add file = one file, omitted file = entry file) and what each mode returns. Some of this duplicates the schema's own descriptions, so not a 5.

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

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

Opens with a specific verb and resource ('List the example packages LivePage ships with and say which one to copy') and states the intended outcome, not just the read. No sibling in the list overlaps this resource, and the three usage modes (no args / key / key+file) are each spelled out, so an agent can distinguish it 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?

Explicit when-to-use: 'Call this BEFORE writing anything you intend to publish', followed by an enumeration of the concrete artifact types it applies to. It also supplies the when-not / why-bother rationale ('writing one from scratch usually misses the platform features') and names the specific features at risk.

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

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

Annotations already declare the safe-read profile (readOnly, idempotent, non-destructive), so the bar is lowered, and the description still adds real value: anchors are pinned to the version the viewer actually saw, and original feedback is returned unchanged. These are non-obvious behavioral traits about versioning and immutability that the annotations do not cover.

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

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

Two compact sentences, front-loaded with the core action, and each clause adds a distinct piece of information (content types, version anchoring, immutability). Slightly dense but no wasted 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 tool with annotations covering safety and no output schema, the description gives a reasonable sense of what comes back. The gap is at the parameters: with three parameters fully undocumented in the schema, the description omits how status and version_id narrow the result, leaving an agent to guess at filtering behavior.

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

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

Schema description coverage is 0%, so the description carries the burden, and it partially does: it enumerates the status values (open/confirmed/disputed/resolved) matching the status enum and references the version-scoping semantics relevant to version_id. However, it never explains that status/version_id act as filters, nor what proposal_id selects, so it only partly compensates.

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 this page's feedback threads') and enumerates the content types it returns (page comments, text anchors, meeting/message feedback, internal notes). It does not distinguish itself from the close sibling list_my_feedback, leaving the agent to infer the scope difference.

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 explicit when-to-use guidance, no statement of prerequisites, and no mention of alternatives such as list_my_feedback or reply_feedback. The only implied usage is 'read feedback for this page', which the agent must infer.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so the safety profile is covered. The description adds genuinely new context by disclosing the returned data surface (counts, sharing exclusions, covers, URLs, passcodes, management URLs), which helps an agent judge output usefulness; pagination/limits are not mentioned.

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

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

Two sentences, front-loaded with the core action, and the second sentence carries the routing instruction. The attribute enumeration is long but each item adds informational value 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 and no parameters, the description compensates well by describing what the listing returns and how it relates to list_proposals. Minor gaps around pagination or ordering behavior remain.

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

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

The tool takes zero parameters, so the baseline is 4; there is no parameter semantics to document or obscure.

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 (this workspace's folders) and enumerates the returned data surface (item counts, sharing exclusions, URLs, passcodes, management URLs). It also names the sibling list_proposals and the distinction between them, so an agent can differentiate without opening schemas.

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

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

Explicitly routes to list_proposals with a folder_id for folder contents, or null for unfiled pages, which clarifies when this listing is the right choice. No explicit 'when not to use list_folders' statement, but the alternative is well identified.

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

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

Annotations already cover readOnly/idempotent/non-destructive, but the description adds genuinely new context: it returns only non-expired invitations, and the invite_id is unavailable anywhere else after creation — an important recoverability constraint an agent can't 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?

Three sentences, zero waste, front-loaded with the core behavior then the motivating use case and the downstream dependency.

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

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

No output schema exists, so the description must convey the return shape — and it does, covering members, roles, invitation links, and the key invite_id. Nothing needed 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?

Zero parameters, so baseline is 4. The description instead characterizes the returned data (members, roles, invitation links), which is the relevant semantic content here.

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

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

Specific verb + resource + scope: it lists workspace members AND roles, plus unexpired invitation links. This clearly separates it from siblings like list_api_tokens, list_folders, or list_sessions.

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 usage context ('identify collaborators, understand who created pages and versions') and names the downstream tool revoke_invite that consumes its invite_id. No explicit when-not guidance, but the routing is clear.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them: it discloses newest-first ordering, the exact status vocabulary, and the non-obvious 'notices ... shown only once' behavior with an instruction to surface them first. This is exactly the kind of side-effect disclosure 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?

Front-loaded with purpose, then usage and relaying behavior; every sentence carries information and nothing is redundant. It is a dense single paragraph with multiple embedded instructions, which slightly reduces scannability but not efficiency.

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

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

With no output schema, the description compensates by enumerating the returned fields (text, category, status values, reply) and explaining the transient notices mechanic. An agent has everything needed to call it and interpret the result correctly.

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

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

Schema coverage is 100% and the single limit parameter is fully documented in the schema (range 1-50, default 20). The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb (List) and precise resource (feedback this workspace has sent to the LivePage team), plus scope and ordering (newest first) and the returned field set. This clearly distinguishes it from siblings like list_feedback and send_feedback_to_livepage without needing to open 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 trigger: 'Call it when the user asks what happened to a suggestion,' and even prescribes follow-up behavior when a reply or shipped status appears. It lacks an explicit contrast against sibling tools (e.g. list_feedback), so it stops short of a 5, but the usage context is concrete and actionable.

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

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

Annotations already declare the safe read profile, but the description goes well beyond them: it explains current_version_id semantics, the distinction between pending_version and held_version, that link_ids are only surfaced here, that legacy links survive visibility changes, and that notices must be relayed once to the user.

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 core routing information is front-loaded, but the body is long and drifts into link/notice workflows that are only tangentially about listing pages, and the trailing keyword dump adds bulk without helping invocation. A capable agent gets what it needs, but several sentences 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 burden of explaining return fields (title, proposal_id, version state, current_version_id, pending/held flags, notices) and does so thoroughly, so an agent knows what to expect and how to act on each field.

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 three-way folder_id semantics that the description merely restates. The description adds no syntax or format detail about the query parameter beyond the schema, so baseline 3 applies.

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

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

The opening sentence states a specific verb and resource ('List pages in the current workspace') and enumerates the returned fields, which lets an agent distinguish it from list_versions, list_folders, and list_feedback. It also preempts naming confusion by explaining that a proposal_id is not a version_id.

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 ('find existing pages rather than asking the user to copy IDs'), parameter-selection guidance for folder_id (omit / ID / null), and names alternatives with conditions — list_versions for earlier versions or rollback, preview_version/get_version for the current version.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds the important scoping note about internal visits and the date-range bound, but does not mention the 90-day maximum, default 30-day window, or pagination/return volume. With annotations carrying the safety burden, this is adequate but not rich.

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

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

Two tight sentences: the first says what is returned, the second says the filtering options and the sibling escape hatch. Nothing is wasted and the front-loaded verb/resource framing is correct.

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 no output schema and partial annotations, the description covers the main return fields and filtering, and points to get_session_timeline. However, it omits the 90-day cap, the default 30-day range, and any pagination/result-size expectation, which an agent needs to invoke it correctly.

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

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

Schema coverage is only 25%: days, link_id and include_internal have no schema descriptions, and only the 90-day/days default hint is present. The description partially compensates by saying it filters by link and optionally includes internal visits, which maps to link_id and include_internal, but it ignores the days parameter and its boundaries. Baseline for near-miss coverage is around 2-3; the description earns a 3 for mapping two of three undocumented params.

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

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

States a clear verb (List) and resource (visits to this page), and enumerates the returned fields (device, start, duration, entry/furthest page, steps, source). It does not differentiate itself from the many other list_* siblings, but the domain object (visits/sessions) is specific enough to distinguish it from list_proposals or list_folders.

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 scope (date range) and the ability to filter by link or include internal visits, plus routes the agent to get_session_timeline for per-step detail. It does not state when NOT to use it or name alternative list tools, but the sibling hand-off for individual steps is a concrete usage 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 cover readOnly/idempotent safety, and the description adds real semantic value: newest-first ordering and the interpretation of rows with status 'published' and is_current false (waiting to publish vs. superseded, and rollback-able via publish_version). It does not mention pagination or result-size limits, so it stops short of full 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?

Front-loaded with the returned shape, then usage routing, then status semantics. Dense but every clause carries information; the field enumeration sentence is somewhat long but earns its place since there is no output 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 and a single parameter, the description compensates well by listing returned fields and explaining status combinations. The only gap is the absence of any statement about result volume/pagination for a listing tool that could return many versions.

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 provenance and identity of proposal_id ('from list_proposals') and stressing that it is not a version_id, which is exactly the confusion an agent would hit. It adds meaningful disambiguation beyond the schema's own 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 the specific resource (the version table of one page), the ordering (newest first), and enumerates the returned columns, so an agent knows exactly what this yields. It also implicitly distinguishes itself from get_version/preview_version by being the listing operation over a proposal rather than a single 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?

Explicitly names the trigger condition ('when a new session has only a proposal_id') and the alternatives that cannot be used (preview_version, publish_version, get_version take a version_id, not a proposal_id). It further routes the agent away from scanning rows by pointing to list_proposals for the current version.

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 generic flags (readOnly=false, destructive=false, idempotent=false). The description adds two non-obvious behavioral facts the annotations do not: removing a page from a folder also strips a folder cover, and moving into a shared folder can grant access to its live version. That is exactly the kind of consequence an agent needs before mutating.

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 core action and null semantics are front-loaded in the first sentence, followed by the two caveats. Every clause carries information, though the final sentence is dense and could be split for readability.

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

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

For a two-parameter mutation with annotations present and no output schema, the description covers the main risks (cover removal, access grant). It does not say whether the move is reversible or what the response contains, but those are minor given the annotations and simple 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 50%: folder_id is documented in the schema itself ('null = not in any folder'), which the description largely repeats, while proposal_id is undocumented in both places. The description adds the access-grant implication of folder_id but nothing about proposal_id, so it partially compensates rather than fully.

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

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

States a specific verb and resource ('Move a page into a folder') plus the null-folder case, so the operation is unambiguous. It does not differentiate itself from sibling tools such as set_folder, which is the only thing keeping it from a 5.

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

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

Usage is implied by the conditional side effects ('moving a folder's cover out also removes that cover'), which hint at when the call has consequences, but there is no explicit when-to-use, when-not-to-use, or alternative-tool 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?

Well beyond the read-only/idempotent annotations: it discloses the 60-minute link lifetime, that screenshots are disabled (screenshot_status is disabled), no-login access, temporary single-version access scope, and that default visitor audience omits speaker notes. It also caps expectations honestly by stating device emulation does not verify real phones, WeChat, or cross-device control.

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 the returned artifact, and nearly every sentence earns its place by adding behavioral constraints. The trailing keyword block is somewhat boilerplate filler, which keeps 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?

No output schema exists, so the description must describe the return value, and it does (interactive_url, 60-minute validity, no images returned). Combined with the lifetime, access, and audience caveats, an agent has everything needed to call it and hand off the result.

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

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

Schema description coverage is 0% across 7 parameters, so the description carries the load. It does add real meaning for audience ('Default visitor audience never includes speaker notes') and viewports (switching and side-by-side comparison), but page, panel, theme, and wait_ms are never explained, leaving most of the parameter surface undocumented.

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

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

States a specific verb and resource: returns an interactive preview link (interactive_url) into the real SPACE viewer for a given version. The negative list (does not publish, record visits, submit feedback, edit access, join live rooms) cleanly separates it from publish_version and the set_* 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?

Gives a clear directive on what to do with the result ('hand interactive_url to the requesting user') and a caution ('share only with the requesting user'). It stops short of naming a specific alternative sibling (e.g., preview_downloads or read_version) and the condition that would select it, so it is strong context rather than 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 only flag destructiveHint=true and idempotentHint=false; the description adds substantial non-obvious behavior: existing versions and comments are preserved, quiet=true suppresses notification to both workspace people and subscribers, and releasing a held version inherits the upload-time quiet choice unless overridden. That is exactly the kind of side-effect and notification 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 prose is front-loaded and every sentence carries behavioral information, but the trailing keyword list ('publish · web page · webpage · link · share ...') is search-engine stuffing that adds length without helping an agent decide or invoke.

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 the state transition, approval gate, preservation guarantees and notification semantics. The main remaining gap is that it never states what the tool returns or how to detect success/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 67% and the description meaningfully extends it: it explains the audience affected by quiet ('workspace people or subscribers'), the inheritance rule for held versions, and the notification consequence. version_id itself is undocumented, so it is not a complete semantic picture.

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

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

States a specific verb+resource ('Make an approved version ... publish live, or roll back to an earlier approved version'), with a clear scope that separates it from preview_version, read_version, list_versions and revoke_versions. An agent can tell what state transition this performs without opening the schema.

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

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

Gives an explicit precondition: 'Call only after the user explicitly approves publishing or rolling back,' plus a caveat that approved uploads without hold may already be live. It does not name alternative siblings (e.g., publish_file) or say when to prefer rollback vs. publish, 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 readOnly/idempotent/non-destructive, and the description adds genuinely new traits: the exact byte delta from the uploaded file (the single script tag), no browser or login required, not_found for other workspaces, and truncation behavior that reports full character count. This is well beyond what structured fields 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?

Front-loads what is returned and why it matters, then layers defaults, exclusions, and error/truncation behavior. A few clauses are wordy ('no browser, no screenshot, no human login, and no need to hand the link to the user'), but nearly every sentence carries operational value.

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

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

There is no output schema, yet the description discloses the return shape (body bytes, truncation with full character count), error cases, and unsupported content types. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is only 50% (version_id has no description), and the description compensates: it explains the default entry-file behavior, the package-relative path semantics, and supported text extensions for `file`. It adds real meaning for both params but stops short of full syntax detail.

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

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

States a specific verb+resource ('read back the rendered body of a version') and immediately scopes it as the reader-visible bytes, which separates it from get_version (metadata/artifacts) and preview_version. An agent can tell exactly what this returns 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 the motivating use case ('confirms for itself that what went live is what it made') and routes to alternatives: get_version artifacts to list files/entry, preview_url or get_version page count for PDF/PPTX. Explicit exclusions are stated (PDF/PPTX, still-uploading versions, cross-workspace not_found).

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 idempotentHint=true, but the description goes well beyond them: it discloses per-request membership rechecking, that existing tokens die on their next request with no separate revocation needed, that removal is irreversible, and that prior per-recipient links are not restored. These are exactly the operational consequences an agent must know before invoking a destructive tool.

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

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

Front-loaded with the critical constraint ('Owner only') and every sentence carries real information. It is on the long side, with the token-behavior clause and the creator-exclusion clause each doing work, though a couple of asides could be tightened without loss.

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-in-spirit membership operation with no output schema, the description covers permissions, side effects on tokens and links, irreversibility, the edge case of the workspace owner, and the correct recovery path. Nothing an agent needs before calling 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 already documents the single user_id parameter including its 26-character constraint. The description adds meaning beyond the schema by warning that 26-character IDs look alike and pointing to list_members as the source that reveals nicknames — useful disambiguation for a single opaque ID.

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

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

States a specific verb and resource ('Remove someone from this workspace') and immediately scopes the effect to pages, folders, links and feedback, which distinguishes it from siblings like set_member_role or revoke_api_token. An agent can tell what this does without opening the schema.

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

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

Gives explicit preconditions ('Owner only'), the intended use case (cutting someone off immediately since membership is rechecked per request), a hard exclusion (the workspace creator cannot be removed), and the correct sibling for reversal ('re-adding them needs add_member or invite_teammate'). It also prescribes confirming the target with the user before calling, which is unusual and valuable 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?

Beyond annotations (destructiveHint=true, idempotentHint=true), the description discloses that removal is irreversible, that it writes to the audit log, notifies the workspace owner on WeChat, leaves payment marks unaffected, and changes form behavior to show totals without a payment step. This is rich 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?

The description is front-loaded with the core action and scope, then proceeds through consequences and alternatives. It is slightly long but every sentence adds distinct value, with only minor redundancy against 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?

Given no output schema and a destructive, idempotent tool with zero parameters, the description covers side effects, irreversibility, notification behavior, form impact, and the correct alternative. Nothing critical for correct invocation is missing.

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

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

There are zero parameters, so the schema carries no semantic burden and the description need not add parameter details. Baseline for 0 params is 4.

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 ('Removes') and resource ('displayed QR-code image', 'business collection QR code'), and clearly distinguishes it from the sibling tool set_payment_qr by noting that one swaps codes directly. The clarification 'no funds are involved' adds precise scope beyond the title.

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

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

It explicitly says the tool is not needed to swap codes and points to set_payment_qr as the alternative. It also provides the context of what happens to forms carrying an amount, giving clear guidance on when this tool applies.

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

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

Annotations only cover the generic profile (not read-only, idempotent, non-destructive); the description adds real behavioral context beyond that — only the name changes, links/versions/visibility/analytics are untouched, no version content is modified, and every rename is audited. That is exactly the value-add expected on top of 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 the core action, then the disambiguation rule, then side-effect guarantees. The keyword list ('keywords: rename, change title, retitle') is mildly redundant noise but the rest 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?

No output schema, and the description covers side effects, non-effects, audit behavior, and the rename-vs-publish distinction, so an agent has enough to call it correctly. Only the undocumented proposal_id leaves a small gap.

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

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

Schema coverage is 50% (proposal_id undocumented), so the description must compensate. It does so for 'title' by explaining that the page name is distinct from the manifest title, though it adds nothing for proposal_id.

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

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

States a specific verb+resource ('Rename a page') and explicitly distinguishes the page name from a version's manifest title, which is the exact confusion an agent would otherwise have. This separates it from siblings like publish_version and set_visibility.

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 trigger condition: 'If the page title changed but lists still show the old name, rename it with this tool,' and clarifies that publishing a new version does not rename the page. It does not name alternative tools (e.g. move_proposal) or state exclusions, so it falls short of the 5 bar.

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 the mutation/safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=false), and the description adds real value beyond them: the reply renders verbatim on the reader's page, matches the web-console reply path, internal threads are visible only to workspace members, and a permission requirement exists. It stops short of covering failure modes or whether replies can later be edited.

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 scoping facts, but the historical sentence ('Until this existed an agent could read...') is rationale rather than invocation guidance and costs space. Four sentences, mostly earning their 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 mutation tool with no output schema and annotations already carrying the safety profile, the description supplies everything an agent needs: where to get thread_id, permission limits, visibility semantics, and rendering behavior.

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

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

Schema coverage is 100%, so both parameters are already documented with descriptions. The description only reinforces that text 'appears verbatim on the page they are looking at' and repeats that thread_id comes from list_feedback; it adds no syntax, format, or constraint detail beyond the schema. 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 ('Write a reply under one feedback thread') and immediately distinguishes itself from the status-changing sibling by noting an agent could previously only 'change its status but could not answer it.' An agent can separate this from list_feedback, set_feedback_status, and send_feedback_to_livepage 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 the agent to list_feedback for the thread_id, states a clear exclusion ('Read-only members cannot call it'), and covers the edge case of internal-visibility threads. The conditions that select this tool versus alternatives are all 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?

Annotations only supply the generic safety profile (non-readonly, non-destructive, non-idempotent), but the description adds real behavioral context: a trial takes 5-15 minutes, only the author sees the trial result, every action returns a 'say' sentence to relay verbatim, and the author must be consulted before passcode/public. The local-clock instruction and 'do not invent facts' rule further constrain behavior 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?

Front-loads the purpose and covers nine actions plus lifecycle in a single dense paragraph with no filler sentence. It would read more clearly as a short bulleted lifecycle, but every clause carries information useful for correct invocation.

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 nine-action, thirteen-parameter tool with no output schema, it covers the create→trial→enable→manage lifecycle, prerequisites, and the 'say' return contract. The only residual gap is that the full task_id workflow (list-then-operate) is implied rather than spelled out, though the schema notes it.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: proposal_id absent means a new page (so title is needed), update takes only what changes, request_append adds rather than replaces, and until resumes on the given date. These clarify usage of key parameters beyond their schema descriptions.

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

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

States a specific verb and resource (keep one page updated on a schedule at the same link, pushed to WeChat) and enumerates the full action set. An agent can distinguish this from siblings like push_to_wechat or publish_version 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 mapping for essentially every action: create when the author specifies coverage/time/visibility/notify, enable only after a successful trial, update for later changes, runs when the author asks whether it went out. Prerequisites (a successful trial is required first) and the passcode/public confirmation rule are stated outright.

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

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

Goes well beyond the annotations by detailing exactly what is destroyed: ALL old URLs stop working immediately, including URLs already sent to intended viewers. It also specifies what is retained (visibility and reading statistics) and requires the agent to confirm the consequence and provide the replacement URL afterward.

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

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

The description is front-loaded with the core action, then immediately explains the destructive consequence and the retained data. Every sentence contributes useful information: scenario, warning, confirmation requirement, and retention behavior.

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

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

Complete for this tool despite no output schema. It covers the target scope, destructive impact, confirmation requirement, retained data, and the expected follow-up of providing the new URL. An agent has everything needed to invoke it responsibly.

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 that exactly one of folder_id or proposal_id must be supplied. The description repeats the mutual exclusivity without adding format, syntax, or other semantic detail beyond the schema, 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 and resource: replace the URL for exactly one proposal_id or folder_id. It clearly describes the operation and its target scope, including 'for example after a leak.' It does not explicitly name or contrast with close siblings such as revoke_share_link, so it falls just short of the top score.

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 a clear usage scenario ('after a leak') and a strong prerequisite to confirm the consequence before proceeding. It does not explicitly state when to use this versus alternatives like revoke_share_link, but the context is sufficient to guide selection.

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

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

Annotations only declare the mutation profile (readOnly=false, destructive=false), so the description carries the interesting burden and does add unique context: the 30-day retention limit, the permanence of purge, and the post-restore behavior (link works again with prior visibility). It does not address what happens on a duplicate restore, though idempotentHint=false makes that a relevant gap.

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

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

Two sentences, front-loaded with the action and its deadline, with the trailing clause earning its place by explaining why purge is irreversible. 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 one-parameter, no-output-schema mutation, the description covers the retention window, irreversibility, and the resulting state of the restored link. Only the duplicate-restore behavior (relevant given idempotentHint=false) and confirmation that proposal_id is the deleted page's ID 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 description coverage is 0% and the single parameter (proposal_id) is never mentioned in the description. The description talks only about 'a page' and never says the caller must supply the deleted proposal's identifier, so it fails to compensate for the documentation gap beyond the fairly self-explanatory parameter name.

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

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

The description gives a specific verb ('Bring back') and resource ('a page you deleted'), plus the governing condition (within 30 days). An agent can immediately distinguish this from delete_proposal and the other proposal-management siblings without opening the schema.

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

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

It states both the use window ('only within 30 days of deletion') and the hard exclusion ('a page already erased cannot be restored'), which is exactly the when/when-not guidance an agent needs. It stops short of naming any alternative path, but there is no real substitute for a restore.

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 idempotentHint=true, but the description adds substantially beyond them: irreversibility ('this cannot be undone'), the absence of a restore tool, the requirement to recreate via the web console with a new secret, the visible-scope rule (own credentials, or everything if workspace owner), and the self-revocation edge case where the calling connection dies.

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 effect and the 'when to use' trigger, and every sentence carries actionable content (irreversibility, scope, self-revocation, blast radius). It runs long and slightly restates the single-credential scope in the opening and closing sentences, but there is no filler.

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

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

For a one-parameter destructive tool with no output schema, the description covers everything an agent needs: effect, triggers, irreversibility, permission scope, error behavior ('reports not found'), and the self-revocation hazard. Nothing material is left to inference.

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

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

Only one parameter and schema description coverage is 100%, so the schema already documents token_id and its provenance. The description reinforces the provenance ('which credential ... by reading its name and prefix from list_api_tokens'), which adds minor confirmation value but nothing the schema lacks.

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

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

States a precise verb+resource ('make one credential stop working immediately') and clarifies the effect in operational terms ('refused on its next call'). It is clearly distinguishable from its revoke_* siblings (revoke_share_link, revoke_invite, revoke_versions) because it names the object as a credential/API token rather than a link or invite.

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 triggers ('when a credential leaked or a third-party app should no longer have access') and an explicit prerequisite workflow: read the name and prefix from list_api_tokens and confirm with the user first. It also states the permission boundary and what to do instead when the credential is out of scope ('anything else reports not found').

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=true, and openWorld=false, but the description adds meaningful context beyond them: the owner-only permission requirement, immediate effect, that it does NOT remove existing members, and post-revocation behavior for anyone opening the stale link. That is the full behavioral picture an agent needs for a destructive mutation.

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

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

Front-loaded with the critical 'Owner only' constraint and appropriately sized for a destructive tool. The metaphorical 'stop the bleeding' phrase is slightly florid but does not obscure the meaning, and every sentence carries a distinct fact.

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

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

With no output schema, the description still covers everything needed: auth requirement, effect, exclusions, parameter sourcing, and downstream consequences. Nothing an agent must know before invoking this tool is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by telling the agent where to obtain invite_id ('Get invite_id from list_members ... invite_teammate also returns it once, at creation'), which is more actionable than the schema's terse property note.

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

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

The description states a specific verb+resource ('Make one unexpired invitation link stop working immediately') and explicitly scopes it apart from sibling remove_member and revoke_share_link. An agent can distinguish it from the other revoke_* tools 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 the precondition ('Owner only'), the scenario that selects it ('forwarded somewhere it should not go'), and names the alternative for the closely-related case ('People who already joined through it are NOT removed; that is remove_member'). The word 'unexpired' also implicitly tells the agent not to bother with expired links.

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, but the description adds substantial context beyond them: holders receive 403, visibility settings do not stop these links, revocation is irreversible with no restore tool, and only that one link is affected while the URL and other legacy links keep working.

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 effect and the use case, then prerequisites, irreversibility, and the alternative. It is fairly long, but nearly every sentence delivers actionable information 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?

Covers what the tool does, when to use it, how visibility interacts, that it is irreversible, its blast radius, where to get the id, and the alternative tool. No output schema is needed for a revoke action, and nothing an agent requires 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% and the single link_id param is already documented as coming from list_proposals. The description adds only the marginal note that link_id is available nowhere else on this surface, so the schema still carries the parameter burden.

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

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

States a specific verb (revoke) and resource (one legacy per-recipient link) with immediate effect (holders get 403). It is clearly distinguishable from sibling revoke tools (revoke_api_token, revoke_invite, revoke_versions) and from reset_default_link, which it explicitly names.

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 (a link reached the wrong person or was forwarded somewhere it should not go), a named alternative with its selecting condition ('To replace the URL instead, use reset_default_link'), a sourcing prerequisite (get link_id from list_proposals), and an interaction guard ('Confirm which link with the user first').

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

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

Goes well beyond the destructiveHint/idempotentHint annotations: it discloses that the current version and link are untouched, that revoked versions cannot be switched back to, that preview addresses stop working, which versions are skipped (in-review/converting/uploading, dedicated-link-pinned), and the storage-dedup nuance behind how much is actually freed.

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 trigger and the reassurance about the current version before the mechanics, and each sentence carries real information. It is dense and long, but there is little filler to cut.

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

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

For a destructive, no-output-schema mutation tool, it covers the trigger, scope/default, exceptions, irreversibility, side effects on addresses, and even what the receipt reports. An agent has everything needed to call it 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 67%; the description compensates by explaining that confirm must be the exact page title (a non-obvious string, clarified in the otherwise-Chinese schema), that omitting up_to_seq revokes everything before the current version, and that up_to_seq is inclusive up to version 1. proposal_id remains unexplained in both places, keeping this short of a 5.

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

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

States a specific verb and resource (revoke a page's older versions) plus the motivating condition (storage full / quota_exceeded). It is clearly distinguishable from siblings such as list_versions, preview_version, and delete_proposal.

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 trigger ('Use this when storage is full (quota_exceeded)') and prerequisites ('check which versions go with list_versions first, and confirm with the user'). It does not contrast against an alternative for reclaiming storage, e.g. deleting a whole proposal, so the routing picture is strong but not complete.

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

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

Annotations only cover safety hints (readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=false). The description goes far beyond: it explains a two-step confirmation dance, what the platform auto-attaches, the upload flow with a 15-minute URL, the 5 MB limit, the no-terminal limitation, that the team reaches out via account-bound contacts, and what the return value contains.

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

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

Front-loads the core purpose, but the paragraph is long and packs many procedural rules into dense prose, which can be hard to parse quickly. Every sentence carries useful information, but the structure could be tightened without losing 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?

Covers the full lifecycle: draft‑show‑agree step, prerequisites for each optional field, the attachment PUT flow with validity window, what the platform attaches automatically, what the return value includes, how to check status later, and when to redirect to support. No output schema exists, and the description adequately describes the return (id and status).

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds procedural meaning beyond the schema: the meaning of user_confirmed (must reflect real agreement), contact_ok (only pass when explicit consent given), version_id (to pinpoint a display problem), and how attachment works. It enriches rather than repeats.

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 (send), resource (user's feedback about LivePage itself), and recipient (the LivePage team). It explicitly distinguishes itself from the sibling add_external_feedback by clarifying that this is not a comment on a page.

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 (after the user sees a draft and agrees), when-not-to-use (if they were venting, or want a person instead of leaving a suggestion, use the support link), and names the sibling alternative add_external_feedback. Conditions for user_confirmed, contact_ok, and attachment feasibility are all spelled out.

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

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

Annotations only cover mutation/safety hints (readOnly=false, idempotent=false). The description adds the critical traits annotations cannot express: 5-minute code validity, 5-attempt limit, hard rate limits (1/60s, 5/day per number, 10/day per user), binding is permanent per account, and numbers bound elsewhere are refused. Exceptional 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?

Front-loaded with the core action, then constraints and warnings in a logical sequence. Dense but every sentence earns its place given the number of behavioral caveats. Slightly long, but the density is justified for a tool with real foot-guns.

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 covers the full lifecycle: what's sent, how to complete verification, error conditions (already-bound number), retry guidance (wait when limited), and identity model. 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% and the single parameter is fully described in the schema (including mainland vs. international format). The description adds context about which number to supply (caller's own, not someone else's) and international country-code requirements, but this overlaps with the schema. Baseline 3 for high coverage 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 (send a 6-digit SMS code to the user's own phone) and names its scope: real-name verification binding the caller's own number. The pairing with verify_phone_code is made explicit, distinguishing it from any other sibling.

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

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

Provides explicit when-to-use (user has explicitly asked to verify) and when-not-to-use (never on your own initiative, don't fill in someone else's number), plus the follow-up tool. This is a textbook routing instruction.

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 annotations (destructiveHint=true, idempotentHint=false), the description discloses that approve/hold are reversible while delete is not, that delete strips the row from the page, exports and counts with only a content-free audit entry, that approving records a false-positive publisher release, and that every decision bumps data_revision. This is exactly the side-effect and reversibility detail an agent needs before a destructive 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?

It is a single dense paragraph but front-loads the core decision semantics before side effects and provenance. A few clauses are padded, notably the 'until now there was nothing you could do about such a row' framing, which adds length without actionable content.

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

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

For a mutation tool with no output schema but with safety annotations, the description covers reversibility, side effects, audit behavior and row_id provenance. The one hole is proposal_id, whose origin is documented nowhere an agent can see.

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 67%. The description elaborates the action enum well beyond the schema's short enum strings (per-action reversibility and visibility semantics) and tells where row_id comes from. proposal_id is left unexplained by both schema and description, which is the remaining gap.

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 precise verb+resource: rendering a decision on a single viewer-appended row via three named actions (approve/hold/delete), each defined in a clause. It implicitly scopes itself to viewer-appended rows, distinguishing it from sibling write tools like set_data and from the read-side list_data_rows.

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

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

It routes the agent explicitly ('Get row_id from list_data_rows') and gives the effect of each action, which effectively tells the caller which action to choose. It stops short of stating when not to use this tool (e.g., non-viewer rows handled elsewhere) or naming a preferred alternative for those cases.

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) cover the safety profile, and the description adds substantive behavior: revision-based conflict detection, immediate application to live versions, and that enabled=false disables all download URLs while preserving the list. It omits permissions/auth requirements and returns, but the concurrency semantics are a meaningful addition.

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

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

Front-loads the core action and then packs constraint details densely; each sentence carries operational information. It is a bit clause-heavy in the middle (label/description/downloadName/showFilename), but nothing is wasted.

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

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

With no output schema and a nested config object, the description covers the mutation semantics, concurrency, and disable behavior adequately. Minor gaps remain around permissions and exactly what the caller should do after a successful write.

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 0%, so the description must carry the load, and it does: it explains source (or null), ordered attachments, required labels, optional description/downloadName, showFilename defaulting to false, keeping filename extensions, and the enabled toggle. Only revision/version_id semantics are left to inference (partially hinted by the 'read get_downloads first' instruction).

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

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

States a specific verb and resource with scope: 'Replace an approved version's download settings without reuploading its content.' This clearly distinguishes a write/config operation from read siblings like get_downloads and preview_downloads.

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 instructs 'Read get_downloads first for its revision and candidates' and gives a conflict-handling rule ('read and review again; do not overwrite blindly'), which is real when-to-use guidance. It does not, however, contrast with preview_downloads or state prerequisites such as the version needing to be approved/published.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false. The description adds behavior beyond them by stating that only workflow status changes and that original comments remain, clarifying the mutation's scope. Permissions and downstream effects are not covered.

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

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

Two sentences, front-loaded with the verb and resource. No wasted words; the status enumeration is compact and directly useful.

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

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

For a simple two-parameter status mutation with annotations covering safety and no output schema, the description is adequate: it explains what changes and what persists. It omits auth requirements and how to obtain a thread_id, but these are minor for this operation.

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

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

Schema description coverage is 0%, so the description must compensate. It names the target resource for thread_id and enumerates the valid status values, but the enum already exists in the schema and thread_id's format or source is not explained.

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 and resource: 'Mark a feedback thread' with enumerated target states. It distinguishes itself from sibling feedback tools like reply_feedback and list_feedback by its status-setting action, though it does not explicitly name 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?

No explicit when-to-use guidance, alternatives, or prerequisites are given. Usage is only implied by the action itself, leaving the agent to infer when to choose this over reply_feedback or list_feedback.

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 the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), and the description adds real behavioral context beyond them: the cover/page linkage requirement, the null-to-restore semantics, and that the cover renders the page's live version. It omits partial-update semantics (whether unspecified fields are left untouched) and any permission 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?

Four short sentences, front-loaded with the primary action and followed by the cover-specific rules in priority order. The null-reset sentence partially duplicates the schema's own cover_proposal_id description, which is a minor redundancy but not wasted space.

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

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

For a four-parameter mutation tool with no output schema and reasonable annotation coverage, the description supplies the field list, the cover constraint, and the reset behavior. It stops short of stating permission requirements or whether untouched fields are preserved, which are the only notable gaps.

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

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

Schema description coverage is only 25%, with just cover_proposal_id documented inline, so the description does meaningful compensating work by naming the three mutable fields (name, introduction, cover) and reiterating the null-reset behavior for the cover. Only folder_id and the fine-grained format limits remain unexplained by both sources.

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 concrete verb and resource ('Change a folder's name, introduction or cover') and enumerates the mutable fields, so the agent immediately knows this is a partial-update tool for folders. It does not explicitly distinguish itself from siblings like create_folder or list_folders, but the mutation scope is 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?

The description gives conditional rules rather than usage routing: the cover must be a page inside this folder shared through the folder link, and setting cover_proposal_id to null restores the generated index. There is no explicit statement of when to prefer this tool over alternatives, but the constraints imply the intended usage context.

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 the mutation profile (readOnly=false, idempotent=false, destructive=false) but nothing about side effects. The description adds substantive context beyond that: default value is false, cached results and crawler copies may persist after disabling (a non-reversible effect), and the confidential-content warning. Strong disclosure for a mutation tool.

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

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

Front-loads the core action and default in the first two sentences, then layers prerequisites and warnings. Dense but each sentence carries information. Slightly compressed into a run-on list of caveats.

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 this is a mutation, so the description correctly covers preconditions, side effects, and irreversibility. It is nearly complete except for the unexplained proposal_id parameter, which leaves a gap given the 0% schema coverage.

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

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

Schema description coverage is 0% and neither parameter is meaningfully explained. The description implies the boolean default ('Default false') but never clarifies what 'indexable' toggles versus what 'proposal_id' identifies. With no schema help, the description fails to compensate for the gap.

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

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

States a specific action on a specific resource: allowing/disallowing search-engine indexing of public pages. This is distinguishable from visibility-style siblings by the word 'indexing', though it never names the sibling it should be contrasted with (e.g., set_visibility). Clear purpose, no explicit sibling routing.

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 real preconditions: 'Requires public visibility and publishing eligibility' and 'Making the link private or passcode-protected disables indexing.' It also instructs confirmation before enabling. It stops short of naming alternative tools for related settings, so it earns a 4 rather than 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?

Beyond the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false), the description discloses real behavioral consequences: an unshared page vanishes from the folder page, cannot be opened via the folder link, and retains its own separate link visibility. It does not mention permissions/auth requirements or reversibility explicitly, but the effect disclosure is strong.

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

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

Four short sentences, front-loaded with the core action before the consequences. Each sentence adds a distinct fact (effect on folder page, effect on folder link, effect on own link, effect on public link), so there is little waste, though the last two clauses overlap thematically.

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

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

For a simple two-parameter boolean toggle with no output schema, the description covers the semantics of the state well but is incomplete where it matters most: the boolean polarity and the identity of proposal_id. No annotation or output schema compensates for that 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 0%, so the description must carry the parameter burden, and it does not name either parameter. The boolean's polarity is left ambiguous: it explains the 'not shared through folder link' state but never maps that to internal=true/false, which is the single most important thing an agent needs. proposal_id is entirely unmentioned.

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

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

The description gives a concrete verb-concept ('Choose whether') and a specific resource: whether a page is shared through its folder link. It clearly describes the state being toggled, but never names itself as distinct from close siblings like set_visibility, set_visitor_internal, or set_folder, leaving the agent to infer the boundary.

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 semantics rather than stated. There is a partial exclusion ('This does not make a public link private'), which hints at when the tool is NOT the right one, but no explicit when-to-use guidance or named alternatives among the many set_* siblings.

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

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

Goes well beyond the annotations (readOnlyHint false, idempotent true, destructiveHint false) by disclosing that the change takes effect immediately for already-issued tokens, that the creator is permanently owner, and that self-demotion is irreversible. These are consequential behaviors an agent could not infer 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-loads the critical constraint (Owner only) and each sentence carries distinct information. It runs slightly long, with the token-behavior and self-demotion clauses both present, but neither 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 exists, and the description never states what is returned or whether the call fails silently on the forbidden cases, which is a minor gap. For a two-parameter mutation it otherwise covers permissions, side effects, and irreversible cases thoroughly.

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 enum is already defined, so the baseline is 3; the description adds real value by explaining the operational meaning of the roles and pointing to list_members for user_id. It does not, however, add format or edge-case detail beyond that.

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 (change), resource (one member's role), scope (this workspace), and the exact target values (editor or viewer). An agent can immediately distinguish it from add_member, remove_member, and invite_teammate 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/when-not guidance: owner-only, the workspace creator cannot be changed, and you cannot change your own role. It even explains the workaround (have another owner do it) and where to source the input (user_id from list_members), leaving nothing to inference.

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

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

Annotations already declare write (readOnlyHint=false), idempotent, and non-destructive behavior, so the bar is lower. The description still adds real value beyond them: where the name surfaces (web console, member lists, future authorization screens) and the 24-character limit, which the annotations do not convey.

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

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

Front-loaded with the core action and limits. The final clause ('there is no argument for choosing someone else, so it cannot rename another member') partly repeats the preceding sentence, a minor redundancy, but overall it is tight and well ordered.

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, non-destructive, idempotent setter with no output schema, the description covers scope, limits, and where the change is visible. Nothing essential is missing, though the maxLength inconsistency between schema and description should be resolved.

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

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

Schema coverage is 100% and the single parameter is fully documented, so the baseline is 3. The description restates the 24-character constraint but adds nothing about format or validation beyond the schema; note also that the schema's maxLength (64) conflicts with the 24-character limit asserted in both the schema description and the tool description.

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 ('change the display name') and immediately scopes it to the authorizing user, which cleanly separates it from siblings like set_member_role, rename_proposal, and set_workspace_profile. An agent can identify the target object 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?

Makes the usage condition explicit ('always changes your own name... cannot rename another member'), which implicitly rules out the member-management and rename siblings. It does not name those alternatives directly or state prerequisites, but the self-only constraint is a strong routing signal.

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 destructiveHint=true and idempotentHint=false, and the description adds real context beyond that: replacement takes effect immediately, the old image cannot be recovered, every change hits the audit log and notifies the workspace owner on WeChat, and money could silently route elsewhere on error. This is exactly the extra behavioral detail annotations cannot carry.

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

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

Front-loaded with the safety framing and the compliance rule, and the closing sentence routes to the alternative. It is long and slightly redundant ('no money moves' restated as 'never places an order, collects or transfers funds'), but the density is justified by the money-loss risk.

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 the full burden: what gets overwritten, irreversibility, side effects, audit/notification behavior, and the sibling that undoes it. Nothing an agent needs to call this safely 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 meaning: the image must be recognised by its bytes (a .png filename proves nothing), must be PNG or JPEG up to 2 MB, and must semantically be a merchant collection code rather than any QR. That reinforces and extends the schema's constraints.

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+resource: it stores exactly one QR-code image and replaces the workspace's business collection QR code. It also names the sibling it is not (remove_payment_qr) and the related set_form flow, so the agent can place 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 about when to use (viewers who submit a form carrying an amount will see this code), when not (use remove_payment_qr to take it down), and prerequisites (confirm it is the user's own merchant code; never scrape an image off a web page). The compliance rule on personal vs business static codes is spelled out with the effective date.

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

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

Annotations only flag it as a non-read-only, non-idempotent, non-destructive write. The description goes well beyond that with masking, background pause, 8 MB per-visit cap, 1 GB per-workspace quota, 30-day retention, future-visits-only scope, and precedence rules – exactly the operational context an agent needs before mutating this setting.

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, then packs the behavioral constraints into a dense but purposeful block. Nearly every clause carries a concrete limit or precedence rule, though the middle sentence is heavy enough to require careful parsing.

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 and no return-value expectations needed for a boolean toggle, and the behavioral picture is thorough. The gap is parameter identification, but otherwise an agent has enough to invoke and reason about the effect.

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 0% and neither parameter is named or explained. The description never clarifies that 'on' is the boolean toggle and 'proposal_id' identifies the target page/link, so an agent must reverse-engineer both from the schema alone.

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

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

States a specific verb pair (enable/disable) and resource (HTML session recording for this page's link and folder visits). The clause about the workspace-wide off switch implicitly distinguishes it from the sibling set_replay_settings, but it never names that alternative, so the differentiation is inferential rather than explicit.

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?

Conveys context (default on, opt-outs persist, workspace switch overrides), which helps an agent understand the setting's behavior, but gives no explicit when-to-use vs set_replay_settings or get_replay_settings, and no prerequisites for calling it.

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 (which only say readOnly=false, destructive=false, idempotent=false). It discloses that re-enabling preserves per-page opt-outs, that existing recordings keep their 30-day retention, and that changes affect future collection only — exactly the edge behavior an agent needs before mutating recording state.

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 tight sentences, front-loaded with the permission constraint, then consequences, then retention, then scope. Every sentence conveys a distinct operational fact with no filler.

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

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

For a one-parameter toggle with no output schema and existing annotations, the description covers permission, effect, reversibility of opt-outs, and retention behavior. Nothing essential for correct invocation is missing.

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

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

The single boolean has 0% schema description coverage, so the description must carry the meaning. 'Disable to stop recording' and 'Re-enabling preserves...' implicitly define the two states of enabled, adding real semantic value, but the parameter is never explicitly named or mapped to true/false.

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

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

States a specific action and resource: disabling stops recording 'across all pages and legacy links', scoping the operation to workspace-wide recording. Clear enough to distinguish from the read sibling get_replay_settings, though it does not differentiate itself from the similarly named set_replay.

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?

'Owner only' supplies a real prerequisite, and 'Disable to stop recording' implies the triggering condition. However, it never names alternatives or states when to prefer this versus get_replay_settings or set_replay, so usage is only implied.

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

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

Annotations only cover the safety profile (readOnly=false, idempotent=false, destructive=false); the description adds material behavior the annotations cannot: immediate effect, folder-level inheritance overriding private links, separation of excluded items and legacy permissions, and stable-URL semantics. Return/pagination context is absent but not critical for a mutation here.

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

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

Front-loads the one-of constraint and the three modes, then layers behavioral notes. Dense and mostly justified, though the trailing sentences on link semantics and 'reading records' are somewhat clipped and 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?

For a mutation tool with no output schema, the description covers effects, inheritance, and cross-tool interactions well. It omits return/confirmation behavior, but 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 75% and the enum for visibility has no inline description in the schema, yet the description defines private/passcode/public precisely and clarifies passcode 'generated or retained when omitted'. It adds real meaning beyond the schema, though the exact passcode format is already in the schema.

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

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

States a specific verb (Set) and resource (visibility) and immediately scopes it to 'exactly one proposal_id or folder_id'. It also names the sibling reset_default_link and its distinct role, letting an agent separate the two without opening schemas.

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

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

Gives a clear directive ('Confirm external sharing with the user first') and routes URL-reset needs to reset_default_link. It lacks explicit when-not conditions, but the context for use 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 declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the safety profile is already carried. The description adds genuinely non-structured context: the filter is applied at read time, history is retroactively recomputed, and the operations view reports how many visitors were excluded so the change stays auditable. It stops short of describing failure modes or what happens to a visitor_id that no longer exists.

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