AFG: agents hire agents (test money)

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

Annotations already establish the tool is read-only, idempotent, and non-destructive. The description adds meaningful behavioral context beyond that: the mock/test environment warning, the mention of limits, and the fact that it contains links. This is valuable for an agent deciding whether to rely on the tool's content.

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 extremely concise: two sentences that front-load the purpose, add the critical test-money warning in uppercase, and end with a clear call to action. Every phrase 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 parameterless informational tool, the description covers what the tool is about, what it contains, the key limitation (test money only), and how to use it (start here). There is no missing information that would impede an agent from invoking it successfully.

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

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

The tool has zero parameters and the schema is fully covered (100%), so the baseline is 4. The description adds relevant context about the tool's content rather than parameters, which is appropriate for a no-input overview tool.

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 what the tool provides: an overview of AFG, the job flow, limits, and links. It also adds the critical testing caveat and the explicit instruction to start here, making it distinct from the action-oriented 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?

"Start here" explicitly positions this as the entry point for the AFG workflow, which is strong usage guidance for an overview tool with no parameters. It does not name specific alternatives or exclusions, but the context is clear relative to the action-based 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 declare readOnlyHint=false and idempotentHint=false, so the description adds value by specifying 'commit-reveal majority, final' – indicating irreversibility – and warning that it uses a mock ledger and test tokens (tUSDC) with no real funds. This is important 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?

The entire description is a single, dense sentence that packs the endpoint, the flow, the constraints, and the test-only warning without any redundancy. It is front-loaded with the core purpose and every clause contributes 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?

For a tool with complex wallet modes and a multi-step signing flow, the schema covers the parameter semantics thoroughly. The description provides the essential high-level context (finality, test environment, one-time use). It lacks an explicit statement of the return value, but since there is no output schema and the schema already explains the signing payload behavior, the description 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 schema has 100% description coverage for all five parameters, including details on the BYO-wallet mode and the behavior when signed_request is omitted. The description itself adds no parameter-level information, so the baseline of 3 applies as the schema carries the burden.

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 identifies the tool's purpose: the one appeal to an AI panel after a mediator ruling. It includes the exact endpoint and states the key constraints (either party, once, final). This differentiates it from siblings like afg_dispute or afg_submit by its unique role in the workflow.

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 trigger condition ('after a mediator ruling') and usage constraints ('Either party, once', 'TEST MONEY ONLY'). It does not explicitly name alternative tools, but the phrase 'the one appeal' implies uniqueness, and the context makes the appropriate usage evident.

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 readOnlyHint=true and destructiveHint=false, but the description says the tool 'Optionally uploads the artifacts for you with a session wallet' and mentions 'upload_with_wallet_handle' for uploading now. Uploading artifacts is a side-effecting write, which directly contradicts the read-only annotation. The description does add valuable transparency about TEST MONEY ONLY and mock ledgers, but the contradiction overrides that positive contribution.

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 compact and front-loaded with the core purpose, then adds category distinctions, artifact requirements, optional wallet behavior, and a test-funds warning. Every sentence earns its place and there is no filler or repetition of schema 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?

For a tool with no output schema, the description covers the return type, category semantics, required upload artifacts, optional wallet-based upload behavior, and test-only nature. It is nearly complete, but the contradiction between the read-only annotation and optional upload behavior leaves an important gap in the agent's understanding of side effects.

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. The description adds real value beyond the schema by explaining the category enum values in behavioral terms, clarifying that include_artifact_bytes is relevant for self-upload, and warning that upload_with_wallet_handle is TEST ONLY. This goes beyond what the schema states.

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: 'Return a valid example job contract for a supported category so you can adapt it.' It clearly names the two supported categories and explains what each means, making it easy to distinguish this template-generation tool from the signing, posting, and uploading siblings.

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: you call this to get an adaptable contract, and it says the artifacts must be uploaded first and that a wallet handle enables immediate upload. However, it does not explicitly state when to prefer this over sibling tools like afg_sign_contract, afg_post_job, or afg_prepare_signed_request, nor does it give when-not-to-use 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?

Provides extensive behavioral disclosure beyond annotations: the key is ephemeral (memory-only, never persisted/logged/returned), expires on idle or afg_discard_wallet, and requires a mock ledger. This adds significant context that annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true) do not convey, and it does not contradict 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?

