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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals idempotency, eager pushing of rendered HTML to the Railway bucket, URL structure with a fallback, and access restrictions—all beyond what a schema would convey. It does not cover error handling (e.g., what happens if the file does not exist) or rate limits, but the core behaviors are transparent and align with the operation's nature.

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 description is longer than a single sentence but well-structured: the first line states the core purpose, the second details idempotency and output mechanics, and the third addresses access control. Every sentence adds substantive value; there is no fluff. The pacing is efficient, though it could be tightened by moving the Railway bucket detail to the output schema or a separate note.

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?

Given the tool's complexity (multiple output URLs, gating, idempotency) and that an output schema exists, the description covers the most critical runtime context: what the agent will receive (both URLs), that it is safe to call repeatedly, and the exact gate alternative. It does not describe preconditions (e.g., file must exist and be in a publishable state) or error scenarios, but the provided information is sufficient for correct invocation in the common case.

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 the file_id parameter is already fully documented in the schema ('File UUID to publish'). The tool description adds no additional semantic detail about the parameter (e.g., format, validation, or edge cases). Since the schema fully covers the parameter, the baseline score of 3 is appropriate—the description does not need to repeat schema information.

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 opens with a precise action: 'Publish a shared file: generate the public share token + slug and URL.' It clearly identifies the resource (shared file) and the output (token, slug, URL). It also distinguishes itself from other publishing tools (e.g., storage_publish) by detailing the specific token/slug mechanism and the /s/ URL format. This leaves no ambiguity about what the tool accomplishes.

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 description explicitly states when to use this tool and when not to, naming the alternative: 'Agent seats (org tsk_ / agent_run) are refused — call request_gated_approval(gate="publish") instead. Console humans (ts_session) still publish.' It also implies usage context through idempotency, informing agents that repeated calls are safe and return existing tokens. This is explicit, actionable guidance that completely removes guesswork.

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