read_course_page

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

Annotations already carry readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral value not present in the annotations: the result is a 'partial browser snapshot' (acknowledges incompleteness), the page must be 'same-origin' (a real access constraint), and 'no form interaction' (a hard limitation). This is constructive behavioral context rather than a repeat of the annotations.

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?

A single 21-word sentence with no waste and no filler. Every clause earns its place: the verb and resources, the fallback condition ('when an API cannot expose it'), the outcome caveat ('partial browser snapshot'), and the exclusion ('no form interaction'). It front-loads the core action and each remaining fragment carries semantic weight.

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?

For a one-parameter, no-output-schema tool whose annotations already declare read-only, open-world, and idempotent behavior, the description covers what is read, the case that triggers it, the limitation of the result, and the constraint on the input. The description could explicitly state what the return payload contains, but since the outputs (visible text, links, embedded media) are already listed as the objects being read, nothing essential is missing.

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?

The schema offers only 'url: string, uri' with 0% description coverage, so the description must compensate. It does so by narrowing the valid value set to 'a same-origin Brightspace page (a Brightspace page)', which is materially more information than the raw URI type. It still leaves relative-vs-absolute formatting open and doesn't fully specify page eligibility, but for a single-string parameter the compensation is substantially adequate.

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 uses a specific verb ('read') with concrete resources ('visible text, links and embedded media') on a defined target ('a same-origin Brightspace page'), and the condition 'when an API cannot expose it' positions this as a browser-snapshot fallback. This clearly distinguishes it from API-backed siblings like get_course_content, read_course_service, and read_material. The 'partial browser snapshot' clause further cements the resource without ambiguity.

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?

The description explicitly states when to use this tool: 'when an API cannot expose it', giving a clear fallback context relative to API-backed siblings. It also gives a when-not condition via 'no form interaction', telling the agent not to expect form capabilities. It stops short of naming specific alternative tools, so the guidance is clear but not maximally explicit, which keeps it a 4 rather than a 5.

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