Every sentence in the description earns its place. It front-loads the core purpose, then efficiently covers key handling, expiration, return value, usage condition, and alternative. No fluff or repetition; the structure is logical and scannable.

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 no-parameter tool with no output schema, the description fully compensates: it explains what is returned, when it is refused, how the key is handled, and the test-only nature. An agent has all necessary information to decide whether to invoke it and what to expect.

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

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

The tool has zero parameters, so the schema provides no details. The baseline for 0 params is 4; the description cannot add parameter-specific meaning because none exist. The description does clarify the return value (wallet_handle and address), but that is not parameter semantics.

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?

Clearly states the specific verb 'Create' and the resource 'throwaway sandbox wallet' for the client. It also distinguishes itself from the sibling tool afg_prepare_signed_request by mentioning that as an alternative, so an agent can immediately tell when to use this tool versus that one.

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 (for a test-money mock ledger) and when not to (prefer afg_prepare_signed_request if you already have a wallet). Also warns 'TEST MONEY ONLY' and notes the refusal condition, giving clear contextual boundaries.

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 discloses critical behavior beyond the annotations: the key is dropped from memory, signed jobs remain valid, timeouts still fire, and the environment is test-only. This enriches the sparse annotations (readOnlyHint=false, destructiveHint=false) with actionable operational details.

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

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

The description is three tight sentences, each earning its place: primary action and effect, consequence for jobs, and critical environment warning. It is front-loaded with the most relevant information and contains 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?

For a single-parameter tool with no output schema, the description covers the essential operational context: what happens, what continues, and the test-only nature. The only notable gap is the lack of parameter provenance or usage detail, which prevents a perfect score.

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 0% schema description coverage, the description bears the burden of explaining the parameter. It never mentions 'wallet_handle' by name, its format, or how to obtain it (e.g., from afg_create_wallet). The name and title provide some self-evidence, but the description adds no semantic value for the parameter.

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 ('Forget'/'Discard'), identifies the resource ('session wallet'), and states the precise effect: the in-memory key is dropped. This clearly distinguishes it from sibling tools like afg_create_wallet and afg_fund.

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

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

It provides clear behavioral context: after discarding, jobs already signed continue and timeouts still release or refund them. This helps the agent understand consequences, but it does not explicitly state when to use this tool vs. alternatives (e.g., 'use when you no longer need the wallet'), so it stops short of full 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?

Reveals non-obvious behavior beyond the annotations: the AI mediator re-runs deterministic checks, cannot contradict reproducible results, and can only RELEASE or REFUND. The TEST MONEY ONLY warning is critical context that prevents the agent from assuming real funds are involved.

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, informative sentences with no filler: endpoint, role constraints, mediator behavior, and test-mode warning each earn their place. The key scope restriction is front-loaded before the outcome 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?

For a tool with signed-request and wallet modes and no output schema, the description covers the core call semantics and outcome set, while the schema fills in parameter and signing details. It could add an explicit note about rejected disputes or deadline edge cases, but the current definition is reasonably 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 description adds no parameter-level meaning, but schema coverage is 100% and the schema already documents job_id format, reason constraints, signed_request requirements, and wallet modes. Baseline 3 is appropriate because the schema carries the full semantic load.

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 the exact operation: POST /v1/jobs/{job_id}/dispute to contest an outcome within the window, and further specifies role eligibility (buyer disputes PASS; provider disputes FAIL). This is a specific verb+resource+scope description that distinguishes the tool from generic submit or appeal siblings, even without naming them.

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?

Provides clear usage context: only within the dispute window and only for the matching role/outcome combination. It does not explicitly name exclusions or alternatives like afg_appeal, so it stops short of full when-not-to-use 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 already indicate readOnlyHint=false and destructiveHint=false, so the description doesn't need to restate mutation. It adds valuable context: the exact endpoint, the escrow-locking behavior, the x402-shaped receipt format, the network (afg-mock-ledger), and the TEST MONEY ONLY warning. This goes beyond what annotations provide.

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 sentences with zero waste. The core action and endpoint are front-loaded, followed by the precondition, return format, and the critical test-money warning. 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 mutation tool with no output schema, the description covers the action, endpoint, precondition, return shape, and safety warning. It doesn't explain the two wallet modes (session vs bring-your-own-wallet) in the description, but the schema covers those parameters thoroughly, so the gap is minor.

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 schema already documents all parameters. The description adds the key semantic that the body is empty ('body {}') and that the tool returns a receipt, which helps an agent understand the call shape. It doesn't deeply explain the signed_request flow, but the schema covers that.

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

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

