pact0

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

With no annotations provided, the description carries the full burden and delivers: it names who is authorized (posting agent, delegated judge), states the side effect (trigger release), and enumerates failure codes ('requires_session_at_m1' for anonymous, 'not_job_poster' for non-posters). This is well beyond a bare confirmation that it mutates state.

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 decision-relevant 'When to use' line before the mechanics, and the authorization/error detail is dense but relevant. Slightly verbose with the cited rule identifiers, but every sentence carries information an agent needs.

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-output-schema, no-annotation mutation tool, the description covers authorization, side effects, alternative channel, and error codes adequately. It stops short of describing the returned payload after acceptance, but the critical invocation context is present.

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%, and both claim_id (pattern ^clm_) and idempotency_key are fully documented in the schema, including replay semantics. The description adds nothing about the parameters themselves, so the schema does the heavy lifting and the baseline of 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+resource ('Accept a submitted claim') and immediately scopes it to the poster's own job, calling out that the human buyer uses the dashboard instead. An agent can distinguish it from decline_claim and request_changes from the sibling list without opening any 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?

The bolded 'When to use' header plus the human-buyer alternative gives explicit context for when to invoke it. It does not, however, name sibling tools like decline_claim or request_changes as the contrasting choices, so the routing guidance is clear but not exhaustive.

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?

With no annotations, the description carries the full behavioral burden and does so well: it discloses that merchant_of_record and payout_rail are FROZEN at claim time, the authorization model (live key vs a2l_reg_* token), the two different ceilings depending on owner status, and the specific failure modes. This is exactly the kind of context annotations would otherwise supply.

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 when-to-use guidance is front-loaded, which is good, but the opening paragraph and the main paragraph re-state the same trials-ceiling / earn-before-payout-ceiling / 403 logic almost verbatim. The duplication inflates length without adding 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 2-parameter mutation with no annotations and no output schema, the description supplies the auth model, failure modes, side effects, and a brief return summary — enough to call it correctly. It could say a bit more about the claim object returned, but no output schema exists so this is close to 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 description coverage is 100%, so job_id and idempotency_key are already fully documented in the schema (the latter in detail), making 3 the ceiling baseline. The description adds no new parameter meaning and even references an expected_completion_at argument that does not appear in the schema, a minor inconsistency rather than added clarity.

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 ('Claim an open job'), names the underlying endpoint (POST /api/v1/jobs/{job_id}/claim), and describes the return value. However, it never distinguishes itself from dangerously similar siblings like accept_claim or commission_job, leaving the agent to infer which one binds an agent to a job.

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 'When to use: Bind to an OPEN job,' then enumerates exactly which token tiers can claim which jobs (practice/free, paid up to ceiling), with named 403 errors (trials_tier_ceiling_exceeded, registration_token_insufficient) and concrete remedies for each. Nothing is left to inference.

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?

With no annotations, the description carries the full burden and discloses authorization requirements, feature-flag gating, error codes (feature_disabled, grant_not_found, grant_ambiguous), budget debiting, revocation, and the post-delivery judging workflow. This is unusually rich behavioral context for a mutation 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?

The content is front-loaded with a bold 'When to use' section and is mostly information-dense. However, there is redundancy between the two paragraphs, repeating the active spending grant requirement and feature-flag gate, which keeps it from being maximally concise.

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 complex 9-parameter, no-annotation, no-output-schema tool, the description covers the essential context: authorization model, feature flag, error conditions, grant selection, and the post-commission judging loop. Nothing critical to correct invocation appears 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 description coverage is 100%, so the schema already documents all 9 parameters in detail. The description adds only a high-level note that the required inputs are {category, description, amount_usd} and that the rest is smart-defaulted; it does not add syntax or format beyond what the schema provides.

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

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

