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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), it discloses the critical non-obvious behavior: the capability URL is returned only once and only its secret hash is stored, and the URL is a bearer credential that should be revealed only on explicit request. This is exactly the kind of irreversibility and credential-handling context 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?

Roughly 70 words with little waste, and the one-time-URL warning and usage gating are both important. Structure is slightly awkward—it opens with a dependent reference to 'The capability URL' before stating the action, and the raw POST path is implementation detail rather than agent-facing 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?

For a 5-parameter mutation tool with no output schema and low schema coverage, it covers the return-value caveat (URL shown once) and the space-selection workflow, but omits required permissions on the target node and the semantics of type, framePolicy, and expiry. Adequate for the basic call path, with clear gaps.

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

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

With only 20% schema description coverage, the description must compensate but mostly doesn't: targetSpaceId is mentioned, yet the required type enum (node/change-request/record-detail), typeId, the complex framePolicy anyOf, and expiresInMinutes are left unexplained in both schema and description. The agent cannot infer how the polymorphic link type affects typeId or what the frame policy does.

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 title and description make it clear this creates a polymorphic, read-only embed link for a node (or change-request/record-detail via the type enum), with a specific verb+resource. It does not explain how it differs from nearby siblings like change_requests_create_preview_link or node_share, so it stops short of a 5.

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

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

It gives an explicit when-to-use rule ('only when the user explicitly asks to share or preview that node') and a concrete multi-space prerequisite (call auth_verify, ask the user which space, then pass targetSpaceId). No explicit when-not or named alternative is given, which keeps it from 5.

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