agent-transaction-control

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

Annotations state readOnlyHint=true, but the description uses 'create' and 'generates' which imply a write operation. This is a clear contradiction, and the description does not add behavioral context beyond the 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?

Two sentences: first sentence states when to use, second explains the manifest's purpose. Front-loaded, no wasted words.

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 many optional parameters and no output schema, the description does not mention return value or side effects. Given readOnlyHint contradiction, completeness is hindered.

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% with descriptions for all 13 parameters. The description adds background about FLINT authority but does not enhance meaning beyond the schema, so baseline 3.

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 the tool creates a `/.well-known/flint.json` Trust Manifest for merchants, API sellers, etc. It distinguishes from sibling tools like issue_agent_passport or verify_agent_authority by focusing on manifest generation.

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 says 'Use this tool when...' for various actors needing a trust manifest. Provides clear context but does not mention when not to use or suggest alternatives, which is acceptable given the narrow scope.

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 provide readOnlyHint=true, so no contradiction. Description adds that it 'creates boundaries' but does not elaborate on side effects or idempotency beyond what annotations imply.

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 sentences, front-loaded with usage context, no redundant words. 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?

For a tool with 7 parameters and no output schema, the description adequately explains when and why to use it and how it relates to issue_authorization_record, though it could briefly note the return value.

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 all parameters are described in schema. The description mentions categories (financial, counterparty, action, time boundaries) that loosely map to parameters but adds no new semantics beyond 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?

The description clearly states the verb 'generate' and resource 'authorization scope', specifies when to use (agent commerce workflow before issuing a signed verification record), and distinguishes it from siblings by mentioning it produces input for issue_authorization_record.

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 use ('before issuing a signed verification record') and identifies the sibling tool that consumes the output, but does not provide when-not-to-use or alternative scenarios.

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 provide readOnlyHint and openWorldHint. The description adds value by specifying the returned data (compact identity, mandate, status, URL) without echoing the full envelope, which goes beyond 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 a single, well-structured sentence with no wasted words. It efficiently conveys purpose, input, and output characteristics.

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 no output schema, the description adequately explains what is returned (identity, mandate, status, URL). For a simple read-only lookup with clear annotations, this is fully sufficient.

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% with one parameter that has a pattern and description. The description does not add additional semantic meaning to the parameter beyond what is in the schema, so baseline score 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?

The description clearly states the action 'resolve' and the resource 'FLINT Agent Passport by passport_id'. It distinguishes from siblings by implying a read-only lookup, though it does not explicitly contrast with issue or update 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?

The description indicates when to use (to resolve a passport by ID), but lacks guidance on when not to use or alternatives among sibling tools like issue_agent_passport or update_agent_mandate.

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 (readOnlyHint=false, openWorldHint=true) indicate a non-idempotent write. The description adds transparency: it specifies that the passport signs identity only, the mandate is separate and mutable, and returns a public URL and one-time claim link when minted anonymously. No contradictions 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 yet complete, with each sentence adding value: purpose, minimal requirements, optional fields, behavior, and return values. It is front-loaded with the core action, and no information is redundant.

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 complexity (2 params, no output schema), the description provides adequate context: return values (URL, claim link), the nature of the credential, and the mutable mandate. However, it does not mention any prerequisites or side effects beyond what annotations imply, leaving minor gaps.

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%, and the description adds significant meaning beyond the schema. For the 'agent' parameter, it explains required vs optional fields. For 'mandate', it clarifies it is mutable and not part of the passport signature, providing actionable semantic context for the agent.

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 the tool's purpose: 'issue a free FLINT Agent Passport: a hybrid-signed, verifiable identity credential for an autonomous agent.' It uses a specific verb (issue) and resource (Agent Passport), differentiating from sibling tools like get_agent_passport (read) and update_agent_mandate (update).

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 provides guidance on minimal requirements: 'The zero-config mint path only needs agent.agent_name or agent.agent_id.' It also clarifies optional fields and that mandate can be updated later, distinguishing it from update_agent_mandate. However, it lacks an explicit 'when not to use' statement for alternatives.

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 adds value beyond annotations by detailing the multi-step process: verifying authority, checking scope, issuing a record, and returning evidence for dispute review and Trust Graph updates. It does not contradict any annotation.

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 sentences, front-loaded with usage context, and every phrase adds value with no 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?

The tool has 7 parameters and nested objects, but no output schema. The description explains actions but omits the return structure (e.g., what the signed record contains), leaving a gap for a complex 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?

With 100% schema coverage, the baseline is 3. The description references agent_claim and declared_scope in context but adds little specific meaning beyond the schema's already descriptive property descriptions.

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 explicitly states the tool issues a signed verification record and lists specific use cases (payment, paid API call, checkout, etc.), differentiating it from siblings like verify_agent_authority by emphasizing issuance over mere verification.

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 clearly directs when to use the tool (before initiating commercial actions), providing strong context. However, it lacks explicit when-not-to-use guidance or alternative tool references beyond the sibling 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?

Annotations already indicate readOnlyHint=true and openWorldHint=true. The description adds value by stating that it returns 'aggregate reputation without exposing raw runtime identifiers or internal signal fields,' which clarifies data privacy behavior beyond the annotations. No contradictions.

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 sentences with no wasted words. The purpose and usage are front-loaded. 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?

