get_public_share_by_slug

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

Annotations already declare the tool read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds only the HTTP method and path, which does not meaningfully disclose behavior beyond what is already inferable from the tool name and annotations; no auth, response-format, or rate-limit context is provided.

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 short and the endpoint is front-loaded, which is good. However, the 'Args' block merely repeats schema information and the main sentence is too thin to be genuinely helpful, so the brevity crosses into under-specification.

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 one-parameter public read endpoint with an output schema, the description is still incomplete: it leaves the slug semantics unexplained, gives no indication of what data the public share endpoint returns, and does not distinguish this from sibling subresource endpoints. The existing output schema and annotations cannot compensate for the lack of usage context.

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?

The schema has 0% description coverage and the single required parameter is documented only as 'slug: Path parameter.' This merely restates the schema's field name and type without explaining what a slug is, what format it expects, or how to obtain it, providing no additional semantic value.

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 states a clear verb and resource ('Get public share') and includes the endpoint, so the basic purpose is understandable. However, it does not say what the returned share object contains or how it differs from sibling tools like get_public_share_by_slug_cover, get_public_share_by_slug_download, or get_public_share_by_slug_track_by_index, leaving room for ambiguity.

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?

There is no guidance on when to use this tool versus any alternative. The description never mentions related share subresource tools or explains that this is the main metadata endpoint, so an agent has no contextual help for choosing it.

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