Rokha

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

Goes far beyond the annotations (readOnlyHint=false, destructiveHint=false) by disclosing validation rules (reserved names and taken handles refused, handle charset and ≤32 length), failure modes (402 publish_cap at the allowance ceiling, model with no key refused), and the economics of who pays for chats. This is exactly the kind of consequence-level context annotations cannot express.

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 auth precondition is correctly front-loaded, but the single dense paragraph then wanders into builder-page promotion, revenue share, and per-turn billing — useful context, yet not all of it earns its place in a create call. It would scan much better as a short prerequisite line plus a separate notes block.

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 14-parameter mutation with an output schema already documenting the return, the description covers everything an agent needs: auth path, defaults, validation constraints, two distinct refusal cases, and the natural next calls. Nothing material is left to inference.

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 on top: persona is "required to go live", empty model means the platform default, a keyless model is refused, and rigs/skills are sourced from the user's own library via rig_search. Some of it (handle charset, ≤32) merely repeats the schema.

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

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

States a specific verb and resource — "Creates an agent you own" — and immediately distinguishes it from the sibling family by naming agent_publish, product_set, and payout_wallet_set as separate downstream steps. An agent can tell this is the creation entry point rather than a listing or pricing tool 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?

Gives an explicit precondition chain ("sign in headlessly with auth_wallet_challenge → auth_wallet_verify") and explicit follow-ups ("Next: agent_publish puts it on the market; product_set prices it"). What's missing is a negative case — no statement of when not to use it, e.g. cloning an existing agent via registry_adopt instead of authoring a new one.

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

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

Annotations cover the read-only, non-destructive profile, and the description adds real value on top: no login required, deterministic classification into four credential modes, and that it returns a single recommended next step. It doesn't describe failure behavior for malformed URLs, but the output schema carries the return 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 the 'AUTH LADDER' framing, then a compact enumeration of the four buckets and the return contract. Dense but every clause carries information; the capitalized branding is slightly promotional 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?

With one required param, full schema coverage, annotations, and an output schema, the description supplies everything needed to call it and to interpret the four result categories. Only edge-case handling for invalid URLs is unspecified, which is minor here.

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% for the single server_url parameter, so the schema already documents it fully. The description explains the classification outcomes but adds no format or validity details for the input beyond what the schema states; 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 and object ('classify any MCP server URL') and enumerates the exact output categories: open, key, tier1, oauth_spec. An agent can distinguish this classification tool from the auth_wallet_challenge/auth_wallet_verify siblings without opening a 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?

Establishes clear context as the entry point of the auth flow ('Returns the one right next step') and notes it 'works without login', so it can be called pre-authentication. It does not explicitly say when to prefer auth_wallet_challenge or auth_wallet_verify instead, so alternatives are only implied by the ladder metaphor rather than named.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds the genuinely useful behavior that it returns a signable challenge rather than a session, and that a new wallet is auto-registered on first verify as a free account. The pricing/limits paragraph is informative but reads as upsell rather than behavior an agent needs before invoking. Nothing contradicts the annotations.

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

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

The first two sentences are tight and front-loaded with the essential purpose and the follow-up call. The final third drifts into free-tier quotas, run-pack pricing, and subscription pricing that belong to product_checkout/subscribe rather than to a challenge-generation call.

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 an output schema present, annotations covering the safety profile, and full parameter coverage, nothing an agent needs in order to call this correctly is missing. The flow, supported chains, and next step are all 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 the schema already documents chain auto-detection and the wallet_type defaulting rule; the description only restates the address shapes (base58 Ed25519, 0x). Baseline 3 applies since the description adds little beyond the structured fields.

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 ("Step 1 of registering (or logging in) a user with a wallet keypair") and names the exact artifact produced ("a challenge message to sign with the wallet's private key"). It explicitly routes to the sibling auth_wallet_verify, so an agent can distinguish it from the other auth tools 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?

Gives an explicit sequencing rule ("Follow with auth_wallet_verify") and names the alternative flow this belongs to (register vs. login), plus the precondition that no browser is needed. Supported address formats are spelled out (base58 Solana / 0x EVM), which is the main condition that selects the correct call.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses that the call mints a JWT, exactly how to transmit it ('Authorization: Bearer <token>' on every subsequent request), and which capability set it unlocks. That is meaningful behavioral context for a state-changing auth handshake. Gaps remain around token lifetime/expiry and failure or re-submission behavior, which an agent would need to handle.

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 step number and outcome, then chain-specific encoding detail, then the unlock list — a sensible ordering with little waste. The trailing tool enumeration with an ellipsis ('schedules, …') is slightly loose but still informative rather than filler.

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

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

For a three-parameter auth-completion tool with a full output schema, the description covers the prerequisite, the return value's use, the header format, and per-chain signature encoding. Since an output schema exists, it need not document response shape, and 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 100%, so the baseline would be 3, but the description adds real meaning beyond the schema: the signature must be Ed25519 over the raw challenge message bytes on Solana (base58 or comma-separated bytes) and EIP-191 personal_sign hex on EVM. That signing-standard detail is not derivable from the schema's simpler 'base58 for Solana, 0x hex for EVM' note.

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

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

States a specific verb and resource ('submit the signed challenge') and frames itself explicitly as 'Step 2', which cleanly separates it from the sibling auth_wallet_challenge (step 1). The title plus the success outcome (returns session_token JWT) make the tool's identity unambiguous 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 prerequisite is explicit: this runs after auth_wallet_challenge, whose challenge_id is required. It also names the downstream owner-scoped tools that become available once the JWT is held, giving strong context for why and when to call it. It stops short of stating when-not to call it (e.g., if a valid token already exists), which keeps it from 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds real context beyond that: no auth is needed for the public call, the signed-in form returns your own remaining questions and runs, and results are keyed under `per_day`. It also explains that every refusal names both upgrade doors, which tells the agent how this data relates to gate errors. It does not describe caching, rate limits, or freshness beyond 'each UTC day'.

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

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

