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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the return behavior (an immutable SHA-256 content hash) and the audit-trail purpose — important since no output schema exists. It still omits storage/retention semantics, duplicate handling, and any auth requirements.

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 front-loaded sentence covering purpose, output, and use case, followed by a short example — no filler. The example largely duplicates the `examples` block already present in the input schema, which is mild redundancy, but overall it is tight and readable.

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 write tool with no output schema, the description competently fills the return-value gap by stating that a SHA-256 content hash comes back, and the four parameters are fully documented by the schema. The remaining gaps are secondary: permanence/retention of the record and the relationship to settlement.ledger are not explained.

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 all four parameters (actor, action, detail, target) are already documented in the schema, including the nested detail object. The description's inline example illustrates realistic values but adds no format, constraint, or sizing rules beyond what the schema already states, so the baseline of 3 applies.

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 states a specific verb and resource — recording cross-agent call attestations (记录跨 Agent 协作的调用存证) — and adds the outcome (a tamper-evident SHA-256 content hash) and the purpose (pre-settlement audit). It is clearly distinguishable from generic siblings like metering.record, but it never explicitly names or contrasts with metering.record or settlement.ledger, which sit closest to it.

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 phrase 用于任务结算前的存证审计 implies the usage window (before task settlement), which is real contextual guidance. However, there is no explicit when-not guidance and no named alternative for the near-identical metering.record or settlement.ledger siblings, leaving the agent to infer which recorder to call.

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