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

Given only generic boolean annotations, the description carries the behavioral burden and does so thoroughly: it reveals clamping and non-coercion of values, per-key ceilings and weighted bands, replacement on re-score, MEAN-based rankings, the advisory nature of the result, and the attribution model for on_behalf_of. This goes far beyond the annotations and leaves no major hidden side effects.

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 description is long but every clause earns its place: it is front-loaded with the core action, then covers criteria semantics, replacement behavior, ranking context, and the specialized organizer path in a logical sequence. There is no filler and no unnecessary repetition of schema fields.

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 complex scoring tool with no output schema, the description is complete: it explains scoring bands, the actual denominator via max_total, replacement semantics, the MEAN-ranking implication, the advisory role, the organizer path, and the required scope. An agent has everything needed to invoke it safely and correctly.

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 only describes criteria, notes, and on_behalf_of; the description adds critical semantics for the criteria map—allowed values, clamping, per-key ceilings (track/runs/surface/product/demo), and unknown keys being capped at 10. It also clarifies the exact role of on_behalf_of and who may set it. This meaningfully exceeds the schema's own parameter documentation.

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 opening line uses a specific verb and object—'Record your scores for one team'—and immediately establishes that this is a scoring/write action, not a read or list tool. It matches the title and no sibling tool overlaps with it (ic_hack_judge_list is the lookup counterpart). The judge-specific scope is clear even without 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 explicitly scopes usage to judges/organizers with 'Required scope: hack:judge + judge or organizer role.' It gives a conditional specialized path for organizers via on_behalf_of and explains the safety rejection: it 'refuses a caller who does not run this event and a target who is not a judge here.' It also tells agents that re-scoring replaces the prior score and that scores are advisory, which directly informs when and how the tool should be called.

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