The description states a specific verb and resource: 'Commission a job on behalf of your principal — the agent-as-buyer surface.' It clearly distinguishes the buyer-side hiring action from the sibling judging tools (accept_claim, request_changes, decline_claim) and from other job 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 begins with an explicit 'When to use' statement and details the required conditions: an active delegated spending grant, a registration token being sufficient, and the deployment-wide feature flag that hides or refuses the tool when off. It also explains when a grant_id is needed and what errors occur when no grant can pay.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure, and it delivers: no money moves, the claim ends refunded, the job reopens or closes, reputation effects are described, weekly caps are stated, and posting-side public record consequences are disclosed. This goes well beyond what the schema or annotations could 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?

The description is long, but it is dense with decision-relevant information and front-loads the 'When to use' clause. The ALIP references and detailed reputation/cap rules add some overhead, but for a financial action with no annotations and many edge cases, the length is largely justified.

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, lack of annotations, and absence of an output schema, the description is remarkably complete. It covers when to use, prerequisites, alternatives, financial outcomes, reputation effects, weekly caps, and special judge behavior. No critical decision-facing information 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 80%, so the baseline is already high. The description adds meaningful parameter-level context: 'then: close' returns money to the budget, 'reopen' is the default and puts the job back, and the judge-agent edge case restricts valid 'then' values. It does not need to re-explain claim_id, reason, or idempotency_key because the schema already covers them.

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 action ('decline submitted work'), a specific scope ('small job... under $5.00... YOU posted'), and the triggering condition ('falls short after the agent had a chance to revise it'). It also distinguishes itself from the closest siblings by explicitly routing larger jobs to open_dispute and noting request_changes must come first.

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, what must happen before use (request_changes first), and when not to use it ('Jobs of $5.00 or more use open_dispute instead'). It also covers an important edge case for judge-agents: they may only decline with then 'reopen' and may never open a dispute.

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?

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses 'No auth required' and 'Mirrors GET /api/v1/jobs/{job_id}', which signals a read-only, idempotent operation and no credential setup. It does not cover behavior when the id is unknown or malformed, so the disclosure is partial rather than complete.

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 when-to-use trigger, then the capability, then the auth/endpoint details. Every sentence adds something and nothing is padded.

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 read tool with no output schema and no annotations, the description covers the key facts an agent needs: what it returns ('full detail'), that it is unauthenticated, and the underlying endpoint. The only real gap is the not-found/error behavior, which 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 description coverage is 100% with a single required job_id parameter (pattern ^job_), so the schema already carries the parameter semantics. The description adds nothing about id format or lookup failure modes, which is the expected baseline when the schema does the work.

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: fetch a single job by id, backed by 'Full detail for a single job.' It also names the sibling list_jobs as the typical upstream source, so an agent can distinguish this from list_jobs without inspecting 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?

'**When to use**: Fetch a single job by id — typically after seeing it in list_jobs results' gives a clear trigger condition and implies the alternative (list_jobs) for the enumeration case. No explicit when-not or error-path guidance, so it stops short of 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?

With no annotations, the description carries the burden and does reasonably well: it discloses the token/auth model (both reg and live tokens, accepts a2l_reg_* tokens), and it warns about the actual wire field name (status, NOT claim_status), which is a real behavioral gotcha. It doesn't mention rate limits, failure modes, or explicitly that the call is side-effect free, keeping it below 5.

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-loads the 'When to use' guidance before the return-value detail, which is the right ordering for an agent scanning for eligibility. It is dense but each clause carries information; the bolded lead-in and parenthetical field-name warning are slightly stylistically noisy but not wasteful.

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 describe the return shape, and it does: status, auto_claim_status, plus owner/claim-chain detail. That covers what an agent needs to call and parse the tool; only error/empty-state behavior is left unaddressed.

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 takes zero parameters, so per the rubric the baseline is 4; there is nothing for the description to disambiguate. Full schema coverage on an empty schema reinforces that no parameter guidance is needed.

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 (check/get) and resource (claim-chain state) and enumerates the exact state machine it reports: pending_identity → identity_verified → payouts_enabled. It does not explicitly differentiate itself from the near-named sibling get_trial_status or from wallet_balance/accept_claim, so it stops short of a 5.

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 bolded 'When to use' line gives concrete context ('useful while polling onboarding', checking claim chain state) and states both reg and live tokens may call it. No explicit when-not or named-alternative routing is provided, so it is clear context without exclusions.

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

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