Given one parameter and no output schema, the description adequately covers what the tool does and what it returns (aggregate reputation without raw identifiers). A minor gap is the lack of detail on the return structure, but it's sufficient for an agent to understand the tool's role.

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 input schema provides full coverage (pattern and description for flint_agent_id). The description adds no additional meaning beyond the schema, so baseline score of 3 is appropriate.

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 the tool's purpose: to query historical reputation from the FLINT Trust Graph. It specifies the verb 'query' and resource 'reputation', and lists specific use cases (payment, paid API call, etc.), making it distinct from sibling tools like create_flint_trust_manifest or get_agent_passport.

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 provides explicit when-to-use scenarios (before permitting various commercial actions). However, it does not mention when not to use or alternative tools, leaving the agent to infer from sibling names. Clear context but lacks 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?

Annotations already provide readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds the behavioral context of updating the agent's reputation in the Trust Graph, which is useful but does not disclose additional traits beyond the 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 two sentences long, front-loads the usage context, and contains no redundant or unnecessary 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?

Given the tool has four parameters, no output schema, and annotations that cover safety and idempotency, the description adequately explains when and why to use the tool. It could mention what happens after submission (e.g., confirmation), but the key points are 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 description coverage is 100%, so the schema already documents each parameter. The description does not add significant new meaning beyond what the schema provides, meeting the baseline for high coverage.

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 specifies the action ('submit transaction outcome') and the context ('after a FLINT-authorized transaction, paid API call, etc.'), distinguishing it from sibling tools that handle creation, verification, or authorization.

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 explicitly states when to use the tool ('after ... completes, is disputed, or is flagged'), providing clear context. However, it does not include exclusions or explicit mention of when not to use 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?

Annotations indicate readOnlyHint=false, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds context by clarifying that only mutable mandate fields are updated, that the passport is not reissued or re-signed, and that authentication is required if claimed. This goes beyond annotations and provides useful behavioral details.

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?

Three concise sentences: first states purpose, second clarifies scope and exclusions, third adds a conditional requirement. No redundant words; every sentence serves a distinct purpose.

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 no output schema, the description covers input semantics, behavioral limits, side-effect exclusions, and an authentication condition. For a two-parameter tool, this is fairly complete. It could mention return value/success indication but not required.

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 baseline is 3. The description reinforces that the mandate object includes 'allowed_actions, max_transaction_amount, notes', which is already hinted in the schema description. It adds marginal value by grouping these fields under 'mutable mandate config'.

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 the verb 'update' and the resource 'mutable mandate config for an existing FLINT Agent Passport'. It specifies what is updated (allowed actions, amount limits, notes) and distinguishes from siblings like issue_agent_passport (issuance) and get_agent_passport (retrieval).

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 explicitly states when to use the tool ('update mutable mandate config') and what it does not do ('does not reissue the passport and does not re-sign the identity credential'), providing exclusions. However, it does not explicitly point to alternative tools, though sibling names provide implicit differentiation.

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, so the agent knows it is a safe read operation. The description adds value by detailing exactly what is checked (FLINT as authority layer, signed records, outcomes, Trust Manifest, Trust Graph reputation), providing behavioral context beyond the annotation. No contradictions.

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 sentences with zero wasted words. The first sentence sets usage context, the second describes actions. Every sentence earns its place. Ideal conciseness.

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 tool has one required parameter with good schema description, but there is no output schema and the description does not specify what the tool returns (e.g., boolean, report, validation errors). For a validation tool, this is a noticeable gap. The description is otherwise adequate for the use case but lacks output specification.

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% and the schema description for 'architecture_description' is already descriptive ('Summary of the payment, paid API access, x402, MCP, or checkout flow.'). The tool description adds indirect context about what validation occurs but does not provide additional syntax or format details for the parameter, so baseline 3 is appropriate.

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 specifies a clear verb ('Validate') and resource ('Agent Commerce Readiness'). It lists distinct use cases (commerce architecture, API marketplace, paid MCP tool, x402 endpoint, autonomous checkout flow) and enumerates the specific checks performed (FLINT layer, signed records, outcomes, Trust Manifest, Trust Graph). This distinguishes it from sibling tools that focus on creating or issuing individual records.

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 begins with 'Use this tool when reviewing...' providing explicit guidance on appropriate scenarios. It covers a concrete set of use cases but does not explicitly state when not to use it or name alternative tools for specific tasks. The context is clear, but exclusions are missing.

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 and openWorldHint=true. Description adds behavioral details: cryptographically verifies JWS signature, checks expiration, decodes payload, and business context (before payment/access). No contradictions.

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 sentences that front-load usage context and then describe functionality. No redundant information. Ideal length for quick comprehension.

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?

Covers verification steps and business usage. Lacks explicit return value description (no output schema), though 'decodes the payload' implies it returns decoded data. Minor gap but overall adequate for the tool's simplicity.

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 100% so baseline is 3. Description echoes schema descriptions ('Compact JWS signed verification record', 'Optional JWKS URL with origin constraint') but doesn't add new semantic meaning beyond what schema provides.

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?

Description clearly states it verifies signed verification records from agents, with specific verb 'verify' and resource 'verification record'. It distinguishes from sibling tools by focusing on cryptographically verifying JWS for payment/access execution.

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 says 'Use this tool when a merchant or API seller receives a signed verification record from an agent', providing clear context. Does not mention exclusions or alternatives, but the guidance is sufficient for typical use.

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