Venture Foundry QA

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

Annotations already indicate non-read-only, non-destructive, and idempotent. The description adds important behavioral context: creating a quote does not create a transaction or move funds, and the quote is time-limited (ten-minute). No contradiction with annotations.

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

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

Three short sentences, front-loaded with the use case, and each sentence adds a distinct piece of information: when to use, what it does, and what it does not do. 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 a complex nested job schema and no output schema. The description explains the quote's purpose and side effects but does not describe the return value, how the quote is consumed by sibling tools like settle_checkout, or lifecycle expectations. Given the complexity, it is minimally adequate but not comprehensive.

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 only idempotencyKey with a description; buyerAddress and job lack top-level descriptions. The description indirectly references 'paying Base wallet' and 'exact content' to hint at the purpose of buyerAddress and job, but does not explain idempotencyKey or provide field-level guidance. This partially compensates for low schema coverage but leaves gaps.

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 creates a quote by validating a QA job and binding it to content and a Base wallet, with a specific verb ('bind') and resource. It distinguishes from siblings focused on reporting or checkout settlement, and clarifies the tool does not transact.

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 gives a clear when-to-use context ('Use before delivering a structured AI report...') and implies the quote precedes delivery. It does not explicitly name alternatives or when-not-to-use, but the usage scenario is unambiguous.

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, destructiveHint, and idempotentHint. The description adds value by stating 'cannot initiate payment,' which directly addresses potential confusion with payment siblings, and highlights the 'secret bearer token' for security awareness.

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 core action and parameters. No redundant wording; the second sentence adds a critical limitation without 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 2-parameter read tool with no output schema, the description covers what it does, the required inputs, and a key limitation. The workflow context (token from prepare_checkout) is provided in the schema for reportToken, rounding out the picture.

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 50% (only reportToken has a description). The description maps 'job ID' and 'secret bearer token' to the two parameters, giving semantic meaning to jobId and reinforcing the token's secrecy. This partially compensates for the missing jobId description in 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 'Read one settled report' with specific parameters (job ID and secret bearer token). It distinguishes itself from sibling tools by explicitly noting it cannot initiate payment, making it distinct from checkout workflows.

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 phrase 'settled report' implies usage after payment, and 'This tool cannot initiate payment' excludes payment-related use cases. While it doesn't name alternatives explicitly, it provides clear context that this is a read-only companion to the checkout flow.

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=false and idempotentHint=true. The description adds meaningful context: it reserves state, returns a single transfer boundary and token, and explicitly excludes signing/approving/submitting. This goes beyond annotations without contradicting them.

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 crisp sentences, front-loading the main action and then stating the critical boundary. No redundant words; every clause adds value.

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 the core purpose and non-behavior, and annotations help with safety and idempotency. However, since there is no output schema and the job parameter is highly nested, the description doesn't fully explain the return structure or the checkout flow relative to sibling tools, leaving some 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 description coverage is only 25% (only idempotencyKey has a description), and the tool description does not compensate. It doesn't explain quoteId, buyerAddress, or the job parameter's meaning, leaving the agent to infer them from the nested schema alone, which is insufficient.

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

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

The description uses a specific verb ('Reserve') and clearly names the resources involved ('unchanged quoted job', 'Base USDC transfer boundary', 'protected report token'). It differentiates this tool from siblings by emphasizing it prepares checkout without executing the transfer.

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 what the tool does not do ('does not sign, approve, or submit the transfer'), providing a clear when-not boundary. It implies this tool is used before settle_checkout but does not name any sibling tool explicitly, so it stops short of full alternative 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?

The description adds a specific safety boundary ('cannot move funds') and enumerates the exact information returned, going beyond the generic readOnlyHint/idempotentHint annotations. It does not contradict any annotation and provides behavioral context that isn't captured by 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?

Two sentences, front-loaded with the usage directive, and every clause adds value. It is concise and well-structured without 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 no output schema, the description compensates by listing all return categories (scope, price, schemas, examples, limitations, payment safety boundary, integration links). It also covers usage context and safety boundary, making the tool's behavior complete for an agent despite zero parameters.

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 zero parameters and trivial 100% schema coverage, the baseline is 4. The description needs no parameter explanation, and it correctly focuses on the output/behavior of a parameterless info query.

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 return specific pre-release QA info (scope, price, schemas, examples, limitations, payment safety boundary, integration links). The phrase 'Use this first...' and the explicit 'cannot move funds' distinguish it from the fund-moving sibling tools.

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

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

It gives explicit when-to-use guidance ('Use this first when an agent needs pre-release AI output verification') and an exclusion ('This tool cannot move funds'). While it doesn't name alternatives directly, the sibling context and 'use this first' imply a sequence, but exclusions are 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 already indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds valuable context by stating that no wallet transfer is created or repeated, and that it operates on an already-submitted transaction against a boundary. It does not disclose failure modes or detailed side effects, but the added constraint is meaningful.

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 the main action front-loaded ('Verify an already-submitted Base transaction...'). The second sentence states a critical limitation concisely. No fluff or redundant 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 description provides a clear high-level operation but does not specify the return value/output, error handling, or how the released report is delivered (e.g., whether get_report is needed afterward). With no output schema, this leaves ambiguity. It also assumes knowledge of 'prepared exact-payment boundary' without further explanation.

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 only 33% because only reportToken has a description; jobId and transaction are described only via patterns. The description does not explain jobId or the format/role of transaction beyond calling it a Base transaction, and it does not compensate for the low schema coverage. The reference to the 'prepared exact-payment boundary' adds a bit of context to transaction, but it is not enough.

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 verifies an already-submitted Base transaction against the prepared exact-payment boundary and releases its report. It also explicitly says it cannot create or repeat a wallet transfer, which distinguishes it from siblings like prepare_checkout and create_quote.

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 after prepare_checkout by referencing an 'already-submitted' Base transaction and a 'prepared exact-payment boundary,' and the schema's reportToken description mentions prepare_checkout. It also states a key exclusion: it cannot create or repeat a wallet transfer. However, it does not explicitly name sibling tools or state when to use get_report afterward.

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