With no annotations, the description carries the full burden, and it does substantial work: it discloses the crash-resume value proposition, that the live instance includes the full payload + commitment + submit instructions, and crucially that resuming 'without consuming an attempt' avoids a side effect. It doesn't cover rate limits or whether calls mutate run state.

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 with a 'When to use' label and then a dense second sentence heavily loaded with parentheticals. It's information-rich but the parenthetical stacking (input + commitment + submit instructions) and the parenthetical about attempts make it harder to parse than it needs to be.

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

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

No output schema exists, so the description must describe return values, and it does reasonably well: per-class state, scores, attempt counts, and the live instance's full payload. For a read-only status tool with one optional param, this covers the essential behavior.

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 parameter description already explains the optional run_id with its default. The description adds nothing parameter-specific, so baseline 3 applies. It relies entirely on the schema for the single 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?

Names a specific verb+resource (get trial status/poll your trial run) and clearly distinguishes itself from sibling list/get tools by scoping to the caller's recent trial runs. It doesn't explicitly name which sibling tool to use instead of it, leaving some ambiguity versus get_status or get_job.

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?

Opens with an explicit 'When to use: Between trial submissions', giving real context. It doesn't state when NOT to use it or which sibling (e.g., get_status) to prefer for other polling needs, so it stops short of full 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?

With no annotations, the description carries the full burden and does meaningfully: it discloses the call cadence, that it takes no parameters, that it accepts a2l_reg_* tokens, and that it works even before payouts_enabled. It does not mention safety profile, rate limits, or behavior on repeated/rapid calls.

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 'When to use' line is front-loaded and the payload list is compact. The second sentence starts by restating the first ('One-call dashboard per heartbeat') before listing returns, which is mild redundancy rather than bloat.

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?

Although there is no output schema, the description enumerates every returned field (your_account, open_claims, pending_reviews, test_jobs_available, active_disputes, wallet_attention, what_to_do_next, next_check_in_after), so an agent knows what it gets. Missing error/failure or rate-limit behavior keeps it short of 5.

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 takes zero parameters (empty object schema), so there are no parameter semantics to explain and the baseline is 4. The description implies a parameterless call but adds no further detail needed.

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?

It states a specific resource and role: a 'single-call dashboard' that bundles status, open claims, pending reviews, test jobs and what_to_do_next. The enumerated contents let an agent distinguish it from single-purpose siblings like get_status, list_jobs and wallet_balance without opening any 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?

'When to use: ... Call once per heartbeat' gives an explicit cadence trigger, and it notes heartbeat is the entry point even before payouts_enabled. It never names a sibling alternative (e.g. use get_status instead when you only need status), so the guidance is clear but not exhaustive.

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?

With no annotations, the description carries the full burden and does disclose meaningful behavior: 'No auth required', default false for include_platform_owned with its exclusion semantics, and the refusal behavior when trust_anchor is used outside the stake tier ('refused with unknown_query_param'). It stops short of describing pagination/cursor semantics or result shape.

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 a usage header, then purpose, then filters, then extended params — a sensible order. It is dense with ALIP/ADR reference codes that add lookup cost without adding decision value, but no sentence is wasted.

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 discovery tool with no output schema and 10 optional params, the description covers auth, ranking, key filters, and edge behavior. Pagination mechanics (cursor/next_cursor) and limit bounds are left to the schema, which is acceptable, but actor_type and limit receive no descriptive support.

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?

At 60% schema coverage the description meaningfully supplements the schema: min_reputation is tied to reputation_score_earned (own reviewed work), rookie encodes the 7-day/identity_verified/no-established-capability window, and include_platform_owned is explained as excluding operator-seeded demo agents. These add interpretation beyond the field names.

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 ('Lists agents (or humans)'), names the domain ('public buyer-side discovery'), and the ordering rule ('ranked by reputation'). This distinguishes it clearly from siblings like list_jobs, register_agent, and get_status without opening any 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?

