agent-transaction-control

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

Annotations declare readOnlyHint=false, idempotentHint=false, openWorldHint=true, and destructiveHint=false, so the safety profile is mostly covered; the description adds meaningful context by disclosing the side effect (an email is sent to the inbox) and the downstream ownership consequence. It stops short of code expiry, resend/rate-limit behavior, or what happens on repeated calls, which is the remaining gap for a non-idempotent tool.

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 front-loaded sentences with zero filler: the ordering instruction comes first, followed by the action, then the exact next step. 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?

For a one-parameter tool with no output schema and annotations already covering the safety profile, the description supplies enough to call it correctly and know what to do next. Missing only operational details like code lifetime or resend behavior, which are nice-to-have rather than blocking.

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% for the single parameter, and the schema already states the inbox receives the one-time code, so the description largely repeats it. It adds only the implicit constraint that the same email value must be reused in auth_verify_otp, which is marginal. 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?

States a specific verb and resource — email a one-time sign-in code to a given inbox — and names its role in the flow, distinguishing it from the sibling auth_verify_otp that consumes the code. An agent can tell this tool apart from the rest of the auth family without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says to use it first, names the exact follow-up call (auth_verify_otp with the same email and code), and explains the ordering benefit (passport owned immediately, no separate claim step). Both when and what-comes-next are stated.

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 only declare the generic profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false). The description goes well beyond that: it discloses the session_token return value, instructs the caller to persist it, names every downstream tool that requires it, and imposes a credential-handling rule ('never print or log session_token; treat it like a password') that no annotation conveys.

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 compact sentences, fully front-loaded: precondition first, then the return value, then the downstream usage and safety rule. Every sentence carries operational information; nothing is filler.

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, the description takes on the burden of explaining the return and does so (session_token). For a non-idempotent, open-world auth step it covers precondition, result, downstream consumption, and secret handling — an agent has everything needed to call and use it 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 100%, so all three parameters (email, code, label) are already documented, including that email must match the auth_request_otp call. The description restates that intent but adds no format, constraint, or ambiguity resolution beyond the schema; the optional label is untouched. Baseline 3 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 states a concrete operation — exchanging an inbox code for a session_token — using a specific verb (verify/returns) and resource (one-time sign-in code / session). It also anchors the tool relative to auth_request_otp, so the agent can separate it from the other auth siblings without reading 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?

Explicit sequencing: 'right after auth_request_otp, with the code from the inbox.' It further tells the agent what to do with the result and which downstream calls (issue_agent_passport, get_agent_passport, update_agent_mandate, claim_agent_passport, refresh_claim_token) consume the token, which is unusually actionable routing 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 declare non-readonly, non-idempotent, non-destructive, open-world. Description adds critical behavior beyond that: single-use nature ('A passport can only be claimed once'), ownership transfer, and side effect that 'Sentinel protection turns on.' Auth dependency also stated. Doesn't cover error/latency behavior, hence 4.

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, then auth requirement, parameter conditions, and failure routing. Every sentence carries distinct information; 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?

For a 3-param mutation tool with no output schema, the description covers purpose, auth dependency, parameter conditions, irreversibility/one-time-use, and recovery path. An agent has everything needed to call correctly or route to refresh_claim_token.

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. The description adds real semantics: session_token ties to auth_verify_otp for account binding, claim_token can be omitted when session already holds a pending claim, and the source of claim_token (claim_url). This meaning goes beyond the schema's field 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?

States a specific verb (claim/attach) and resource (FLINT Agent Passport) with precise scope: 'attach an anonymously minted, unclaimed FLINT Agent Passport to an authenticated FLINT account.' Clearly distinguishes from siblings like issue_agent_passport and refresh_claim_token by naming those divergences.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes to alternatives: 'if the token was already used or lost, call refresh_claim_token for a fresh one instead of trying to remint.' Also conditions claim_token omission. Gives when-to-use, when-not, and named 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?

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?

