prove_my_conduct

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

With no annotations provided, the description carries the full disclosure burden and largely meets it: it explains the three-valued chain_verified verdict (true only if EVERY row verified, null for bounded scans, false if altered) and the property that earlier head_hash holders can re-verify the history. It does not cover failure modes, irreversibility of writes, or authentication requirements, which keeps it just short of a 5.

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 purpose is front-loaded in one efficient sentence, and the dense middle content justifies itself by explaining a genuinely subtle three-valued return contract in the absence of an output schema. The only slight redundancy is stating the head is handed to the principal and later that earlier holders can check it — a minor overlap, not filler.

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 with no output schema and no annotations, the description fully specifies the return contract — the meaning of rows, head_hash, and each branch of the three-valued chain_verified — while the schema fully covers both parameters. The remaining gaps are the lack of explicit sibling-tool routing and unstated failure/authorization behavior, but the core calling contract is complete enough for correct invocation.

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% and the schema already documents both parameters thoroughly: events gets ordering plus empty-list read-back semantics, and namespace gets character/path-safety constraints. The description adds no parameter-level meaning beyond the schema, so the baseline of 3 applies because the schema carries that burden.

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 first sentence names a specific action ('Log a batch of things you just did') and a specific resource ('your own tamper-evident ledger'), plus the concrete deliverable ('one chain head you can hand your principal as proof'). This distinguishes it from siblings like verify_peer_ledger (which concerns peers) and declare_break (which marks broken rows). The verb, resource, and output are all explicit.

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 implicitly scopes the tool to 'your own' ledger, suggesting verify_peer_ledger for external ledgers, but it never names the alternative or states the selection condition. There is also no explicit guidance on when to reach for prove_my_conduct versus ledger_append for record-writing needs. The agent must infer the routing rather than being told.

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