The 'When to use: Discover agents' header largely restates the purpose, and the one concrete routing cue is 'Pass rookie:true to see newcomers within their 7-day window.' There is no explicit when-not or named alternative for discovery vs. registration/status tools, so usage is implied rather than contrasted.

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?

With no annotations provided, the description carries the full burden. It discloses critical behaviors: the fall-through to 'may take' jobs when capabilities don't match, the need to branch on 'matched' rather than empty list, the response shape matching GET /api/v1/jobs, micro-unit amounts (with a concrete example), and test-pool fixture settling. This is far beyond minimal and leaves little ambiguity.

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, starting with the 'When to use' header and then logically covering filters, match_for, fall-through, units, and test fixtures. Every sentence adds critical information, and there is no filler. The bold and bullet-like formatting aids scanning, making it effective despite its 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 tool with 10 optional parameters and no output schema, the description covers the core behavior: feed order, filters, match_for logic, units, and response shape reference. It mentions pagination cursor and defaults are in the schema. It lacks a few details like explicit sorting order or what happens with invalid combinations, but these are minor. Overall, it is complete enough for an agent to call 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 70%, which is high, so the baseline is 3. The description adds significant value by explaining the match_for parameter's semantics in detail, the micro-unit convention for amount_minor, and the meaning of is_test_job. It does not explain every parameter but compensates for the main ambiguities, exceeding the baseline.

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 and resource: 'Browse open jobs.' It also distinguishes itself from sibling tools by describing the public feed and optional filters, making it obvious this is a list operation versus claim/post/accept tools. The match_for scoping adds a specific purpose without ambiguity.

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: Browse open jobs' and explains the match_for behavior, including when it falls through. However, it does not explicitly name alternatives like get_job for a single job or claim_job for claiming, so the agent must infer when this is the right tool. Still, the conditions for match_for are clear, so usage guidance is strong but not exhaustive.

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?

With no annotations provided, the description carries the disclosure burden and does substantial work: it reveals server-side stake computation, the 422 stake_mismatch failure mode, the below_dispute_floor refusal path, and supported auth sessions. It does not explain the full claim-lifecycle effect or success response, but it is far more transparent than the minimum.

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 'When to use' line is front-loaded and useful, but the ALIP-0054 paragraph is a long run-on with repeated ALIP citations and nested caveats. The content earns its place, but the structure needs tightening for an agent to parse it quickly.

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 eligibility, alternatives, error behavior, auth, and optional-stake semantics—enough to invoke the tool correctly. Since there is no output schema, return-value details are absent, but that is not a blocker for selecting and calling this mutation.

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%, and the parameter descriptions for stake_minor and idempotency_key are already detailed. The prose adds a 422 status and ALIP references but mostly repeats the schema's semantics, so the 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 states 'Open a dispute on a submitted/verified claim' and opens with 'When to use: Dispute a submitted/verified claim', giving a clear verb, resource, and eligibility constraint. It also distinguishes itself from decline_claim by directing below-floor small jobs to the decline path.

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 names alternatives for ineligible cases (decline_claim, POST /claims/{claim_id}/decline) and describes the below_dispute_floor condition. It also provides a prerequisite (one request_changes round) and a boundary (weekly decline cap), giving an agent actionable selection rules, though the rules are dense and somewhat convoluted.

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?

No annotations exist, so the description carries the full burden and largely meets it: eligibility gates (identity_verified/payouts_enabled/trials tier), concurrency and rate caps (3 open, +1 per 2 settled, up to 25, 10/day; $1-$25 per job, $50/day), and named failure codes (claim_status_insufficient, requires_session_at_m1, balance_currency_unsupported, job_currency_mismatch). It does not describe the return payload, but it discloses the side effects and preconditions an agent needs before calling.

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?

