decision_explanation

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

With no annotations provided, the description carries the full burden of disclosing behavior. It does mention that passing `actor` causes a rights:explanation entry to be logged with the document's hash, which is a meaningful side effect. However, it does not disclose whether the tool performs a write/read-only operation beyond that conditional log, how the document is returned, whether it can fail, or how it handles missing data.

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 one long, dense sentence that front-loads the purpose and lists the included content. It is not excessively long, but the lack of punctuation and overloaded structure make it harder to parse than necessary. The side-effect behavior of `actor` is tucked into the middle rather than being clearly separated.

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 tool that produces a legal/regulatory explanation document with multiple optional parameters and a conditional logging side effect, the description leaves out important operational context: how the document is delivered, what happens with missing `seq` data, how `subject` and `request_id` affect the output, and whether this tool should be used only in certain regulatory workflows. The absence of an output schema and annotations raises the burden on the description.

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 0%, so the description must compensate for documenting the parameters. It only explains `seq` (the action sequence) and `actor` (triggers a logged rights:explanation entry). It does not explain `subject` or `request_id`, their optional roles, or how they influence the explanation. With 4 parameters and no schema descriptions, this is a significant gap.

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 identifies the tool as producing an Art. 86 explanation document tied to an action `seq`, enumerating the content that goes into it (action metadata, memory state, recall results, oversight events, disclosures, incidents, risks, corrective actions). It is fairly specific about the resource, though it could more directly distinguish it from sibling tools like oversight_report or governance_report.

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 conveys that this is for generating an explanation-of-decision document at a given action sequence, but it does not explicitly state when to choose this over sibling tools such as oversight_report, compliance_report, or governance_report. There is no guidance on prerequisites, intended requester context, or exclusion criteria.

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