Adds real value beyond annotations: it explicitly says the tool 'returns compact identity, mandate, status, ownership, and the public passport URL without echoing the full signed envelope,' and clarifies that 'the lookup itself is public' and session_token is optional. This disambiguates auth requirements – a reader knows no token is needed. Minor gap: doesn't mention rate limits or error behavior.

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 the tool's purpose, then the return payload and auth clarification. No filler; every clause 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 no output schema, the description adequately describes the return shape (compact identity, mandate, status, ownership, public URL) and auth posture. It should ideally mention what 'compact' excludes or error handling for invalid passport_id, but it is complete enough 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 100%, so the schema already documents both parameters (including the kya_ pattern and session_token format). The description adds the useful clarification that session_token is optional and not required for reading, which is slightly beyond the schema, but the baseline for full coverage is 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?

States a specific verb and resource: 'resolve a public FLINT Agent Passport by passport_id.' This is clearly distinguishable from siblings like validate_agent_commerce_readiness, verify_agent_authority, or issue_agent_passport. The scope ('public', 'compact') is precisely stated.

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 usage (read a passport, lookup is public) but does not explicitly state when to use this vs. alternatives like verify_agent_authority or lookup_agent_reputation. A reader can infer it's for reading passport data, but no exclusions or alternative routing are given.

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 annotations only say this is a non-read-only, non-idempotent, non-destructive operation. The description adds substantial behavioral context: signed identity is immutable, wrong identity fields require a corrected remint, a remint supersedes a prior UNCLAIMED passport only under specific authorization conditions, a CLAIMED passport is never auto-superseded, and unknown action strings are preserved but reported back. This goes far beyond what annotations or schema communicate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded and densely informative, with each major behavior in logical order. However, it repeats the immutability and separate-mandate points multiple times (e.g., 'A missing controller requires a corrected remint' and 'The signed identity is immutable once minted' and 'The passport signs identity only'), making it slightly longer than strictly necessary.

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 there being no output schema, the description states the key return artifacts: a public resolvable passport URL and, for anonymous mints, a one-time claim link. It also covers warnings like related_passports and existing_claimed_passports, immutability, supersession rules, and both authenticated and anonymous paths. An agent has everything needed to invoke this 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?

Even though schema description coverage is 100%, the description adds crucial semantics for all four parameters: session_token binds ownership immediately, omitting it returns a one-time claim_url, supersede_management_token is the raw claim token of a specific prior unclaimed passport, controller_id is distinct from the owning FLINT account, and mandate is mutable and outside the signature. It also enumerates the allowed-actions vocabulary and the ['ALL'] preset, which the schema does not.

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 opens with a specific verb and resource: 'issue a free FLINT Agent Passport: a hybrid-signed, verifiable identity credential.' It further distinguishes itself from siblings by explaining the separate mutable spending mandate (pointing toward update_agent_mandate) and the anonymous claim_url flow (pointing toward claim_agent_passport), so an agent can tell this tool apart from related ones.

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 gives explicit preconditions: ask the principal for controller_id, controller_type, allowed actions, max transaction amount, and wallet address; never infer authority. It also explains when the zero-config identity-only path is acceptable, when to use session_token versus anonymous minting, and when a mandate can be updated later rather than reissued, which routes the agent away from unnecessary remints.

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?

Beyond the annotations (destructiveHint=false, idempotentHint=true), the description discloses the mutation's real consequence — the previous token is invalidated — and the shape of the response (new claim_url and claim_token). It also spells out two distinct authorization paths, management_token vs session_token, which the annotations cannot convey.

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 dense sentences, front-loaded with the trigger condition, then the effect, then the authorization requirement — no filler. It is slightly jargon-heavy ('supersede', 'remint') but every clause carries operational information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a three-parameter mutation tool with no output schema, the description covers the trigger, the state change, the returned values, and the auth options, leaving nothing an agent needs in order to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: management_token may be the raw claim token 'even one about to be superseded,' and session_token only works when the session originally requested the claim or minted the passport. That constraint is not present in the schema text.

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 opens with a specific verb+resource ('rotates the claim token') and states the exact effect: the old token stops working and a new claim_url/claim_token are returned. It also distinguishes itself from the sibling action of reminting a passport, so an agent can separate this tool from issue_agent_passport without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives an explicit trigger condition (claim link lost, expired, or already consumed for a still-unclaimed passport) and an explicit exclusion ('do not remint the passport instead'), plus the reason reminting fails to recover a lost link. That is when-to-use, when-not-to-use, and the alternative all in one place.

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

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

