get-download-url

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

Annotations only declare readOnlyHint and openWorldHint; the description goes well beyond by disclosing that the URL is short-lived and pre-authenticated, that it streams bytes with NO Authorization header, that it avoids base64 round-tripping through the agent context, and that failure on unsupported endpoints returns the reason and points at download-bytes. These are exactly the behavioral traits an agent needs and can't infer from structured fields.

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 core action and its safety property, then the alternative, then the return shape, then the edge case. Dense and purposeful, though the $value/--enable-attachment-urls case is stated twice (once in the guidance and again in the parameter note), adding minor length.

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?

No output schema exists, and the description compensates by naming the return fields ({ downloadUrl, name?, size?, contentType? }). Combined with the usage rule, the no-auth streaming detail, and the unsupported-endpoint fallback, an agent has everything needed to call or avoid this tool correctly.

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% and the single 'target' param is already documented in full, including trailing-/content stripping and the --enable-attachment-urls caveat. The description mentions the same accepted path families, so it is largely redundant with the schema; baseline 3 is appropriate.

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+resource ('Resolve a short-lived, pre-authenticated download URL for Microsoft Graph binary content') and immediately scopes it to drive/SharePoint file content. It explicitly names the sibling download-bytes as the thing it supersedes, so an agent can route correctly without opening either 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 an explicit selection rule ('Prefer this over download-bytes for any file above a few KB or any bulk download') and additionally rules in a case the agent would otherwise get wrong: mail attachment $value paths and meeting recordings, with an explanation of what happens on a server with vs. without --enable-attachment-urls. Both when-to-use and when-the-other-tool-answers-instead are covered.

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