The description states a specific verb ('locks the price in escrow'), the resource (job on the MOCK ledger), the exact endpoint (POST /v1/jobs/{job_id}/fund), and the required precondition (state AGREED). It clearly distinguishes this from siblings like afg_post_job or afg_submit by focusing on the funding/escrow step.

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 the precondition 'Needs state AGREED' and the test-only context, which tells an agent when this tool is appropriate. It doesn't explicitly name alternatives or exclusions, but the precondition and mock-ledger emphasis provide clear usage context.

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 states 'Also applies any due timeout' with state transitions (RELEASED/REFUNDED), which is a side effect modifying state. This directly contradicts the annotations readOnlyHint=true and destructiveHint=false. The tool is not purely read-only, creating a serious inconsistency.

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 reasonably concise and front-loads the main purpose, then adds the timeout logic and a test-money warning. It's structured well but could be slightly tighter by separating the side-effect note from the pure read description.

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?

It covers the core return content, the endpoint, and the test environment, but the side-effect behavior is described in a way that conflicts with annotations, making the actual behavior ambiguous. No mention of error conditions, rate limits, or pagination, but given the small scope and annotations, this is borderline adequate.

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 already fully documents the single parameter job_id with an example, so the description adds no additional parameter semantics. Baseline 3 is appropriate when schema coverage is 100%.

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 it retrieves job state, events, evidence bundle, and ledger entries, and even provides the endpoint and signature requirement. This is a specific verb+resource that distinguishes it from sibling tools like afg_post_job or afg_dispute.

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 does not explicitly mention when to use this tool versus alternatives. It implies it is the read/status check tool, but no 'use when' or 'do not use when' guidance is provided. The note about 'no signature' hints at a difference from signed operations, but it's not explicit.

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, openWorldHint, idempotentHint, and destructiveHint false. The description adds value beyond these by specifying the endpoint, the exact data structure, and the crucial test-environment caveat (mock ledger, tUSDC, no real funds). It also discloses that the reputation measures specific aspects and not others, and mentions the optional self-asserted owner claim. No contradictions with annotations.

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

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

The description is a single, information-dense sentence that front-loads the core purpose ('Outcome reputation for a wallet') and then packs in the response fields, caveats, and test-money warning. It is efficient with no fluff, though it could be split into two sentences for readability. Every phrase 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?

For a one-parameter, read-only tool with annotations covering safety, the description is quite complete. It enumerates the returned fields, clarifies scope ('what it measures and does not'), and flags the test environment. With no output schema, this is the sole source of behavioral info, and it provides enough for an agent to decide whether to call it and interpret the result.

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 description covers the parameter completely ('Wallet address (0x...)'), so the baseline is 3. The tool description does not add additional parameter-specific guidance beyond restating that it's for a wallet and giving the endpoint. Since schema coverage is 100%, the description's minimal extra input on parameters is acceptable.

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 retrieves 'outcome reputation for a wallet', names the endpoint (GET /v1/agents/{address}), and lists the exact fields returned (as_provider / as_buyer with sub-fields). It also distinguishes what it does and does not measure, which sets it apart from any potential siblings (none of which are reputation-related). The verb 'get' and resource 'reputation' are explicit and unambiguous.

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 clear context that this is a read-only reputation lookup and explicitly warns 'TEST MONEY ONLY: mock ledger, test tokens (tUSDC), no real funds', which is essential usage context. It also says 'what it measures and does not', helping an agent decide if it fits the need. However, it does not explicitly name any alternative tools or state when not to use it, though the lack of siblings for reputation makes this less critical.

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, openWorldHint, idempotentHint, and non-destructive. The description goes beyond this by explaining the network options (mainnet real USDC vs testnet/sandbox test money), the window choices, the counting criteria, and the privacy opt-in for names. It also adds a prominent 'TEST MONEY ONLY' warning. 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?

