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?

Goes well past the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false): it discloses the quota and premium gating, that binding never takes the user's DNS keys, that ICP filing determines mainland vs overseas serving and can later be switched via set_domain_region, and how root domains either flatten in place or 301-redirect through a US host with an added latency cost. Idempotency is not merely restated — the description says a repeat call returns the same record plus current progress, which is the practical detail an agent needs.

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

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

Front-loaded correctly: cost/quota gating, then the return shape, then the follow-up sequence, then the conditional root-domain detail. The bolding and phrasing give an agent clear landmarks. It is, however, a very long block for a two-parameter tool, and the ICP/root-domain material could be tightened or moved to the sibling tools that act on 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?

With no output schema, the description carries the return-value burden and does it: it enumerates records (type/name/value/why), dns_provider, notes, say, retry_after_s and state, and instructs the agent to relay say verbatim. Combined with the premium, quota, ICP and apex handling, nothing an agent needs in order to call this correctly and hand off to verify_domain is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it tells the agent to pass apex_mode="flatten" only after the user confirms their edition, and names which providers are recognised automatically (Cloudflare, DNSPod Enterprise; Alibaba Cloud DNS Flagship requires explicit confirmation). The hostname examples duplicate the schema's own example rather than adding to it, keeping this from 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 ("Bind LivePage to the user's own domain") and immediately scopes what readers see and what the single call returns ("every record to add at the DNS provider in records"). It explicitly names the sibling steps it is not: set_page_path for the default address, verify_domain for progress, set_domain_route for routing. An agent can pick this tool out of a large sibling list without opening the schema.

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

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

Gives explicit preconditions (owner-only, premium account, 3 domains per workspace, quota_reached on free accounts) and explicit alternatives (use set_page_path for the default <workspace>.hy.24haowan.com address). It also routes the follow-up flow: call verify_domain after records are in, repeat after retry_after_s until state=active, then set_domain_route. Even the branching on whether the agent has the user's DNS-provider tools is 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 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?

Annotations only say it is a non-destructive, non-idempotent, non-open-world write; the description adds substantially: the allow_copy precondition, concrete failure codes (403 copy_not_allowed, 410 revoked/expired/deleted) with an instruction not to work around them, the fact that the result is an unpublished draft independent of the source, and that it consumes storage quota.

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 trigger sentence, then structured bullets for preconditions, side effects, and follow-up calls — no filler. It runs long with heavy bolding and parenthetical keyword lists, which is slightly more than strictly needed, but each bullet carries operational information.

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

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

No output schema exists, yet the description implies the returned handles (version_id for read_version, proposal_id for publish_file) and covers preconditions, error paths, side effects, and the publish flow. An agent has everything needed to invoke it and handle failure.

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

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

