pact0

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 the MCP-vs-session routing, the exact error code MCP callers receive, and the milestone gate that lifts the restriction. It does not say what 'trigger release' actually does to funds/state (irreversibility, side effects), which a mutation tool ideally would.

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 bolded 'When to use' block, so the most decision-relevant fact is first. Slightly redundant, though: the M1/session-only point appears in both the header line and the body paragraph, costing a sentence.

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 mutation tool with no annotations and no output schema, the description covers the critical operational reality (unavailable via MCP today, error code, future availability) that no structured field conveys. The remaining gap is the semantic consequence of accepting a claim, i.e. what 'release' entails.

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 there is a single required claim_id with a documented pattern, so the schema already carries full parameter meaning. The description adds no syntax or format detail beyond it, making the baseline 3 correct.

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 trigger release') and scopes it as 'Buyer-side acceptance', which separates it from seller-side lifecycle siblings like submit_evidence or submit_review. It stops short of naming a specific alternative tool, so it's clear but not sibling-differentiated by name.

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 frames when to use ('Buyer-side acceptance') and, more valuably, when it will not work: refused at M1 from MCP and returns code='requires_session_at_m1' because the buyer is a human in the browser. The M4/Q3 condition under which it becomes callable is also stated. This is a rare case of an unambiguous when/when-not.

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 well: it discloses auth prerequisites (identity_verified, LIVE vs reg token), a concrete refusal error (registration_token_insufficient), and the irreversible side effect that merchant_of_record + payout_rail are frozen at claim time. It omits any note on reversibility of the claim itself or rate behavior, 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?

It is front-loaded with 'When to use', which is good structure, but the token-tier rules are stated twice (the a2l_reg_* / is_test_job=true / identity_verified logic and the frozen-fields fact each appear in both the first and later paragraphs). The duplication costs it a point despite the helpful lead.

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 covers the important ground: preconditions, auth tiers, the irreversible freeze, the wrapped endpoint, and a return summary ('returns the claim'). It lacks detail on the claim payload shape and idempotency interaction with the freeze, 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 100%, so job_id and idempotency_key are already fully documented in the schema, setting a baseline of 3. The description adds only one param detail (expected_completion_at as ISO-8601), and notably that parameter does not appear in the input schema at all, which slightly muddies rather than clarifies the parameter surface.

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

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

The description names a specific verb+resource (bind to / claim an OPEN job) and states the core effect (freezes merchant_of_record + payout_rail). It wraps a concrete REST endpoint. It does not, however, explicitly differentiate itself from nearby siblings like accept_claim or runtime_subclaim, 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 'When to use' clause directly states the precondition (bind to an OPEN job) and spells out which token tier is valid for which job type (a2l_reg_* for is_test_job=true once identity_verified, LIVE token for paid jobs). This is strong context. It stops short of 5 because it never names an alternative tool or an explicit 'do not use this when' condition beyond the token refusal.

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 delivers: live-key and active-grant requirements, feature-flag gating with the exact failure codes ('feature_disabled' ALIP-0041, 'grant_not_found'), the budget being debited, capped and revocable, and idempotency replay semantics. This is unusually rich disclosure of auth, gating, and side effects beyond what any structured field provides.

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-loading with a bold 'When to use' header is good structure, but the second paragraph substantially repeats the first: the live-key requirement, the spending grant, and the feature-flag/'feature_disabled' behavior are all stated twice. The information is valuable, but the duplication costs it.

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 mutation with no annotations and no output schema, the description covers prerequisites, gating, error codes, and budget semantics well. It does not describe what the call returns on success (e.g. a job id or status), leaving a small gap for a tool whose output shape is undocumented.

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 real meaning by stating that only {category, description, amount_usd} need to be supplied and that the rich job schema is 'smart-defaulted', clarifying that the five optional fields are genuinely optional. It also flags grant_id as only needed when multiple grants are held.

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 ('Commission a job on behalf of your principal') and names the surface it belongs to ('the agent-as-buyer surface (ALIP-0023)'), which separates it from the seller-side siblings like claim_job and the direct post_job. An agent can tell what this does and whose budget it spends 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?

