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

The description adds real behavioral context beyond the annotations — caller scope, the hard rejection of non-owner customer_ids across all plans, the summary + per-thesis return shape, and retry behavior. However, it explicitly claims 'Idempotent — a re-call only re-grades anything not already graded' while the annotations state idempotentHint: false, a direct conflict on a core behavioral trait. Per the contradiction rule, this dimension scores 1.

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?

Four front-loaded sentences, each with a distinct job: purpose, caller scope, permission exclusion, and return/retry behavior. Nothing is wasted, and the most decision-critical fact (caller's own theses, reject others) appears early.

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 moderately complex bulk-action tool, the description covers what an agent needs: target population, the permission restriction that could otherwise cause rejected calls, and the return shape. A full output schema exists so return details need no elaboration. It is docked a point because the idempotency contradiction leaves genuine ambiguity about retry semantics — the one place an agent needs certainty.

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 100%, with all three parameters already documented including defaults and the customer_id restriction, so the baseline is 3. The description reinforces 'omit customer_id' and adds the frontend-cron rationale for the max cap, but these are marginal additions over what the schema already states.

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 and resource: 'Find every thesis past its horizon with no outcome yet, and grade each via score_thesis_outcome.' It distinguishes itself from the closest siblings by naming score_thesis_outcome as the per-thesis grader it wraps (bulk vs. single), and the title 'bulk auto-grader' separates it from score_due_claims by resource type. An agent can tell exactly what this tool does without opening the 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?

The description gives explicit when/when-not guidance: 'Operates on the caller's OWN theses — omit customer_id' states when to use it, and 'Targeting another user's customer_id is reserved for Valuein's internal scoring service and is rejected for every plan' is a hard exclusion. It names the underlying singular tool (score_thesis_outcome), which implies the alternative for single-thesis grading, though it never explicitly says 'use score_thesis_outcome for one thesis' or contrasts with score_due_claims, so it stops just short of a 5.

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