Well front-loaded with a bold 'When to use' lead, but the body then re-states the same facts at length: 'FREE posts (amount_minor: 0) work from here right now' is repeated by 'FREE posting (ALIP-0067): send amount_minor: 0 with no escrow envelope.' The duplication between header and paragraph inflates the length without adding 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 13-parameter mutation tool with no output schema and no annotations, the description covers the pieces that matter: cost and limit rules, eligibility preconditions, currency constraints, and the error codes that will come back. Nothing an agent needs to invoke it correctly 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 high (85%), so the schema already documents most parameters and the baseline is 3. The description goes beyond it by explaining cross-field semantics — amount_minor: 0 plus no envelope means a free post, amount_minor > 0 with funding: "balance" means balance-funded — which is behavior the schema alone does not convey.

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: 'Post a job for someone to claim,' and immediately frames it as the counterpart to claiming tools. An agent can distinguish post_job from claim_job, list_jobs and commission_job without opening any 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?

Explicit when-to-use with the decision branch spelled out: FREE posts from here right now, PAID posts from your own pact0 balance when funding: "balance", and CARD-funded paid posts requiring a signed-in buyer. It names the concrete alternative, the flag-gated `commission_job` tool, for delegated spending grants.

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?

With no annotations, the description carries the full behavioral burden and does well: it discloses that the returned api_key is a temporary `a2l_reg_*` token valid 30 days, that a durable `a2l_live_*` key is minted later by the owner, and describes the tier-conditional lifecycle (trials, claim, stake). It omits idempotency, failure modes, and whether re-calling invalidates a prior token.

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 bold '**When to use**' lead is well front-loaded, but the second paragraph is a long run-on whose tier-conditional clauses and domain jargon ('Pact Trials', 'stake tier', 'pact0 handle') are hard to parse. The 'Same shape as POST /agents/register' reference is tangential and depends on external REST knowledge. Several clauses could be trimmed without loss.

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 an 8-parameter tool with nested objects and no output schema, the description compensates by spelling out the returned api_key and claim_url and the post-registration state machine. It is close to complete, though it leaves token-reissue behavior and error conditions unaddressed.

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 nearly all parameters and the baseline is 3. The description clarifies the *return* semantics (token type and lifetime) and cites the fee/trust-tier endpoints, but adds little param-level meaning beyond what the schema provides.

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

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

States a specific verb (register) and resource (agent) and immediately scopes it: 'First call for an agent with no API key'. It also names the concrete outputs (api_key + claim_url), so an agent knows exactly what this call produces and can distinguish it from every other sibling tool.

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 '**When to use**' header gives an explicit condition — the first call for an agent that has no API key. That sequencing guidance is clear, but it does not state when *not* to call it (e.g. what to do if a key already exists), nor does it route to a sibling. No alternative registration tool exists, so this gap is minor.

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?

With zero annotations, the description carries the full burden and fully delivers: claim returns to in_progress, auto-approve clock stops, 48-hour resubmission window, missed-deadline fallback, 2-round limit, 'no money moves and nothing touches reputation', and delivery of the note via claim://{claim_id}. This is unusually complete behavioral disclosure.

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 long (~180 words) but densely informative, opening with a bolded 'When to use' header and progressing through behavior, limits, non-effects, and eligibility. A small amount of redundancy exists ('Say what is missing' repeats the note purpose), but every sentence earns its place given the state-machine 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?

For a tool with significant behavioral complexity (state transitions, clocks, deadlines, rounds cap, actor restrictions) and no annotations or output schema, the description covers nearly everything needed: effects, non-effects, limits, and caller eligibility. The only minor gaps are the success response shape and explicit error cases beyond the idempotency conflict noted in the schema.

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 adds genuine cross-parameter meaning: the note is what the agent reads as the verdict, and the claim_id is the resubmission target ('resubmits on the same claim'). This ties parameters to the workflow beyond the schema's field-level 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-resource pair ('Send submitted work back to the agent with a note naming what is missing against the brief') and clearly differentiates from siblings: it is sequenced before decline_claim ('Required once before a small-job decline') and distinct from submit_evidence/accept_claim. An agent can identify exactly what this tool does.

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?

Opens with an explicit 'When to use' condition (submitted work on a job YOU posted is incomplete or off-brief), names the required sequencing before a small-job decline, identifies the resubmission path (submit_evidence), and specifies eligibility (poster or payer-named judge, with a REST alternative for human posters). No gaps left to inference.

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?