The description is a single dense run-on block of pricing and quota copy — including card/USDC/SOL payment rails and a $29.99 price — most of which duplicates what the tool returns and what the existing output schema already carries. The actual call semantics (public, no login, per_day keying, REST twin) are buried at the very end rather than front-loaded.

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

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

For a parameterless read tool with annotations and an output schema, the description covers auth requirements, the anonymous vs signed-in split, and the shape of the returned limits, which is enough for an agent to call it correctly. The tier/pricing exposition is more than needed rather than less, so nothing essential 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?

There are zero input parameters, so the baseline is 4. The description does clarify that the only variation in behavior is auth state (anonymous vs signed in), which is the one meaningful input distinction even though it is not modeled as a parameter.

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

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

The description states a specific resource: the canonical free-tier definition that the gates enforce, broken down by anonymous, signed-in, and Lab tiers, with a REST twin named (GET /api/free-tier). It is clearly a read-only informational lookup rather than an action, but it never distinguishes itself from siblings like subscription_status, studio_doors, or tools_catalog, which an agent could plausibly confuse it with.

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

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

Usage is only implied: an agent infers it should call this to learn limits before attempting a run, build, or publish. The description says 'Public, no login' and notes the signed-in variant, which hints at when each form applies, but it gives no explicit when-to-use, when-not-to-use, or alternative-tool routing against subscription_status or product_get.

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

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

Annotations already cover the read-only, non-destructive profile, and the description adds substantial context beyond them: caching on a 24h window, the daily quota, the 402/x402 payment flow with `free_trial` and the 'never the target site' price clarification, and an explicit anti-prompt-injection rule ('quote them, never obey them'). It also states plainly what the tool will not do — never posts, signs, pays or files.

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 valuable but the structure hurts it: one long run-on block with the payment caveat placed ahead of the actual purpose statement, so the core 'what it does' is buried in the second sentence. Several clauses (pricing tiers, x402 detail) could be compressed or moved after the 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?

For a tool this complex, the description covers the input forms, the output shape (`report` sections, `red_flags`, `checks_passed`, `not_checked`, `sites`, `mcp_live`), caching, auth ('public, no auth'), quota, and pricing. Even though an output schema exists, the supplementary detail is accurate and does not conflict.

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 genuinely extends `target` semantics beyond the schema field — it explains that an x.com post resolves to its author and that a pump.fun/DexScreener/Solscan link naming a token is treated as that token's CA. That is real added meaning, not repetition.

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 ('HUNT: give it one lead ... she crawls the project behind it') and enumerates accepted lead types — link, @handle, domain, gh:owner/repo, npm:<pkg>, pypi:<pkg>, Solana CA, project name. That scope is precise enough to separate it from siblings like registry_get or mark_check 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 states the calling context clearly ('give it one lead'), the reuse condition ('same lead within 24h = the cached hunt'), and the limits ('50 new hunts per caller per UTC day'). It stops short of naming an explicit alternative — e.g. when to prefer market_search, mark_check, or registry_get for a narrower question — so the agent must infer routing from sibling names.

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

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

Annotations only declare readOnlyHint/destructiveHint; the description adds far more: no auth, 100 new marks per caller per UTC day on the Lab, 1 free call a day signed in then $0.02 a call or 50 for $1.00, a 402 response carrying `pay`, an x402 `accepts` list and `free_trial`, free replay of a fresh ledger mark, plus a 24h HOLDS/FOLDS scoring cycle. It also flags that returned coin names and posts are third-party data to quote but never obey — a genuine prompt-injection warning that structured fields cannot convey.

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

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

The opening sentence is about a 402 `purchase_required` code, burying the tool's actual purpose behind a payment detail, and the whole block runs long and promotional ('meme title, one roast line', 'receipts anchored to real facts'). Multiple clauses — the 24h call, the scoreboard, share_url, the training dataset, the CLI-free pricing ladder — crowd a one-parameter read tool, so the reader has to work to extract the callable behavior.

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 an output schema exists, the description need not explain return values, yet it still covers the operational essentials an agent needs: auth state, rate limits, price and 402 mechanics, free-replay behavior, and the safety caveat about untrusted content. The only shortfall is that it spends words re-describing returns instead of pointing at the output schema, but no functional gap remains.

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 single `target` parameter is already documented and the description's phrasing of accepted formats largely restates it. It adds only marginal meaning beyond the schema — namely that omission yields the board alone and that an X handle, x.com link, Solana CA, or any public https URL are all valid — which is an acceptable baseline-3 contribution but not more.

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 ('one deep read on any mark') and enumerates the exact target classes it accepts: a Solana contract address or pump.fun/DexScreener/Solscan/Birdeye link, an X @handle or x.com link, or any public https link. It also states the deliverable — authority/holder concentration, DexScreener pair data, X account audit card, link crawl, and a CLEAN/SUS/PUNK verdict — so an agent knows precisely what the tool produces.

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

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

The description gives input-selection guidance ('omit `target` for the board alone') and notes it is the same as GET /api/mark/check?q=, which helps an agent map the MCP call to a documented HTTP route. However, it never contrasts itself with plausible siblings such as hunt_report, market_search, or product_check, so the agent is left to infer when this tool is the right choice rather than another.

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

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

Annotations already declare readOnlyHint=true, but the description adds material behavior on top: 'Public, no auth, cached 30 s', the cursor is 'opaque, signed, bound to the query', `total` is null when q is set, and facets are returned. It also discloses a privacy boundary ('Never an owner wallet, email or runner identity') and notes that every item runs for real with a trace, which no structured field 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?

