cloud_links

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

With no annotations, the description carries the full burden, and it does disclose a genuinely useful trait: links are resolved live, so results reflect current cloud node content rather than link-creation-time snapshots. It also notes per-link routing to the originating cloud. However, it says nothing about permissions, dangling/missing links, or failure behavior for what is otherwise a read operation.

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 the action and scope, then the freshness behavior, then the sibling relationship. No filler or redundancy.

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-param read tool with no output schema and no annotations, the description covers the core behavior (live resolution, per-cloud routing) but leaves the `initiative` parameter unexplained and omits error/edge behavior for dangling links. Adequate but 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?

Schema coverage is only 50%: `name` is documented in the schema, but `initiative` has no description anywhere. The tool description talks about 'a node's cloud soft links' but never clarifies what `initiative` scopes or requires, so it fails to 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?

Specific verb+resource: 'Resolve a node's cloud soft links' with the scope clarified as fetching the cloud nodes they point at. It explicitly positions itself as 'The read half of `link_cloud`', which lets an agent distinguish it from the write-side sibling 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?

The 'read half of `link_cloud`' framing tells the agent when to pick this over the write tool, and the live-fetch emphasis implies use when current cloud state matters. No explicit when-not or mention of other read alternatives like `cloud_recall`/`clouds`, so it stops short of a 5.

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