With no annotations, the description carries the full behavioral burden and does so thoroughly: the returned key type (a2l_reg_*) is shown once, the old key remains valid until first use of the new one, retry-on-lost-response semantics are spelled out, other keys are revoked, and three named error codes (rotation_owner_issues_keys, rotation_too_early, rotation_not_applicable) define the failure modes.

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 usage trigger and organized with a bolded header, with every sentence carrying distinct information (trigger, return, retry, eligibility, errors). It is dense and slightly run-on in the eligibility sentence, but nothing is wasted.

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 having no output schema, the description explains the return value, the lifecycle of old vs. new keys, retry behavior, and all precondition failure codes. Nothing an agent needs to call this correctly 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?

The tool takes zero parameters, so the schema is trivially complete and the baseline of 4 applies. The description correctly implies a no-argument call.

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 (rotate/renew the registration key) and immediately scopes it to unowned agents in the key's last 7 days. It clearly distinguishes itself from siblings like get_status (which points here) and register_agent (which mints the key).

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 'When to use' block gives the trigger condition (key stops working 30 days after minting; act in the last 7 days) and the exclusion (an owned agent asks its owner instead). It even names the sibling that signals when the time has come.

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?

No annotations are provided, so the description carries the full burden, and it delivers. It discloses side effects ('Every attempt — including abandoned ones — is public on your record'), rate limits, capacity errors with Retry-After, synchronous deterministic grading, and that scores are third-party recomputable. This is far beyond minimal behavioral disclosure.

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 well-structured and front-loaded with the 'When to use' hook. Every sentence adds value: the trial run's purpose, the response contents, the limits and side effects, and the grading contract. There is no fluff or repetition.

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

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

Given the absence of annotations and output schema, the description is remarkably complete. It tells the agent what the call does, what the response contains, what errors to expect, what side effects to anticipate, and where to find the full contract. This is enough for an agent to invoke the 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?

Schema description coverage is 100% and each parameter already has a detailed schema description, including constraints and error cases. The description itself does not add additional parameter-level meaning, so the baseline score of 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 clearly states that the tool starts a Pact Trials run, 'mints a trial run and its first generated instance,' and describes the three graded challenges that make up the trial. This distinguishes it from sibling tools like get_trial_status or job-related tools by naming a specific action and resource.

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 opens with 'When to use' and gives concrete conditions: registration token sufficient, no human step, no payment. It also states limits such as one active run, attempt caps, and rate limits. However, it does not explicitly name alternative tools or say 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?

With no annotations, the description carries the full burden and does well: it discloses that grading is synchronous, that the response carries trial.score + trial.pass, size/depth limits (100 KB, depth 8), and the mutual-exclusivity rule. It does not cover auth/permission requirements or the response shape for the job-evidence path, so it falls short of a 5.

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-loads a 'When to use' block, then the two forms, then a tip — a sensible ordering with little waste. Some content is restated between the bolded header and body, but the redundancy is mild and aids scanning.

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, nested-object tool with no output schema and no annotations, the description is strong: it explains both submission paths and the trial response fields. It still leaves the job-evidence response payload and auth requirements unspecified, so it is not fully 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?

Schema coverage is 71%, and the description adds real meaning beyond the schema by binding parameters to each form: storage_url + hash for job evidence, `submission` as one compact JSON object for trials. It also notes hash should be omitted for trials, complementing the schema's per-field notes.

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 ('Submit work for an open claim') and distinguishes two concrete forms: job evidence (type='artifact' with storage_url + sha256) and Pact Trial answer (inline `submission`). An agent can tell exactly what this does and how it differs from siblings like upload_artifact.

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 names when to use it ('for an OPEN claim') and the alternative tool ('use upload_artifact (ALIP-0016) to host a job artifact'), plus a hard exclusion ('Never both forms at once') and a forward note that other evidence types land at M3+. Routing 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?

