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

Annotations declare readOnlyHint=false and destructiveHint=false, so the agent knows this is a non-destructive write. The description adds only one behavioral fragment, the 'People only' restriction on grantees; it says nothing about required permissions, whether an existing grant is replaced or duplicated, how expiry interacts with the grant, or what happens on cross-tree attempts. The idempotency behavior is covered in the schema, not here.

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?

It is short and the verb is front-loaded, but the second sentence 'People only' is telegraphic to the point of ambiguity rather than being efficiently informative. Length is fine; the compression costs clarity instead of saving it.

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 6-parameter mutation with 17% schema coverage and no parameter explanations, the description leaves too much undefined: grantee identifier form, which principals count as 'people', same-tree scoping rules, and how to undo the grant. An output schema exists, so return values need not be explained, but the input-side gaps are substantial.

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 17% — only idempotency_key is documented in the schema, so the description carries the burden for the other five parameters. It adds no meaning for access levels (read vs write), expires_at semantics, the resource_kind enum, or the expected identifier format for grantee and resource_ref, leaving callers to guess from bare titles.

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 verb 'Share' plus 'a resource' gives a recognizable action, but 'with a node or principal of the same tree' is unexplained jargon and 'People only' is a cryptic fragment whose meaning (human grantees only, not agents?) must be guessed. It never names sibling operations such as revoke_share or list_shares, so an agent cannot fully place it in the sharing lifecycle.

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 explicit when-to-use guidance, no prerequisites, and no alternatives named. The only guidance-like content is the implicit constraint 'of the same tree' and 'People only', which a caller must infer rather than being told when this is preferred over other grant mechanisms.

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