It is front-loaded with the tool's identity, which is good, but the body is one dense semicolon-chained block that enumerates all eleven parameters and then restates the full item payload. The item-field list largely duplicates the output schema, and the sort/ids semantics repeat the schema descriptions verbatim, so several sentences do not earn their place.

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

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

For an 11-parameter, zero-required browse tool this covers everything an agent needs: filter vocabulary, ordering semantics, pagination mechanics, auth and caching posture, the `ids` shortcut with a shareable URL pattern, and a pointer to the shelves endpoint. The output schema exists, so the item enumeration is redundant rather than necessary, but nothing important is absent.

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 baseline would be 3, but the description adds meaning the schema does not: `q` ranks 'title match > tag > description' with proven first in ties, `paid` means 'has an active creator product — Buy/Hire', and `proven` means ran end to end. Some of the sort/ids text is near-duplicated from the schema descriptions, which caps it at 4 rather than 5.

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 concrete identity: 'everything you can run on Rokha in one store' and enumerates what that includes (rigs, skills, MCP servers, agents, builders, marketers) plus the synced open registry. That gives an agent a clear sense of scope and implicitly supersedes narrower siblings like registry_search and rig_search. It never names a sibling tool explicitly to route against, so it stops just 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?

Usage context is unusually rich: 'omit q to browse', pass next_cursor back as cursor, 'pass ids ... every other filter is ignored, no cursor', and defaults for every filter (limit 24, sort popular, hire default off). What is missing is explicit when-to-use-this-vs-that guidance against siblings such as registry_search or tools_catalog, which the agent must infer from the 'everything in one store' framing.

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

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

Beyond the non-destructive mutation hints in annotations, the description discloses that the calling identity becomes owner, that an existing handle is edited in place while a new handle triggers a rename (a consequential side effect), and that omitting style preserves stored styling versus sending the full object replaces it.

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 purpose and mode logic are front-loaded, but the remainder collapses into one enormous parenthetical nesting style, gallery, and fit sub-keys, which makes it dense to parse. The details earn their place individually; the packaging does not.

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 nested objects, the description covers ownership, auth, rename-on-new-handle semantics, and style merge-vs-replace behavior, and an output schema already exists so return values need no explanation. 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?

Schema coverage is already 100%, so the baseline is 3, but the description adds real meaning: the style object is characterized as the page's brand knobs with dimensions and ranges, gallery images hang as posters up to four per side, fit objects set focal point/zoom/dim, and banner_url accepts a client-downscaled data:image URI capped at 600k. Some of this duplicates the schema's own style summary.

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 opening sentence states a specific verb and resource ('Claim your public /@handle page') and immediately disambiguates the two modes: re-claiming your own handle edits in place, while a new handle renames. An agent knows exactly what the call 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 clearly signals the claim-vs-update branch and the auth prerequisite ('Requires Authorization: Bearer <JWT>'). What it doesn't do is route the agent to siblings such as page_me for reading an existing page, so guidance on alternatives is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds real context on top: an explicit auth requirement (Authorization: Bearer <JWT>) and the two distinct response shapes for claimed vs unclaimed callers. It stops short of covering rate limits or what happens with expired tokens, but the essential behavioral picture is there.

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 tight sentences, front-loaded with the core purpose, then the fallback branch, then the identity payload and auth requirement. The enumerated field list is dense but each field carries a non-obvious semantic detail (empty-string sentinel for x_verified_type, derived bool for x_verified).

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 read with an output schema and read-only annotations, the description covers everything an agent needs: what identity it is scoped to, the auth mechanism required, the branch condition for the unclaimed case, and the next tool to call. Nothing material is left to inference.

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

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

