canvas_find_files

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond that: the exact set of surfaces searched (front page, syllabus, modules, assignments, announcements, page list, linked pages, Files list) and the fact that external links like Dropbox are reported separately. It stops short of noting cost/latency of crawling many pages or result limits, which would matter for a broad crawl.

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 purpose and the 403/404 trigger, then the search surface, then the read handoff. It is dense but every clause carries information; the enumeration of searched surfaces is long but justifies itself for a crawling tool. Minor length cost only.

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 explaining exactly what is returned: each Canvas file_id with its name and where it is linked, plus separate listing of off-site links. Combined with the two follow-up read tools being named, an agent has everything needed to call it and act on results.

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 100%, so the baseline is 3, and the description earns an extra point by documenting the omission semantics of query ("omit query to list every linked file") and noting that all words must match implicitly via the topic framing. It adds real meaning beyond the schema text rather than restating it.

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?

Opens with a specific verb+resource ("Find files in a course by name or topic") and immediately scopes it to courses that hide Files/Pages from students, which cleanly separates it from siblings canvas_files and canvas_pages. An agent can pick this tool without inspecting 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 trigger (canvas_files / canvas_pages return 403 or 404), names the fallback behavior, and routes onward to canvas_file_content or canvas_file_original for reading. It also states the degenerate case: omit query to list every linked file.

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