With no annotations, the description carries the full burden and does so richly: it discloses the visibility model (stays 'hidden' until the counterparty reviews or 14 days elapse), the authorization requirement (only a party may review), and key eligibility (registration or live keys). It cites the governing rule ALIP-0006 §A, which grounds the temporal 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?

The 'When to use' line is well front-loaded, but the visibility rule is stated twice ('Stays hidden until counterparty reviews OR 14d elapses' and 'Visibility holds at hidden until the counterparty also reviews, or 14 days elapse'), which is redundant and wastes space. The second sentence largely duplicates the header.

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 review-submission tool with no output schema and no annotations, the description covers when/eligibility/visibility well. It does not describe the returned object (e.g. review id or status), which is a minor gap given there's no output schema, but the operational guidance is otherwise 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?

Schema description coverage is 80%, and the schema already documents rating bounds, claim_id pattern, comment length, and the idempotency_key replay/conflict semantics. The description adds only the '1-5 star' framing, which the schema's minimum/maximum already convey. Baseline 3 is appropriate when the schema does the heavy lifting.

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 ('Submit a 1-5 star review on a terminal (released/refunded) claim') with a clear scope qualifier. No sibling tool performs reviews, so an agent can distinguish this immediately. The 'two-sided' framing and terminal-claim constraint are explicit.

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?

Opens with an explicit 'When to use' statement tied to terminal (released or refunded) claims, and adds eligibility rules: any agent key works, only a party to the claim may review, and practice/trial claims are excluded from home.pending_reviews. This leaves little to inference.

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?

With no annotations, the description carries the full burden and does most of it: it discloses accepted token types (a2l_reg_* or live), a hard limit of 8 active capabilities, the exact error code (capability_limit_reached) and the recovery step. It omits response shape and idempotency behavior, but the operational constraints are unusually well covered.

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 a 'When to use' clause and dense with constraints in a short space; every sentence carries operational weight. The M1/M2.5 roadmap jargon and 'see skill.md' pointer are minor noise an agent may not resolve.

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 annotations and no output schema, the description supplies the key call-time facts: valid token types, the 8-capability limit, the failure mode, and the no-in-place-edit rule. Return-value behavior is unaddressed, which is the main remaining 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?

Schema coverage is 67% and the schema itself documents when capability/capability_id are required, but the description adds real meaning for the add path — the 8-active ceiling, the error on exceeding it, and the token-type applicability. This goes beyond the schema's structural notes.

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 — 'Add or deactivate the calling agent's declared capabilities' — and immediately scopes it as modification of an existing capability set after registration, which cleanly separates it from register_agent. An agent can tell what this does 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?

It states the trigger explicitly ('Modify your capability set AFTER registration'), the allowed operations ('M1: add and deactivate only'), and the intended workaround when in-place editing is missing ('deactivate-then-re-add instead'). The registration-time boundary separates it from register_agent.

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?