With zero input parameters there is nothing to disambiguate, so the baseline is 4. The description instead spends its words on returned fields (x_handle, x_verified_type, x_verified and their provenance via the OAuth broker), which is a reasonable use of space even if partly overlapping the output 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 opening sentence names the specific resource (the caller's own builder page) and the exact scope ('as the logged-in identity sees it'), which distinguishes it from registry/profile-style siblings. It also distinguishes itself from page_claim by describing the unclaimed case as a returned payload rather than a write.

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 conditional routing rule: if no page has been claimed, the response is { claimed: false, suggested_handle }, and the caller should follow with page_claim. That names the alternative tool and the precise state that selects it, which is exactly the kind of when/when-not guidance that prevents mis-invocation.

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 destructiveHint=false the annotations say little about a money-moving call, and the description fills that gap thoroughly: auth via JWT or rk_ key, on-chain verification and immediate settlement for x402, self-confirming transfers for usdc/sol, 60-second price validity, a $250 per-payment cap, refusal before anything is created on stale or unfillable prices, and the creator's 80% USDC cut. It also discloses the costly edge cases — wrong amount, wrong sender or a late transfer will not settle — which is exactly the behavior an agent cannot infer elsewhere.

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 auth requirement and the core purchase action, and each clause carries distinct operational fact rather than filler. Structure is weaker than the content: one long em-dash-and-semicolon paragraph mixing rail mechanics, pricing rules and settlement caveats is hard to scan under load.

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?

Return values needn't be explained because an output schema exists, and the description covers auth, per-rail mechanics, timing and failure modes comprehensively. The remaining hole is the undocumented 'rokha' rail and the unmentioned ref_code, which the schema documents but the description never situates in the flow.

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, and the description genuinely adds sequencing semantics: signature is only meaningful on the x402 second call, payer_wallet only applies to usdc/sol, and rail values map to distinct flows. The gap is that the enum's 'rokha' value is never explained in the description even though it is grouped with the agent rails in the schema text.

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

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

States a specific verb and resource ('Buy product_id for YOURSELF') and immediately frames the tool as a payment-rail selector, which no sibling covers. It also names the follow-up tool (purchases_mine) that answers the adjacent question, so an agent can place it precisely amid product_get, subscribe and purchases_mine.

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

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

Gives per-rail selection conditions in unusual detail: x402 requires the two-call challenge/signature loop, 'usdc' and 'sol' require payer_wallet, 'card' is for a human via Stripe URL, 'signet' is session-only and never an rk_ key. What's missing is an explicit exclusion — nothing says what to do when the item is free or already owned, or that product_get should precede this call.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's main contribution is behavioral: it notes the tool is public, describes the 402 purchase_required behavior for paid items, and explains that buying a pack unlocks every contained item. It also summarizes the return shape, though that overlaps with the output schema. The added context is useful and not contradicted by annotations.

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

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

The description is a single dense paragraph that front-loads the core question and keying options. Every sentence is functional, though it is somewhat long and the return-shape sentence could be leaner given the output schema exists. It avoids filler and follows a natural order from purpose to identification to result behavior.

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 a six-parameter tool with zero required parameters, complex polymorphic keying, and a purchase-gating workflow, the description covers identification, return contract, pack semantics, and the 402 fallback with a pointer to product_checkout. An agent has enough to call it correctly and knows what to do next on failure.

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

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

Schema description coverage is 100%, so baseline would be 3, but the description adds real meaning: it clarifies that the four keying strategies are alternatives, that kind + ref identifies a pack via pack id, and that provider_id + external_id refers to a registry listing such as a rig, skill, or harness. This goes beyond the schema's individual property descriptions, which do not spell out the combinatorial selection logic.

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 question in verb form ('Is this item paid, and what does it cost?') and names the exact resource family: rig, skill, harness, agent, pack. It is immediately distinguishable from siblings like product_checkout or market_search because it is a read-only price lookup, not a purchase or search operation.

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

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

The description provides clear when-to-use context by listing all four mutually exclusive ways to identify an item (product_id, provider_id + external_id, agent_handle, kind + ref) and explicitly routes the agent to product_checkout for purchase, including payment rail options. It does not explicitly state when to prefer market_search or registry_get_skill, but the 'name it by' guidance covers the main ambiguity of a polymorphic lookup 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?

It adds the concrete requirement for a JWT or an rk_ key, which is useful context absent from the annotations. Beyond that, it provides little operational detail and does not explicitly clarify side-effect behavior even though readOnlyHint is false, though there is no direct contradiction.

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

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

Two compact fragments front-load authentication and then enumerate exactly what is included. The field-name hints add precision without filler 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?

For a zero-argument tool with an output schema, the credential requirement, resource scope, and key field hints are nearly sufficient for correct selection and invocation. Explicit sibling differentiation and clearer read behavior would make it more 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?

There are no parameters, so no input documentation is needed and the zero-parameter baseline applies. The period_end and runs_left parentheticals usefully clarify returned concepts rather than inputs.

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 identifies the resource as the caller’s paid unlocks, passes, and run packs, making the purchase-inventory purpose clear despite the lack of an explicit retrieval verb. It does not distinguish this view from subscription_status or free_tier_status.

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 authentication prerequisite and resource scope imply using the tool to inspect one’s own purchases, but there is no explicit when-to-use statement. It also does not explain when a sibling such as subscription_status or free_tier_status would be more appropriate.

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?

Far beyond the annotations: it discloses idempotency keyed to (you, listing), refresh-on-re-adopt semantics, that runs bill the caller's allowance and never the creator's, the required Bearer JWT, and the return shape. No contradiction with readOnlyHint=false / destructiveHint=false — this is clearly a mutating but non-destructive copy operation.

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

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

Front-loaded and dense with the actionable path first, then consequences. The closing sentences about RokhaApp rendering and the ./rokha-app.html artifact describe what happens after a subsequent run rather than what adopt does, so they are somewhat off-topic baggage for this specific tool.

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?

An output schema exists, yet the description still usefully names what returns (rig_id plus declared input) and how to use it next. For a two-param mutation with auth and billing implications, nothing an agent needs in order to call 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 100%, so the baseline is 3, but the description adds real meaning: both identifiers are sourced from registry_search, and external_id only resolves to something adoptable if the listing carries a metadata.rig skeleton. That precondition is not in the schema and materially affects whether the call is worth making.

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: 'materialize YOUR OWN runnable copy of any published rig listing.' The 'select → input → run door' framing plus the named listing identifiers let an agent distinguish this from registry_search, rig_get, and rig_run without opening a schema.

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

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

Explicitly routes the agent: get provider_id + external_id via registry_search, requires the listing to carry a metadata.rig skeleton, then execute via the run stream with user_context.rig_id and run_input. It also covers the repeat case — re-adopting is idempotent and refreshes the copy rather than duplicating.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false, and the description is consistent with a pure read. It adds useful context beyond the annotations: what the returned SKILL.md contains (frontmatter name/description plus body), the classification taxonomy, and the presence of required binaries that may need to exist before adoption.

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

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

Two sentences, zero filler: the first states what is returned and is front-loaded, the second gives the install procedure. Nothing is repeated from the title or schema, and every clause carries information.

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

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

With an output schema present, the description needn't describe return shape, and it still names the notable payload fields and the required binaries. Against a two-parameter read tool with full schema coverage, nothing an agent needs in order to call and use the result 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 description coverage is 100%, and both parameters are documented in the schema with their provenance from registry_search and the provider auto-resolution order. The description adds no further parameter 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?

The description uses a specific verb and resource ('Fetch everything an agent needs to adopt a Registry skill') and enumerates exactly what is returned: the full SKILL.md, its classification (prompt-shaped vs scripted vs mcp), and required binaries. This is far more specific than the title alone and tells an agent what payload to expect without opening the output 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 a concrete next step ('save the returned skill_md as SKILL.md inside a folder named after the slug in your agent's skills directory'), which implies the intended fetch-then-install workflow. However, it never states when to prefer this over adjacent tools such as registry_adopt or registry_search, leaving the agent to infer that search yields slugs and adopt performs installation.

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?

Well beyond the annotations, it discloses the auth requirement, server-side derivation of the display author, that a caller-supplied `author` is ignored except for superadmins, global uniqueness of the slug under your ownership, and the mutation-vs-update rule. This is exactly the context an agent needs before writing to a shared registry.

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 critical constraints (ownership, auth, name uniqueness) are front-loaded ahead of the listing_type breakdown and return-value note. It is a single dense paragraph with heavy em-dash nesting; a short structural break would improve scannability, but little 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 9-parameter nested-object mutation with auth and ownership implications, the description covers what an agent cannot infer: who owns the record, how updates are triggered, how listing_type maps to metadata, and what identifiers to retain. Return values are additionally noted even though an output schema exists, which is a bonus rather than a 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 already 100%, so the baseline is 3; the description adds real meaning on top by mapping each listing_type to its required metadata key (skill_md / harness / rig) and spelling out the naming constraint. It leaves tag, version, homepage, and metadata size limits to the schema, which is acceptable.

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

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

The description opens with a specific verb+resource: 'Publish (or update) YOUR listing in the Rokha Registry', and clarifies the create-or-update duality ('re-publishing your own slug updates it'). It does not name any sibling tool (e.g. registry_adopt, registry_get_skill) to differentiate itself, so it falls 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?

It establishes clear preconditions and context: requires a logged-in identity with a Bearer JWT, listing is owned by the verified caller, and re-publishing your own slug is the update path. It also disambiguates the 'server' legacy alias. No explicit exclusions or pointer to alternative tools, so not 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description adds real value beyond that by disclosing the result field set, the exact-id lookup behavior for UUIDs, the meaning of 'proven' (ran end to end with no step error) and the proven_at marker on results. It does not discuss pagination/limit interaction or result ordering, which keeps it 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-loaded with the core purpose and return shape, then the special modes; every sentence carries operational information. The parenthetical 'the live count is in GET /api/marketplace/registry/stats' is incidental noise that an agent calling this tool does not 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?

For a four-parameter, all-optional read tool with an output schema and clear annotations, the description covers purpose, result fields, the exact-id path, the proven filter, and the natural next call. Nothing an agent needs in order to invoke it correctly is absent.

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 would be 3, but the description genuinely adds semantics the schema lacks: a UUID-shaped query is treated as an exact-id lookup rather than text search, and query may be empty when combined with type='rig' plus proven=true. That is meaningful behavioral meaning layered on top of the parameter definitions.

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 — search the public skill and MCP registries plus Rokha builder listings — by free-text query, and enumerates exactly what comes back (name, slug, provider, author, version, downloads, description). The UUID exact-id lookup mode is called out distinctly, so an agent can tell this apart from a plain keyword search.

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

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

Gives concrete usage routing: follow up with registry_get_skill for full SKILL.md and install metadata, use a UUID query for exact-id lookup, and pass proven=true (optionally with type='rig' and an empty query) to list proven rigs. What's missing is differentiation from the other search siblings in the toolset (market_search, rig_search), so an agent still has to infer which search surface to pick.

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

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

Annotations declare it is a non-read-only, non-idempotent, non-destructive write, and the description supplements this well by stressing that bound steps are 'a real MCP tools/call' and that signet steps 'move value under the mandate'. It also warns that secrets must ride secret_refs rather than literals and that an unbound step silently becomes a model turn with no tools. It stops short of describing persistence semantics of saving over an existing key or any approval/abort 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 content is front-loaded with purpose and execution pairing, then flows into node/edge semantics and binding categories. It is dense and occasionally packs multiple rules into one sentence, but almost every clause carries real information for building a valid graph.

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 graph-authoring tool with an output schema already covering returns, the description supplies the execution model, binding taxonomy, templating, and the required follow-up call, plus a pointer to tools_catalog for rarer fields. What remains thin is the save/validation lifecycle implied by name and key, which the agent must infer.

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 would be 3, but the description adds a conceptual layer the schema does not: it groups the mutually exclusive node binding kinds (endpoint+tool, url, data_op, signet_actor, questions, sub_rig, doc_input) and explains that a node with no binding is a tool-less model turn. It also documents the template syntax for {{input}}, {{upstream.<field>}}, and {{secret:<alias>}} in one place rather than per-field.

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

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

The description opens with a specific verb and resource: 'Author a multi-step Rig as a graph the runtime executes for real.' It immediately positions the tool against the execution sibling by pointing to rig_run afterwards, so an agent knows this builds while rig_run runs.

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 a clear operational path: author, then call rig_run (wait: true) in the same turn. It also explains what each distinct key means for saved rigs. It does not explicitly exclude cases where skill_author or agent_create would be the better sibling, leaving that inference to the 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds genuinely new context: owner scoping and the required 'Authorization: Bearer <JWT>' header. It also reveals the return shape (steps, wiring, guards, stage) beyond the annotation profile.

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 purpose and scope, then usage, then auth constraint — a sensible order. The middle clause ('rather than against what you remember authoring') is longer than needed but does carry real meaning; the stray internal whitespace is cosmetic.

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 an output schema present, the description needn't explain return values, and it covers auth, ownership scoping, and usage timing. Minor gap: no mention of failure modes such as a missing rig or a non-owned id.

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?

Only one parameter and schema description coverage is 100% — the schema already explains that id is the rig's UUID and that rig_search lists them. The description adds nothing further about the id's format or source, so this is the baseline case where 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 (read) and resource (one rig) with explicit scope: 'Read ONE of your rigs in full — its steps, wiring, guards and stage.' The emphasis on ONE plus the full-detail enumeration separates it from list-style siblings such as rig_search.

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

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

Gives concrete when-to-use conditions: before editing so changes are made against saved state, and after a run to verify rig shape. No explicit 'when not to use' or named alternative, though the schema's parenthetical points at rig_search for obtaining the id.

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

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

Goes well beyond the readOnlyHint=false / destructiveHint=false annotations: discloses that the run bills the CALLER's allowance, executes REAL tools including money steps requiring a granted mandate, returns 402 purchase_required for paid rigs, and is rate-limited to 5 free runs/day with pack and subscription pricing. It also states the authentication requirement (Bearer JWT or rk_ key) and the async trace landing behavior. Nothing here contradicts the annotations — the write-capable profile matches readOnlyHint=false.

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 action and is logically ordered, but it is markedly overlong for a 6-parameter tool: the wait/render/stage_html contract is restated from the schema, and a pricing/marketing passage (run packs, Lab month, x402/usdc/sol) crowds the core invocation guidance. Formatting artifacts and padded spacing further hurt scanability.

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 mutates state, bills money and runs asynchronously, the description covers everything an agent needs: addressing, input semantics, sync vs async result paths, the 402 paid-rig recovery route, auth, quotas, and the security constraint on rendering returned HTML. An output schema exists, so return-value detail is appropriately left to it.

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: what 'input' means in practice ('a token address, a URL, a query'), that provider_id+external_id 'adopts YOUR OWN copy first, then runs it, which also heals a stale adopted copy', and the sandbox constraints for rendering stage_html. Only minor redundancy with the schema keeps it from a 5.

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 ('RUN a rig, for real, right now') and distinguishes itself from the authoring/scheduling siblings by noting that without it an agent could 'AUTHOR a rig, schedule it and hang a webhook on it' but never execute it. The rig_id vs provider_id+external_id addressing modes make the invocation target unambiguous.

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

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

Explicit about when to use each addressing mode (owned/adopted rig vs published listing), warns to 'read the rig before running someone else's' when money steps are possible, and routes paid-rig situations to product_get / product_checkout / free_tier_status by name. It also says when not to expect synchronous output (wait:false → results land as traces).

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

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

Annotations already declare readOnlyHint and destructiveHint, so the safety profile is covered. The description adds genuinely new behavioral context — owner scoping, newest-first ordering, and the required 'Authorization: Bearer <JWT>' header — but says nothing about result size limits, defaults, or empty-set 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 core action is front-loaded, but the sentence sprawls with em-dashes, capitalized 'RECOVERS', and stray whitespace runs that read as formatting artifacts. The recovery rationale is useful, yet it takes three clauses to say what one would do.

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?

Output schema exists, so return values need not be explained, and the description covers scope, auth, ordering, and filtering. Given only two optional parameters, this is nearly complete; only default `limit` behavior and result-size expectations are unstated.

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

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

Schema coverage is 100%, so baseline is 3; the description does add that `query` matches against name and summary and that omitting it returns everything owned. `limit` is not elaborated beyond the schema's 'how many (newest first)', leaving a small 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?

States a specific verb and resource ('List YOUR saved rigs'), plus ordering ('newest first') and an optional filter. It is clearly distinguishable from rig_author (write) and rig_get (fetch a known id) by emphasizing owner-scoped enumeration.

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 the use case as cross-session recovery and contrasts with rig_author, warning that re-authoring would silently create a duplicate rig. It stops short of mentioning rig_get, which is the natural alternative when an id is already known, so the 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false), it discloses the material consequences: the agent can run rigs, read saved keys/OAuth grants, and spend budget. That is exactly the risk context an agent needs before invoking a non-read-only tool.

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

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

Three sentences, front-loaded with the core action before the auth-behavior caveats. Dense and largely waste-free, though the closing sentence ("This is the door to...") is promotional rather than informational.

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?

Output schema exists so return values need not be described, and the critical auth/permission model is covered. What remains unaddressed is failure behavior (e.g., unknown agent name) and latency/streaming characteristics of a conversational 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?

Schema coverage is 100%, so the baseline is 3; the description adds the default agent identity ('rokha-agent'), which the schema only shows as an example. There is a mild tension with the schema marking agent_name as required while the description implies a default, which keeps it from a 5.

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?

"Send a message to a Rokha agent ... and get its reply" gives a specific verb, resource, and round-trip outcome, plus the default agent name. It is clearly distinguishable from the surrounding registry/rig/auth tools, which do not involve agent conversation.

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 two usage regimes explicitly: authenticated callers get an agent acting as them, anonymous callers get general chat only. That is clear when-to-use context, though it does not name an alternative tool or say when not to use this entry point.

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 annotations only declaring readOnlyHint=false and destructiveHint=false, the description adds important behavioral detail: it returns the assembled SKILL.md to save in a skill folder and fills the human builder form in Rokha UI. It does not clarify persistence, auth, or rate limits, but it usefully explains that the tool generates output rather than silently writing it.

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 front-loaded with the core purpose and organized around the required skill components. Each sentence carries substantive guidance, though the dense single-paragraph format makes it slightly less scannable than ideal.

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 an output schema exists and all 7 parameters are described at 100% schema coverage, the description is complete for authoring a skill: it covers required fields, optional fields, formatting rules, return behavior, and save location. An agent can infer how to call the tool without missing critical context.

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 meaning beyond the schema by explaining compatibility triggers ('set when the skill needs system packages, a language version, network access, or scripts; omit for pure-instruction skills') and reinforcing allowed_tools scoping and metadata pairs. Some fields are repeated from the schema, limiting the score to 4.

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

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

The first sentence states a specific verb and resource: 'Author a standard agentskills.io Agent Skill and get back its SKILL.md.' This clearly distinguishes the tool from generic publishing or creation siblings, though it does not explicitly differentiate from rig_author or registry_publish.

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

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

The description provides extensive guidance on what makes a strong skill and when to set compatibility, but it does not explicitly say when to use this tool versus alternatives such as rig_author or registry_publish. Usage is implied by 'Author a standard agentskills.io Agent Skill' but no exclusions or sibling routing are given.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that — "Public, no auth" and the fact that values are live and must not be cached or recalled — which is exactly the kind of behavioral note annotations cannot carry. It stops short of describing freshness window or how the prices are structured, and has output schema coverage for return values.

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

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

The description is a wall of marketing prose with duplicated content (the free-tier rules are stated twice in near-identical form), stray typos ("own model key.."), and the operative sentence stranded at the very end. Front-loading is absent — an agent must read to the last line to learn what the tool does. Only the pricing detail itself arguably has value, and even that is redundant with the return payload.

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?

Because an output schema exists, the description need not explain the returned price structure, and it does correctly flag that the values are live and require no authentication. However, for a zero-parameter, read-only lookup, the description is simultaneously over-long on irrelevant tier marketing and under-clear on the one thing that matters: what exactly gets returned and when an agent should call this versus other billing-related siblings.

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 of 4 applies; there is nothing for the description to disambiguate. The schema is empty and fully specified, and the description correctly presents this as a context-free lookup with no inputs to supply.

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 actual function appears only in the final sentence: "Returns the live prices — never quote one from memory." Everything before it is product copy about tiers and fees, and the name/title ("studio_doors") give no clue about pricing. An agent can eventually infer the tool returns current pricing, but the verb+resource is buried rather than stated up front, and no sibling (product_get, subscription_status, free_tier_status) is distinguished.

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?

"Never quote one from memory" is an implicit directive to call this tool instead of recalling prices, which is real but thin guidance. There is no statement of when to prefer it over product_get, subscription_status, or free_tier_status, and no when-not conditions. Usage is implied rather than specified.

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 only readOnlyHint=false and destructiveHint=false from annotations, the description carries real weight and delivers: payments are final with no refunds, cancellation is by email to admin@rokha.ai, USDC orders expire in 48 hours unpaid and self-confirm, SOL quotes hold only 60 seconds, and an exact amount must be sent. Minor gap: it never says what happens if the wrong amount is sent or whether a failed/unpaid order leaves any lingering 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?

Every clause carries information, but it is a single dense run-on paragraph stitched with semicolons and parentheses, and it opens on the auth prerequisite rather than the tool's purpose. The pricing/rail/timing facts are hard to scan for an agent deciding between rails.

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 payment-initiating tool the description covers auth, price, per-rail mechanics, expiry windows, finality, cancellation path, and cheaper alternatives; return values are covered by the existing output schema, so nothing essential is left dangling.

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 already 100%, yet the description adds per-rail behavior the schema cannot: 'usdc' + payer_wallet returns exact pay instructions that self-confirm within 48 hours, 'sol' + payer_wallet quotes in exact base units valid 60 seconds, 'card' returns a Stripe Checkout link. Slight gap: the 'rokha' enum value is never described in the text, 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?

States a specific action and resource: 'Starts the Lab month — $29.99 a month, full access to everything: the runtime, the Lab, 300 runs a day.' It also scopes it ('for YOURSELF; it never names another account'), which separates it from account-level siblings like page_me or subscription_status.

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

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

Explicitly routes the agent: use this to start a paid month, check subscription_status afterwards, and if cost is a concern use the free tier or a run pack via product_checkout instead. Prerequisite auth path (JWT or rk_ key via auth_wallet_challenge → auth_wallet_verify) is spelled out.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'Read-only' plus the auth requirement (JWT or rk_ key), which is real behavioral context not present in the structured fields. It also decodes the meaning of key values (studio true = full access) and gives the enum-ish access values, though it does not say what happens when unauthenticated or on the free tier.

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?

Auth and read-only status are correctly front-loaded and no sentence is pure filler, but the middle section is a dense run-on field dump ('and the ladder — free runs a day, the run pack (product_id, price, how to buy) and the Lab month (subscribe)') that resists parsing. Structure could be a short list rather than em-dash chains.

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

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

For a no-parameter read with an output schema available, the description covers what an agent needs: auth requirement, safety posture, and the semantic meaning of the main fields. Remaining gaps are minor — the meaning of 'the ladder' and 'house'/'holder' access states is only gestured at.

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 there is no parameter semantics to add; the schema is empty and fully covered by definition. Baseline 4 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 makes clear this returns the caller's own access/entitlement state, enumerating the concrete fields (studio, access, current_period_end, tier, full_access, run pack, Lab month). It also distinguishes the free-run-count case by pointing to free_tier_status. It falls short of 5 because the verb is implicit — it never literally says 'returns your subscription status'.

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

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

Usage is only implied: the auth prerequisite (JWT or rk_ key) is stated, and the final clause routes today's-run-count questions to free_tier_status. There is no explicit statement of when to call this versus page_me, studio_doors, purchases_mine, or subscribe.

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

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

Annotations already declare a safe read (readOnlyHint=true, destructiveHint=false) and nothing here contradicts that. The description adds real behavioral context beyond annotations: the default listing is core-only, every tool is callable even when unlisted, and a `query` hit returns one line in the form name · title · toolset.

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 tightly front-loaded — the core-only limitation comes first, then each argument's effect — with no filler sentences. The telegraphic style ('No arguments: the toolsets with counts.') is efficient though slightly clipped for a first-time reader.

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

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

For a three-parameter discovery tool with an output schema, this covers all four invocation modes and the returned shape well enough to call correctly. The only blemish is that the set list in the prose omits `core` and `all` that the schema's `toolset` description does include, a small inconsistency an agent must reconcile.

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 a 3 is the floor, but the description genuinely adds meaning: `query` words are matched against every tool's name, title *and* description and returns one line per hit, `toolset` returns 'one set in full', and `name` returns the complete definition including inputSchema. This goes past the per-parameter schema strings rather than repeating 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 the resource (the tool catalog) and contrasts it with the built-in `tools/list`, which only carries the `core` set: 'this finds the rest'. It then enumerates the four distinct modes (no args, `query`, `toolset`, `name`), so an agent knows exactly what each call returns 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 gives concrete routing guidance per mode — search by words, load a full set, load one definition and 'call it next' — plus an alternative mechanism (?toolset=... on the server URL, or `all`) for connect-time listing. It never states when *not* to use this tool (e.g. that `tools/list` should be preferred for core), which keeps it from 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 readOnlyHint/idempotentHint already covering safety, the description still adds substantial behavioral context: signed-in callers see only their own traces, unauthenticated callers can read a PUBLIC rig's run only if they hold the id, runner identity is stripped, and everything else returns not-found. That is exactly the kind of access-control and failure-mode detail annotations cannot express.

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 verb and scope, then the auth rules and REST twins, so an agent can stop reading early. It is dense but occasionally redundant, and the embedded extra spacing/line breaks make it slightly harder to parse than a clean sentence flow.

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?

An output schema exists, so return contents needn't be enumerated, and the description still spells out what each mode yields (input/result/status/timing vs status/steps/output/every trace) plus auth and REST equivalents. Nothing needed 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 description coverage is 100% and both parameters are already documented as UUIDs with 'Pass this OR id' in the run_id field. The description restates the id/run_id choice without adding format, precedence, or default behavior when neither is supplied (required count is 0), so it stays at 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?

States a specific verb and resource plus the two access modes: 'READ one trace in full (input, result, status, timing) by `id`, or a whole run by `run_id`'. That's concrete enough to separate it from trace_search behaviorally, though it never names trace_search as the lookup alternative, so an agent must infer which sibling finds the ids.

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?

Explains when each mode applies: single trace by id vs an entire run by run_id, plus the auth branching (signed in = your traces, no token = public rig). It does not state prerequisites for obtaining the ids or point to trace_search for discovery, so guidance is clear but not complete.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is carried by structured data. The description adds genuinely useful context beyond that: ordering, the signed-in vs anonymous access model, that the runner's identity is stripped on public reads, and that a private run returns not-found rather than forbidden (an anti-enumeration detail an agent would otherwise misread as an error).

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 purpose is front-loaded and the filter list is dense with signal, but the prose is one long run-on paragraph with line-wrap artifacts mid-sentence, and the run_id explanation is given twice (once in the filter list, once in the anonymous sentence). The 'makes the run untestable' clause is motivational padding rather than operational information.

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

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

With an output schema present, return values need no explanation, and the description covers the remaining burden for a 7-param, zero-required filter tool: every filter's purpose, the auth/anonymity model, privacy failure semantics, and default ordering. Nothing an agent needs to call 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 100%, so the baseline would be 3, but the description supplies intent the schema lacks: parent_trace_id is framed as 'the STEPS under one run' for spotting guard-skipped steps, run_id is tied to the exact value rig_run and POST /api/rigs/run return, and trace_kind is explained as containers vs steps. It also states that run_id works anonymously for public rigs, which is not derivable from 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 definition uses a specific verb and resource ('List your Traces') plus scope and ordering ('newest first'), and explicitly positions itself against the sibling rig_run as 'the other half' — the run reports start, the trace reports the outcome. An agent knows immediately this is the read-side inspection tool rather than the execution 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?

It states when to reach for it (to learn whether a rig run actually worked, and which steps a guard skipped) and names rig_run as the counterpart, plus when anonymous access applies and which filter to pass. The gap: it never mentions trace_get, so the choice between listing traces and fetching one trace 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?

Annotations only declare readOnly/no-destructive; the description goes well beyond by disclosing cost and quota tiers, what the Lab's reply_sample is bounded to, that limits on what a public-API sample can prove are declared, and that it returns `result_url`. That is exactly the behavioral context an agent needs before spending a paid call.

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?

One dense paragraph, front-loaded with the verb and output shape, then mechanics, then pricing. Nearly every clause earns its place, though the parenthetical engagement-unit arithmetic ('reply 13.5 · quote 1.5 · repost 1.0 · like 0.5') is closer to marketing detail than invocation guidance.

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-param read tool with an output schema and readOnly annotations, the description covers modes, cost, quota, sampling limits, and the returned link. Only edge behavior (unknown handle, exhausted quota response) is left unstated.

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: `deep` is scoped to the Lab, returns a bounded reply_sample, and runs on its own daily lane (implying separate quota), while `handle` accepts an X handle with or without the @.

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: 'give it any X @handle and get an organic-ness audit', then names the concrete artifacts (0–100 score, ORGANIC/MIXED/SMOKE verdict, anchor in engagement units). No sibling in the list does anything comparable, so the agent can route here unambiguously.

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?

Explains the two modes clearly — default audit vs `deep: true` which adds the reply sample for quality judgement — and states the quota ('one free audit a day', then $0.02 in packs of 50, signed-out returns the price). It does not name a when-not-to-use case or point at any alternative tool, which keeps it below a 5.

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