Grade an answer

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

Well beyond the annotations, it discloses exactly what is persisted ('Leanfare keeps only the grade, with the model that answered and the kind of part, never the words'), where 'why' goes ('only to the model asked again'), and a real system side effect ('A model graded below good too often for a kind is moved down, so plans and delegate stop picking it for that kind'). It also warns that fix leanfare spawns another round producing 'a new hand off to review and grade too', which is essential for an agent to avoid a loop. The annotations only mark it as a non-idempotent write, so this text carries the substantive 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 core instruction is front-loaded, which is good, but the body is a single dense run-on chain of sentences with ambiguous referents ('a new hand off to review and grade too') and repetitive restatement of the fix loop. Every clause carries information, yet the compressed grammar forces re-reading, so it is information-dense rather than concise.

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 10-parameter, nested-object tool with no output schema, the description covers the workflow, persistence, consequence and the whole-result case — far more than most. It is still silent on what a plain grade (without fix) returns and on error behaviour, which an agent would need to confirm success, so it falls short of fully complete.

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 schema already documents every parameter, including enums and the nested checks object — that sets the baseline at 3. The description does add one genuinely useful routing rule beyond the schema ('grade a delegate answer with handoff; a plan's part with id and part'), which is a slight lift, but it never clarifies the model/kind pairing or when checks must be supplied, so it does not fully transcend the schema.

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+resource ('Review every answer... then say how good it was: good, partly or wrong') and identifies exactly which artifacts it grades: 'delegate, or a plan's part from plan_status'. That implicitly separates it from siblings like delegate, plan_status and report. It loses a point because the jargon-heavy, clipped phrasing ('a hand off', 'one tier up') makes the core purpose take a couple of passes to parse.

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?

It gives a clear use rule ('Review every answer Leanfare brings back before you use it') and a separate trigger for the whole-result case ('At the end of a prompt that handed work off, grade its whole result too'). It also routes the agent on each verdict (if partly/wrong, fix myself or use fix leanfare with why). No alternatives are named, but for a terminal grading step there are no comparable siblings, so the absence is minor.

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