555 Critique · Heart

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, which the description does not contradict. The description adds beyond annotations: requires non-empty target, lists return types (risk, floors, human impact), and describes modes. However, it does not detail behavioral variations across modes, keeping a score of 4.

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 a single dense paragraph that front-loads purpose and usage. It packs substantial information without excessive verbosity, though it could be better structured with separation of modes and return types.

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?

Given 7 parameters (all optional, mostly metadata), no required params, and existence of output schema, the description covers core aspects: purpose, selection criteria, modes, requirements, and return types. Minor inconsistencies (mode list) and missing details on non-core parameters prevent a 5.

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 provides partial meaning for 'mode' and 'target' but contains inaccuracies: lists modes like 'simulate' and 'instruction_scan' not in schema enum, and omits 'shadow' and 'empathy'. Also states target is required but schema allows null default. With 0% schema coverage, the description poorly compensates.

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 clearly states the tool performs ethical/dignity/risk stress testing before judgment, distinguishing it from SEAL. It specifies the conditions for selection (blast_radius MEDIUM+, human/dignity impact, irreversible risk) and names a sibling tool (arif_judge) for binding verdict.

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?

Explicitly states when to use (blast_radius MEDIUM+, human/dignity impact, irreversible risk) and when to skip (pure technical with zero human stake). Also mentions authority level L1 and available modes, providing clear context for agent decision.

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