ScopeProof

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

The description adds meaningful behavioral details beyond annotations: a $0.01 stablecoin machine payment, deterministic reason codes, policy/action digests, and a tamper-evident receipt. It also discloses a limitation ('not ... a safety guarantee'). Since annotations already cover readOnly/idempotent/destructive, this additional context is complementary rather than repetitive.

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 three sentences, with the core purpose front-loaded, followed by payment/output details and a clarifying caveat. Every sentence earns its place with no filler. It is dense but not bloated.

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 complex tool with no output schema and highly nested parameters, the description is incomplete. It does disclose the return categories (within_scope, outside_scope, review_required) and receipt, which is good. But it does not explain when review_required would be returned, what the reason codes mean, or how to correctly populate the action/authority structures, leaving an agent to guess at decision semantics.

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 0%, and the description only maps 'proposed action' and 'supplied authority' to the two required parameters at a conceptual level. It provides no guidance on fields like allowedActions, deniedActions, maxSpend, approvalRequiredFor, or how action.type/resource interplay with authority. An agent must rely entirely on field names and types, which is insufficient for such nested objects.

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 opener 'Determine whether one proposed action is within explicitly supplied authority' is a specific verb+resource statement. The closing clause clarifies what the tool is not (identity verification, legal authorization, safety guarantee), which distinguishes it from related concepts. It does not explicitly name sibling tools like preflight or verify_receipt, so it misses a full 5.

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 clearly establishes when to use this tool: whenever a proposed action needs to be checked against explicitly supplied authority. The negative clauses tell the agent not to use it for identity verification, legal authorization, or safety guarantees. However, it never references the sibling tools or gives a when-not condition that points to an alternative.

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, and non-destructive behavior. The description adds valuable behavioral context: it is free, accepts no credentials, raw prompts, arbitrary request bodies, or secrets, and returns no substantive authorization verdict. This goes beyond the annotations. However, it does not disclose what the tool does return (e.g., a validation status or error details), leaving some ambiguity.

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 concise with two sentences and front-loads the core purpose. There is no filler or redundancy. However, the brevity contributes to the lack of detail in other dimensions, so it is efficient but at the expense of completeness.

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?

This tool has complex inputs with nested objects, three parameters, zero schema descriptions, and no output schema. The description is far too sparse to cover these gaps. It omits return behavior, parameter semantics, and usage context, making it inadequate for an agent to correctly construct or interpret the call.

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 0% description coverage, so the description must compensate by explaining the parameters. It only hints at 'authority envelope' (likely mapping to the 'authority' parameter) but provides no explanation of 'action' or 'context'. No parameter names, data types, or construction guidance are given, leaving agents without the information needed to invoke the tool correctly.

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 clearly states a specific verb ('validate') and resource ('structured authority envelope'). It also clarifies that it returns no substantive authorization verdict, which distinguishes it from an authoritative check. However, it does not explicitly name sibling tools like check_action or verify_receipt, so it does not achieve full differentiation.

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 mentions it is free and returns no substantive verdict, implying it serves as a lightweight preflight check, but it never explicitly states when to use this tool versus alternatives. No alternative tools are named, and there is no guidance on conditions that would make this tool inappropriate.

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=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds meaningful context: it states the tool operates 'without exposing the server signing key' (a security guarantee) and is 'free and repeatable' (cost/rate implication). No contradiction with annotations.

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 concise: two sentences with no waste. The core action is front-loaded ('Verify the cryptographic integrity'), and the additional notes (key exposure, free/repeatable) provide useful context without 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 single-parameter tool with no output schema and strong annotations, the description covers the essential purpose and adds useful behavioral notes. However, it omits what constitutes a successful verification or error conditions, and it does not clarify how this tool fits into a workflow relative to check_action and preflight.

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 0% for the 'receipt' parameter, and the description only mentions 'one ScopeProof receipt,' offering no structural or format details. The schema itself merely defines the parameter as an object, so the description does not adequately compensate for the lack of parameter documentation.

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 clearly states a specific verb ('verify'), a resource ('ScopeProof receipt'), and the nature of verification ('cryptographic integrity'). It distinguishes the tool by its focus on verification, but it does not explicitly contrast with sibling tools (check_action, preflight), so the differentiation is implied rather than 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 implies the use case (verifying a receipt's integrity) but provides no explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives. The phrase 'Free and repeatable' hints at cost/rate behavior but does not explain when to select this tool over its siblings.

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