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

Goes well beyond the annotations by disclosing the authorization requirement, the viewer privilege cap, that repeat calls mutate rather than duplicate, that there is no cost, and that it authenticates via API key or connected account. The annotation set already flags destructiveHint=true, so the remaining gaps (exact shape of the returned shares list) are minor.

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?

Front-loads the action and target, then layers prerequisites and caveats in short clauses with no filler. Slightly dense and semicolon-heavy, and the one-word 'Free.' is terse, but nothing is wasted.

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?

Covers what an agent needs for a mutation tool: who can call it, what the access ceiling is, auth mode, and that shares are returned. With no output schema, the return value is only named rather than described, which is the one loose end in an otherwise complete definition.

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?

Adds meaning past the 75%-covered schema: it names both identifier forms for team (slug or id) and user (email or user id), and explains that the access value on a repeat call overwrites the prior grant. The access enum itself has no schema description, so the description's read/write/admin framing carries real weight.

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 (share a library file) plus the full target space (team by slug/id, person by email/user id) and access levels. The clause 'sharing again changes the access' also separates it from unshare_file and from creating a duplicate share, so an agent can route correctly without opening the 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?

Gives clear preconditions — you need admin access on the file as creator, org admin, or admin share — and the caveat that viewers are capped at read regardless of the requested level. It does not name unshare_file as the removal alternative, relying on 'sharing again changes the access' as an implicit hint.

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