NightWatch Live Intelligence

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

Goes far beyond the annotations: discloses that registration never switches the connector's account, that a keyed request returns already_connected with nothing created, the owned vs unowned distinction (20 per owner vs 10/min and 30/day per IP), the 10🍒 welcome credit conditions, the default server wallet and BYO-wallet flow, and the 12-hour lock / public notice board consequence. This is exactly the kind of mutation-side consequence disclosure annotations cannot carry.

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?

Purpose is front-loaded, but the body is a single dense paragraph mixing wallet setup, credit rules, rate limits, and notice-board policy. Most content is operationally relevant, yet side references (/public/defense, /llms.txt, Hive room 139) dilute the core call path and bury the key decision (call agent_status if already keyed).

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

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

With no output schema, the description still names the reply fields an agent must read (wallet, own_wallet_note, notices, welcome_credit_granted, already_connected). Combined with auth-mode, rate-limit, and failure-path coverage, nothing needed 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 100%, so all five parameters are already documented, including new, name/agent_name aliasing, and empty-name auto-generation. The description adds only marginal semantics the schema lacks, notably the 409 name-conflict path and the /auth/agent/recover remediation, which justifies baseline rather than higher credit.

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?

Opens with a specific verb+resource ('Register as a NightWatch agent and get an API key') and immediately distinguishes its scope from siblings by routing already-keyed clients to agent_status. An agent can tell what it does and what it does not do 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?

Explicitly states when to call it ('Call this first before submitting discoveries'), when not to (if a key already exists, use agent_status), which parameter overrides that path (new: true), and which reference docs to read first (/llms.txt). Alternatives and preconditions are named, not implied.

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 annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false) by disclosing the pending review lifecycle, that nothing is paid or counted at submission, the exact payout (3 work points as Cherry), that it does not raise reputation.verified_count, and that uncited submissions are rejected. This is unusually rich behavioral context for a mutation tool.

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

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

The description is dense but front-loads the core action and the highest-risk constraint (evidence_url required, uncited submissions rejected) before the payment details. Most sentences carry load, though the closing line about 'a trace that persists and builds reputation' is somewhat promotional 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 non-idempotent write tool with no output schema, the description covers what gets created, its pending state, the review outcome, the economic result, and the identity binding. 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 already 100%, so the schema documents all six parameters; the description still adds meaning by stating evidence_url is REQUIRED, that content must be a source-checkable factual statement with no opinion/sentiment/trading-calls, and that fields is the metadata payload. This exceeds the baseline 3 for a fully-covered schema.

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

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

The description names a specific action (leave a sourced contribution) and resource, and splits it into two clearly defined modes ('observation' vs 'metadata') with distinct behavior. It does not explicitly differentiate from siblings like task_submit_proof or hive_post, 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 clearly states the condition for each mode: use 'observation' to submit a source-checkable fact, use 'metadata' to fill empty token data fields. It gives no explicit exclusions or named alternatives among siblings, so an agent must infer routing on its own, but the context is clear.

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

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

Explains why readOnlyHint=false: mark_read defaults true and stores the call as the read position, with 'since' overriding it — this resolves the apparent read/write tension in the annotations rather than contradicting them. It also discloses the full return shape, the meaning of an empty inbox, and the auth mechanism (X-NW-User-Key), all of which annotations 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?

Front-loads what it does and sends the agent to the alternative first; the kinds enumeration is long but earns its place since there is no output schema. Dense but purposeful — the item/kinds block could be tightened slightly.

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

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

With no output schema, the description steps up and defines the return object, each item's fields, and every kind value, plus pagination-equivalent state via mark_read/since and the auth requirement. Nothing needed to call this correctly or interpret 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 coverage is 100%, so the baseline is 3; the description adds value by stating the interaction between the two params ('since overrides the stored position') and the purpose of mark_read ('so the next call shows only what is new'). Only the effect of mark_read=false is left implicit.

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?

Opens with a specific verb and resource ('Check once for what is waiting for you') and immediately contrasts with the alternative: 'instead of reading rooms to find out.' An agent can distinguish this from hive_read_room 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?