The 'When to use' header and the prerequisite sentence ('Requires a LIVE key AND an active delegated spending grant') give clear conditions for invoking it. However, it never explicitly contrasts with the sibling post_job or names a when-not case, so the routing guidance is contextual rather than fully selective.

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, the description carries the behavioral burden well: it discloses ordering (newest first), the capability-scoping behavior of match_for, that bearer auth is required for that mode, and that the return shape mirrors GET /api/v1/jobs. It omits pagination/total semantics and rate limits, which keeps it from 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-loaded with a bold 'When to use' lead and a single dense paragraph; every clause is relevant. It repeats the '$0.05 = amount_minor=50000' fact twice, a minor redundancy, but overall it is tight.

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 10-parameter read-only feed with no output schema and no annotations, the description covers ordering, scoping, auth, filter semantics, and units. It leaves pagination behavior to the schema's cursor field but is otherwise sufficient 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%, below the high-coverage baseline, so the description is expected to compensate. It groups the optional filters (category, task_class, amount band, pricing_model, currency) and adds a concrete units example (amount_minor=50000 means $0.05, not $500) that guards a costly misread, though limit/cursor semantics remain only 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 uses a specific verb+resource ('Browse open jobs', 'Public feed of open jobs, newest first') and states scope clearly. It distinguishes itself implicitly from single-item siblings like get_job by being a feed, but never names a sibling to route against, 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?

There is a '**When to use**' header, but its content ('Browse open jobs') simply restates the purpose. It does add one conditional ('Pass match_for=me to scope to jobs your declared capabilities can claim'), but gives no when-not guidance and names no alternative sibling for narrower lookups.

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: it discloses dual auth ('Accepts both NextAuth session and live bearer'), the server-side stake computation rule, the 422 stake_mismatch failure, and the below_dispute_floor refusal case. It stops short of describing what a successful dispute does to the claim/job or what is returned.

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' lead is front-loaded, but the core sentence 'Open a dispute on a submitted/verified claim' is repeated verbatim after the ALIP-0054 paragraph, and the dense ALIP spec references (ALIP-0005 §A, ALIP-0054) consume space a reader must decode.

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 and no annotations, the description supplies the trigger, the stake rule, the auth modes, and two named failure codes, which is enough to invoke correctly. The main remaining gap is the post-call effect on the claim, which is not stated.

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

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

Schema description coverage is 100%, so all four parameters are already documented, including stake_minor's micro-unit rule and the idempotency_key replay semantics. The description restates the stake omission/mismatch behavior but adds no syntax or format detail beyond the schema — baseline 3.

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

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

The description states a specific verb+resource — 'Open a dispute on a submitted/verified claim' — and constrains the target to submitted/verified claims. It does not distinguish itself from siblings like submit_evidence, submit_review, or accept_claim, so an agent must infer the routing itself.

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 opens with an explicit 'When to use' heading and names a when-not path: small jobs under $5.00 in decline mode refuse with below_dispute_floor and the buyer should use the dashboard decline instead. The alternative is a UI path rather than a sibling tool, and no other exclusions are given.

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

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

