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

With no annotations provided, the description carries the full burden and does so richly: it enumerates all three decision outcomes (ALLOW/DENY/STEP_UP), discloses the 90-second authToken TTL and its binding scope, the required immediate follow-up via writ_verify_token, and the audit receipt side effect with receiptId.

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 most critical instruction ('CALL THIS BEFORE any consequential write') before the Args list, and every section earns its place. It runs long, but the length is justified by the decision-state and token-lifecycle content; only minor trimming is possible.

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?

Despite an output schema existing, the description still explains the decision semantics, token lifetime, and next-step routing an agent needs to act correctly. For a high-stakes gate tool with no annotations, nothing essential 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 0% and all five parameters are required, so the description must compensate — and it does, defining each parameter with role plus concrete examples ('verify_human', 'send_payment', 'benefit-case-123') and the binding constraint that approval is tied to purpose. This adds substantial meaning beyond bare string types.

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 ('Ask Writ whether an action may proceed') and immediately distinguishes its role as the pre-write gate. An agent can tell it apart from writ_verify_token, writ_grant, and writ_receipts 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?

Explicitly states when to call ('BEFORE any consequential write') and defines the trigger condition with concrete examples (money, messages, access/identity, deletion, external APIs). It names the alternatives and when to use them: writ_grant for STEP_UP, writ_verify_token after ALLOW.

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 well: it discloses single-use consumption semantics ('the next writ_check consumes it and returns ALLOW'), tenant scoping, and the required WRIT_SPONSOR_TOKEN. It does not explain grant expiry behavior (ttl_seconds) or failure/error modes, which leaves a small gap.

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 short sentences, front-loaded with the sponsorship constraint and purpose, then the trigger condition, then the consumption behavior. Every sentence adds distinct information with no repetition of the 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?

The output schema exists so return values are covered, and the workflow context is strong, but for a 6-parameter, 0%-coverage security-sensitive tool the parameter and expiry semantics are under-specified. Adequate for routing, thin 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 0% and there are 6 parameters, so the description must compensate. It only vaguely gestures at 'verb', 'target', 'purpose' via 'a specific action', plus sponsor and token, while ttl_seconds, agent_id, and sponsor_id are never explained in a way that adds meaning beyond the bare property names.

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: 'Mint a one-time grant approving a specific action', with a hard scope qualifier ('SPONSOR ONLY'). It implies its role relative to writ_check, but does not explicitly contrast itself with the other siblings (writ_revoke, writ_verify_token, etc.).

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 trigger condition: 'Use this when writ_check returned STEP_UP and the human sponsor approves.' This names the prerequisite tool and the human-approval gate, so the agent knows exactly when this tool is applicable rather than inferring it.

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?

No annotations are provided, so the description carries the full burden. It does convey that this is a read ('Read ...') and that the result describes allow/deny/grant/step-up rules, which is useful behavioral context. However, it says nothing about auth/tenant scoping requirements or whether the policy is cached or tenant-specific beyond the word 'tenant'.

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?

