Audifact

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, yet the description adds substantial context beyond them: X-API-Key requirement, org-scoped visibility, and the deliberate EVENT_NOT_FOUND behavior that masks unknown vs other-org hashes identically. That security/behavioral detail is exactly what structured fields cannot convey.

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?

Purpose is front-loaded in the opening sentence, followed by clearly labeled usage, auth, and return sections. Despite its length, every sentence supplies actionable information rather than 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?

With no output schema, the description compensates by enumerating the returned fields (event_hash, trust_level, trust_label, anchor status, chain metadata) and documents auth and error behavior. An agent has everything needed to call and interpret this tool.

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 coverage is 100%, so the single event_hash parameter is already documented, and the description largely restates the 64-char hex format. However it adds genuine semantic value by explaining the failure behavior for unknown or other-org hashes, which the schema does not state.

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 states a specific verb (fetch), resource (public proof payload), and selector (one ledger event by its 64-char hex event_hash). It clearly distinguishes itself from the sibling list_* and log_* tools that operate on the same ledger entities.

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?

Contains explicit 'When to use' and 'When NOT to use' sections. It names the alternatives (list_agent_decisions / list_agent_outcomes for browsing, log_decision / log_outcome for writes) and the exact condition selecting each, leaving nothing to inference.

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

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

Annotations already declare read-only/idempotent/non-destructive, and the description adds context beyond them: X-API-Key requirement, org-scoping (not a public explorer), and the important edge-case behavior that unknown public keys return an empty list with total 0 rather than an error. It also discloses the return shape and pagination contract.

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?

Front-loaded with the core purpose, then the when/when-not routing, then the return contract. It is dense and stacks many clauses into single sentences, but every sentence carries information an agent needs; nothing is 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 read-only, 3-param, org-scoped list tool with no output schema, the description supplies the auth requirement, scoping, empty-result semantics, return fields, and pagination procedure. An agent has everything needed to call it correctly and to chain pages.

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 coverage is 100%, so the baseline is 3; the description goes further by explaining where agent_public_key comes from (a prior log_decision response or register_agent) and how cursor/next_cursor chain across pages. It does not add format detail for limit beyond what the schema already states.

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?

States a specific verb+resource with scope: 'List decision events for one agent (by public key) in the API key's org, newest first by default.' It explicitly distinguishes itself from siblings list_agent_outcomes, get_proof, log_decision and log_outcome, so an agent can route without opening any schema.

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?

Provides explicit 'When to use' (review logged events, pick an event_hash for get_proof, page history before linking an outcome) and 'When NOT to use' with the correct alternative named for each excluded case. It also pre-empts a likely wrong invocation by noting it does not accept agent_name.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, but the description adds material behavior beyond them: X-API-Key auth requirement, org-scoped (not a public explorer), unknown public keys return an empty list with total 0 rather than an error, and the exact return shape including decision_event_hash linkage.

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?

Front-loaded with purpose, then clearly labeled use/avoid sections and return/output notes. Dense but structured; only slightly long, and each sentence carries actionable information.

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?

There is no output schema, so the description's explicit return contract ({outcomes, total, next_cursor, has_next}) and the empty-list-on-unknown-key behavior fill the critical gap. Auth, scoping, ordering, paging, and edge cases are all covered.

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 coverage is 100%, so the baseline is 3, but the description adds real meaning: it clarifies the tool does NOT accept agent_name and that public_key must come from a prior log_decision/log_outcome response or register_agent, and it explains that next_cursor should be echoed back as cursor for paging older.

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?