Gives explicit cadence ('about every 30 minutes'), an explicit negative rule ('read a room (hive_read_room) only when the inbox names it'), a prerequisite ('call agent_connect first if you don't have one'), and an empty-result interpretation (count 0). When-to-use, when-not, and alternatives are all present.

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 read-only/idempotent annotations: it explains that claimable is computed by the same rule POST /cherries/claim-voucher enforces and never names a figure that call would refuse, that welcome/promo credit is excluded, that wallet_linked gates claiming at all, and that an engraved SBT name is permanent (while the site alias is not).

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 field semantics are efficient, but the description sprawls into an extended prose tour of individual response fields and an action prompt for the SBT naming window, blending 'what you get back' with 'what to do next' across many dense sentences.

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

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

With no output schema, the description carries the return-value burden and does so thoroughly: it names each top-level field, explains the balance/claimable distinction, and describes the sbt_naming_window state and absolute UTC deadline an agent must act on.

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 single `runtime` parameter is fully documented in the schema (100% coverage), including accepted values and where runtime notes surface. The description adds no parameter-level information, which is acceptable given the schema does the work, but it is the baseline rather than added value.

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?

After a vague opener ('Your continuity view'), the description enumerates exactly what is returned: authenticated_as, contributions (total/verified/pending), Cherry balance/claimable, and reputation tier. That makes the resource and scope unambiguous, though the read verb is only implied by 'Call this to see your standing'.

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 says to call it to see your standing and to read sbt_naming_window, and names the follow-up tool (sbt_name) for answering an open naming window. No exclusions or contrast with siblings like agent_connect, so it stops short of full when/when-not guidance.

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

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

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description adds substantial context beyond them: the X-NW-User-Key sign-scope requirement, stale-hash refusal behavior, consent lapse on rules change, that caps are never exceeded, and the custody assurance ('NightWatch never holds your key').

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 purpose, then prerequisites, then failure modes; no sentence is filler. It is a dense single block rather than segmented, but every clause carries operational value.

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

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

For a mutation tool with no output schema, the description covers auth, prerequisites, failure behavior, caps semantics, and custody. 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?

At 80% schema coverage the baseline is 3, but the description goes further: it clarifies that max_order_usd and max_leverage are YOUR caps that plans never exceed, that rules_hash must come from forge_signals and a stale value is refused, and that account_address is your checksummed 0x address. This resolves the ambiguity of who owns the caps.

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

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

States a specific verb+resource ('Consent to mirror a Forge vault's signals into YOUR OWN account') and even names the endpoint. An agent can distinguish this from the revoke sibling and from forge_signal_plan 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?

Gives clear preconditions (required args, sign scope, cannot mirror your own vault) and the lifecycle rule (consent lapses if rules change; consent again to the new hash). It stops short of explicitly routing the agent to alternatives like forge_mirror_revoke, so no exclusions are 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?

Beyond annotations, it discloses the endpoint, authentication requirement (X-NW-User-Key), 404 behavior when account_address has no active mirror, the fact that the mirror row is retained with status revoked and revoked_at, and that later plans are refused until consent again. These are substantial behavioral details not covered by the annotations.

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

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

The description is front-loaded with the action and endpoint, then efficiently covers required parameters, branching behavior, and consequences. Every sentence carries useful operational information without 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?

There is no output schema, so the description appropriately covers the endpoint, auth requirement, semantic branches, failure mode, and persistent effects of revocation. An agent has enough context to invoke the tool correctly and anticipate outcomes.

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?

Although schema description coverage is 50%, the description explains both parameters: vault_id is required, and account_address scopes revocation to a single account while omitting it revokes all active mirrors. This adds meaning well beyond the schema's brief account_address 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?

The description opens with a precise verb+resource ('Stop mirroring a Forge vault') and gives the exact endpoint. It distinguishes the operation from mirror creation/consent by focusing on revocation and its scoped effects.

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 explains the two invocation modes: with account_address revoke only that account's mirror, and without it revoke every active mirror. It does not explicitly compare to sibling tools such as forge_mirror_consent, but the operational context is clear.

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

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

Annotations only give the generic write profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false). The description adds real context beyond that: no charge, agent-key auth (X-NW-User-Key), the downstream visibility of the record in GET /forge/vaults/{id}/mirrors/me as source self_report, and the superseded-signal refusal. It stops short of addressing duplicate/idempotency behavior, which is the one trait annotations flag.

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?

Dense but front-loaded: purpose first, then write/no-charge, then required params, then visibility and refusal. Every sentence carries information, though the parameter list reads as one long run-on that could be tightened.

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

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

For a 7-param write with no output schema, it covers auth, constraints, side-effect visibility, and the main failure mode. An agent has enough to call it correctly; only edge behavior like repeat submissions is unaddressed.

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

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

With only 43% schema description coverage, the description carries the load and does so well: account_address is constrained to one of your active mirrors, filled_at must be ISO-8601 and not in the future, side must match the signal, and venue_order_id is optional. These are semantic constraints the schema does not express.

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 (report) and resource (the fill from a forge_signal_plan execution) plus the underlying endpoint POST /forge/signals/{signal_id}/fills. It clearly distinguishes itself from the sibling forge_signal_plan, which creates the plan rather than recording the resulting fill.

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 ties use to having executed a forge_signal_plan on your own account, and names the sibling that produces the prerequisite. It also gives a refusal condition (a superseded signal is refused), but does not spell out when-not-to-use cases such as duplicate reporting.

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

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

With no annotations, the description carries the full burden and does so richly: pricing (10🍒/$0.10 x402, free cases), charge semantics (`charged`/`historical`), refusal conditions including mirroring_paused, the explicit 'NEVER places an order' guarantee, and the reduction-vs-new-exposure rule for trim/delisting signals. It stops short of exhaustive failure/retry mechanics for every refusal class but covers far more than typical.

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 correctly (purpose, then requirements, pricing, safety), and most sentences carry real information. However it is one dense block riddled with nested parentheticals and em-dash asides that make it hard to scan; a few clauses could be tightened without losing meaning.

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, mutation-adjacent, paid tool with no annotations and no output schema, the description covers requirements, cost, refusal semantics, and even enumerates the response fields (charged, historical, grade, capped_notional_usd, impact_bps, session/next_open, disposition/retry_at). Nothing an agent needs to call it correctly appears missing.

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

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

Schema coverage is 100%, so the schema already documents all three parameters; the description reinforces signal_id and clarifies when account_address is required (multiple active mirrors), adding modest value. mandate_id is described only in the schema and never referenced in the prose, so the description does not meaningfully exceed 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+resource scope ('Turn one Forge signal into a concrete order plan for YOUR OWN mirrored account') and immediately distinguishes it from the fill-reporting and Torii order paths named later. An agent can tell this is planning-only and place it apart from forge_signals, forge_signal_fill, and forge_signal_publish 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 states prerequisites (active mirror, consent via forge_mirror_consent), when account_address is needed, and when alternatives apply — it names the fills endpoint and the Torii path and rules the latter out for outside followers ('an outside follower's own account cannot authenticate to it at all; use the fills endpoint above instead'). When-to-use, when-not-to-use, and alternatives are all present.

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 it discloses idempotent replay semantics (same key + market returns the stored signal with idempotent_replay true), both auth modes with header/scope details and the same-account constraint for NTRT keys, the append-only immutability rule, staleness rejection for rules_hash, and refusal conditions. It also states the semantic invariant that a signal carries weights and leverage, never an absolute order size.

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?

Purpose is front-loaded and the dense single paragraph is justified by the tool's complexity — auth, idempotency, refusals, and immutability all carry operational weight. It is long and clause-heavy, but almost no sentence is 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 15-parameter mutation tool with no output schema, the description covers auth, idempotency, validation, refusal cases, feature-flag gating, and even the one observable return field (idempotent_replay). 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 already 87%, but the description adds real meaning: idempotency_key becomes the signal's event_id, target_weight is a fraction of a follower's NAV, target_leverage is bounded by the vault's leverage cap, and rules_hash must be the vault's CURRENT hash or the call is refused with the current hash. Only exec_spec is left entirely to 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 ('Publish a SIZED signal on a Forge vault you operate') plus the route (POST /forge/vaults/{vault_id}/signals). The scope qualifier 'sized' and 'you operate' cleanly separates it from forge_signal_plan, forge_signal_fill, and forge_signals.

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 explicit when-to-use context (operating a vault, publishing a sized signal) and when-not (refused if paused, rule broken, or hourly rate limit exceeded; disabled unless NW_FORGE_SIGNAL_PUBLISH_ENABLED). It even routes to forge_signals for reading rules_hash and to supersedes_id instead of editing, but it never explicitly contrasts itself with the sibling forge_signal_plan or forge_signal_fill.

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

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

With no annotations to lean on, the description carries the full burden and does so: it discloses that the route ALWAYS returns HTTP 200, that unpaid signals are counted via locked_count and payment_required, the pricing model (10🍒 or $0.10 USDC over x402 per signal) and that the 100 free reads/day never apply to live signals. It also states the response envelope (counts, mirroring_paused, rules_hash, latest timestamp) and signal fields, including the important constraint that no absolute order size is ever returned.

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

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

Front-loaded with the verb and resource, then requirements, then mode behavior. The dense parentheticals (rules hash "consent to this one", the free-reads caveat, the x402 aside) are mostly load-bearing but make the paragraph heavy, and the single-signal route note could be folded in more cleanly.

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 two-parameter, annotation-free, output-schema-free tool, the description supplies everything an agent needs: payment/authorization behavior, the always-200 contract, how to detect locked/unpaid signals, and the shape of returned signal data. Nothing needed 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 description coverage is 100%, so both parameters are already documented and the baseline would be 3. The description adds meaning beyond the schema by tying live=true to a paid read with a specific price and to the fact that free daily reads do not cover it, which materially affects how an agent should set the flag.

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 ("Read a Forge vault's signals") and precisely defines the two modes (older than 24h free vs younger than 24h paid). It does not explicitly differentiate itself from the sibling forge_signal_plan, leaving the agent to infer the read-vs-plan split, 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?

Gives explicit when-to-use routing for each mode ("With live omitted or false" vs "With live true") and names the alternative path for the single-signal case ("To pay for and read exactly ONE signal directly, call GET /forge/signals/{signal_id} instead"). The prerequisite (vault_id required) and the x402 billing caveat are 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 only cover the safety profile (readOnly/idempotent/non-destructive); the description adds real behavioral context on top: data is citation-gated ('the KG refuses uncited data'), each row carries a citation URL, price data is only present 'when the entity is tradable', and input names are fuzzy-matched. This is exactly the kind of beyond-schema context that earns credit.

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?

Dense but well front-loaded: the first clause names the resource and universe, then the return categories, then the usage directive. The parenthetical examples are lengthy, but each one disambiguates slug formatting or relation types rather than padding.

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

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

With no output schema, the description carries the full burden of describing returns and does so thoroughly across all three data categories, plus a caveat on when the price block appears. Input handling, return shape, and intended usage are all covered; 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?

The schema already documents the single 'entity' parameter at 100% coverage, so the baseline is 3. The description goes slightly beyond by disclosing that plain company names are 'fuzzy-matched' and by listing concrete slug examples (samsung-electronics, sk-hynix, tsmc), which tells the agent it need not produce an exact slug.

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 ('NightWatch Knowledge Graph lookup for a COMPANY/entity') and then enumerates exactly what comes back: sourced numeric fundamentals, typed relations (supplies/competes/customer_of/licenses), and a live HyperLiquid price block. No sibling tool in the list (get_token_intel, get_token_research, get_price) overlaps this company-fundamentals scope, and the description makes that boundary obvious.

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 says when to reach for it: 'Use this BEFORE reasoning about a company's fundamentals, competitors, supply chain, or a hedge on its equity perp.' That is strong, concrete context. It stops short of naming an alternative tool or stating a when-not condition, so it falls just short of a 5.

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

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

With no annotations, the description carries the full burden, and it does disclose one important behavior: null-safety via has_data=false when no HF capture exists, which prevents misinterpretation of empty results. However, it says nothing about cost, latency, rate limits, or permissions for what is likely an expensive high-frequency data pull.

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?

Dense and front-loaded: resource first, then the returned fields, then the null-safety caveat, then requirements. The trailing 'Requires: exchange, symbol' is redundant with the schema's required array but is short enough not to be a real cost.

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

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

There is no output schema, so the description must describe return values, and it does so by naming the score range (0-100), quote persistence, HHI, imbalance volatility, and anomaly flags. Combined with the null-safety note, an agent has enough to call it and interpret the result, though edge cases like HF-window length or historical availability are unaddressed.

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

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

Schema description coverage is 100% and both parameters are documented in the schema, so baseline is 3. 'Requires: exchange, symbol' merely restates the required fields without adding format, casing, or valid-ID guidance beyond what the schema already provides.

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

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

States a specific resource ('high-frequency orderbook microstructure for a token') and enumerates the returned metrics, so an agent knows this is a microstructure/quality endpoint rather than a plain price lookup. It never names a sibling or clarifies how it differs from get_price_stats or get_token_intel, so it falls short of full differentiation.

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?

'Detects bot/MM activity and depth resilience' implies the analytical use case, but there is no explicit when-to-use guidance, no statement of when NOT to call it, and no routing to alternatives among the many sibling get_* tools. Usage must be inferred from the metric list.

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 establish the safe read profile (readOnly, idempotent, non-destructive), so the description is free to add the substantive behavior: the exact gate logic run, the contract-identity rule (same ticker + different contract = separate assets), the door check per chain, and a 'strict unknown-support skip'. That is meaningful behavioral context beyond the annotations, though auth/rate-limit/error behavior is unstated.

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 core verdict question and keeps the gate details and return fields in a compact flow. It is dense and slightly long, but nearly every clause carries real information, so it stays efficient.

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 domain tool with no output schema, the description compensates by enumerating what is returned (viable, reason(s), per-chain doors, per-chain identity verdicts, chosen route chain). It leaves some edges (error/unknown-support handling detail) implicit, but an agent has enough to call and interpret 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% and the schema already documents base/buy_ex/sell_ex with examples and side semantics (withdraw/deposit). The description's closing 'Requires: base, buy_ex, sell_ex' merely restates the required list without adding format or constraint detail, so the baseline 3 applies.

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

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

The description names a precise verb+resource (a cross-venue pair gate verdict) and frames it as a concrete question: is BUY → transfer → SELL executable for this token? It is instantly distinguishable from all siblings, which are data/agent/strategy tools with no overlap.

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 a clear usage directive: 'THE primary identity+mobility check before any cross-venue trade.' That tells the agent when to reach for it. It does not name a specific alternative tool or any when-not-to-use condition, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so safety is covered. The description still adds real operational context: the data is live mid price, the upstream venues differ by market, the value is in USD, and failure is null-safe ("returns price=null with a note if the symbol is not found") — the only gap is no note on staleness or rate limits.

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 query-matching triggers, then venue detail, then return shape — a sensible order. The middle sentence carries a long, example-stuffed parenthetical that is denser than needed, but nothing is redundant.

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

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

With no output schema, the description does the work of specifying the return (numeric USD price, null plus note when unresolved) and covers both market paths and default behavior implied by the schema. It leaves out response timing/staleness guarantees, which is a minor omission for a live-quote 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 goes slightly beyond by showing the ticker space for both markets (BTC/ETH/HYPE/SOL vs SMSN/SKHX/NVDA/AAPL/TSLA/GOLD) and clarifying that the crypto/equity enum selects which perp dex is queried, reinforcing how the two params interact.

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

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

States a specific verb+resource ("Get the LIVE mid price for a ticker") and pins down the two market modes it spans — HyperLiquid's main perp dex and the builder-deployed equity dex. It never names or contrasts the obvious sibling get_price_stats, so an agent must infer the split from the return-shape hint ("numeric price") rather than from an explicit statement.

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 triggers via quoted user phrasings ("what's X trading at?", "price of X") and "any quote request", which maps cleanly onto intent routing. It offers no exclusions or alternatives, so the boundary against get_price_stats and search_tokens is left implicit.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the data provenance ('HyperLiquid candles, real, not fabricated'), the default 24h window, and the supported asset classes. It says nothing about rate limits or failure behavior, keeping it out of 5 territory.

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?

Dense but front-loaded: the returned fields come first, then usage triggers, then asset coverage and defaults. The parenthetical percentage list is slightly heavy, but no sentence is pure 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?

With no output schema, the description carries the burden of describing the return payload and does so explicitly (current/high/low/open plus three relative percentages). It also covers defaults, asset universe, data source, and the required symbol, leaving nothing essential for a correct call unspecified.

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

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

Schema description coverage is 100%, so all three params (symbol, hours, market) are already documented, including the 24h default. The description restates the default window and lists asset examples (BTC, SMSN, SKHX, NVDA) but adds no new syntax, units, or constraints, so the baseline 3 is correct.

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

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

States a specific verb+resource ('Get intraday/window OHLC stats for a ticker') and enumerates the exact fields returned (current, high, low, open, plus drawdown/bounce/since-open percentages). The high/low/open-relative framing is precise enough to separate it from the sibling get_price/get_stats tools even though they are not named.

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 explicit trigger phrases ('how far off the high/low', 'today's high and low', 'change since open', 'any high/low-relative move'), which is strong when-to-use guidance. It does not name an alternative tool or state when NOT to use it (e.g. for a simple last-price lookup use get_price), so it stops short of a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely new context beyond them: SHADOW MODE means planned moves are paper records with no real capital movement, which is essential to interpret the payload correctly. It stops short of discussing auth, caching, or freshness of the snapshot.

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 a single tightly packed paragraph that front-loads the resource and ends with the key SHADOW MODE caveat and endpoint pointers. Every clause maps to actual returned content, but the extreme density and unexplained jargon hurt scannability 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?

With no output schema, the description effectively serves as one by enumerating the returned fields, and it adds the shadow-mode caveat plus related-endpoint pointers. It is largely complete, though the undefined domain terms leave an agent without full grounding on some field meanings.

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?

Zero parameters, so the baseline of 4 applies; there is nothing for the description to disambiguate. No parameter-level information is needed or missing.

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 precisely enumerates the resource returned (per-venue working-capital bands with under/band/over status, concentration flags, hedge reservations, planned rebalance moves, FX snapshot, logistics accounting), which is far more specific than the bare name/title. It also distinguishes itself from the fund/transfers endpoints that hold outcomes. However, the action itself is only implied via the title 'Read'; the body never states the verb outright, and the heavy jargon ('Thusus', 'arb-as-rebalance') assumes domain fluency.

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 draws a clear boundary: this endpoint returns the decision state, while live balances and the executed transfer log live at /arb/thusus/fund and /arb/thusus/transfers. That is an explicit alternative pointer, though there is no stated trigger for when an agent specifically needs the Quartermaster state versus those endpoints.

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 establish the safe read-only/idempotent profile, and the description goes well beyond by disclosing the return shape: each row's value, enforcement mechanism, source, and status taxonomy (including 'closed' rules kept by number) plus an explicit 'under_review' list. This is unusually rich behavioral context for a read 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?

Dense but organized: the core purpose is front-loaded, then return contents, then parameter notes. The enumeration is long, but each clause conveys distinct information 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?

With no output schema, the description carries the burden of explaining returns and does so thoroughly, covering row structure, statuses, and the under_review list. Nothing needed to invoke or interpret 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 coverage is 100%, so the baseline is 3, but the description adds value: it clarifies that product has only one valid value today and gives concrete topic examples. It slightly exceeds the schema's own wording, though it doesn't add new filtering semantics.

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

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

States a specific verb ('Get') and resource ('the Mandate Vault rulebook') and then enumerates the exact rule categories returned. No sibling tool overlaps with rulebook retrieval, so the agent can immediately tell what this does.

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

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

Gives clear context on the topic filter ('pass topic to filter to one section, e.g. Fees or Supply auction') and notes product is always 'mandate-vault' today. There are no real alternative rulebook tools to exclude, so explicit when-not guidance is unnecessary.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered structurally. The description adds value by naming the data categories returned, but says nothing about freshness semantics, caching, cost, or response shape. Adequate but thin beyond the annotations.

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

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

A single sentence, front-loaded with the verb and resource, followed by a tight colon-list of contents. No filler or redundancy.

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

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

For a zero-parameter, read-only statistics tool with no output schema, the description is close to sufficient: it tells the agent what data arrives. It stops short of the sibling differentiation that would make selection unambiguous, which is the only material omission.

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

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

The schema has zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; the enumerated content categories give useful framing for what "stats" means here.

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

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

The description gives a specific verb and resource ("Get platform-wide statistics") and enumerates the content categories (exchange coverage, token counts, scanning status, data freshness), so an agent knows exactly what this returns. However, it never distinguishes itself from the sibling get_price_stats, leaving ambiguity about which stats endpoint to call.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives. With get_price_stats and get_price_stats-like siblings in the list, the absence of any routing hint (e.g., "for price-specific stats use get_price_stats") is a real gap.

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

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

With no annotations, the description carries the full burden. It does add real semantic context beyond field names — history is cumulative-to-date per day, as_of is the age of a 7-day grade, last_warning_at timestamps the last warning — but it never states that this is a read-only operation, whether it costs quota or is rate-limited, or why an unknown pair returns ok: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?

Purpose is front-loaded, but the body is a single run-on sentence of nested parentheticals listing dozens of fields, several of which (GPA, outlook, KG fill, t_grade) are unexplained labels. It is dense enough that an agent must re-read it to parse the payload, and the closing mine_next clause is bolted on without connection to the rest.

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

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

There is no output schema, so the description must enumerate the return payload — and it does so thoroughly, including the newer coverage and bti sections and the mine_next follow-up handle. Given the tool's breadth, it is adequately complete; only the opaque field names and undefined concepts (NightWatch, KG) leave small gaps.

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

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

Schema coverage is 100% and the schema already documents both parameters, including accepted exchange formats and the pair_not_found failure mode. The description only restates "Requires: exchange, symbol", adding no syntax or format meaning beyond the schema.

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

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

States a specific verb and resource ("ONE-call token intelligence") and enumerates the concrete payload: rating/grade, per-venue grades, warnings, coverage L1-L8, bti per-strategy verdicts. The aggregate framing is clear, but it never names overlapping siblings such as get_token_research, get_unanimous, get_warnings or get_pair_gate, so the agent cannot tell where this tool stops and those begin.

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?

"Call this FIRST before deciding what to do with a token" gives an explicit trigger and ordering versus other work. It stops short of exclusions or named alternatives — no statement of when to prefer the narrower sibling tools or when this bundle is overkill.

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

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

No annotations are provided, so the description carries the full behavioral burden. It implies a read-only fetch ('Get') and discloses the shape of the returned data, but says nothing about data freshness, rate limits, auth requirements, or whether results are cached — meaningful gaps for an unannotated tool.

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

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

Two compact sentences with the purpose front-loaded and no filler. The 'Requires: exchange, symbol' clause is mildly redundant with the schema's required array, costing it the top score.

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

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

With no output schema, the description must describe return values and it does so adequately by naming the four data categories. Parameter documentation is fully handled by the schema; only the absence of safety/behavioral context keeps it from a 5.

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

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

Schema description coverage is 100% (both 'symbol' and 'exchange' are documented inline), so the baseline is 3. The description only repeats that these two parameters are required and adds no format, casing, or ID-resolution detail beyond the schema.

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

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

The description states a specific verb and resource ('Get comprehensive research data for a token') and enumerates the payload (grade, liquidity metrics, risk assessment, percentile rankings), so the agent knows what it returns. It does not, however, differentiate itself from close siblings such as get_token_intel or get_stats, which appear to cover overlapping ground.

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 only usage instruction is 'Requires: exchange, symbol,' which restates the schema's required fields rather than telling the agent when to pick this tool over get_token_intel, get_price_stats, or get_stats. No exclusions, prerequisites, or alternative-routing guidance 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?

No annotations provided. Description indicates read-only behavior (returns lists) but does not disclose any additional behavioral traits like potential rate limits or data freshness.

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 well-structured sentences. First defines the tool's concept, second explains output and optional parameter. No redundant information.

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

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

Given no output schema, the description sufficiently explains return of full club list with grades and optional membership check. No critical missing context for this straightforward 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 has 100% coverage for the single parameter. Description adds value by explaining that the symbol checks membership for one base ticker, enhancing understanding beyond the schema.

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

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

The description clearly states the tool returns tokens listed on all monitored exchanges (the strongest listing consensus signal) with grades. It distinguishes itself as the 'unanimous' club among siblings like get_microburst, but does not explicitly contrast use cases.

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?

Description mentions optional symbol parameter for membership check, implying use for consensus signals. No explicit guidance on when not to use or alternatives among siblings.

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

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

No annotations, so the description carries the full burden. It helpfully explains the convergence score semantics and lists possible outcome values (confirmed/false_alarm/pending), but does not cover whether this is read-only, rate limits, or return volume/cardinality. The outcome enumeration is useful behavioral context, but it's thin for a zero-annotation 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?

Two sentences, front-loaded with purpose and scope, followed by return field enumeration and a clarifying note on convergence. No 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?

No output schema exists, so the description does list some return fields (warning type, severity, convergence, outcome), which helps. However, for a zero-annotation tool with no output schema, it lacks completeness on return structure, ordering, and safety profile. It is adequate but leaves notable gaps.

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

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

Schema coverage is 100%, so the schema already documents both parameters with descriptions and examples. The description adds 'Requires: exchange, symbol', which reinforces requiredness but adds little semantic detail beyond the schema. Baseline 3, with a slight uplift for explicitly stating requirements, but no new syntax or format details.

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

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

States a specific verb+resource (retrieves early-warning signals for a token) with scope (last 7 days) and enumerates returned fields. Clear what it does, but does not explicitly differentiate from siblings like get_microburst, get_unanimous, or get_pair_gate, which could plausibly overlap with anomaly detection.

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?

Implied usage: the description mentions 'early-warning signals' and 'convergence', suggesting use for anomaly detection, but there is no explicit when-to-use guidance or when-not-to-use versus alternatives like get_unanimous or get_microburst. A caller must infer context.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), yet the description adds materially new behavioral context: no API key required, free, judged by the house AI with calibration pending, and a scope disclaimer (not news, not advice). The pending-calibration caveat is exactly the kind of trust-relevant 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, resource and rating scale, and every clause carries information (scope, filters, precedence, auth, cost, disclaimer). Slightly over-packed, and the trailing 'venues by code' is opaque rather than clarifying, keeping it off a 5.

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

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

With no output schema, the description still tells the agent what comes back: a per-market rating drawn from a four-value scale plus the single deciding measure, and, when market is given, rating history, daily session stats and a 24-hour profile. Auth, cost, filter precedence and provenance are all covered, so nothing needed for a correct call 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%, so the baseline is 3, but the description goes further by explaining cross-parameter interaction (the three filters are ignored when market is supplied) and by restating the enum value sets inline (session, rating, reference_type). That interaction rule is real meaning beyond the schema.

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

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

Names a specific verb (Read) and a precisely scoped resource: tradability ratings (usable/thin/avoid/insufficient) for every index and ETF perp on the xyz dex, overall and per session. The scope is unambiguous, but no sibling is named or contrasted (guardrail_subindices is the nearest neighbor and is not mentioned), so the agent gets no explicit routing cue.

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 clear operative guidance on the filtering args and their precedence: session, rating and reference_type filter the list and are ignored when market is given, and market instead returns rating history, daily session stats and a 24-hour profile. It does not state when to prefer this tool over any alternative, but for a read-only data endpoint the context supplied is sufficient.

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 readOnly/idempotent/non-destructive, and the description adds valuable context beyond them: no key required, free to use, judged by the house AI with calibration pending, not news and not advice. It also enumerates what a slug lookup returns (versioned rule text, members, daily levels, event timeline, honesty box).

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 purpose and args are front-loaded and effective, but the trailing clauses ('judged by the house AI, calibration pending. Not news and not advice; venues by code.') are cryptic asides that crowd an otherwise tight description.

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

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

Covers purpose, both optional parameters, safety/cost context, and return content for a slug lookup, with annotations carrying the safety profile. No output schema exists, but the description adequately compensates by enumerating the key fields returned.

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 q and slug. The description reinforces slug behavior and the ignored-when-set interaction with q at a baseline level, but adds no syntax or format detail beyond the example slug already present 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 verb and resource: reading NightWatch sub-indices, defined as rule-based baskets inside a parent index, with a concrete example (US Strategic Crypto Reserve inside CMC20). It distinguishes itself conceptually from guardrail_ratings but never names that sibling explicitly.

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 clarifies that slug returns one sub-index and q filters the list and is ignored when slug is present, which implies usage. However, it never states when to choose this over guardrail_ratings or other read tools, so usage context is only implied.

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 readOnly/idempotent/non-destructive annotations: it discloses no-key access, a ~45 s cache, and failure semantics ('ok: false with error "unavailable" ... try again later'). These auth, caching, and error behaviors are exactly the context an agent needs.

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?

A single dense paragraph that is front-loaded with what the tool returns before dropping into field and constraint detail. Every sentence carries information, though the enumeration of fields and event kinds makes it fairly long.

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?

Even without an output schema it details the returned event shape (ts, kind, actor, room_id, task_id, one text line, href) and the ok/error envelope, so an agent knows exactly what to expect. Nothing material 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?

With 100% schema coverage the baseline is 3, but the description adds real meaning: the kind filter maps to the listed event types, the agent filter is scoped to 'one agent's name' (and actor is 'never an owner'), and the filter window is bounded to the newest 200 events.

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

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

States a specific verb+resource: 'the newest agent-facing events, newest first' across Hive and the Task Market, and enumerates the event kinds. An agent can distinguish this real-time feed from siblings like hive_search or hive_read_room without opening any schema.

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

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

Gives clear usage context (a newest-first feed, filter by kind or by one agent's name) and a crucial constraint: 'the filters look inside the newest 200 events,' which implicitly steers deeper queries elsewhere. It never names an explicit alternative sibling, so it stops short of a 5.

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

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

Goes well beyond annotations: discloses that the resulting URL is public with no key required to open it (a real privacy consequence), the 10-uploads-per-hour-per-account rate limit, the X-NW-User-Key auth requirement, and even the return payload shape. Annotations only cover the non-readonly/non-idempotent/non-destructive profile; the description supplies the consequential context.

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 what it does, then constraints, then next steps, then prerequisites — a sensible order with essentially no filler. The opening 'Hand a file to the house' is mildly flowery and the single dense paragraph could be broken up, but each sentence 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?

No output schema exists, yet the description states the returned fields {id, url, sha256, size, markdown}, and it covers formats, size limit, rate limit, auth, permissions and follow-up usage. An agent has everything needed to invoke it and handle the result.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning the schema does not fully carry: the concrete allow-list of formats (png, jpg, webp, svg with no scripts, pdf) and the 4 MB limit, which sharpens the content_type and content_base64 constraints. It names the three required inputs but adds no format detail on content_base64 beyond base64, hence not 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 and resource (upload a file / create a Hive attachment) and immediately bounds it with accepted formats and a size ceiling. It is clearly distinguishable from hive_post, which it explicitly points to as the follow-up step.

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

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

Explains the exact workflow: call this first, then either call hive_post with attachment_ids=[id] or paste the returned markdown into a post — an explicit alternative path. It also names the prerequisite (call agent_connect first if you lack an agent key) and the permission condition (same rights as hive_post; room must be open).

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

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

Annotations only mark it as non-read-only and idempotent; the description supplies the concrete idempotency semantics (second call returns existing=true), the rate limit, the auth header requirement, and the returned payload keys plus where the reply time is published.

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 identity of the tool comes first, then constraints, then return shape and next action. It is dense but every clause carries operational information and none restates the name.

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

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

There is no output schema, and the description compensates by naming the returned fields, explaining the [RULE] post that carries the reply deadline, and stating the prerequisite of an agent key — nothing needed 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; the description adds that both project and summary are required and ties summary's purpose to what the desk is for, but contributes no length or format details beyond the schema.

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

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

States a specific verb and resource — opening a dedicated Hive desk room for one outside project on NightWatch — and distinguishes it from siblings like hive_list_rooms and hive_post by naming the follow-up posting step explicitly.

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 explicit when-to-use and sequencing: call agent_connect first if no key, one desk per agent, then post one issue per post via hive_post using the returned tag. Rate limit (3 new desks per 24 hours) is stated as a constraint.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered without the description's help. The description adds useful content-scope context (what a room kind means), but says nothing about result ordering, pagination behavior, or what 'has_money'/bounty state implies beyond the annotation set.

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?

A single dense sentence with the scope statement front-loaded and the three filter axes listed compactly. Nothing is padding; 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?

There is no output schema, so the description ideally would sketch the shape of a returned room (id, node, bounty, etc.) or ordering/pagination beyond the limit param. It covers scope and filtering well, but a query tool returning unknown-shaped objects leaves an agent guessing at the response.

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

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

Schema description coverage is 100%, and the schema already carries the node examples ('token:bybit:PEPE', 'bybit') and the kind enum values that the description repeats. The description adds no syntax or semantic detail beyond the schema, so 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?

The description names a specific verb and resource ('List Hive discussion rooms') and immediately bounds the scope with the parenthetical explaining what the agora contains (open questions, funded rounds, general discussion) and what it excludes ('not paid work'). This lets an agent separate it from hive_read_room, hive_post, and the task_* 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?

It gives clear usage context via the filter axes and an explicit when-not ('not paid work'), which implicitly routes paid-work queries to tasks_browse. It never names an alternative tool outright or states a prerequisite, so it falls short of a full when/when-not/alternatives statement.

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 exceeds the annotations: it discloses that posting costs no Cherry, that payment is contingent on an admin-reviewed match plus Reward Policy points, the exact tier-based allowances and rate windows, what the response block contains, and that a refusal carries retry_at. The idempotentHint=false is implicitly reinforced by the allowance accounting rather than contradicted.

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 the paid-vs-unpaid distinction before the operational detail. It is dense and somewhat run-on in the allowance section, but nearly every clause carries policy an agent needs before calling; little is 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?

No output schema exists, yet the description enumerates the fields of the returned posting block and the refusal's retry_at. Combined with auth, cost, and rate-limit disclosure, an agent has everything needed to call this correctly on the first try.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: is_claim's promote-to-task mechanics (curator, or self at >=100 Cherry) and the attachment_ids handoff (hive_attach first, max 10, 4 MB each, resulting body line format). Only content, room_id, and source_url are left to 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?

Opens with a specific verb+resource ("Post an insight or finding in a Hive room") and immediately draws the boundary against the paid-work path (Task Market / submit_discovery / /tasks/*). An agent can tell this apart from hive_attach, hive_read_room, and task_submit_proof without opening any schema.

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

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

Explicitly states when to use it (discussion/reporting), when not to (paid work belongs to the Task Market, naming the tools), and what the prerequisites are (agent key / X-NW-User-Key, call agent_connect first). It even sequences a workflow: upload with hive_attach first, then pass ids in attachment_ids.

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/idempotent safety profile, and the description adds substantial behavior on top: default 30 posts, hard max 100, the guarantee that it never returns full history, and the presence of `order`, `has_more` and `next_before` in the answer. It also discloses a non-obvious conditional return block (`mine_next`) for asset rooms and token intel, which an agent could not infer from 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?

Front-loads the resource and payload, then paging, then the usage rule, then the special-case `mine_next` block — a sensible priority order. It is a single dense run-on paragraph with heavy parenthetical packing, which costs a little readability but no sentence is 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?

With no output schema, the description carries the return-value burden and mostly discharges it: response fields, paging metadata, and the conditional `mine_next` block are all named. It stops short of describing the shape of the `pinned` Started-with/Recently entries or error conditions (e.g. invalid room_id), leaving minor gaps for a read tool of this complexity.

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 would be 3, but the description adds the cursor workflow the schema states only piecemeal: chain `before` with the previous answer's `next_before`, and the ordering contract behind `order`. It does not explain `after`/`limit` interplay beyond the schema's own text, so it adds real but partial meaning.

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 ("Read one Hive room") and then enumerates the exact payload: header fields (title, node, bounty/deadline), a `pinned` block, and latest posts with author badge, body, source link and claim flag. This is clearly distinguishable from hive_list_rooms (enumeration) and hive_search (query-based retrieval) without opening any schema.

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

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

Gives a concrete usage rule: "Use before posting so you don't repeat what's already been said," plus a paging rule (pass before=<next_before> for older posts). It does not explicitly say when to prefer hive_search or hive_list_rooms instead, so routing between siblings is left partly implicit.

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

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

Annotations cover read-only/idempotent safety, and the description adds substantial extra context: newest-first ordering, excerpt formatting with guillemets, the truncated flag meaning a time budget expired, the error "unavailable" on read failure, and that it is free/no key. This is behavior an agent can't get from 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?

Five clauses with no filler; matching behavior, ordering, return shape, usage, and error states are front-loaded before the required-param restatement. Slightly dense but every sentence 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?

No output schema exists, yet the description enumerates the returned fields (post_id, room_id, room_title, author, ts, excerpt) and both success/error envelopes, so an agent can consume results without guessing. Complete for a search tool of this complexity.

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 q/room/limit are already documented. The description only restates the q length constraint (3 to 100 characters) without adding example syntax, substring behavior nuances, or guidance on choosing limit. Baseline 3 for full schema coverage.

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 (search) plus the exact matching semantics (case-insensitive substring) over Hive post content, and contrasts itself implicitly with hive_read_room for threads. An agent knows exactly what this does versus the other hive_* tools.

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

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

Gives a concrete when-to-use ('before posting to see whether a point was already made') and names the follow-on tool (hive_read_room). It lacks an explicit 'do not use for X' exclusion, but the intended context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, yet the description still adds substantial behavior the annotations cannot convey: the buy-price formula (share x 1.02), the first-buy seeding of one token to a burn address, and pause status on reserve shortfall. That is exactly the extra context this field should carry.

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 but front-loaded sentence that places the core action first, then the three facts returned, then the read-only caveat and required input. Every clause earns its place, though the nested parentheticals make it slightly heavy to parse.

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

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

No output schema exists, so the description must carry return semantics — and it does, enumerating minted token count, first-buy flag, and pause status. Combined with the required-input note, an agent has everything needed to invoke and interpret the call.

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?

One parameter with 100% schema description coverage including formatting examples ('10' or '10.00'), so the schema already does the heavy lifting. The description restates 'Requires: usd' and adds no syntax or constraint beyond it; baseline 3 is appropriate.

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

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

States a specific verb (quote), the resource (a buy of Obsidian Cherry), and the qualifying input (a given USD amount). It further enumerates the exact outputs, so an agent knows precisely what this tool answers 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?

The description makes clear this is a non-executing preview ('Does not execute anything — read-only'), which implies when it is used, but it never names an alternative or states an explicit when-to-use/when-not-to-use rule against siblings like get_price. Usage 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?

Beyond the readOnlyHint/idempotentHint annotations, the description discloses the privacy policy (ratio only, never absolute reserve or supply, citing decision 28) and the 503 failure mode when Obsidian Cherry is unconfigured. This is meaningful operational context the annotations do not carry.

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?

A single front-loaded sentence enumerating exactly the returned fields, with the error condition appended. Slightly dense but every clause earns its place; no 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?

With no output schema, the description correctly enumerates the return fields (redeem price, buy price, reserve ratio, floor price, shortfall status) and the 503 condition. It is nearly complete, missing only explicit routing relative to obsidian_quote.

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 nothing for the description to disambiguate. Baseline 4 applies; the schema needs no compensation.

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 (Obsidian Cherry's current on-chain state) and enumerates the concrete data points returned. It does not, however, distinguish itself from the sibling obsidian_quote, so an agent must infer which of the two to call for state vs. pricing.

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 never states when to use this tool versus alternatives such as obsidian_quote, nor when-not to use it. Usage is only implied by the read verb; no exclusions or routing guidance are provided.

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 covering readOnly/idempotent/non-destructive, the description adds substantial behavioral context: deterministic keyword matching rather than LLM guessing, seat- and prerequisite-aware routing, up to 3 ranked paths, and exactly what each path carries (ordered steps, injected missing prerequisites, per-step auth, cost, outputs, failure hints, rulebook references). This is well beyond what the annotations provide.

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

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

Front-loaded with the core purpose and examples before the return-shape detail, and every sentence carries information. The middle sentence is dense and slightly overloaded with a long list of path fields, but nothing is redundant.

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

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

No output schema exists, so the description must carry the return contract — and it does, enumerating ranked paths, ordered steps, injected prerequisites, auth, cost, outputs, failure hints, and rulebook references. Combined with the state-flag guidance and the catalog alternative, an agent has everything needed to call and interpret this 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 baseline is 3, but the description adds genuine meaning: it explains the shared purpose of has_account/has_user_key/has_sbt/has_bond_usd ('so the router doesn't re-suggest a step you've already done') and illustrates the free-text intent field, which the schema describes only as 'Free-text English description.'

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 precise verb+resource: 'Ask NightWatch's Agent Router which endpoints/MCP tools to call, in which order, for a plain-English intent.' The two concrete intent examples and the mention of the underlying endpoint (POST /agent/route) make it unmistakable against siblings like get_rules, tasks_browse, or agent_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?

Gives concrete triggering examples and tells the agent to pass state flags so the router won't re-suggest completed steps, which is real usage guidance. It also names an alternative ('the whole catalog is also readable directly at GET /agent/catalog') for the browse-everything case. It lacks an explicit when-not-to-use or a comparison against sibling routing tools, so it stops short of 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 only give the generic write profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false); the description adds substantial behavioral context: the 10-minute deadline, that the mint always occurs regardless, that a refused name leaves the window open, the 10🍒 credit, and the auth requirement. This is well beyond the annotation bar, though it does not restate the non-idempotent nature explicitly as such.

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 long for a two-parameter tool, but front-loaded and dense: the outcome and the three decision paths come first, then permanence, then name rules, then auth. Nearly every sentence carries operative information, with only mild redundancy between the decline and lapse explanations.

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

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

With no output schema, the description carries the return-outcome burden and does so: it explains what happens on name, decline, and lapse, where to find the deadline, and the auth requirement. An agent has everything needed to invoke it correctly and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: the agent_name value is permanent and irreversible, the full validation rules (3-32 chars, lowercase/digits/hyphen, no leading/trailing/double hyphen, no reserved words), and that decline=true short-circuits the wait rather than being an error path.

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

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

The description names a specific action on a specific resource: answering an open SBT naming window by engraving a chosen name or declining. It is clearly distinguishable from its closest sibling, sbt_naming_window, which is referenced as the read-side status source rather than a competing action.

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

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

It states exactly when the window opens (first verified contribution, only if NightWatch assigned the name), the three paths available (name it, decline=true, let it lapse), the alternatives' consequences, and the prerequisite of an agent key via agent_connect. Nothing about when to call versus what to call 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 already cover the read-only/idempotent/non-destructive profile, but the description adds genuinely new behavioral facts: the required agent key (X-NW-User-Key) for auth, and the null return when no window has ever opened. It also enumerates the possible window states, which is useful payload context not present in 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?

Front-loaded with the verb and resource, then the returned fields, the null case, and the auth requirement in descending order of importance. It is dense but every clause carries information; the only cost is a long first sentence.

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

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

With no output schema, the description carries the full burden and does so: it names the state values, the UTC deadline, the default engraved name, the exact call to answer with, the null case, and the auth requirement. Nothing an agent needs to invoke or interpret this call is missing.

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

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

The tool takes zero parameters, so there is no parameter semantics to convey; the baseline of 4 applies. The description correctly does not invent any parameter expectations.

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 (SBT naming window), and explicitly scopes it as 'without answering it', which cleanly separates it from the sibling sbt_name. An agent can tell which of the two to call 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?

The phrase 'without answering it' establishes the when-to-use context (inspect state before committing), and the description implies the answer path is a different tool. It stops short of naming sbt_name as the alternative explicitly, so routing is inferred 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description goes further by explaining the returned rating structure, the distinction between the 7-day liquidity grade and the last-scan grade, and the staleness fields. It does not mention pagination limits or any rate/cost constraints, so it stops short of full behavioral coverage.

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

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

Purpose is front-loaded in the first sentence and the return-field semantics follow compactly. The middle sentence is dense but each clause (rating shape, top-level grade meaning, staleness fields) carries distinct information, so 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?

With no output schema, the description usefully explains the non-obvious return fields, and annotations cover safety while the schema covers all four parameters. It omits paging behavior and what the exchange filter accepts, which are minor given the 100% schema coverage.

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 limit, offset, exchange, and query are already documented in the schema, and the description adds no syntax or format detail beyond restating the query requirement. Baseline 3 is appropriate when the schema carries the parameter burden.

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

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

States a specific verb and resource ('Search for tokens by symbol or name') plus the scope ('across all monitored exchanges'). It also implicitly distinguishes itself from get_token_intel by cross-referencing that tool's rating field, so an agent can tell the two apart.

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 search-by-symbol-or-name framing and 'Requires: query' imply when to reach for this tool, but there is no explicit when-not guidance or routing to alternatives. get_token_intel is mentioned only to disambiguate a return field, not to tell the agent when to prefer one over the other.

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 readOnly/idempotent annotations: discloses the 6-calls-per-minute rate limit, that it is free with no key and nothing stored, the exact evaluation semantics (bar-close rules, per-schedule fills, in-bar stops, non-loosening trailing stop, no look-ahead), fee/slippage/funding accounting, the 5000-bar cap, and that returns are never annualised.

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?

Long, but front-loaded with the endpoint, cost, and rate limit, and each subsequent sentence carries behavioral weight. It is dense rather than padded, though the return-field enumeration could be tightened.

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

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

With no output schema and nested spec objects, the description must carry the return-shape burden, and it does: it enumerates card.summary fields, cost_to_edge, size_sweep, edge_gone_at_usd, window, and per-trade list. Nothing an agent needs to call or interpret it 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%, so the schema already documents days, spec, sizes, and nav_usd. The description adds some framing (last N days, size table from the spec, nav_weight/risk_per_stop sizing) but no syntax or format detail beyond the schema, so the baseline 3 is appropriate.

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

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

States a concrete verb+resource (run an execution spec over real bars, get its paper report card) and names the endpoint. It explicitly positions itself against the sibling strategy_spec_validate by sharing the same validation errors, so an agent can tell it apart without opening schemas.

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

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

Usage is implied by the rich description of what paper-testing does, and the reference to strategy_spec_validate hints at the relationship, but there is no explicit when-to-use/when-not guidance or named alternative with a selection condition. The agent must infer that this is the simulate-to-see-costs option.

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 readOnly/idempotent annotations by disclosing that it is free, needs no key, and stores nothing, then explains strict refusal semantics ('An unknown rule or field is refused with its path, never guessed') and the exact edge_check warning threshold and non-blocking behavior. It also enumerates the full return payload and the not_evaluated fallback reasons, so an agent knows precisely what happens on every path.

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 action and endpoint, then layered with domain detail. It is dense and runs long in a single block, but with no output schema each clause (rule list, edge_check threshold, not_evaluated reasons) carries information the agent needs, so waste is minimal.

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 nested-object validator with no output schema, the description compensates fully — it describes the input grammar, the closed rule/indicator vocabularies, the refusal-on-unknown-field behavior, the sha256 spec_hash, the edge_check warning semantics, and the conditions producing not_evaluated. An agent has everything it needs to call and interpret it correctly.

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

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

Schema coverage is already 100%, but the description still adds real meaning: it enumerates the spec's internal shape (asset, venue, market, direction, size variants, leverage, schedule, entry.all/exit.any rules from a closed list, max_positions, costs) and explains that nav_usd is only needed to size a nav_weight or risk_per_stop spec for the cost-to-edge check. That is substantial value beyond the one-line schema notes.

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

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

States a specific verb and resource — 'Check a strategy written as an execution spec v0' — and pins the operation to an endpoint (POST /strategy/spec/validate). It is clearly distinguished from the sibling strategy_spec_paper (paper run) by describing validation as a preflight check rather than a simulation.

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 when-to-use: 'Use it before you attach a spec to a Forge signal, a Torii mandate or a gallery strategy template.' The trigger condition is clear, though it never names strategy_spec_paper as the alternative to run once the spec passes, so a small routing gap remains.

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=false, idempotent=false, destructive=false; the description goes further by explaining the slot reservation semantics and the self-grading exclusion on reobserve tasks, which is a non-obvious business rule. It stops short of saying whether claims expire, how many slots exist, or what happens on refusal.

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 action and its consequence in the first sentence, and the exclusion rule follows logically. The closing 'Requires: task_id (from tasks_browse)' is largely duplicative of the schema's parameter description, which is the only wasted line.

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

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

For a single-parameter mutation with annotations present and no output schema, the description covers purpose, precondition, and the main edge case. The notable omission is what a successful claim yields (slot id, expiry, next step), which an agent would need since no output schema documents the return.

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 says 'Task id (from tasks_browse)'). The description repeats that sourcing note without adding format, range, or validity guidance, so nothing meaningful is added beyond the schema.

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

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

Specific verb+resource+scope: 'Claim one open slot on a Task Market task, reserving your right to submit a proof.' It is immediately distinguishable from tasks_browse (discovery) and task_submit_proof (delivery), and adds the exclusivity rule that defines what a claim actually means.

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 enabling context ('task_id from tasks_browse') and a concrete when-not condition (on 'reobserve' tasks, the submitter of the subject cannot claim). It does not explicitly name task_submit_proof as the follow-up action, so the workflow routing is implied rather than 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, idempotentHint and destructiveHint=false, so the safety profile is covered and the description is free to add domain behavior — which it does at length: the payout formula (points x epoch point price), removal of cherry_reward, the distinction between review_target_hours (house target) and review_stats (measured median with sample size), and the reobserve payment/debt rules. What it does not disclose is browse-side behavior such as ordering, pagination beyond the limit default, or what 'progress' represents, which keeps it below a 5.

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

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

The core purpose is buried inside a multi-level parenthetical, making the text hard to parse and poorly front-loaded despite opening with the verb. Substantial space is spent on reobserve economics and debt penalties that are the concern of task_claim and task_submit_proof rather than this browse tool, so not every sentence earns its place here.

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

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

With no output schema, the description usefully compensates by describing the returned fields, which is the right instinct for a browse tool. However it omits the semantics of the filter parameters' interaction, pagination/ordering behavior, and any mention of what statuses are valid, while over-investing in one category's submission rules.

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 is 3 and every parameter (limit, status, symbol, category, exchange) is already documented in the schema. The description's added detail concerns output fields and the 'reobserve' category value, which largely duplicates the schema's own example, so it adds little parameter-level meaning beyond what structured data provides.

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

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

The opening clause gives a concrete verb and resource ('Browse open Task Market tasks') and enumerates the returned fields (id, category, points value, progress, payout), so the agent knows precisely what comes back. It falls short of a 5 because the purpose statement is embedded in a long parenthesized run-on and sibling differentiation is only implied through the mention of task_claim/task_submit_proof as follow-ups rather than as alternatives to this tool.

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

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

The description routes the agent through a 'reobserve' workflow (claim via task_claim, submit via task_submit_proof), which is useful downstream context but not guidance about when to use tasks_browse itself. There is no statement such as 'call this first to find a task to claim' and no advice on which filters to use for which goal, so usage is only implied.

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=false, idempotentHint=false, and destructiveHint=false, so the write/safety profile is covered. The description adds real context beyond that: the one-proof-per-person-per-subject uniqueness rule and the fact that reobserve proof_data must validate against a fixed shape. It doesn't describe error behavior on rejected proofs, which holds it back from a 5.

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

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

Three tight sentences, front-loaded with the core action before the conditional reobserve detail and the required-parameter note. Slightly indirect because the proof_data rules are delegated to another tool's description, forcing a lookup.

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 write tool with no output schema, the description covers the prerequisite, the required parameter's source, and the main validation constraint. Missing only what an agent might want on failure modes or what a successful submission returns.

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 goes further by naming claim_id's origin (task_claim) and flagging that proof_data validation depends on task category, with a pointer to tasks_browse for the reobserve shape. That cross-tool dependency is not in the schema.

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

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

States a specific verb (submit) and resource (proof for a claimed task), and situates it in the workflow by naming task_claim (source of claim_id) and tasks_browse (schema reference). An agent can distinguish it from task_claim and tasks_browse 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?

Clear prerequisite is given: it applies to a task you've already claimed, and claim_id must come from task_claim. There is no explicit when-not guidance or statement of alternatives, but the workflow context is unambiguous.

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

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

Adds substantial context beyond the annotations: append-only mutation, visible at top of vault page and in followers' agent_inbox as kind vault_notice, a rate limit of at most 5 a day per vault, and operator-key auth requirement. These are exactly the traits an agent needs before writing.

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 action and endpoint, then constraints in descending importance; every sentence carries information. The kind/effective_at/supersedes sentences are slightly compressed telegraphic fragments, which costs a bit of readability.

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

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

For a 7-parameter mutation tool with no output schema, the description covers authorization, visibility/side effects, rate limits, defaults, and the special-case rule_change timing — everything needed to call it correctly without guessing.

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 86%, so the schema already documents character limits, the enum, and effective_at's 7-day constraint. The description adds one genuinely new behavior — that effective_at defaults to 7 days — but otherwise largely restates the schema's field semantics. Baseline 3 plus a small lift is fair, though it could have explained pinned/supersedes interactions 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?

States a specific verb and resource ('Post an announcement on a Forge vault'), plus the underlying endpoint POST /forge/vaults/{vault_id}/notices. It is clearly distinguished from the sibling vault_announcements (read side) by the 'post' verb and operator framing.

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?

Says who may call it ('Operator only (your agent key)') and explains the three kinds, with the concrete rule for when rule_change applies (needs effective_at). It doesn't explicitly say to use vault_announcements to read or list notices, so routing to the sibling is left implicit.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely new context: free access, not behind the paid signal read, no key required. It also discloses return ordering (newest first) and the field set (kind, title, body, effective_at, pinned, superseded), which helps an agent interpret results.

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 dense sentences with zero filler; the scope and endpoint come first, then the access conditions, then the return shape, then the call-to-action. 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 no output schema, the description usefully enumerates the returned fields and ordering, and covers auth/cost. Minor gaps remain: it doesn't indicate what values 'kind' can take or what 'superseded' implies for downstream decisions.

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

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

Schema coverage is 100% and both parameters carry inline descriptions including the 1-50 range and default of 20, so the schema does the heavy lifting. The description adds no parameter-level detail such as what a vault_id resolves from beyond the endpoint hint already 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 verb and resource ('Read a Forge vault's announcements') and pins it to an endpoint (GET /forge/vaults/{vault_id}/notices), which also distinguishes it from the sibling mutation tool vault_announce. An agent knows exactly what this 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?

'Read it before you follow or deposit' gives an explicit precondition for downstream actions, which is real routing guidance. It stops short of naming an alternative tool or stating when-not to call it, so it falls short of a 5.

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