agent-transaction-control

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

Annotations include readOnlyHint=true, suggesting no side effects. The description says 'generates' a machine-readable policy file, which is consistent with a stateless computation. It adds value by describing what the manifest declares (FLINT authority verification, signed records, etc.), going beyond annotations. No contradiction detected.

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 paragraph of three sentences, efficiently stating the purpose and usage context. It is front-loaded with the when-to-use instruction. Could be slightly more concise, but overall well-structured with minimal waste.

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 13 optional parameters with full schema descriptions and no output schema, the description provides a good overview of the tool's purpose. However, it does not mention what the tool returns (the generated manifest) or how it is delivered. This is a minor gap in completeness.

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% (all 13 parameters have descriptions). The tool description does not add additional parameter semantics beyond what is in the schema. Baseline of 3 is appropriate as the schema already explains each parameter adequately.

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 generates a FLINT trust manifest and specifies the exact use cases: merchants, API sellers, MCP tool providers, x402 endpoints, or agent storefronts needing a .well-known/flint.json file. It distinguishes from siblings by focusing on manifest creation, while siblings handle authorization, passports, 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?

It explicitly states when to use the tool: when an entity needs a FLINT trust manifest. It provides context on the type of entities and the purpose of the manifest. However, it does not mention when not to use it or direct to alternatives, which would improve clarity among siblings.

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 include readOnlyHint=true, indicating no state mutation, but description uses 'creates' which could be misinterpreted. However, it does not contradict annotations; it adds context about output usage. More explicit indication of side-effect-free generation would improve transparency.

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 action and purpose, no redundant information. Efficient for agent consumption.

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?

Description explains role in workflow and connection to sibling tool. With no output schema, it could mention return shape, but the schema and context are sufficient for decision-making.

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 description adds little beyond listing boundary types. It does not elaborate on parameter formats or relationships beyond schema descriptions, maintaining baseline score.

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 the tool generates a delegated authorization scope with specific boundaries (financial, counterparty, action, time). It also names the sibling tool `issue_authorization_record` that receives the output, differentiating it from other 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?

Description explicitly says 'Use this tool when an agent commerce workflow needs a well-formed delegated authorization scope before issuing a signed verification record.' This provides a clear use case and implies it is a preparatory step, distinguishing it from siblings.

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 and openWorldHint, indicating no side effects. The description adds behavioral details: it returns compact identity, mandate, status, and the public URL without echoing the full signed envelope. No contradiction.

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 clear sentence that is front-loaded with the purpose. Every phrase adds value; there is no fluff.

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 simple read tool with one parameter and no output schema, the description adequately explains what is returned (compact identity, mandate, status, URL) and behavior (no full envelope). It is sufficient for an agent to use 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?

The schema has 100% coverage for passport_id with pattern and description. The description adds meaning: it specifies that the passport_id is a FLINT Agent Passport id starting with kya_ and explains the purpose of the tool, supplementing 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?

The description clearly states the tool resolves a public FLINT Agent Passport by passport_id, and specifies the returned data (identity, mandate, status, URL). It distinguishes itself from sibling tools like issue_agent_passport (creates) or verify_agent_authority (verifies).

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 says 'Use this tool to resolve...', indicating its primary use case. It does not explicitly state when not to use it or list alternatives, but the context of sibling tools makes the differentiation clear.

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 non-read-only, non-destructive. Description adds that the passport is free, hybrid-signed, and returns a public URL and one-time claim link. No contradictions. Could mention idempotency but annotations already note it is not idempotent.

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 sentences, front-loaded with purpose, each sentence adds distinct value (what, how, optionality, behavioral note). No redundancy or unnecessary detail.

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?

With no output schema, description adequately describes return values (URL and claim link). Covers key behavioral aspects for a creation tool. Could mention if multiple issuance for same agent is allowed, but openWorldHint suggests it is.

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. Description adds meaning: explains that 'agent' object only requires name or ID, and other fields optional; clarifies 'mandate' is mutable and not part of passport signature, adding purpose 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?

Explicitly states it issues a FLINT Agent Passport, a verifiable identity credential. Distinguishes from siblings like 'get_agent_passport' (retrieval) and 'update_agent_mandate' (mandate updates) by highlighting that the passport only signs identity and mandate is separate.

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?

Clearly states when to use (to issue a passport) and mentions zero-config path requiring only agent name or ID. Implicitly guides against reissuing for mandate changes by noting mandate can be updated later without reissuing, referencing sibling 'update_agent_mandate' indirectly.

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 the tool is not read-only and not destructive. The description adds behavioral context such as verifying authority, checking scope, issuing a signed record, and returning evidence for disputes, which goes 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 guidance, and every sentence adds value. No redundancy or unnecessary details.

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 high schema coverage and annotations, the description lacks details about the return value (no output schema). It mentions 'returns evidence' but doesn't specify the format or structure, leaving a gap in contextual completeness for a tool with 7 parameters and nested objects.

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 has 100% description coverage, so the schema itself documents all parameters. The description does not add new information about individual parameters; it only provides high-level context. 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 clearly states the tool's purpose: issuing a signed verification record before initiating financial transactions. It uses specific verbs ('verifies', 'checks', 'issues', 'returns') and distinguishes from siblings by listing concrete use cases like payments and API calls.

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 says 'Use this tool before an AI agent initiates a payment...' and lists specific transaction types, providing clear guidance on when to use it. However, it does not mention when not to use it or suggest alternatives, though sibling tools exist.

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 and openWorldHint. The description adds context by stating the tool returns aggregate reputation without exposing raw runtime identifiers or internal signal fields, which clarifies the scope of results and behavioral constraints beyond 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?