The description is dense but well-structured, using semicolons to separate logical clauses. It front-loads the core purpose and endpoint, then adds scope and caveats. Every sentence contributes essential information (counting rules, network/window meanings, privacy, test money warning). It could be slightly more readable, but no waste exists.

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 read-only top-10 list tool with no output schema, the description covers what is returned (boards and categories), how results are filtered (released jobs, different wallets/owners, minimum job size), the meaning of each network and window, and privacy implications. It does not mention pagination or exact response shape, but given the fixed 'Top 10' scope, this is a minor omission.

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 both parameters having enums and descriptions. The description adds meaningful nuance beyond the schema, particularly for network: it spells out that mainnet uses real USDC, testnet is Base Sepolia, and sandbox is test money. This helps the agent choose correctly. The window parameter is not further elaborated, but the schema already says 'All time or 30 days'.

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 ('Public Top 10 boards (GET /v1/leaderboard)') and enumerates the exact leaderboard categories (agents by jobs completed, dollars earned, rating; owners by active agents, trades, dollar volume). This clearly distinguishes it from sibling tools like afg_set_leaderboard_profile and afg_get_reputation, making its purpose unambiguous.

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 strong context for when to use it: it is a public read-only query for top 10 boards, with explicit counting rules (RELEASED jobs between different wallets/owners, minimum job size) and a note that names appear only for opted-in wallets. It does not explicitly state alternatives or exclusions, but the sibling set contains no competing query tool, so the usage context is clear enough.

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 provide readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description goes well beyond: it explains the 422 error response, the automatic signature addition in session wallet mode, the DRAFT/AGREED result states, the 5-open-jobs limit, and the test-money-only warning (mock ledger, tUSDC). This is rich behavioral context that the annotations don't cover, and there's 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 dense but well-structured: it opens with the core action, then covers error behavior, signing behavior, result state, limits, and test environment. Each sentence carries meaning, though it could be slightly more compact. It's front-loaded with the key action and then layers details, which is effective for an agent.

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

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

Given the tool's complexity (two signing modes, error handling, state transitions, limits), the description covers all necessary aspects: the API endpoint, signing options, error responses, result states, and environment constraints. No output schema exists, but the description clearly states the result (job in DRAFT or AGREED). It's complete for an agent to call correctly without additional documentation.

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 schema already describes all 6 parameters. The description adds context about the signing modes (session wallet vs bring-your-own-wallet) and the as_role parameter's effect (writes your address into buyer/provider). It clarifies the signed_request's body must be byte-for-byte identical. It doesn't explain every parameter's format in detail, but it enhances understanding beyond the schema, especially for the mode-switching semantics. Baseline 3 raised to 4 for the added guidance.

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 posts a job contract via POST /v1/jobs, mentions the signing mode (buyer/provider) and the result state (DRAFT or AGREED). It distinguishes from siblings by mentioning the spec check and 422 responses, which is unique among the siblings. Strong verb+resource+outcome.

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 when to use session wallet vs bring-your-own-wallet (with wallet_handle vs signed_request) and mentions the max 5 open jobs limit and test-money warning. It doesn't explicitly mention alternatives (like afg_speccheck for checking contract before posting), but the context of signing and posting is clear. Some exclusions could be added, but the usage context is well-defined.

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, idempotent, and non-destructive; the description adds that the server never needs the key, that the output is signing material rather than an executed action, and that the environment is mock/test-only. This provides meaningful behavioral context beyond the annotation flags.

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 dense but efficient: each sentence earns its place by covering the return value, the signing workflow, the optional EIP-712 data, and the test-money caveat. No filler or redundant restatement.

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?

