canvas_browse_files

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds genuinely non-obvious behavior — that offset windows are fresh reads that can shift as files change, and that download_file only persists files locally in stdio — but says nothing about pagination limits or auth/scope requirements. It also references a parent_folder_id field that appears nowhere in the input schema, which risks confusing the agent about where that value comes from.

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-loaded with the core purpose, then the routing and caveats in short sentences with no filler. The parent_folder_id sentence is stranded, though, since it refers to something the input schema never defines.

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?

An output schema exists, so return values need not be described, and the read/download alternatives are covered. But for a five-parameter listing tool with zero schema descriptions, leaving kind and search_term undefined means an agent cannot confidently construct a filtered browse call from this definition alone.

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 0%, so the description must carry the semantics, and it only partly does: folder_id (omit vs provide) and offset (fresh, unstable windows) are explained well, but kind (files vs folders enum), limit, and search_term are never mentioned. Two of five parameters remain semantically opaque.

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?

"Browse personal Canvas files or folders, including submission folders" names a specific verb and resource with scope (personal, submission folders), and the closing sentences explicitly separate this listing tool from canvas_read_file and download_file, which share the same file domain.

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 gives concrete routing rules: omit folder_id to list personal files/all folders, supply it for immediate contents, use canvas_read_file to read, download_file to save an original. What's missing is guidance on the remaining modes (kind files vs folders, search_term) and any explicit 'don't use this for X' exclusion.

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