The description is two sentences, front-loaded with usage context, and each sentence adds value. No wasted words or 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?

Given a simple single-parameter tool with annotations and no output schema, the description covers the main purpose, usage context, and output characteristics (aggregate reputation, no raw identifiers). It could briefly mention the output format, but for a lookup tool this is nearly complete.

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 single parameter flint_agent_id is fully described in the schema (100% coverage), so the description adds no additional parameter meaning beyond what the schema provides. Baseline 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 queries the FLINT Trust Graph for historical reputation, specifies the verb 'query' and resource 'historical reputation', and lists specific use cases (payment, API call, checkout, x402, delegated commercial transaction). It distinguishes from sibling tools by indicating it returns aggregate reputation without exposing raw identifiers, implying other tools handle raw data.

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 provides when to use the tool ('before permitting...'). It implies when not to use by stating it does not expose raw runtime identifiers or internal signal fields, suggesting alternative tools for those needs. However, it does not name specific sibling alternatives or explicitly state exclusions.

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 the tool is not read-only, is idempotent, and not destructive. The description adds that it updates the agent's reputation in the Trust Graph, providing useful behavioral context beyond 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?

The description is two sentences, front-loaded with the core purpose. It is concise and every sentence adds value, though the second sentence is slightly longer.

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 description covers when to use the tool and its effect on reputation, but lacks details on return values or error handling. Given no output schema, some additional context would be beneficial, but annotations partially compensate.

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?

All parameters are fully described in the schema (100% coverage). The description does not add additional semantics beyond the schema, so it meets the baseline but does not exceed it.

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 submits ground-truth outcome feedback for FLINT-authorized transactions. It uses a specific verb ('submit') and resource ('transaction outcome'), and the context distinguishes it from sibling tools like issue_authorization_record or create_flint_trust_manifest.

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 lists when to use the tool: after completion, dispute, or flagging of various transaction types. It does not give negative guidance or alternative tools, but the context is clear enough for an agent to decide when to invoke 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 already indicate mutation and idempotency. The description adds valuable behavioral details: it clarifies the update scope (no reissue/re-sign) and specifies authentication requirements if the passport is claimed. This complements 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 three sentences, front-loading the purpose, then clarifying constraints and authentication condition. Every sentence adds necessary information with no fluff.

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 two parameters and no output schema, the description covers the effect and a key precondition. However, it omits whether the update is a merge or replacement of the mandate, and does not describe the return value (success indication or updated object).

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 baseline is 3. The description repeats the schema information about mandate fields but adds no additional nuance beyond the schema descriptions. No extra value beyond what the schema already 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?

The description clearly states the tool updates mutable mandate config for an existing FLINT Agent Passport, specifying exactly what fields are updated (allowed actions, amount limits, notes) and what it does not do (reissue or re-sign). This differentiates it from sibling tools like issue_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 context on when to use this tool by stating it updates an existing passport and does not reissue or re-sign, implying it is for modifying existing mandates. However, it does not explicitly compare with alternative tools or provide when-not-to-use 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?

Description claims the tool 'submits outcomes' and 'publishes a Trust Manifest,' which are write operations, yet annotations declare readOnlyHint=true. This contradicts annotations and misleads agents about side effects. No behavioral detail beyond misleading claims.

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?

Description is reasonably concise within 3 sentences. Could be better structured (e.g., bullet points) but no excessive verbosity.

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?

No output schema, so description should explain return value (e.g., boolean pass/fail, detailed report). It does not. Also unclear if the tool actually performs writes or just validates them. The contradiction exacerbates incompleteness.

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 covers 100% of the single parameter with a clear description. The description adds no extra semantic value beyond the schema's own 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?

Description clearly states the tool checks commerce architecture readiness for FLINT compliance, specifying distinct actions like verifying signed records and publishing Trust Manifests. It distinguishes from sibling tools like verify_agent_authority (verification) and create_flint_trust_manifest (creation) by focusing on holistic validation.

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 enumerates use cases (reviewing commerce architecture, API marketplace, etc.) providing clear context. Lacks explicit 'when not to use' guidance but sufficiently narrows 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 mark the tool as read-only and open-world. The description adds behavioral detail: it verifies cryptographic signature, checks expiration, and decodes payload. It does not contradict annotations and provides useful insight into what the tool does beyond the structured metadata.

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, clear sentence that front-loads the usage context ('Use this tool when...') and succinctly states the core operations. No extraneous 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 absence of an output schema and the presence of annotations, the description explains the verification flow adequately. However, it could be more complete by hinting at return values (e.g., decoded payload or success/failure). Still, it covers the main behavioral aspects for an agent to decide usage.

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 parameters are well-documented. The description references the 'compact JWS signature' (matching the 'jws' parameter) but does not add new meaning beyond the schema. The optional 'jwks_url' is not elaborated. 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: cryptographically verify a JWS signature, check expiration, and decode the payload. It specifies the context (when a merchant receives a signed record from an agent) and distinguishes from sibling tools that create or issue 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 explicitly says 'Use this tool when a merchant or API seller receives a signed verification record from an agent,' providing clear usage context. It does not explicitly exclude scenarios or mention alternatives, but the sibling list includes related tools, implying differentiation.

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