States a specific verb+resource (list outcome events for one agent by public key), plus scope (API key's org) and default ordering (newest first). It is clearly distinguishable from list_agent_decisions and get_proof without needing to open either schema.

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?

Explicit 'When to use' (audit recorded results, find an event_hash for get_proof, page without knowing hashes) and 'When NOT to use' with named sibling alternatives for each excluded case (list_agent_decisions, get_proof, log_decision/log_outcome). Routing is unambiguous.

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

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

With no annotations, the description carries the full burden and does substantial work: events are immutable once recorded, organization is derived from the API key, managed mode provides strong auditability, and the scenario hash is computed server-side. It omits failure modes, rate limits, and what a successful response returns.

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?

Front-loaded with the action, then dense but substantive sentences covering modes, immutability, org derivation, and hashing. Every clause carries information, though the run-on sentences would read better as bullets.

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 20-parameter, zero-required, nested-object tool with no output schema, the description covers the hard parts: signing modes, key management, org scoping, scenario resolution, immutability, and outcome linkage. It leaves the decision_type/label/value semantics and response shape to the schema and inference.

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 coverage is 75%, and the description resolves the genuinely ambiguous parameters: the managed-vs-client signing path (agent_name vs agent_private_key_b64/signature/public key), why scenario_hash is normally omitted, and the organization_id exclusion. It adds little for the many public_* mirror fields and decision_label/value, which rely on the schema alone.

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?

States a specific verb and resource: 'Log a signed decision event to the ledger.' It immediately distinguishes itself from the outcome-recording sibling by scoping to the decision event and noting that linked outcomes must match the decision's signing method.

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?

Gives clear operating guidance: managed mode is the default, omit signing fields and pass agent_name; client-side signing is for maximum provenance; don't send organization_id; usually omit scenario_hash. It stops short of explicitly routing the agent between log_decision and siblings like log_outcome or list_my_recent_decisions.

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

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

With no annotations, the description carries the full burden and largely succeeds: it discloses that the managed key is auto-resolved from the linked decision's agent, that signing method must match the source decision, that agent_name is ignored, and that scenario fields are rejected because context is inherited. It omits immutability/error behavior expected of a signed ledger event, so it isn't complete.

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?

Four tight sentences in a single paragraph, front-loaded with 'what it does' before the signing branch detail. Slightly dense with two clauses covering key/signature alternatives, but every sentence earns its place.

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 14-parameter, unannotated, no-output-schema tool, the description covers signing, linkage, and scenario inheritance but leaves the public_* mirroring fields, ts semantics, idempotency, and failure modes unaddressed. Adequate to call the tool, incomplete for the tool's 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?

Schema coverage is 71%, and the description meaningfully supplements it by explaining the signing parameters as two mutually exclusive modes, the decision_event_hash linkage, and why agent_name/scenario fields are non-operative here. It does add real meaning beyond the property-level descriptions, though ts, metadata_json, and the public_* mirroring rules are left to the schema.

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?

States a specific verb and resource ('Log a signed outcome event') and its linkage requirement ('linked to a prior decision via decision_event_hash'), which is enough to separate it from log_decision. It never names a sibling explicitly, so the differentiation is inferential rather than stated.

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?

Gives concrete operating guidance: omit signing fields in Managed Mode (default), pass agent_private_key_b64 or agent_public_key + signature for client-signed decisions, and the signing method must match the linked decision. It doesn't state when to prefer this tool over log_decision, but the signing-mode branches are genuinely actionable.

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

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

Annotations declare idempotentHint=true and destructiveHint=false, and the description reinforces idempotency with specificity ('same value always resolves to the same agent'), plus adds auth requirements (X-API-Key) and the return shape, which annotations do not cover.

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?

Front-loads the purpose, then structures when-to-use/when-not-to-use and behavioral notes compactly. Every sentence earns its place with zero redundancy.

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?

With no output schema, the description compensates by naming the returned fields (id, public_key, name), and it covers idempotency, auth, and routing. An agent has everything needed to invoke it correctly.

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 coverage is 100%, so both parameters are already documented in detail, including the name-update-on-lookup behavior and Base64 Ed25519 format. The description adds little parameter syntax beyond the schema, so the baseline 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?

States a specific verb (register/look up) plus resource (agent identity) and scope (under the API key's organization). It distinguishes itself from siblings like log_decision by explicitly telling the agent not to use it for logging decisions.

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?

Explicit 'When to use' and 'When NOT to use' sections name the alternative (Managed Mode log_decision with agent_name) and the condition that selects it. Nothing is left to inference.

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