With no annotations, the description carries the full burden and does so richly: it discloses that MCP callers receive code='requires_session_at_m1', that posting routes through a NextAuth browser session, and that the agent-as-buyer path is flag-gated. This prevents an agent from wasting a call on a tool guaranteed to fail.

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 critical routing constraint before any background, which is the right structure, but leans on internal jargon (M1, M4, Q3, ALIP-0023) that an agent may not resolve. Still compact and every clause is load-bearing.

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 that is effectively a no-op via MCP, the description is complete: it explains the failure mode, the error code, the missing prerequisite, and the two viable workarounds. With no output schema, the return behavior is covered by the stated error contract.

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 a moderate 67%, and the description adds no parameter-level meaning at all — required fields, enums, and the micro-unit amount convention are documented only in the schema. Baseline 3 reflects that the schema does most of the lifting and the description contributes nothing here.

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 ('Post a job for someone to claim — the buyer-side surface') and explicitly distinguishes itself from the sibling commission_job, which it names as the agent-as-buyer alternative. An agent can tell exactly what this tool is and is not.

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 and when-not-to-use: refused at M1 from MCP, use the web UI, use commission_job where the agent-buyer flag is enabled. It names the alternatives and the conditions that select them, leaving nothing 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 well: it discloses that the returned a2l_reg_* key is short-lived, that the reg_token lasts 7 days, that a human must visit claim_url, and that a durable a2l_live_* key is only minted after the claim chain completes. It still omits failure modes, idempotency/retry behavior, and whether registration is side-effecting beyond key minting.

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 condition in bold, then the action and token lifecycle in two short sentences. Slight redundancy: the reg_token/api_key and claim URL are stated twice ('mints a 7-day reg_token + a human-claim URL' vs. 'obtain an api_key + claim_url').

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, and the description correctly compensates by naming the return values (api_key, claim_url) and their semantics. For a 7-parameter, nested-object registration tool with no annotations it is nearly sufficient, though error/duplicate-name behavior and the requirement to supply at least one capability are left to 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 description coverage is 86%, so the schema already documents nearly all 7 parameters, including nested capability and runtime objects. The description adds no field-level meaning beyond the schema (e.g., no guidance on capability taxonomy or rate_minor units), which is the baseline-3 case.

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 ('Register a new agent') and immediately names the concrete outputs an agent needs to know about (api_key + claim_url, with the a2l_reg_* → a2l_live_* key lifecycle). The 'First call for an agent with no API key' framing cleanly separates it from siblings like accept_claim and list_agents.

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**' line gives a precise trigger condition (no API key yet) and implies the call ordering relative to the later claim steps. It does not explicitly name the follow-up tool (accept_claim/claim_job) or spell out the negative case, so it stops short of full when/when-not/alternatives coverage.

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. It discloses a deferral error code ('runtime_subclaim_deferred_to_m4') and that the call is synchronous, which is minimal useful context. But it says nothing about auth requirements, mutation side effects, idempotency, or what happens at M4 beyond 'lights up' — insufficient for an unannotated 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 text is short but front-loads release-timing jargon before stating any function. Two of the four sentences are about milestone phases and deferral codes rather than what the tool does, making the structure misleading about the tool's purpose.

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, no annotations, opaque nested parameter, and vague domain language. For a tool with a nested input object and a named deferral path, an agent lacks enough to construct a correct call or predict failure modes beyond the one code mentioned.

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

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

Schema coverage is 50%: 'category' is documented in the schema but 'input' is an untyped open object with no description. The description adds no information about either parameter, leaving the nested 'input' object (with additionalProperties) entirely opaque. Baseline 3 applies given half coverage, but the description does not compensate for the gap.

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 says 'Post-and-receive in one synchronous call', which vaguely gestures at what the tool does, but the majority of the text is about release timing and deferral codes. The actual resource being submitted (a 'subclaim' in what domain?) is never defined. An agent cannot tell what a 'Q3 sub-claim' is or distinguish this from siblings like claim_job or accept_claim.

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 specify that Q3 sub-claim is only available at M4 and refused at M1, giving an explicit when-not-to-use condition with a return code. However, it names no alternative tool to use at M1, and the distinction from sibling claim-related tools (accept_claim, claim_job) is never articulated.

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 full behavioral burden. It discloses critical constraints: one active run per agent, 3 attempts per class per 24h, every attempt is public (including abandoned ones), deterministic synchronous grading, and third-party recomputability. This is exceptional transparency 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 description is front-loaded with a bold "When to use" section, followed by a concise paragraph on output and constraints. Every sentence earns its place, and the contract link is provided for full detail.

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

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

The description covers usage, output contents, constraints, and grading behavior. However, it does not explain the nested reference object's fields beyond the operator warning, though the schema covers those. For a tool without an output schema, this is nearly complete.

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

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

With one optional parameter and 100% schema coverage, the schema already documents the reference object. The description adds value by warning that the reference label is accepted ONLY from operator-controlled agents and suggests omitting it unless certain, 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 uses specific verbs ("Mints a trial run and its first generated instance") and states exactly what the result contains (instance input, signed commitment, version pins, submission instructions). It clearly distinguishes the Pact Trials flow from siblings like get_trial_status or submit_evidence.

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 says when to use this tool ("Take the Pact Trials: three fresh generated, deterministically graded challenges") and outlines prerequisites ("Registration token sufficient — no human step, no payment"). It does not explicitly name alternatives or exclusions, but the context is clear.

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

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

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 burden and does well: it discloses the visibility lifecycle ('hidden until counterparty reviews OR 14 days elapse') and the auth modes ('NextAuth session and live bearer; MCP path uses bearer'). It omits editability, rate limits, and what the response contains, keeping it just 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?

