create-drive-item-share-link

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

Description adds context like no email sent and inheritance, but annotations have destructiveHint=true while the operation is not destructive (it creates or returns existing link). This contradiction reduces transparency. No explanation of destructive consequences.

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?

Description is efficient, with a tip and clear structure. It includes key information without unnecessary words, but could be slightly more concise in the tip section.

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 no output schema, description informs about return (permission with link.webUrl) and mentions inheritance. Covers main use case, but lacks details on error conditions and full response structure.

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 coverage is 83%, and description adds value by providing enums for type and scope, and clarifying the effect of body fields (e.g., no email). However, it omits some schema fields like message and recipients, so not fully complete.

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?

Description explicitly states the tool creates a sharing link for a driveItem, distinguishes between creating a new link and returning an existing one, and differentiates from the sibling tool 'share-drive-item' by noting it does not send invitations.

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?

Provides clear guidance: 'Pair with share-drive-item when you want to grant explicit access; use this when you only need a URL to paste into a doc/email/chat without triggering OneDrive notifications.' Also explains behavior when link already exists.

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