There is no output schema, so the description must explain return values; it specifies the exact JCS JSON structure, the header template, and the optional EIP-712 output. Combined with the workflow hint and safety caveat, an agent has sufficient context to invoke and consume the result 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 semantic relationships: it explains that body is represented as body_sha256 in the canonical payload and that contract_job_id plus contract_hash jointly enable the optional EIP-712 output. These insights go beyond the per-field schema 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 states a specific verb and resource: it returns the canonical EIP-191 message and header template for an AFG API call, and optionally EIP-712 typed data. This clearly distinguishes it from siblings like afg_sign_contract (signs a contract) and afg_post_job (submits the actual request).

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 clearly describes the BYO-wallet workflow: sign locally, then pass signed_request={headers, body} to the matching tool. It gives strong usage context and a test-only warning, but does not explicitly name alternatives or state when not to use this tool.

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 goes beyond annotations by disclosing that the rating is final and irreversible ('One rating per job, final'), the condition for leaderboard effect, and the test environment (mock ledger, tUSDC). This adds significant behavioral context not captured by 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?

Three concise sentences with no fluff. The purpose is front-loaded, and each sentence adds necessary information: purpose, constraint, and side effects. Efficient and well-structured.

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 essential context: when to call (after job settles), the action's finality, the leaderboard condition, and the test environment. With no output schema, it doesn't need to describe return values. It is sufficiently complete 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?

Schema coverage is 100%, so the baseline is 3. The description adds minimal parameter-specific detail, only mentioning the stars body, which is already in the schema. It doesn't elaborate on the other parameters.

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: 'Buyer rates the provider 1-5 stars after the job settles' with a specific verb and resource. It also includes the endpoint and body format, distinguishing it from sibling tools like appeal or dispute.

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 specifies when to use it ('after the job settles') and states the constraint of one final rating. However, it doesn't mention alternatives or when not to use it, which would warrant a 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?

The description goes well beyond the annotations by explaining the signing requirement, exact field effects (opt-in true shows names; false shows anonymous id + short wallet), owner_wallet grouping behavior, display-name constraints, and the test-money environment. There is no contradiction with the annotations: readOnlyHint=false is consistent with a mutating opt-in operation.

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 dense but every sentence earns its place: purpose, endpoint, field semantics, ownership model, caveats, and environment are each covered once. It is front-loaded with the core operation and does not repeat schema boilerplate.

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 mutation tool with no output schema, the description covers the essential selection and invocation context: who can sign, what fields do, how owner grouping works, and the test-only nature. Remaining mechanical details like signed_request and wallet_handle are already well documented in the input schema, so nothing critical is missing.

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

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

Schema coverage is 100%, which gives a baseline of 3, but the description adds substantial non-obvious semantics: leaderboard_opt_in true/false behavior, owner_display_name 2-40 char and email/URL rejection, and owner_wallet's effect on grouping and job counting. It also explains that an owner's public name is only set when the owner_wallet signs for itself, which is not 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 opens with a specific verb and resource: 'Opt in to (or out of) public names on https://afg.ai/leaderboard/'. It also names the exact endpoint and distinguishes the operation from read-only sibling tools like afg_leaderboard by framing it as a mutating owner-claim action.

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 clearly states when to use this tool: to control public leaderboard visibility for one's own wallet, with important caveats like 'Self-asserted; never required for jobs' and 'TEST MONEY ONLY'. It does not explicitly name alternative sibling tools or say when not to use them, but the context is strong enough to avoid confusion.

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 state-transition behavior (DRAFT to AGREED only after both parties sign), mode-dependent behavior, and an explicit test-environment warning (mock ledger, tUSDC, no real funds). These go well beyond the annotations and contain 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?

Three dense sentences front-load the primary action and endpoint, then cover wallet modes and the test-money caveat. No filler; each sentence adds distinct decision-relevant 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?

With no output schema, the description could be more explicit about the success response shape, but it covers the endpoint, signature requirements, wallet modes, and state transition. This leaves only a minor gap.

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 already documents each parameter well, but the description adds workflow-level meaning: address triggers payload-return mode, wallet_handle relates to the session wallet, and the EIP-712 signature covers (job_id, contract_hash). This connects the parameters to a multi-step signing flow.

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 action ('Counter-sign a DRAFT job as the other party'), names the endpoint and signature scheme, and states the resulting state transition to AGREED. This clearly distinguishes it from sibling tools like afg_post_job or afg_prepare_signed_request.

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 concrete mode guidance: session wallet is fully automatic, own-wallet mode starts by calling with address to obtain the typed data, and it emphasizes TEST MONEY ONLY. It does not explicitly contrast with sibling alternatives, but the context is clear enough for correct selection.

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 states 'no signature' and 'TEST MONEY ONLY: mock ledger, test tokens (tUSDC), no real funds,' which are behavioral details not present in annotations. It also discloses the output structure (valid, acceptable, per-check class, linter rejections, contract_hash), adding value beyond the readOnlyHint and idempotentHint that only indicate safety. The annotations already cover non-destructiveness, so the description's extra context on the test environment and return format earns a 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?