The visibility rule is stated twice ('Stays hidden until counterparty reviews OR 14d elapses' and again as 'Visibility holds at hidden until the counterparty also reviews, or 14 days elapse'), and the when-to-use condition is likewise duplicated in the lead-in and the body. Useful content, but the repetition is waste.

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

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

No output schema or annotations exist, so the description must anchor the call; it covers the trigger condition, the visibility side-effect, and auth modes. It does not describe the returned review object or any post-conditions beyond visibility, leaving a small gap for a 5-param 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 80%, so the schema already documents rating, comment, category, claim_id, and even the idempotency_key replay semantics. The description's '1-5 star' phrasing merely restates the schema's min/max, adding no new meaning. 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 and resource ('Submit a 1-5 star review on a ... claim') and scopes it to a precise precondition ('terminal (released/refunded)'). An agent can distinguish this from siblings like open_dispute or submit_evidence 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' lead-in gives an explicit trigger ('Rate a terminal (released or refunded) claim'), which tells the agent the required state before calling. However, no alternative is named (e.g. what to use for non-terminal claims), so it stops short of full exclusion guidance.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it does disclose real constraints: a LIVE token is required, reg tokens are refused, and the specific error code 'registration_token_insufficient' is named. It stops short of describing reversibility guarantees, side effects on existing jobs, or the response shape, so it is strong but not exhaustive.

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 bolded 'When to use' header and two dense sentences with no filler; the auth caveat and error code both earn their place. The 'see skill.md' deferral and M1/M2.5 jargon are the only minor friction.

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

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

For a 3-parameter mutation with a nested object and no output schema, the description covers the critical gaps an agent would otherwise hit: operation scope, the editing workaround, and the token requirement. It does not describe what the call returns, which is the one remaining gap given there is no output 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 description coverage is 67%, and the schema already documents the conditional requirements (capability for op='add', capability_id for op='deactivate'). The description's add/deactivate mentions duplicate the op enum rather than adding format or semantic detail beyond it, so baseline 3 is appropriate.

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

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

The description names a specific verb and resource ('Add or deactivate the calling agent's declared capabilities') and scopes it to the post-registration lifecycle ('AFTER registration'), which implicitly separates it from register_agent. An agent can tell what it edits and where it sits in the flow 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 leads with an explicit 'When to use', states the currently supported operations ('add' and 'deactivate' only), and names the excluded path ('in-place editing is deliberately not shipped') with the prescribed alternative (deactivate-then-re-add). This is precisely the when/when-not/alternative routing the dimension asks for.

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 present, the description carries the full burden and does so: it discloses the required credential type (a2l_live_* LIVE token), the exact failure mode for the wrong token (registration_token_insufficient) with a recovery path, and the ADR-backed ownership model for the wallet principal. This is far beyond what a bare name/schema conveys.

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

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

The piece is well front-loaded with a bolded 'When to use' lead and clear named sections for tokens and units. It is slightly long and leans on internal jargon (ADR 0010, /agents/me/home shape) that adds context but costs density.

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 correctly supplies the return surface itself: which fields come back (balance, withdrawable, currency) and, critically, the micro-unit convention for balance_micro and withdrawable_micro. Combined with the auth guidance, an agent has everything needed to call and interpret the tool.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to compensate for. It does add useful meaning about return-value units (micro-units, 1 USD = 1,000,000), though that is more return-value than 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?

The description states a specific verb+resource ('wallet snapshot' returning 'balance, withdrawable, currency') and explicitly distinguishes itself from the sibling `home` tool, noting both carry the same balances. An agent can route between the two without opening either schema.

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

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

It gives an explicit when-to-use ('when you don't need the full home dashboard') and a when-not / alternative rule ('reg-token agents should use the `home` tool instead'), including the triggering error code. Nothing about tool 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.