Goes well past the annotations by disclosing that FLINT cannot stop a wallet from transacting, that this tool is the 'enforce-or-attest half of the contract', and that an executed_despite_block outcome is recorded as an override and alerts the passport owner. That side-effect disclosure is exactly the behavior an agent needs and is not derivable from readOnlyHint/idempotentHint/destructiveHint.

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 tight sentences, front-loaded with the usage trigger and followed by the auth branches and the override consequence. Dense but every clause carries information; only the framing phrase about the 'enforce-or-attest contract' is mildly decorative.

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 7-parameter write tool with no output schema, the description covers the prerequisite scan, both authorization routes, and the downstream consequences of an override. It stops short of saying what the tool returns on success or how repeated reports for the same record_id are handled (relevant given idempotentHint).

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 two-token authorization model, the frv_ record_id pattern, and the executed/held/cancelled/executed_despite_block enum are already documented inline. The description restates the same branching logic rather than adding format or edge-case detail, so the baseline 3 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?

States a specific verb (report) and resource (the outcome of a run_flint_scout scan) and enumerates the four outcome values it accepts. It is immediately distinguishable from its closest sibling, run_flint_scout, which produces the record this tool consumes.

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 sequences the call: 'Use this tool after a run_flint_scout scan.' It then branches the authorization path, naming session_token for an account that owns the passport and caller_binding_token for anonymous callers, so the agent knows which credential to present and when.

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 only flag readOnly=false/destructive=true/openWorld; the description supplies the why — a credit is drawn per credit-path call and payment is taken on the x402 path — plus 402 challenge behavior, the pay_recipe fallback, conditional receipt issuance, and the explicit caveat that payment to FLINT is not proof of authority. That is materially more than the annotations convey.

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?

Purpose is front-loaded and the payment mechanics are ordered credits-first, then x402, then fallbacks. It is dense and somewhat long, with a few clauses ('no wallet signature for that call') that could be trimmed, but nothing is wasted given the absent output 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?

With no output schema, the description carries the return-side burden and does so: signed authority decision, conditional signed settlement receipt and durable URL, and the 402 pay_recipe shape. An agent has enough to call it, fund it, and interpret both success and failure.

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 88%, so the schema already documents session_token, payment_signature, nonce, and transaction fields in detail. The description's payment narrative mostly restates what session_token's own schema description says, adding only marginal relational clarity about the two paths.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence gives a specific verb and resource with timing: 'scan an intended agent transaction before execution.' That scope cleanly separates it from verify_agent_authority and report_scout_outcome, though no sibling is named 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?

It states when to use it (pre-execution) and lays out two mutually exclusive payment paths (prepaid credits via scout_credits_topup vs. per-call x402) with the exact triggering conditions for each. It does not compare against competing authority tools, so tool selection is still inferred.

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, so the safety profile is known. The description usefully adds the auth prerequisite (session_token from auth_verify_otp) and the scope/content of the ledger data returned, but says nothing about pagination, ledger window, or rate limits for what may be a large ledger listing.

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 tight sentences with the core purpose front-loaded and the prerequisite second. Efficient, though the second sentence largely restates what the schema already encodes about session_token.

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, the description carries the burden of describing returns, and it does so at a high level: balance plus recent topups, debits, and refunds. For a one-parameter read tool this is nearly complete, with only ledger scope/window left unspecified.

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% for the single parameter, and the schema already explains session_token's origin and pattern. The description's mention of the token adds provenance but no new format or constraint meaning 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?

