Create share link

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

Annotations cover the safety profile (write, non-destructive, non-idempotent, not open-world). The description adds genuinely useful context beyond that: the link grants anonymous read access, it can be made to expire or never expire, and revocation is only possible through the web UI. It stops short of describing the returned value or repeat-call behavior.

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 core action and its access implication. No filler, and the revocation caveat is placed where an agent will see it before calling.

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 annotated safety hints, the description covers access semantics, expiry, and the revocation path. The one omission is the return value (presumably the share URL) — with no output schema, that would have been worth stating explicitly.

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 in the schema. The description only restates the optional-expiry idea without adding format guidance 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 and resource ('Create a secret share link') and immediately qualifies the effect: anyone with the URL can read the memo without signing in. That distinguishes it cleanly from the read/write siblings like get_memo or update_memo.

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 clear operating context — optional expiry and the fact that revocation happens in the Memos web UI, not here. It does not explicitly say when to prefer this over another approach, but no sibling tool overlaps, so the routing risk is low.

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