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

Goes well beyond the annotations (which only say readOnly=false, destructive=false, idempotent=false): it discloses that changes take effect immediately, that omitting a passcode generates or retains one, that private shows a blocked page to non-members, that a shared folder propagates access to included live pages while excluded items and legacy link permissions stay separate, and that read records identify devices not people. That is exactly the kind of consequence-of-invocation detail annotations cannot carry.

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

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

The core rule is front-loaded, but the latter two-thirds sprawl across folder inheritance, excluded items, device-level read records, allow_copy, and a long home-page digression. Sentences like 'Reading records identify devices, not named people' and the home-page paragraph are relevant but dilute the operational core and could be tightened substantially.

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, and the description compensates by describing return-adjacent behavior — the folder result names pages that are private on their own but visible through the folder, and the agent is told to relay that to the user. It also covers the home page's members-only-by-default, owner-only rules. Only the unaddressed set_home overlap keeps this from full marks.

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 83%, so the structured baseline is already strong, but the description still adds meaning: it defines what private/passcode/public actually do for viewers, clarifies that the passcode is generated or retained when omitted, and explains allow_copy's coupling to copy_proposal. Minor gap: it does not tie the enum values to any restriction, and it says nothing extra about passcode length/format beyond the schema's 4–16 constraint.

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

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

Opens with a precise verb + resource + arity constraint: 'Set visibility for exactly one proposal_id or folder_id', and extends it to the workspace home page mode. An agent immediately knows this is a sharing/permission mutation scoped to one page, one folder, or the workspace home — distinguishable from siblings like set_indexable, set_internal, or set_home without opening any schema.

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

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

Gives real operational conditions: pass home:true with no proposal_id/folder_id for the home page, confirm external sharing with the user first, and note that reset_default_link replaces the URL. However, it never states when to use this tool's home:true path versus the sibling set_home tool, leaving a genuine routing ambiguity among 70+ siblings.

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