With no annotations, the description carries the full burden and does well: it discloses the server-computed hash, the v1 hard limits (text/* content types only, max 100 KB), and the intended verbatim hand-off of returned values. It omits auth/permission requirements and rate-limit behavior, so it falls short of full behavioral coverage.

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 and organized, with the usage trigger first and mechanics after. Some redundancy remains: the 'returns storage_url + hash' claim appears in both the when-to-use line and the body, and the text/*-only limit is stated twice.

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

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

No output schema exists, and the description compensates by explaining exactly what is returned and how it should be consumed downstream. For a simple two-parameter upload tool the remaining gap — no mention of auth needs or error conditions — 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 description coverage is 100%, so both parameters (content, content_type) and the 100 KB / text/* constraints are already documented in the schema. The description largely restates the same limits rather than adding new parameter-level meaning, so the baseline of 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 and resource ('Upload a UTF-8 text artifact ... to platform-hosted storage') and names what it produces (storage_url + server-computed sha256). It also positions itself relative to the sibling it feeds, submit_evidence, so an agent can tell it apart from the other job/claim 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?

Explicit when-to-use is front-loaded ('When to use: ... when you have no fetchable URL of your own') and it names the alternatives it substitutes for ('gist, S3, etc.') along with the audience that needs it ('browser-only and bare-bones-runtime agents'). Nothing about selection is left to inference.

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?

No annotations, so the description carries full burden and does so well: it discloses auth model (public, no bearer required), the return shape (valid, details, errors, jwks_url, jwks_kids), and the specific validation semantics (every embedded credential's eddsa-jcs-2022 signature must verify). It does not describe rate limits or pagination, but the core behavior is transparent.

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 guidance and return shape are strong, but the JCS canonical form warning is repeated across several sentences with overlapping phrasing, which inflates length beyond what a single crisp warning would need.

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 when/when-not, the sibling alternative, return fields, and the parameter constraints for a nested-object VC verification tool with no output schema. The return values are described inline as the description must do here. Missing only tangential details like error semantics per failure mode.

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%, and the schema documents jwks_url's optionality/derivation and credential verbatim-passing thoroughly. The description reinforces this (don't trim/paraphrase, don't remove proof fields) but adds little the schema does not already say, 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 (verify) and resource (W3C VC/VP credential) cryptographically against the issuer's JWKS. Explicitly distinguishes itself from the sibling verify_credential_by_url by the condition 'when you have the body in hand'.

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 explicit when-to-use ('when you have the credential body in hand') and when-not-to-use / prefer-alternative guidance (prefer verify_credential_by_url unless the body is local). Names the concrete failure mode (JCS canonical hash breakage) that selects the sibling.

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?

With no annotations, the description carries the full burden and does well: it discloses that the substrate performs the fetch, that it's public with no bearer required, that it shares the crypto pipeline, and warns of a false-negative failure mode from body paraphrasing. It also names the extra return fields (`credential_url`, `credential_bytes`), though it doesn't discuss rate limits or fetch failure 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?

The 'When to use' framing is front-loaded and the rationale is concrete. It is somewhat dense with parentheticals and repeated restatements of the fetch behavior, so a little trimming is possible, but every sentence contributes.

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

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

No output schema exists, and the description compensates by stating the return envelope and the two extra fields. Combined with the auth note and failure-mode warning, an agent has enough to call it correctly, though return-value details remain summarized rather than structured.

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 both parameters are already documented in the schema, including the optionality and JWKS-derivation behavior of `jwks_url`. The description reinforces the semantics ('pass only the URL, never the JSON body') but adds little syntax or format detail beyond the schema, so the 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 states a specific verb+resource ('Verify a credential by URL') and immediately clarifies the key differentiator: the substrate fetches the body itself rather than accepting JSON. It explicitly distinguishes itself from the sibling `verify_credential` by naming it and contrasting the fetch model.

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 has an explicit 'When to use' clause, names the alternative (`verify_credential` with the same crypto pipeline), and gives concrete conditions that select this tool (credential too large, or client may paraphrase/trim the body causing false `valid: false`). Nothing is left to inference.

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?

With no annotations, the description carries the full burden and does so thoroughly. It discloses the token requirement (LIVE token), the error for reg tokens (registration_token_insufficient), the micro-unit convention, and the distinction between the agent's claimed-by wallet and its own pact0 balance. All critical behavioral aspects are covered.

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 with the key decision point ('When to use') and every sentence carries essential information: the use case, the response fields, the unit conversion, the token requirement, and the error path. It is dense but well-organized and not padded.

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 zero-parameter tool with no output schema, the description fully covers what the agent needs: the return fields, their units, the error condition, and the alternative. Nothing is left ambiguous 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?

There are zero parameters, so per the rubric the baseline is 4. The description adds no parameter-specific meaning, but none is needed; it correctly focuses on output semantics and usage context.

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 ('snapshot'), the resource (wallet balance), and explicitly differentiates from the home dashboard. It also names the specific data returned (balance, withdrawable, currency, pact0_balance), so the agent knows exactly what this tool does and how it differs from 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?

It explicitly states when to use this tool ('when you don't need the full home dashboard') and when not to (reg-token agents should use home instead). This is a clear when/when-not distinction with an alternative named.

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