Schema description coverage is 100%, so link, title (default = original + '(copy)'), and folder_id (default = no folder) are already fully documented in the schema. The description adds only that the link is passed as-is from the user, which is marginal extra meaning over structured fields; 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: copies the currently-published version of a shared LivePage into a new page in the caller's own workspace. It is clearly distinguishable from siblings like create_proposal (blank new proposal), read_version (read only), and finalize_upload (publish an existing draft).

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 ('when the user pastes a LivePage link and says copy it to my space / I want to edit it'), plus keyword aliases (copy, duplicate, save as, edit a copy). It also spells out the post-call sequence (read_version → edit → publish_file / finalize_upload), so the agent knows both when to enter and what to do next.

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 only say this is a non-read-only, non-destructive, non-idempotent call; the description adds far more: the link is valid 2 hours, succeeds only once, uploads only into that one page, needs no login, and works from WeChat. It also discloses the hold default and its conditional effect, and specifies the required post-call loop (hand the URL over unchanged, then poll get_version every 15–30s and branch on 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?

The routing rule is front-loaded and useful, but the decision tree is stated twice in near-identical wording, the hold explanation duplicates the schema text, and the trailing keywords block plus the throwaway line about the page linking to page details add length without adding decisions. The follow-up protocol is worth its words; the rest is padded.

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

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

For a five-parameter, zero-required tool with no output schema, the description covers everything an agent needs: selection, creation mode, the handoff instruction to the user, and the polling/confirmation loop through get_version up to publish_version. Nothing required to call it correctly or to finish the workflow 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 operational meaning beyond the schema: proposal_id and title are mutually exclusive modes (new version vs new page), folder_id only applies when creating, and proposal_id must be found via list_proposals first. It largely restates hold's semantics rather than extending them, which is why this is 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?

The description states a specific verb and resource (create an upload page link the user opens to pick files) and explicitly separates it from the two plausible siblings, publish_file and create_cli_token. An agent can pick this tool without opening any schema.

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

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

It gives an explicit routing rule: terminal ⇒ SPACE CLI (create_cli_token first); no terminal plus text files under 2 MB total ⇒ publish_file; anything else or unsure ⇒ create_upload_link. It also names the alternative for a single HTML/Markdown file whose content the agent already has, which is a real exclusion, not just a suggestion.

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?

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds substantial context beyond them: pages survive and move to "not in any folder" keeping their links and permissions, the folder link and folder page break immediately, the folder disappears from the home page, and there is a 30-day restore window with a caveat about pages moved elsewhere in the meantime.

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 most important fact (pages are never deleted), then consequences, then recovery, then the confirm requirement. It is a single dense paragraph rather than a list, which slightly hurts scannability, but every sentence carries operational 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 two-parameter destructive mutation with no output schema, the description covers consequences, immediate effects, recovery path, confirmation protocol, and the alternative tool for page deletion. 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 50%: confirm has a description (in Chinese) about passing the folder name verbatim, while folder_id is undocumented. The description compensates by explaining that confirm must repeat the folder name exactly and that list_folders should be used to obtain it, which effectively documents how to source folder_id too.

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 ("Delete a folder") and immediately scopes it: "the folder only, never its pages." That scope statement distinguishes it from delete_proposal, which the description explicitly names as the tool for deleting pages.

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 and alternatives: check with list_folders first, confirm with the user, use restore_folder to undo, and delete_proposal one-by-one if pages should also go. Both the when-to-use and the when-to-use-something-else cases are 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 already declare destructiveHint=true and readOnlyHint=false, so the safety profile is partly covered. The description adds real context beyond them: the immediate 404 for readers, the 30-day restore window, the automatic permanent erasure afterwards, and the exact scope of what ceases to exist. However, the confirm/title-guard behavior is the only invocation-critical detail it describes, and it does not cover whether the call is rate-limited or what a successful response returns. A 3 reflects solid added context while annotations carry the safety signal.

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

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

A single dense paragraph that front-loads the destructive effect and its visibility consequences before the reversible/irreversible distinction. Every sentence carries information, though the parenthetical list of erased artifacts makes it heavier than strictly necessary.

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 two-parameter tool with no output schema, it covers effect, reversibility window, permanent consequences, blocking preconditions, and the safety input. An agent has enough information to invoke this 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 only 50% (proposal_id has no description), but the description compensates: it explains that confirm must exactly repeat the page title as a wrong-deletion guard and that the target should be verified via list_proposals. The one gap is that proposal_id itself is never characterized as the page identifier.

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 plus resource ('Delete a page') with an immediate statement of the observable effect (link breaks, 404, disappears from lists, analytics and folder pages). It is clearly distinguished from restore_proposal and list_proposals, which are named in the text.

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 and alternatives: use restore_proposal within 30 days to undo, resolve any unresolved report before deleting, and check the target with list_proposals first. This covers when to use, when it will fail, and which sibling to reach for in each case.

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

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

Annotations declare destructiveHint=true and idempotentHint=false, but the description goes well beyond them: it names exactly what is destroyed (the name only), what survives (the version, still listed and rollback-able), and the reader-visible consequence in both states (newest remaining tagged version, then newest live version once all tags are gone). The 'Reminds no one' clause additionally discloses that no notification is sent.

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 its scope, then the consequences in a compact sentence. 'Reminds no one' is terse to the point of being cryptic, but every clause otherwise carries real information and 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 destructive two-parameter mutation with no output schema, the description covers the important post-conditions: version retention, rollback path, and reader-facing fallback. Gaps remain around prerequisites (permissions) and error behavior when the named tag or proposal doesn't exist — relevant given idempotentHint=false.

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%: 'name' is documented in the schema but 'proposal_id' has no description anywhere. The description adds no parameter-level meaning at all — it never indicates which page/proposal the tag belongs to or that proposal_id identifies the target page, so it does not compensate 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 with explicit scope: 'Delete one tag from a page', then immediately bounds it ('only the name goes, the version stays'). This is clearly distinct from version-destroying siblings like revoke_versions or delete_proposal 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?

The 'version stays (still in list_versions, can be rolled back to)' clause implicitly contrasts this with version-removal tools, which is helpful context. However, no sibling is named and there is no explicit when-not guidance (e.g., when to use revoke_versions instead, or what to do if the tag is the last one).

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

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

Far beyond the annotations: it discloses latency (PDF/PPTX conversion 1–3 minutes), polling cadence, failure granularity (file/line/fix issues), that review status blocks publishing, that moderation outages never release content, and the critical side effect that by default approval immediately replaces the live version. It also explains when hold is silently ignored (workspace-only pages), which is exactly the kind of non-obvious behavior 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 and purposeful in the first half, but the IMPORTANT block restates the 'readers outside the workspace' condition twice almost verbatim and largely duplicates the schema's hold description. The trailing keyword list ('publish · web page · webpage · link · share to WeChat ...') aids retrieval but is padding rather than instruction.

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

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

For a complex 6-parameter, nested-manifest tool with no output schema, it covers what matters operationally: timing, failure handling, publishing side effects and the hold decision. It omits where the 'preview URL' it tells the agent to provide comes from (presumably get_version/preview_version) and says nothing about the tag/quiet semantics that determine reader-facing outcomes.

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 67%, so the schema already documents hold, quiet, tag and download_basis. The description reinforces hold with decision guidance (only when the user has not explicitly approved), which is real added meaning, but it says nothing about version_id, download_basis, or the large manifest object beyond mentioning that it is validated — leaving the heaviest parameter entirely to the schema.

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

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

Specific: 'Call after all file PUTs finish. Verifies size, SHA-256, signatures, archive and HTML safety, manifest and content moderation' names the verb (verify) and the resource (uploaded files/version), and the IMPORTANT paragraph reveals the second function — approval that can make the version live. It stops short of stating in one place that this is the finalize-and-approve step distinct from publish_version, so an agent has to infer the name's meaning from a later paragraph.

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

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

It gives an explicit trigger ('after all file PUTs finish'), a follow-up loop ('poll get_version every 15–30 seconds'), a remediation path on validation failure ('correct and upload the affected files'), and an explicit branch to another sibling ('hold=true ... then call publish_version'). The conditional for hold (only when the page has readers outside the workspace) is stated twice with concrete examples, leaving nothing to guess.

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 cover the safe-read profile (readOnlyHint, idempotentHint, destructiveHint=false), and the description adds genuinely useful domain behavior: which settings are immutable (follow updates, capsule placement, brand row, 'Make one') and which single premium setting can vary. It also names the four returned values, which is more than the annotations provide.

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

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

The core content is front-loaded and useful, but the first sentence is a long compound statement about fixed elements, and the final sentence about set_visibility is a non-sequitur for a getter tool that dilutes focus without helping the caller invoke 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?

With no output schema, the description correctly compensates by enumerating the returned fields (plan, workspace_capsule, page_capsule, manifest_capsule, effective_capsule) and their value domains. Combined with the documented optional parameter, an agent has enough to call it correctly; only the omission of any note about the corresponding setter is a gap.

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

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

Schema description coverage is 100% and the sole parameter's meaning ('Which page; omit to read only the workspace default') is already fully documented in the schema. The description's 'Omit proposal_id to read only the workspace' restates that same fact rather than adding format or edge-case 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?

The description states a specific verb+resource ('Read the reader side back') and enumerates exactly which reader-side settings are fixed versus settable, so an agent knows what it is reading. It never names the sibling set_reader_view, so it stops short of explicit sibling differentiation, but the read framing is unambiguous.

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

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

'Omit proposal_id to read only the workspace' gives clear conditional usage for the single parameter. However, there is no routing guidance to the obvious sibling set_reader_view for changing these values, and the trailing mention of set_visibility is a tangential aside rather than an alternative-selection rule.

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

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

Annotations already declare 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?

Annotations only declare readOnly/idempotent, yet the description adds substantial behavior: rows are returned newest first but oldest first when since is passed, held vs approved visibility, withdrawn rows remain listed with withdrawn_at, image URLs expire in one hour, and location coordinates null out 30 days post check-in. It also warns that visitor rows carry no identity and must not be read as intent.

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 purpose and the get_data/set_data relationship, and nearly every sentence carries information an agent needs (status values, withdrawal semantics, image and location payloads). It is a dense single paragraph, though, and the payload-shape details would read better as structured lines than run-on prose.

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

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

With no output schema, the description carries the full burden of describing return values and does so thoroughly: per-row status, submitter shape (member vs visitor), device, time, versions, plus conditional images and location objects. Nothing an agent needs to interpret a reply 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 description clarifies semantics the schema only sketches: limit defaults to 100 and caps at 500, since accepts the returned next_since, a row_id, or an ISO time, and crucially that since flips ordering to oldest first. Only proposal_id gets no explanation in either the description or the schema, a minor gap at 80% coverage.

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

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

States a specific verb and resource ("Read rows viewers appended to a data table from the page") and immediately scopes it against the sibling read tool: "These rows are not in get_data rows and are never overwritten by set_data." An agent can distinguish this from get_data without opening either schema.

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

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

Gives explicit alternatives and the condition that selects them: use set_data to merge these rows into the base table, and set_data_row_status to act on a held row. It also names the filtering and pagination affordances (table/status, since) that define when this call is the right one.

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, and non-destructive, so the safety profile is covered. Beyond that, the description adds substantive behavior: a 30-day restorable window, newest-first ordering, and the erasure deadline per item. Pagination or result-size behavior is not mentioned, 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 tight sentences, front-loaded with the scope and ordering, followed by the field summary and the restore routing. No filler or repetition of the title.

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

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

With no input parameters and no output schema, the description carries the burden of describing return values, and it does so by enumerating kind, id, name, deletion time, and erasure time. Missing pagination/count behavior for potentially long lists is the only notable 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?

With zero parameters the baseline is 4, and nothing here detracts. It usefully adds cross-tool semantics by showing how the returned 'id' maps into restore_proposal's proposal_id and restore_folder's folder_id, which is not derivable from this tool's own 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 ('List pages and folders') plus an explicit scope ('deleted in the last 30 days that can still be restored') and ordering ('newest first'). This clearly separates it from list_proposals/list_folders (live content) and from restore_proposal/restore_folder (mutations).

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

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

The description gives clear context for use—only recoverable, recently deleted items are returned—and names the exact follow-up tools with parameter mappings ('restore_proposal (proposal_id = id)', 'restore_folder (folder_id = id)'). It doesn't explicitly say what to use for older/permanently deleted items or for live content, so it falls just short of naming all alternatives.

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

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

Beyond the supplied readOnlyHint and idempotentHint annotations, the description discloses operational constraints: 3 slots per workspace on premium, root-domain-plus-www counting as one slot, and the rule that free accounts cannot bind new domains while existing ones keep working. It also describes the return structure (progress, certificate expiry, paths, slot usage), which is valuable since there is no output 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 purpose and return fields are front-loaded, and every clause contributes useful detail about slot counting or premium restrictions. The first sentence is dense with parentheticals, but no sentence is redundant.

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

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

For a zero-parameter, read-only listing tool with no output schema, the description supplies the missing return-value context (progress fields, certificate expiry, path mappings, slot usage) and the key business rules (premium slots, free-account binding restriction). An agent has enough information to invoke and interpret this tool correctly.

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

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

The tool takes no parameters, so the baseline is 4. The description correctly spends no space on parameter semantics and instead focuses on what the tool returns and when to call it.

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

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

The description states a specific verb and resource ('List the custom domains bound to this workspace') and enumerates the returned fields: progress state, certificate expiry, path mappings, and slot usage. This clearly distinguishes it from sibling domain tools such as bind_domain, unbind_domain, or verify_domain.

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 two triggers: 'when the user asks which domains they have' and 'when you need a domain_id'. It does not explicitly exclude mutation-oriented siblings like bind_domain or set_domain_route, but the read-only framing and trigger conditions provide clear 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?

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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered; the description goes further by disclosing the diff output categories and the concurrency-detection contract via the basis token. It also explains inheritance semantics for omitted downloads (inherit current settings, first version defaults to none, empty array clears) and the rule that missing files must be resolved explicitly — behavior an agent could not infer from annotations alone.

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

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

Purpose and workflow position are front-loaded in the first sentence, followed by return shape and then field semantics — a sensible order. Every sentence carries information, though 'The CLI handles this step' is terse to the point of ambiguity about what an agent should do with that 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 does the necessary work of naming the returned diff fields and basis token, and it explains the mutate-vs-clear semantics that matter for a preview call. The remaining gap is the undocumented manifest vocabulary, which is presumably shared with the upload/finalize siblings but is not referenced here.

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 manifest is a large nested object, so the description carries real weight: it defines the semantics of the downloads field (omission inheritance, defaults, empty-array clearing) and the role of the returned basis token. However, it says nothing about the dozens of other manifest properties (title, entry, cta, forms, actions, theme, etc.) or about version_id, leaving most of the schema undocumented in both places.

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 operation: diffing a proposed downloads manifest against the current version of a version_id, and enumerates the result categories (added, removed, replaced, missing, full list, basis token). Combined with the title and the sequencing sentence, an agent can distinguish this from create_upload_session and finalize_upload without opening any schema.

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

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

It places the call precisely in the workflow — after creating an upload session, before finalizing — and tells the agent to carry the returned basis into finalize_upload as download_basis to detect concurrent changes. It also hints that the CLI covers this step, which is an implicit exclusion but not a spelled-out 'do not call when'. No competing sibling such as preview_version is named 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?

Goes well beyond the annotations with behavior an agent could not otherwise know: 60-minute expiry, screenshots disabled and screenshot_status disabled, no login required, visitor audience never includes speaker notes, device emulation does not verify real phones/WeChat, embed links are origin-locked to allowlisted parents and expire, and renewal keys must stay server-side. This is exactly the extra context annotations can't carry.

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

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

The purpose is front-loaded, which is good, but the body is a dense run-on of chained clauses and the trailing 'Keywords: publish · web page · ...' list is search-stuffing that adds noise rather than agent-relevant meaning. Several constraints are repeated (60 minutes appears twice, no login twice).

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

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

With no output schema, the description correctly names the fields returned (interactive_url, embed.url, screenshot_status, embed.renewal) and covers security/expiry constraints, so an agent can call and hand off the result safely. The remaining gap is the unexplained page/panel/theme/wait_ms parameters, which leave preview composition ambiguous.

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 22% across 9 parameters, so the description must compensate. It does cover the consequential ones — audience (visitor default, no speaker notes), viewports (desktop/mobile/both side by side, fills a phone screen), embed_origin and embed_renewable — but page, panel, theme, wait_ms and version_id get no semantics at all.

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 artifact: returns an interactive preview link to the real SPACE viewer, valid 60 minutes. The explicit 'Read-only: does not publish, record visits...' clause separates it from write-side siblings such as publish_version and push_to_wechat without needing to open their 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 concrete operating instructions: 'Hand interactive_url to the requesting user', 'Pass embed_origin to also get embed.url', 'call again to refresh', and 'share only with the requesting user'. It also enumerates what it does not do (no publishing, no feedback, no presenter rooms). It never names a sibling alternative by name, which keeps it below a 5.

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

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

Beyond the annotations' basic mutation profile, it discloses moderation gating, automatic release, hold and notification behavior, remote fetching constraints, and rejection with too_large rather than truncation. The requirement to hold unapproved releases for pages with external readers is especially valuable safety 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 purpose and routing are front-loaded, but the remainder is a sprawling, dense paragraph with repeated no-terminal guidance and substantial duplication of the hold, quiet, and file-field schema descriptions. The keyword tail adds further bulk, while headings or bullets would make the many modes and constraints much easier to scan.

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

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

For an 11-parameter, multi-mode publishing tool, it covers selection, invocation combinations, content acquisition, limits, moderation, release safety, notifications, and several errors; the schema documents the remaining fields such as manifest. With no output schema, however, the response contract is only indirectly described as a LivePage link and as being the same as finalize_upload, so the definition is not fully self-contained about the returned 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?

Although schema coverage is 100%, the description adds substantial cross-parameter semantics: title versus proposal_id, filename/content versus files, content versus url, and the entry-page fallback order. It also supplies aggregate limits, supported text formats, public-URL restrictions, and concrete failure behavior that the individual schema fields do not fully capture.

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

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

The opening sentence gives a specific action, resource, and outcome: publishing HTML or Markdown content to a WeChat-ready LivePage link without a terminal. It also distinguishes the tool from built-in site publishing and from the CLI and upload-link routes.

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 provides an explicit selection tree among SPACE CLI with create_cli_token, publish_file, and create_upload_link, plus separate guidance for WeChat sharing and binary content. It also explains when to use list_proposals for an existing page and when hold leads to preview followed by publish_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 destructiveHint=true and non-idempotency; the description adds real context beyond them: 'Existing versions and comments remain', the explicit-approval gate, and the notification side effects of quiet=true, including that releasing a held version inherits the upload-time quiet choice. That is meaningful disclosure about side effects not encoded anywhere in the schema, though permissions and rollback reversibility are still unstated.

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 is front-loaded and each of the first four sentences carries real information about preconditions and notification effects. The trailing keyword list ('publish · web page · webpage · link · share · share to WeChat · ...') is thirteen tokens of search-style noise that add nothing to an agent's decision.

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 trigger condition, the survival of existing versions/comments, and the notification matrix. What is missing is modest: whether this requires a specific role or permission, and what happens to readers mid-session when the live version switches.

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% and tag/note/quiet are already richly documented there, so the description only needs to compensate at the margin. It does add one non-obvious interaction (quiet on a held version carries over from upload), but version_id — the sole required parameter — is undocumented in both schema and description beyond the vague 'roll back to an earlier approved version'.

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

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

The first sentence states a specific verb and resource pair ('make an approved version live', 'roll back to an earlier approved version'), which is far more precise than the title alone. It doesn't explicitly distinguish itself from near siblings like publish_file, tag_version, or revoke_versions, so the agent still has to infer which switching tool applies.

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

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

It gives a hard precondition — 'Call only after the user explicitly approves publishing or rolling back' — plus the useful edge case that approved uploads without hold may already be live, avoiding a redundant call. It never names an alternative tool, so the routing guidance to siblings is implied rather than stated.

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

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

Goes far beyond the annotations: discloses the shared deduplication ledger across automatic push/publishing/this tool, the force limit (5/day, self only), the 409 on missing live version, the QR binding flow, and that non-followers are reported but not errors. These are exactly the mutation traits (idempotentHint=false, openWorldHint=true) an agent needs to reason about side effects.

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 default before the edge cases, and every clause carries operational detail. It is dense and long, with mild repetition of the dedup concept, but the length is largely justified by the behavioral quirks it must disclose.

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

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

No output schema exists, yet the description describes the receipt's first line, the dedup message, the failure categories, and the bind_qr_image_url — so an agent knows exactly what comes back and how to relay it. 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?

Schema coverage is 100%, so the schema already documents each param. The description adds meaning beyond it — e.g., that `to: "members"` excludes the caller when "also send to me" is off, and how `force` interacts with the dedup ledger — though it largely restates the schema's own wording for `to` and `include_subscribers`.

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 — sending the page's CURRENT LIVE version as a WeChat template message — and immediately distinguishes itself from alternatives like automatic push and the publish receipt's push_qr_url. An agent can tell what this does versus set_publish_notify or publish_version without opening the schema.

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

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

Explicitly says when to call it ("when the user says send it to my WeChat"), when not to (automatic push already sent it — no need to call), and offers the alternative path (publish receipt's push_qr_url for computer users). Defaults, exclusions, and the force caveat are all laid 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 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 already declare non-read-only, idempotent, non-destructive, so the safety profile is covered. The description adds genuinely non-structured context: where the new name surfaces (web console, invitation pages, home and folder pages), the 40-character ceiling, that links/pages/members are untouched, and the owner-only permission requirement. It stops short of describing the response or failure modes beyond permission.

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

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

Front-loaded with the core action and the character limit, then progressively narrowing with the ★ and ⚠️ markers. All sentences carry real content, though the marker formatting is slightly heavier than needed for a single-parameter 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?

With one required parameter, full schema coverage, annotations present and no output schema, the description supplies everything an agent needs: what changes, what doesn't, size limit, visibility surfaces, and the authorization requirement. Nothing material 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; the description still adds value by giving an example of the intended content ('replace the generated "xxx's workspace" with a company or brand name') and restating the 40-character limit that conflicts with the schema's maxLength of 128. It doesn't resolve that schema/description length discrepancy explicitly.

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 this workspace's display name') and immediately scopes it to the display name only, explicitly excluding the URL slug and the WeChat company name. An agent can distinguish it from set_workspace_slug and set_workspace_profile 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?

Names the two alternative tools and the exact condition that selects each: set_workspace_slug for the <workspace> subdomain, set_workspace_profile's company_name for WeChat share cards. It also states the prerequisite ('Workspace owner only'), so the agent knows when the call will fail.

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 already declare this is a non-read-only, non-destructive, non-idempotent write, and the description adds substantial context beyond that: the wall is public and anonymous by default, only industry is derived from the workspace profile, show_name=true reveals the nickname, requests are moderated, the factory triages daily and replies publicly, the user is notified on status change, and the return value is a public URL. That is genuinely rich disclosure. However, it never states the privacy/user-identity consequence of improving someone else's template or what happens to a request that fails moderation, so it is strong but not exhaustive. Because annotations carry the safety profile and the description adds real behavioral context, a 3 sits appropriately between 'adequate' and '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?

Dense but front-loaded: purpose first, then when-to-use, then content rules, then rate limits and outcome, then the return value. Every sentence carries information, though the middle section on text content and privacy is packed into one long clause-heavy sentence that is harder to skim.

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

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

With no output schema, the description correctly states what is returned (the request's public URL) and to show it to the user, and it covers the consent, anonymity, and moderation flow an agent needs before calling. The gap is the internal inconsistency between the schema's maxLength of 1000 and its own note of 'up to 500 characters', which the description does not resolve.

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, and the description earns an increment by explaining that template_key must be the key from list_examples, that show_name should only be passed with user consent, and by giving content guidance for text (say what they want, who reads it and where). It stops short of addressing scene or the 1000-vs-500 character discrepancy, leaving some ambiguity.

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

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

The description opens with a specific verb+resource: 'Post a request on LivePage's public template request wall', and immediately disambiguates the two modes (kind=new vs kind=improve). It also ties the tool to its sibling, naming list_examples as the source of template_key and the trigger for using this tool, so an agent can distinguish it from sibling 'report_task' or '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?

Explicit when-to-use conditions are given: only when list_examples has nothing that fits, or a template lacks something needed, and only after the user agrees to submit. It also names the alternative (list_examples) and the gate (user consent), plus the per-day cap and moderation step that constrain invocation.

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?

Beyond the annotations, the description discloses meaningful side effects: the original link is reactivated with prior visibility, and pages moved out during deletion are returned if they were not moved elsewhere. The 30-day window is also stated. It does not cover failure behavior after the window or idempotency, but the core restoration semantics are transparent.

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 three tight sentences with no filler. The temporal constraint and restoration effects are front-loaded, and the prerequisite is placed at the end for quick reference.

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 mutation tool with no output schema, the description covers the essential what, when, side effects, and prerequisite. It could mention the non-idempotent behavior from the annotations, but otherwise it is sufficiently 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 0%, so the description must compensate. It does so for the single required parameter by telling the agent to obtain folder_id from list_deleted, which is the key operational detail missing from the schema.

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

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

The description states a specific verb and resource — bringing back a deleted folder — and makes clear it is the inverse of delete_folder and distinct from list_deleted. An agent can identify the operation without opening the schema.

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

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

It gives clear conditions for use: the folder must be restored within 30 days, and the folder_id comes from list_deleted. It does not explicitly enumerate when not to use this tool or name an alternative restore mechanism, but the context is strong enough for correct invocation.

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 say readOnlyHint=false and destructiveHint=false; the description supplies far more: the platform auto-attaches the calling agent, related pages/version, and the last failing tool with its error code, so the agent knows what not to duplicate. It also documents the two-step attachment flow (declare mime/size, then PUT to attachment_upload.put_url with a 15-minute validity and a no-terminal fallback), and states the return is id and status with list_my_feedback for follow-up.

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 purpose and the ★ consent gate before any logistics, and each clause carries distinct operational content (consent, content limits, auto-attached context, attachment upload, contact opt-in, return value). It is dense and reads as one long paragraph, so a few clauses (e.g. the mime list) could be compressed, but there is little pure waste.

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

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

For an 8-parameter mutation with a nested attachment object and no output schema, the description covers the consent contract, what the server attaches automatically, what must never be included (page content, reader info, tokens, passwords), the attachment mechanics, and what the call returns. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, and the description goes beyond it: it explains when to pass version_id (from list_versions, for hard-to-describe display problems), the exact condition for contact_ok (only if the user explicitly permits contact, and don't ask just to fill it), the source="hint" origin from feedback_hint, and the consent semantics of user_confirmed. The attachment sub-object handling is described operationally rather than by field, which keeps it from 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 (send the user's feedback about LivePage itself to the LivePage team) and explicitly delimits the scope against the nearest sibling: "not a comment on a page (that is add_external_feedback)". An agent can route between this and add_external_feedback without opening either schema.

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

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

Gives an explicit precondition (show a draft, call only after explicit agreement with user_confirmed=true) and an explicit negative case ("If they have not agreed, or were only venting without asking to send feedback, do not call it"). It also routes two alternatives: add_external_feedback for page comments and the server-instruction support link for users who want a person.

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?

Annotations only declare destructive/not-idempotent; the description adds far more: 409 rejection on stale revision, moderation and rate limiting of appended rows, 403 for visitors under members_only, a 24-hour self-withdrawal window, and unknown-column warnings in the receipt. These are consequences an agent cannot infer from the annotation flags.

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 actions are front-loaded correctly, but the body is a single dense run-on paragraph stacking parentheticals, HTTP verbs, SDK calls and reader-view field names. Sizeable chunks describe downstream page-read behavior (_row_id, _at, _status, _mine) that belongs to list_data_rows or the page runtime rather than to this call, diluting the operative instructions.

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

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

For a 14-parameter, destructive, no-output-schema tool, the description covers the risky paths (revision conflict, delete, limits reported in the receipt) and explains the receipt since no output schema exists. It stops short of introducing five of the parameters that only appear in the schema, but with 93% schema coverage that gap is modest.

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 93%, so the schema already carries most parameter meaning; the description nonetheless adds real semantics for the highest-risk ones — revision 0-vs-current behavior, rows/csv exclusivity, columns-as-order, and default-off append_open. It says nothing about notify_emails, identity, per_reader, vote_key or identity_visibility, leaving those entirely to the schema.

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

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

The opening sentence gives a specific verb set and resource: "Attach a data table to a page, replace it entirely, delete it, or open/close reader write-back." It also implicitly separates this write tool from the read siblings by telling the agent to call get_data first and noting appended rows are "readable only through 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?

Explicit sequencing and conflict policy: "Call get_data first and pass the `revision` back unchanged: 0 creates, the current value updates; a mismatch is rejected (409) and requires re-reading, never blind overwrites." It also names the mutually exclusive input modes (rows vs csv) and states that a lone `append_open`/`members_only` only flips a switch rather than rewriting the table.

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.