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

Annotations already declare readOnlyHint and destructiveHint, so the safety profile is covered. The description adds valuable behavior beyond that: rows the caller cannot see are omitted, the stored share password is never returned, and only a hasPassword flag is included. The generic ChangeRequests sentence is unrelated to this read-only tool but does not contradict the annotations.

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

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

The main behavior is front-loaded and well organized into a clear paragraph, endpoint, and usage note. However, the final two sentences about ChangeRequests and treating stored content as data are generic platform boilerplate that do not help an agent call this specific read-only tool, making the description longer than 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 simple read-only list with no output schema, the description explains the row semantics, included node fields, ACL filtering, password handling, exclusions, endpoint, and the one relevant auth edge case. Pagination and ordering are not mentioned, but nothing essential to invoking the tool 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?

With 100% schema description coverage, the input schema already fully documents targetSpaceId, including the auth_verify and space-selection flow. The description repeats that guidance without adding new parameter-level semantics, 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 names a precise operation and resource: list every node in the space carrying its own live public share, with concrete row semantics (scope: public, unexpired, joined with name/slug/type/icon). It also explicitly distinguishes this from ancestor-derived shares and from the general nodes.list ACL, so an agent can tell it apart 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 clearly states the intended context: this is the list of grants a person made, each revocable via nodes.share.disable, and it matches the workbench globe set. It gives the multi-space auth flow (auth_verify, ask which space, pass targetSpaceId) and explicitly excludes nodes merely reachable through a shared ancestor. It does not name a direct sibling alternative to use instead, but the boundary is mostly clear.

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