infer_outcome

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

Richly goes beyond the annotations: discloses that a no-op returns status 'skipped' rather than an error (clean session, below friction threshold, no evidence), that repeat calls for the same session/evidence are deduped, that agent auth is required when a key is registered, and that the classification is rule-floor plus optional LLM judge with recording identical to record_outcome. The only mild tension is 'deduped' versus idempotentHint=false, but that is a storage-level dedup of the record rather than a claim the call is a pure read-replay, so it does not rise to contradiction.

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?

One dense but well-ordered paragraph: purpose, then the evidence-passing contract, then the skipped/dedup/auth caveats. Every clause carries a distinct fact, though the run-on middle sentence about the rule-floor-plus-LLM-judge pipeline could be broken out for faster scanning.

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 an 8-parameter, non-read-only, auth-bearing tool with no output schema, the description covers the essentials: what gets recorded, the skipped-not-error return, dedup, and auth. Only the successful return payload (beyond the 'skipped' case) is left implicit, which is a small gap given no output schema exists.

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%, so every parameter is already documented, including the per-field evidence semantics and judge_context's "data not instructions" note. The description reinforces that `evidence` must be caller-precomputed and that the judge is optional, but adds no format or constraint detail beyond the schema. Baseline 3 applies when the schema carries this much weight.

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?

Specific verb+resource ("Classify and record a task outcome") plus an explicit scope constraint ("from host-provided evidence rather than raw transcript text"). It names the sibling it mirrors (record_outcome) and the pipeline it reuses (the Claude Code Stop hook's `outcome --infer`), so an agent can place it precisely among 19 siblings.

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 the selecting condition: use this for hosts whose event model doesn't emit a Claude-Code-shaped JSONL transcript (e.g. dsh/Cordis). It also tells the caller what to supply (pre-computed friction counts, terminal state). It stops short of a clean routing sentence such as "if you already have a classified outcome, call record_outcome instead," leaving that inference to the reader.

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