One front-loaded sentence with no filler; the resource and its contents are stated up front and the sentence ends exactly where it should.

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 zero-parameter read tool with an output schema already covering return values, the description is essentially complete: it states what is read and what the policy encodes. The only minor gap is the absence of any routing hint versus the sibling verbs.

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 takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to clarify beyond what an empty schema already communicates.

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 gives a specific verb ('Read') and resource ('the tenant's verb policy') and even enumerates the policy's contents (allow, deny, require a grant, step up). That is far more than a tautology. It stops short of explicitly differentiating itself from siblings like writ_check, which an agent could plausibly confuse with reading a policy.

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?

Usage is only implied: 'Read the tenant's verb policy' suggests a lookup use case, but there is no statement of when to call this versus writ_check or writ_grant, nor any prerequisite (e.g., tenant context or auth). Adequate but with a clear gap.

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. 'List' safely implies a read-only operation and 'Newest first' discloses result ordering, which is useful behavioral context. However, it says nothing about pagination, whether the trail is complete or filtered by caller, or any access restrictions.

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?

Two short sentences with the resource named first and ordering front-loaded at the end. No wasted words, though it is arguably under-specified rather than maximally efficient.

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 return values need not be explained, and the tool is simple (1 optional param). Still, the absence of any usage context or access requirements leaves the definition marginally complete for an audit-trail 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?

There is one parameter (limit) with a default of 10 and 0% schema description coverage, and the description adds no meaning about what limit bounds or its maximum. The parameter name is self-explanatory but the description does nothing to compensate for the coverage gap.

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 (List) and resource (decision receipts / audit trail), and 'Newest first' clarifies ordering. It is reasonably distinguishable from the action-oriented siblings like writ_revoke or writ_grant, though it does not explicitly contrast with a potential alternative read tool.

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 never states when to use this tool versus alternatives, nor any preconditions (e.g., which auth/role is required to view the audit trail). Usage is only implied by the word 'List'.

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 burden and discloses key behavioral facts: sponsor-only restriction, tenant scoping, required token, and that the principal is re-evaluated by policy. It does not detail idempotency, error conditions, or side effects beyond the re-evaluation, but the core auth and effect context is present.

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 two short, front-loaded sentences with no filler. The most important constraint ('SPONSOR ONLY') is placed first, and every sentence contributes necessary 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?

The output schema exists, so return values need not be explained, and the description covers auth, scope, and effect. However, with 0% schema description coverage, the parameters remain unexplained in both schema and description, leaving a clear completeness gap for invoking the tool 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 description coverage is 0% and the description does not mention or explain either required parameter (sponsor_id, agent_id). It does not compensate for the missing schema descriptions, leaving the meaning of both parameters undocumented.

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 ('Undo writ_revoke') and states the resulting effect ('the principal is evaluated by policy again'). It explicitly names the sibling operation it reverses, allowing an agent to distinguish it from writ_revoke and other writ_* tools.

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 provides clear prerequisites and context: 'SPONSOR ONLY', 'Scoped to your tenant', and 'Requires WRIT_SPONSOR_TOKEN'. The use case is implied by 'Undo writ_revoke', but there is no explicit statement of when-not to use it or a named alternative for granting new access.

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 well: it discloses the immediate effect, that revocation overrides live grants and tenant policy, that it requires a sponsor token, and that it is tenant-scoped. It omits whether the action is reversible or how to undo it (cf. writ_reinstate), which leaves a meaningful behavioral gap.

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 short lines, front-loaded with the access restriction and the core effect, then rationale, then scope, then auth requirement. No filler sentences.

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 return values need not be described, and the safety/destructive profile plus auth requirements are covered. The residual gap is parameter meaning at 0% schema coverage, which is the one thing an agent still cannot infer.

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% with two required parameters (sponsor_id, agent_id), and the description never explains what either identifier is or how sponsor_id relates to the authenticated WRIT_SPONSOR_TOKEN. The word 'principal' gestures at agent_id but adds no real semantic content beyond 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 precise verb+resource+effect: 'Kill switch: immediately deny all future checks for this principal.' The scope ('Scoped to your tenant') and the contrast with siblings writ_check/writ_grant are clear enough that an agent can distinguish it from writ_reinstate and writ_grant 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?

Gives explicit triggering conditions ('compromised, misbehaving, or its task is done') and an access precondition ('SPONSOR ONLY', 'Requires WRIT_SPONSOR_TOKEN'). It stops short of naming the recovery alternative (writ_reinstate) or stating when not to revoke, so it is strong but not fully alternative-aware.

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 behavioral burden well: it discloses the 90-second lifetime, that no API key is required, the exact verb restricted to it, the target prefix constraint, and that it auto-runs writ_check returning an ALLOW decision plus auth token. Only minor gaps remain around failure modes (e.g., what happens with a non-'demo-' target).

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 core value is front-loaded ('Get a free 90-second sandbox grant'), with supporting detail after. It is compact and every sentence adds information, though the second sentence packs several nested clauses.

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 return contents need not be explained (the description still does, helpfully). However, for a 4-required-parameter tool at 0% schema coverage, three parameters have no semantics anywhere, leaving the agent unable to populate the call 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 description coverage is 0%, so the description must define all four parameters. It only adds meaning for 'target' (must start with 'demo-'); sponsor_id, agent_id, and purpose are entirely unexplained in both schema and description.

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 states a specific verb and resource: issue a 90-second sandbox grant for a 'demo_write' on a 'demo-' target. It implicitly separates itself from writ_grant by being the free, no-key practice path, though it never names that sibling explicitly.

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?

Usage context is implied: 'for a demo write' and 'to practice the verify-before-write flow end to end' suggest a sandbox/practice scenario. There is no explicit when-to-use versus the very similar writ_grant, and no when-not-to-use or prerequisites beyond the free/keyless note.

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?

No annotations exist, so the description carries the full burden, and it does disclose failure semantics (expired, tampered, purpose-bound mismatch) and the commit-time enforcement model. It stops short of stating that the call is side-effect free, whether it consumes or rotates the token, or any rate limits.

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 imperative with the imperative instruction first, then the failure branch. The closing sentence ('the check authorizes, the token proves...') is a useful mental model rather than filler, though it is slightly repetitive of the opening.

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 return-value explanation is not required, and the description still explains what 'valid: false' means. For a four-required-param verification tool it is close to complete, missing only token format and whether verification has any side effects on the token's state.

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% across four required params, so the description must compensate. It does clarify that verb/target/purpose must match the actual intended write exactly and that auth_token is a Writ auth token, but it gives no format guidance for the token, target identifiers, or purpose strings.

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 (verify) and resource (Writ auth token) scoped against a concrete action ('the write you are about to execute'). It also separates itself from the sibling writ_check by naming the check/verify division of labor: the check authorizes, the token proves it.

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 timing ('Call this IMMEDIATELY before executing an ALLOWed write'), explicit input expectation (exact verb/target/purpose), and an explicit negative branch ('If valid is false ... do NOT execute the write; call writ_check again'). No inference required.

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