grade_with_rubric

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

No annotations are provided, so the description carries the full burden. It states the action 'Grade' (implying a write operation) and the prerequisite that a rubric must exist, but it does not disclose whether existing grades are overwritten, permissions required, error handling, or any side effects beyond grading. This is a significant gap for a mutation tool with zero annotation coverage.

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?

Two sentences with no filler. The purpose is stated first, followed by precise parameter formats in a compact style. Every sentence adds functional value, making it highly efficient.

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 description covers the core map parameters and a key prerequisite, but it omits the top-level 'comment' parameter and does not differentiate this tool from sibling graders like grade_submission or bulk_grade_submissions. It also lacks explicit behavior about overwriting or idempotency. Given the presence of an output schema (which it need not explain), the gaps are notable but not crippling.

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 description explicitly explains the format for criterion_scores and criterion_comments (keys as criterion IDs, values as points/comment text) and directs the agent to get_rubric for IDs, providing value beyond the schema's generic object types. However, it does not address the 'comment' parameter at all, and since schema description coverage is 0%, the compensation is incomplete.

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 states a specific action ('Grade a submission') and distinguishes it by the use of an existing rubric. It does not explicitly name alternative grading tools like grade_submission or bulk_grade_submissions, but the focus on 'rubric already associated' implies the differentiator.

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 provides a prerequisite instruction ('get criterion_ids from get_rubric') which guides the calling sequence, but it does not explicitly mention when to choose this tool over sibling grading tools (e.g., grade_submission vs this). The 'already associated' requirement hints at a condition, but it is not explicit about exclusions or alternatives.

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