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

With no annotations, the description carries the full burden. It discloses why the tool is free ('from the library (no LLM)'), the deterministic behavior ('instantly from the library'), and the auto-apply safety gate (confidence>=0.85, source=='library', auto_safe==true, and action_class restrictions). It does not mention error handling or timeouts, but the key safety behaviors are well covered, going beyond what annotations would have provided. It emphasizes that 'NEVER auto-apply a mutate or destructive fix', which is transparent about its own limits.

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 slightly long but dense with value. It front-loads the purpose, then provides detailed gate contract and usage triggers. The gate contract is wordy but necessary for safety. Every sentence adds either scope, safety, or usage nuance, so it earns its length, but could be trimmed. A 4 because it is well-structured and clear, with minor redundancy in the gate contract explanation.

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 is comprehensive: covers error types, return structure, free behavior, safety gate, and when to use. With 4 parameters (1 required) and no output schema, the description fully compensates by listing output fields and gate logic. The only gap is not specifying whether the tool handles unexpected error patterns gracefully or what happens if no match, but given the source is a library, that is implied. Extensive context for a diagnosing tool with high complexity.

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 input schema has 100% coverage, with each parameter self-describing (e.g., error as 'exact error text', action as 'tool/operation that failed', format with enum and explanation, context as 'what you were doing'). The description adds a bit by giving examples of errors and the return fields, but it does not introduce new parameter-specific details beyond the schema. Baseline 3 is appropriate because the schema is complete; description adds marginal value in examples but not critical.

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 diagnoses 'cribic AGENT-INFRASTRUCTURE errors' across specific categories (payments, Solana, MCP, RPC, wallets) and returns structured fields (matched, family, failure_class, root_cause, fix, etc.). It distinguishes itself from siblings by focusing on the 'cryptic' infra error pattern matching library, whereas siblings like diagnose_trace or diagnose_batch likely handle different scopes.

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 it: 'the moment you hit a transaction_simulation_failed, BlockhashNotFound, a -32xxx RPC code, a 4001/-32002 wallet error, an attestation failure, or any infra error you can't instantly resolve.' It also implies when not to use (for general trace/batch diagnosis via sibling names) and provides a clear gate contract for autonomous action, which is strong usage guidance beyond typical.

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