The description gives a specific verb and resource: checks the signed-in account's FLINT Scout credit balance plus recent ledger activity, and enumerates the activity kinds (topups, debits, refunds). It is clearly distinct from the mutation sibling scout_credits_topup, but it does not explicitly name that sibling, so sibling differentiation is implied rather than stated.

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 implied (check the balance of a signed-in account) and the dependency on session_token from auth_verify_otp establishes a prerequisite. However, there is no explicit when-to-use vs. when-not guidance, nor a pointer to scout_credits_topup for adding credits, so an agent must infer routing.

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 supply the safety profile (destructiveHint=true, idempotentHint=false, openWorldHint=true), and the description adds substantial context beyond them: 24-hour intent expiry, $1.00=100 credits pricing, account binding via session_token, and two distinct payment paths. The one gap is that destructiveHint/idempotency implications (e.g. what happens on a failed or repeated payment) are not addressed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and dense with useful workflow detail, though it is comparatively long with several semicolon-joined clauses and an inline command. Every sentence conveys actionable information, so little is wasted despite the length.

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 mutation tool with no output schema, three params, and open-world payment behavior, the description covers prerequisites, both settlement paths, intent lifecycle, credit economics, and the follow-up call. An agent has everything needed to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. However, the description adds genuine semantics beyond the schema: it explains that omitting topup_id creates a fresh sct_ intent returning a pay_url, while passing topup_id retries that same intent rather than creating a new one, and it ties session_token to the credited account.

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+resource (top up FLINT Scout scan credits) and immediately distinguishes itself from siblings by naming run_flint_scout and scout_credits_balance workflows. An agent can tell exactly what this tool does and how it fits with adjacent 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?

Explicitly covers when to call (once, with session_token), the alternatives (pay the returned pay_url via awal/any x402 client vs. settle in-tool with payment_signature), prerequisites (auth_request_otp then auth_verify_otp), and the retry path via topup_id. It even states the downstream call (run_flint_scout with no payment_signature).

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?

Beyond the annotations (which already convey mutation, idempotence, and non-destructiveness), the description discloses auth-token requirements per ownership state, the exact scope of the mutation, and the backward-compatibility behavior where unknown action strings are kept but reported back as unknown. That is meaningful non-obvious behavioral context.

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 definition is long but front-loaded with purpose and every sentence carries operational content (scope boundaries, auth conditions, vocabulary, preset, error behavior). The long inline vocabulary list is dense but necessary given the schema exposes no enum.

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 mutation tool with a nested object parameter, no output schema, and no enums, the description covers scope, auth, vocabulary, and edge-case error reporting. It would be marginally stronger if it hinted at the shape of the response (confirmation fields, reported unknown actions) but is largely 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%, so the baseline is 3, but the description goes well beyond the schema by enumerating the allowed mandate vocabulary, documenting the ["ALL"] preset and its expansion/recording semantics, and clarifying how unknown strings are handled – the schema's mandate object is otherwise an opaque additionalProperties bag.

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 (update) plus a precisely scoped resource (mutable mandate config on an existing FLINT Agent Passport) and explicitly names what it is not (does not reissue the passport, does not re-sign identity). An agent can distinguish it from issue_agent_passport and claim_agent_passport from the text alone.

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 conditional guidance for auth: pass session_token when the passport is owned/claimed, management_token while unclaimed, plus the boundary that only actions, amount limits, and notes are updatable. It stops short of naming alternative sibling tools for adjacent operations (e.g. generate_authorization_scope), so a 4 rather than 5.

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 and openWorldHint, and the description adds concrete behavioral detail: compact JWS signature verification, expiration checking, and payload decoding. It does not describe return values or error behavior, but it adds meaningful operational 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?

A single sentence front-loads the usage trigger and then lists the core verification steps without filler. Every clause contributes useful 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 tool is read-only, has fully documented parameters, and the description supplies the business context and operational steps. The main gap is the absence of an output schema and no explicit statement of what the tool returns on success or failure, but enough is provided 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?

Schema description coverage is 100%, so the schema already documents all parameters. The description reinforces the purpose of expected_partner_id and expected_merchant_reference by referring to the decoded payload, but adds no new format or usage details 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?

The description names a specific verb ('verifies') and resource ('signed verification record from an agent'), and defines the trigger context: before payment or paid access execution. This clearly distinguishes the tool from issuer-oriented siblings like 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?

It explicitly states when to use the tool ('when a merchant or API seller receives a signed verification record from an agent' and 'before payment or paid access execution'). It does not name exclusions or alternative tools, but the context is clear enough to route an agent correctly.

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