MUJ428 Trust Layer

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, fully covering the safety profile. The description adds the contextual cue 'before an autonomous payment' but does not disclose any additional behavioral traits such as external dependencies, data sources, or return format nuances.

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 a single sentence, immediately front-loaded with the action verb 'Returns', and contains no filler or repetition. Every phrase adds meaningful information about the resource and context.

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?

Given the tool's simplicity (no parameters, clear read-only intent, no output schema), the description is largely complete: it names the specific resource, the categories of requirements, and the payment context. However, it lacks a description of the return structure or format, which could be useful since 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?

The tool has zero parameters and the schema coverage is 100%, so there is no parameter ambiguity to resolve. The baseline for 0-parameter tools is 4, and the description does not need to add parameter-level detail; it instead clarifies the output categories (payment, network, endpoint, assurance-pricing), which is acceptable.

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 uses a specific verb 'Returns' and names a concrete resource: 'MUJ428 evidence-check payment, network, endpoint, and assurance-pricing requirements'. It clearly differentiates the tool's purpose as a read-only retrieval of pre-payment requirements, distinct in scope from the sibling 'trust_action'.

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 'before an autonomous payment' clearly indicates the temporal context for using this tool. However, it does not explicitly mention when not to use it or discuss alternative tools like 'trust_action', so it stops short of full exclusion guidance.

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?

The description explicitly discloses that this is a verification only: 'FREE_PREFLIGHT execution_authority=false and no funds are moved.' It also gives what the call produces (verdict plus Trust Receipt v1.3). This matches the readOnlyHint and idempotentHint annotations, no contradiction. The description adds significant non-obvious behavior - it cannot execute or move funds - that the annotations alone do not say.

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 only two sentences and the core purpose is front-loaded in the first phrase. It wastes nearly nothing. The phrase 'FREE_PREFLIGHT execution_authority=false' is somewhat jargony but adds precise, high-value safety context in a compact way.

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 16-parameter tool with almost no schema-level descriptions and no output schema, the description is too sparse. It tells the agent why and when to invoke the tool, but not how to properly construct a request against the richer optional context (e.g., trajectory, action_history, previous_trust_receipts). It is not complete enough for an agent to know what inputs matter for a high-quality trust verdict.

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?

The schema has 16 parameters, yet only the 'action' parameter has a description, and that just says 'AI-native action vocabulary.' The tool description does not try to compensate: it never explains evidence, the trajectory, action_history, amount_usd, counterparty, risk_threshold, sensitive_data, or how these combine into a verification request. For a 6% schema coverage, the description leaves essential parameter meaning to the agent's inference.

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 opens with 'VERIFY BEFORE ACT' and immediately scopes the tool to payments, purchases, delegation, approvals, writes, releases, commits, and other consequential actions. It also states the exact return vocabulary (ALLOW, VERIFY, REQUIRE_VERIFICATION, DENY) and that it returns a Trust Receipt, so an agent knows what this tool produces. It does not explicitly distinguish it from the sibling tool, but the main resource and mode are clear.

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 gives a clear use case: run this before consequential actions, and it emphasizes 'VERIFY BEFORE ACT'. This is close to an explicit usage rule. However, it never says when NOT to use it or points to an alternative like the sibling tool, leaving the agent without a concrete exclusion or routing decision.

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