Share File

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

Annotations cover the safety profile (not readOnly, not idempotent, not destructive, openWorld), so the bar is lower. The description adds genuinely useful behavior: that a view/edit link is usable by anyone who holds it, and that confirm=true is mandatory and must follow user approval — an approval-gate workflow the annotations do not convey.

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?

Three tight sentences with the core purpose and modes front-loaded, then the mandatory confirm gate, then the return shape. Nothing is padded and no sentence restates the title.

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?

With 12 parameters fully documented in the schema and an output schema present, the description need not explain return values, and it correctly avoids that. It covers purpose, mode choice, and the approval gate; the only minor gap is that it doesn't flag the OneDrive-root exclusion noted in the item_id schema or account scoping, though the schema handles those.

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 every one of the 12 parameters, including enums for mode, role, and link_type, is already documented in the schema. The description restates mode and confirm but adds no syntax or format detail beyond the structured fields, so the baseline 3 applies.

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 gives a specific verb (share) and resource (OneDrive file or folder) and distinguishes the two operating modes, link vs invite, telling the agent exactly what capability this tool exposes. It is clearly separable from siblings like drive_copy, drive_upload, and m365_update.

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?

It states the mode selection rule ('by link' vs 'by inviting named people') and the mandatory confirm=true step after user approval, which is real when-to-use guidance. It does not, however, say when to prefer this over sibling tools such as m365_update for permissions, nor any explicit negative conditions.

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