inspect_exam_grading_html

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

With no annotations, the description does add meaningful behavioral guarantees: no submission occurs, preview or unsupported structures never establish 100%, and no cache entry is promoted based on model conclusions or partial credit. However, it does not disclose permissions, error/failure behavior, or what happens when the HTML is rejected as unsupported. The disclosed traits are relevant but incomplete for carrying the full behavioral burden.

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?

The purpose is front-loaded in the first sentence, and the later sentences carry behavioral constraints rather than filler. However, phrases like 'never establish 100%' and 'promote any cache entry' are jargon-heavy and lack enough context to be immediately actionable. The description is short but somewhat fragmented.

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?

The tool takes one required string and has an output schema, so the description does not need to explain return values. It provides key no-submission/no-cache-promotion guarantees but omits routing guidance against several closely related grading and exam inspection siblings. For an inspection tool in a dense sibling set, that leaves a meaningful gap.

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% for the single html_source parameter, so the description must compensate. It says the HTML is 'actual grading-page HTML supplied by the browser controller,' which clarifies origin and expected content, but gives no format requirements, size limits, or error behavior for the input. That is only marginal compensation for a completely undocumented parameter.

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 first sentence states a specific verb and resource: read actual grading-page HTML supplied by the browser controller. It explicitly notes 'with no submission,' which separates it from submission-oriented siblings. It does not name the closest read alternatives (e.g., read_owned_exam_grading, inspect_exam_page), so the sibling differentiation is only partial.

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 gives constraints ('preview pages or incomplete/unsupported grading structures never establish 100%') but never states when an agent should call this tool instead of read_owned_exam_grading, inspect_exam_page, or analyze_exam_html. There are no explicit when-to-use or when-not-to-use conditions, and no prerequisites beyond the implied browser-controller source.

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