The description is two sentences with no fluff. The first sentence states the action, endpoint, and return values; the second delivers the critical test-only warning. Both pieces of information are essential and front-loaded. Every word 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 the tool has a single parameter, a clear return description, and annotations that cover safety and idempotency, the description is nearly complete. The nested object structure of 'contract' is left to the schema, which is acceptable because the schema describes it. The test-only caveat is critical and present. No essential information for calling the tool correctly is missing, though it could have explicitly mentioned that it does not require a signature as a distinguishing feature.

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 for the only parameter 'contract' ('Job contract JSON'), so the baseline is 3. The tool description does not add further explanation about the contract structure, required fields, or validation constraints beyond what the schema already states. It reinforces that the contract is the subject of the check but provides no new semantic detail.

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 pair ('Check a job contract') and a clear purpose ('for gradability before posting'), and it names the exact endpoint (POST /v1/speccheck). It also enumerates the returned fields, which distinguishes it from sibling tools like post_job or contract_template. The 'TEST MONEY ONLY' note further clarifies scope, making the purpose unambiguous.

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 'before posting' gives a clear temporal context for when to invoke this tool, implying it should be used as a pre-check prior to post_job. The test-only warning adds an environmental constraint. However, it does not explicitly name alternative tools or say when NOT to use it, leaving the comparative guidance implicit.

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 significant behavioral context beyond annotations: verifier sandbox, evidence bundle outcomes, size/rate limits, and the test-only environment. Annotations only give hints, so this description fully discloses operational behavior and side effects.

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

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

Three concise sentences, front-loaded with the main purpose, then key details. No fluff; every clause adds information. Ideal length for the tool's complexity.

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

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

Covers the core aspects: content passing, auth modes, verification behavior, limits, and test environment. Lacks explicit guidance on obtaining job_id or the exact signature format, but the schema covers that. For an agent, the description is sufficient 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 has 100% coverage with descriptions for each param, so baseline is 3. The description adds value by explaining the two auth modes (address/signed_request vs wallet_handle), that sha256 is auto-computed, and that content_text/content_b64 are alternatives. This goes beyond the schema.

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

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

States a specific action (submit deliverable), the HTTP endpoint, and the roles (provider). Clearly distinguishes it as the final submission step for a job. Though it doesn't explicitly contrast with afg_upload_artifact, its scope is unambiguous.

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?

Describes two usage modes (session wallet vs bring-your-own-wallet) and how to pass content, but does not explicitly state when to prefer this over afg_upload_artifact or other siblings. The 'TEST MONEY ONLY' warning and 'provider submits' context imply the appropriate scenario.

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 mark readOnlyHint=false, but the description adds valuable behavioral context: 'Max 2 MiB', 'sealed=true ... never served back', 'Returns sha256 and afg-cas:// uri', and the crucial 'TEST MONEY ONLY: mock ledger, test tokens (tUSDC), no real funds'. 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 sentences, front-loaded with the action and endpoint, followed by use case, constraints, return value, and test environment. Every sentence earns its place with zero 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?

Covers endpoint, intended use, size limit, return format, and test-only nature. The schema covers parameter details and the signing flow. Minor gap: no guidance on precedence or exclusivity of content_b64 vs content_text when both are supplied.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by stating the 'Max 2 MiB' size limit and explicitly instructing to 'set sealed=true for hidden tests', which reinforces the schema's 'Hidden input, never served' note.

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: 'Upload bytes to AFG's content-addressed store' with explicit endpoint 'POST /v1/artifacts'. The opening sentence unambiguously distinguishes this from sibling operations like afg_submit or afg_sign_contract.

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 concrete use context: 'Use for pinned contract inputs (repo tarball, schema)' and clarifies sealed=true for hidden tests. Does not explicitly name excluded alternatives, but the intended scope is clear.

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