Agent Trust Firewall

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

Annotations already cover readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: no action execution, wallet access, policy storage or decision history; stateless per-call rules; unauthenticated source labels; a limited phrase heuristic with false positives/negatives; and that usage metadata but not request bodies is recorded. These are exactly the caveats an agent needs before relying on an ALLOW result.

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 behavior and return values, then routing, then limits — a sensible order. It is a dense single paragraph, though, and a couple of points (contract scope, payment activation) could be split for scanability rather than compressed into the same block.

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 an 11-parameter, nested-object tool with an output schema, the definition covers activation conditions, precedence, failure mode, trust boundaries and statelessness. Nothing an agent needs in order to call it correctly or interpret the verdict is missing.

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?

With 100% schema coverage the baseline is 3, but the description adds cross-parameter semantics the schema states only locally: action.type=payment activates spending checks and requires amount with remaining_budget, and contract governs data rather than action. It doesn't restate the merchant/allowlist coupling, which is already in the schema, so this sits just above baseline.

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: evaluate a proposed action against evidence, source allowlists, data constraints and payment limits, returning ALLOW/BLOCK with reason codes. The enumerated inputs and the return contract make it unmistakable against the sibling validation/spend tools without opening the 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?

Gives an explicit routing rule set: 'Use this gate before execution, trust_check_spend for budget alone, or trust_validate_data for structure alone', plus the operational directive to enforce BLOCK and fail closed. It also states a precedence constraint (evidence cannot override an over-budget payment), so the agent knows how the checks combine rather than just which tool to pick.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description adds substantial context beyond them: no wallet access, no payment execution, no cumulative tracking, no currency conversion, free/unauthenticated/stateless with per-call-only rules, and a data-handling note (usage metadata recorded, bodies not stored). This is exactly the kind of disclosure annotations cannot carry.

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?

Dense but front-loaded: the ALLOW/BLOCK contract and the budget/ceiling independence rule come first, with operational caveats after. Nearly every clause carries information, though the passage is long enough that a few points (currency-unit advice) are stated twice across description and schema.

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?

Output schema exists, so return values need not be spelled out, yet the description still names the ALLOW/BLOCK verdict and reasons. Combined with the statelessness warning, the caller-must-update-budget note, and the sibling pointer, an agent has everything needed to call this 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 the baseline is 3, but the description adds cross-parameter semantics the schema cannot express: budget and ceiling are independent checks with a worked example (amount=4, budget=10, limit=3 → BLOCK), and equality passes. It also clarifies single-currency/unit usage and the omit-versus-empty distinction for allowed_merchants. Slight overlap with schema text on the empty-list case keeps it from a 5.

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?

Opens with a specific verb+resource ('Compare a proposed spend with a remaining budget, transaction ceiling and merchant allowlist') and states the outcome shape (ALLOW/BLOCK with reasons). It also distinguishes itself from the sibling trust_check_action, so an agent can route without opening 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 routing is given: 'Use trust_check_action to include evidence or data checks,' plus an enforcement instruction ('Enforce BLOCK before paying'). It also states when merchant checks apply versus when they are skipped, and warns that the caller must decrement remaining_budget itself.

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?

Goes well beyond the readOnly/destructive/idempotent annotations: defines the deterministic processing order (trim → PK dedup → required/range checks), states dedup keeps the first row and skips later-row field checks, that missing keys are retained and flagged, that numeric strings are neither converted nor range-checked, that only top-level strings are trimmed, and that inputs are not mutated. It also discloses the operating model (free, unauthenticated, stateless, per-call rules) and the privacy posture (usage metadata recorded, bodies not stored).

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: purpose and return values land in the first clause, with behavioral caveats after. It is dense and semicolon-heavy – some sentences pack two distinct facts (e.g. the collision note) – but nearly every sentence carries decision-relevant 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?

For a six-parameter, stateful-behaving audit tool with an output schema already covering return structure, the description covers the remaining risk surface: ordering effects, what dedup drops, what gets flagged but retained, and the REVIEW-does-not-clear warning. Nothing an agent needs to call it correctly is missing.

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 schema already carries the per-parameter burden and baseline is 3. The description still adds semantics the schema does not spell out as clearly: the 500-row ceiling, the trim-collision example ('a ' and 'a' collide), and the fact that duplicate removal short-circuits later required/range checks on skipped rows.

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?

First sentence gives a specific verb pair ('audit and optionally clean'), the resource ('JSON rows'), the hard scope (up to 500), and the return shape (cleaned_rows, zero-based issues, counts). It also names the sibling it is not (trust_validate_data) for type enforcement, so the agent can tell the two apart without opening 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?

Explicitly routes type-enforcement work to trust_validate_data and warns to inspect issues before use because REVIEW persists after repair, plus notes that an empty array returns ALLOW. Clear usage context, but it does not say when to prefer this over the other audit-related siblings (trust_check_action, trust_check_spend).

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 closed-world behavior, but the description adds substantive context: free/unauthenticated access, operational metadata recording without request-body storage, response scope excluding stored policy/history, and the requirement that rules accompany each check.

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 front-loaded with the core purpose, then covers invocation, sibling alternatives, response scope, auth/metadata behavior, and re-read guidance. Every sentence carries useful information without redundant padding.

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 no-parameter, read-only inventory tool with an output schema, the description supplies the key context an agent needs: what it returns at a high level, what it does not return, authentication status, metadata behavior, and when to re-invoke it.

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?

With zero parameters, the baseline is high, and the description further clarifies that no action, policy, or filter arguments are accepted. It correctly reinforces the empty-object invocation, though little semantic detail is needed for a no-argument endpoint.

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 and resource: discover deployed version, limits, tool names, aliases, and workflow. It clearly distinguishes this inventory endpoint from siblings by naming tools/list for callable schemas and trust_check_action for verdicts.

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?

It states when to call it ('before integrating') and how to call it ('Pass {}'), and explicitly routes the agent to alternatives for schemas and action verdicts. It also says to re-read after a deployment, giving a clear lifecycle usage cue.

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, closed-world behavior, and the description adds context the annotations cannot: free, unauthenticated, stateless per-call rules, usage metadata recorded but request bodies not stored. It also discloses the non-obvious emptiness rule that 0 and false are not treated as empty.

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 action and return values, then constraints and routing, so the most important content comes first. It is a single dense paragraph of considerable length; a line break or two between the constraint rules and the pilot/usage disclosure would aid scanning without cutting content.

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?

An output schema exists, so the description need not enumerate return fields, yet it still names ALLOW/BLOCK, field reasons and checked_fields for orientation. Combined with the dot-path and allow_extra guidance and the statelessness disclosure, nothing needed to invoke it correctly is missing.

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 most parameter meaning is already structured. The description still adds interaction semantics not present in the schema, notably that missing/null/empty optional values bypass other constraints while 0 and false do not, and that allow_extra is a top-level-only comparison that should stay true when using dot paths.

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 (validate) with an enumerated resource (field presence, exact types, primitive enums, inclusive numeric bounds) and names the return shape (ALLOW/BLOCK, field reasons, checked_fields). It also explicitly separates itself from trust_clean_data and trust_check_action, so an agent can route without opening schemas.

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?

Explicitly names alternatives and the conditions that select them: trust_clean_data for transformations, trust_check_action for evidence/spending checks. It also includes a concrete when-to-use construction pattern (combine required:true, type:"integer", min:1) and a scope caveat that this validates structure, not facts or provenance.

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