GreenlandAI

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 so thoroughly: it discloses the HTTP relay, authentication requirement, that results are wallet-scoped, the fee behavior (0.5% rail fee), each status meaning, settlement semantics, and the replay window. This is far beyond what the schema alone would reveal.

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

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

The description is dense but every section earns its place: the opening line front-loads the core purpose, the status legend is essential for interpreting results, and the param/auth details are necessary for correct invocation. No filler or redundant restatement of the tool 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?

Given zero annotations and a moderate two-param schema, the description is complete: it covers inputs, output semantics, status values, payment-fee behavior, cross-referencing to other tools via `attempt_id`, authentication, and paging. The presence of an output schema means return-value shape is already handled, so nothing needed for correct invocation 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 0%, so the description fully compensates by documenting `limit` as 1-200 with default 50 and `offset` as paging. This adds range and behavioral meaning the JSON schema does not provide.

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

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

The description states a specific verb and resource: it lists the wallet's own charge record, attempt by attempt, and explicitly distinguishes itself from `joules_balance` (how much I have vs what I was charged for). It also names the underlying endpoint, making the resource unmistakable.

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 says when to use the tool ('verify your bill without asking us') and explicitly calls out the key alternative (`joules_balance`) with the decision condition. It also clarifies scope ('own wallet only — derived from your credential, never a parameter'), which prevents misuse.

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

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

No annotations are provided, so the description carries the full burden and does so well: free to invoke, bearer required but unverified callers allowed, the 0.5% rail surcharge baked into joules_all_in, per-hop pricing with refund_on_empty/quote_is_maximum, hop limits by key type (agent 10, human 3), and tier selection before any charge for site.reconstruction.

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 core value proposition (exact price before the call, free, invocable) and then packs parameter guidance densely. It is long and slightly run-on with heavy parentheticals, but nearly every clause conveys actionable 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?

For an 8-param, 1-required pricing tool with no annotations, this is complete: it covers auth behavior, billing semantics, refund behavior, per-path parameter meaning, and the site.reconstruction special case. Return values are not belabored since an output schema exists.

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 0% and there are 8 parameters, so the description must compensate — and it does: path is defined with concrete examples mapped to sibling tools, hops is defined as graph depth with key-dependent caps, and lat/lng/entity_type/radius_m/as_of are explained for the site.reconstruction case.

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

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

States a specific verb+resource with scope: 'the exact per-caller price of a metered call BEFORE you make it.' It also names the underlying route (GET /api/v1/billing/quote) and ties itself to per-call pricing, which distinguishes it from sibling quote tools like market_quote and balance_proof.

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?

Clearly signals when to use it: before making a metered call, and to fund joules_all_in rather than the base joules. It also notes bearer is required but no verification is needed, so an unverified caller may still price a call. It stops short of naming an explicit alternative/fallback sibling, so not a 5.

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

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

The description exhaustively discloses metering behavior (reservation, settlement, charging, replay conditions) which goes beyond annotations (none provided). However, it omits behavioral details about the actual data retrieval, such as traversal depth or response structure, so transparency is one-sided.

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

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

The description is extremely long and poorly structured, with the core purpose buried under a massive block of billing information. It is not front-loaded or concise, making it hard for an agent to parse quickly.

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

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

The description covers metering in depth but lacks essential details about the returned company record and graph neighbourhood. Even with an output schema present, the description does not explain the data fields, so an agent cannot anticipate 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?

The only parameter 'id' is referenced as 'by id' but no additional meaning is given—no format, constraints, or examples. With 0% schema coverage, the description fails to compensate, leaving the parameter's semantics thin.

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 begins with 'One company's record and graph neighbourhood by id' but lacks a clear verb and immediately diverts to billing details. It does not differentiate from siblings like 'deposit' or 'relationships', leaving the core purpose vague.

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?

No guidance is provided on when to use this tool versus alternatives. The description is entirely consumed by metering and charging details, with no mention of usage context or exclusions.

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

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

With no annotations, the description carries the full burden. It discloses read-only behavior, append-only nature, ownership scope, and the required API key. It doesn't mention rate limits or error handling, but for a simple list endpoint with output schema, the key behavioral traits are covered.

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

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

The description is a single dense but effective paragraph. It front-loads the core purpose (own receipts, proof), includes the hash detail, and ends with the endpoint. It could be split into cleaner sentences, but every phrase adds value.

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

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

For a low-complexity tool with an output schema, the description covers purpose, auth, scope, and read-only nature. It doesn't explain return structure, but the output schema handles that. Missing pagination guidance is minor given the schema defaults.

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 0% and the description adds nothing about limit/offset. While the parameter names and defaults are self-explanatory, the description does not compensate for the missing schema descriptions, nor does it mention pagination behavior or maximum limits.

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?

Description names a specific resource (contribution receipts), the verb (GET), and the exact scope ('Your OWN', 'no staff fields'). It distinguishes itself from siblings like contribute_submissions by emphasizing ownership and the claim hash, so an agent can tell exactly what this tool returns.

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 usage context is provided: this is for retrieving proof of your own submissions and verifying them via claim_sha256. It also states the auth requirement (X-API-Key). It doesn't explicitly name alternatives, but the 'Own rows only' exclusion effectively disambiguates from broader listing tools.

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

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

No annotations are provided, so the description carries the full burden, and it delivers extensively. It discloses that nothing is written to the graph on submit, claims are queued for a nightly refutation judge at 21:15 UTC, per-item statuses, and that the judge's verdict appears via other tools. It also details the auth identity derivation from the key, covering behavioral nuances beyond basic input/output.

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

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

The description is long but information-dense; each sentence adds essential context. It is not a tautology or padded. However, it is a single dense paragraph that could be broken into structured bullets for readability. The front-loaded purpose sentence is good, but the sheer length makes it slightly less scannable—still it earns its place given the complexity.

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

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

Given the tool's complexity (auth, prerequisites, queueing, statuses, follow-up tools), the description covers everything an agent needs to call it correctly. It explains the full lifecycle from submission to verdict, references the config endpoint, and enumerates all statuses. The output schema exists, but the description goes beyond it to explain meanings, so nothing critical is missing.

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

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

Schema coverage is 0% (the schema only defines arrays of generic objects without property descriptions). The description compensates fully by specifying required fields for each relation (subject, relation, object, source_url, quote) with the quote constraints, optional fields (subject_type, object_type), and the semantics of `entities` (only alongside a relation referencing it). This adds substantial 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?

The description states a specific verb ('Submit'), a specific resource ('evidenced graph relationships to the GreenlandAI contributor door'), and the programme name ('TEN'). It clearly distinguishes from sibling tools like contribute_submissions and contribute_receipts, which are mentioned as follow-up tools for outcomes.

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

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

Provides explicit when-to-use guidance: explains the auth requirement (own key, agent ID not sent), the prerequisite that contribute must be enabled (with the 403 naming the enable endpoint), and directs to other tools for follow-up (contribute_submissions, contribute_receipts) and live config (GET /api/v1/programme/config). Also states nothing is written on submit and claims are queued, setting expectations for usage.

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

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

No annotations are provided, so the description carries the full burden. It explicitly states 'Read-only', which covers side effects, and details the authentication via X-API-Key and that identity is derived from the key. It also lists the returned fields and thresholds. It does not mention error conditions or rate limits, but for a read-only status tool this is a minor gap.

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 front-load the main purpose ('Your OWN contributor standing') and then detail the return fields, auth, and endpoint. No wasted words; every sentence adds value.

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

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

Given zero parameters and an output schema (though not shown, the description lists all returned fields), the description fully covers what an agent needs to know: what it returns, how to authenticate, and that it is read-only. Nothing critical is missing.

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

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

There are zero parameters, so the schema provides nothing. The description adds crucial context: the required X-API-Key header and the endpoint. This goes beyond the schema and is essential for invocation.

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 a specific verb ('Returns'), a specific resource ('contributor standing'), and scope ('Your OWN'), and lists the exact data returned. It distinguishes itself from sibling contribute_* tools by focusing on the caller's own status rather than submissions or receipts.

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

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

The description implies when to use it ('Your OWN contributor standing', 'Read-only') and gives the endpoint, but it does not explicitly mention alternatives or when not to use it. The self-scope is a clear differentiator, yet no direct comparison to siblings like contribute_submissions or contribute_receipts is 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 no annotations provided, the description carries the full behavioral burden. It discloses the required X-API-Key header, the read-only nature, field semantics, the pending-review wording, and the nightly judge schedule. The unexplained 'HELD item' terminology is slightly ambiguous, but the description is otherwise transparent.

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

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

The description is compact and front-loaded with the core purpose and auth requirement before the field list and endpoint. It avoids filler, though the field enumeration is dense and mixes API details with status semantics in a way that could be lightly organized.

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

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

Given the simple optional pagination parameters and existing output schema, the description covers the essential operational context: endpoint, auth, read-only status, item fields, and status meanings. It is not fully complete because it omits explicit alternative guidance and parameter semantics, but those are minor given how much is disclosed.

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 0% for limit and offset, and the description does not explain either parameter or mention pagination. The parameter names and defaults in the schema are self-suggesting, but the description adds no semantic value to compensate for the missing parameter documentation.

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

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

The description clearly identifies the resource as the caller's own per-item submission outcomes and gives the exact endpoint, GET /api/v1/contribute/submissions. The 'Your OWN' qualifier distinguishes this from sibling contribution tools such as receipts, relations, or stats, and 'Read-only' further clarifies the operation.

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

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

Usage context is implied: this is the tool for retrieving your own submission outcomes, and the read-only note signals it is safe to call. However, it never explicitly says when to prefer this over sibling tools like contribute_receipts or contribute_stats, and 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?

With no annotations, the description carries the transparency burden and meets it: it reveals the call is a read ('relays GET'), that it is metered and 'debited from the CALLING agent's own wallet', and defines the response's charged_joules/settlement fields. This goes well beyond the schema and gives agents the safety and cost implications of calling.

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

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

The description is dense but every clause earns its place: purpose, inclusions, sibling workflow, and metering consequence. It front-loads the core action before the detail-heavy metering sentence, with no wasted words.

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

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

For a single-parameter read tool with no annotations, the description supplies path semantics, the search-before-read workflow, return inclusions (with the output schema carrying the detailed shape), and the cost/payment behavior. Nothing an agent needs to select or invoke the tool correctly appears to be 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 only declares a required string 'id' with zero description coverage, so the description must clarify it. It does: id is 'numeric' and maps to the URL path placeholder '{id}', implied by '/api/v1/deposits/{id}'. For a one-parameter tool this fully compensates for the schema gap.

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

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

The description opens with a concrete verb+resource: returns 'One resource deposit's record by numeric id' and even gives the exact REST endpoint. It further names the inclusion set ('commodities[]' and 'operators'), which distinguishes it from the sibling search tool 'deposits(commodity=...)'.

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

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

Explicitly frames a workflow: 'Pair with deposits(commodity=...): search by commodity, then read the deposit.' It also directs cost control with 'Quote with billing_quote("/api/v1/deposits/{id}")' before a call. This is clear when-to-use guidance plus a named alternative.

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 so exceptionally. It discloses the graph-based commodity matching behavior, the metered nature of the call, that charged_joules is debited from the caller's wallet, and the settlement states. It also explains the response's commodity_filter field to preempt confusion.

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

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

The description is long but dense, and every section earns its place: purpose, filter list, critical commodity warning, response shape, and metering/billing. The most important caveat is prominently flagged with '⚠ READ THIS BEFORE USING `commodity`', making the structure effective despite the length.

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

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

Given 9 parameters, zero schema descriptions, no annotations, and an output schema that is not shown, the description is remarkably complete. It covers all parameters, the response shape, the anomalous commodity behavior, and the financial consequences of calling the tool, providing an agent everything needed to invoke 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 description coverage is 0%, yet the description compensates fully by naming every parameter and adding semantic meaning: search is a name substring, limit is capped at 100, and commodity has a non-obvious graph matching behavior with a detailed example. This goes far beyond the schema's bare type information.

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

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

The description opens with a specific verb and resource: 'Search resource deposits (relays GET /api/v1/deposits).' It clearly identifies the tool's scope and differentiates it from the sibling singular 'deposit' tool by focusing on plural search behavior.

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 the search context explicit and enumerates all filters, clearly establishing when this tool is appropriate for listing/filtering deposits. It does not explicitly name an alternative tool or state when not to use it, but the context is clear and precise.

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

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

No annotations are provided, so the description carries the full burden, and it delivers: every state is enumerated with behavioral meaning (held_below_min accumulates and credits as one entry; held_no_fund retries automatically every minute; held_inactive is operator-released), and it asserts 'nothing lost' for each. It also covers auth requirements (bearer or agent key) and the distinction between deposit lag and being flagged. This is unusually complete behavioral disclosure 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?

The content is valuable but the structure is poor: it is one dense paragraph of state definitions with no front-loading of the states, and duplicated phrasing ('nothing lost' repeated five times). The routing detail (greenlandai.ai/api/v1/agent/me/deposit-status) is buried at the end. It earns its content but not its form.

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

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

An output schema exists, so return values need not be explained; the description instead focuses on state semantics, which is the right call. It covers auth, scoping, and the cross-reference to scanner_cursor_block. It could be more complete on precedence (which state wins if conditions overlap) and on whether the states are mutually exclusive.

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 is 4. The description reinforces this by stating the wallet is 'derived from your credential, never a parameter,' which prevents an agent from inventing a wallet-id argument.

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: 'YOUR OWN USDC-on-Base deposit state.' The parenthetical routing (GET /api/v1/wallet/deposit-status; own wallet only, derived from credential) sharpens scope. It does not explicitly contrast with sibling tools deposit or deposits, but the 'own wallet only' scope plus the agent-key endpoint overload gives it a distinct identity.

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 clear when-to-use condition: 'Sent USDC and see nothing yet? Compare your deposit's Base block to scanner_cursor_block.' This is explicit diagnostic guidance. It does not name sibling deposits/deposit as alternatives for different scopes, 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.

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

The description discloses significant behavior beyond what would be expected from the schema: charging model (one quote, one debit, reserved up front, settled for parts delivered), agent-key requirement, side-effect profile (read-only), and the escrow_oracle behavior. No annotations are provided, so the description carries the full burden, and it does so reasonably well. Some details (e.g., the exact interaction with billing_quote) are present.

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

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

The description is long and dense, with many parenthetical asides and specialized jargon. It is front-loaded with the core operation, but the charging section and extensive behavioral details make it hard to scan. Every sentence does carry information, but the structure could be clearer.

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

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

Given the tool's complexity (composite outputs, charging model) and the presence of an output schema, the description provides substantial context: output fields, charging behavior, key requirements, and read-only nature. The lack of parameter explanations for 3 of 5 parameters is a notable gap, but overall it is fairly complete.

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

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

Schema description coverage is 0%, so the description must compensate for the 5 parameters. It mentions `entity` and `as_of` implicitly but does not explain `max_cloud`, `radius_km`, or `entity_type`. Even `as_of` format is given (YYYY-MM-DD, default today), but other parameters are left entirely undocumented, which is a significant gap.

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

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

The description opens with 'state(entity, as_of) — ONE packet for one entity at a date', stating a clear verb-like operation and scope. It names the composite outputs (`target`, `pins`, `graph`, `image`, `escrow_oracle`), which differentiates it from sibling tools like `entity_history` and `relationships`. However, the terminology is highly specialized and doesn't explicitly contrast with sibling tools.

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

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

Usage context is implied (query entity state at a date), but there is no explicit 'when to use this vs entity_history or relationships' guidance. The charging warning and key requirement are functional conditions, not alternative-selection criteria.

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

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

With no annotations, the description carries the full burden and does disclose meaningful behavior: USDC on Base is the agent-fundable rail, deposits are credited automatically by a scanner, state is read live per call (never stale), and the tool does not move money itself. It also distinguishes agent-key vs owner-credential handling. It stops short of stating auth requirements or failure modes.

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

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

The text is a dense run-on packed with nested parentheticals and backticked field names, so the core action is not front-loaded and must be reconstructed. Length is large relative to the small amount of actionable instruction.

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

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

Because an output schema exists, return values need not be described, and the live-state and auto-credit behavior are covered. But the undefined `needed` parameter and the ambiguous 'prepare but does not move money' framing leave the agent without a fully actionable picture.

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 parameter `needed` has 0% schema description coverage and the description never explains it — it only mentions `minimum_usdc`, a different field read from deposit-status. For a tool whose one input shapes funding preparation, leaving `needed` undefined is a real gap.

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

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

States a specific domain and role ('the in-band funding step for a joule shortfall') and rules out the website/card path, but the actual action it performs is genuinely hard to pin down — it both 'prepares' funding and explicitly 'does not itself move money.' An agent learns the topic but not cleanly what this call returns or changes.

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 trigger is a joule shortfall, with `deposit_status` named for tracking and card funding marked as a separate human web flow. However there is no explicit when-not guidance and no clear statement of when to call this vs. the sibling `deposit`/`deposits` tools, so routing remains partly inferential.

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

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

No annotations are provided, so the description carries the full behavioral burden and does so richly: reserve-before/settle-after metering, empty result settles to 0, 4xx releases, abandoned/timeout calls still settle, replay free only for same credential+key+request within 15 minutes, and the settle_failed wallet-lock / 402 behavior. This is unusually complete 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?

Front-loaded with the deprecation and migration guidance, then the charging model, which is genuinely necessary given zero annotations. The operator-ruling rationale is somewhat editorially verbose, but the metering detail earns its place; no true 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?

An output schema exists, yet the description still explains `charged_joules` and the `metering` block fields, and it covers error semantics and deprecation fully. The remaining gap is the undocumented execution parameters (limit/offset/search/as_of/entity), which keeps this 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 0% across 9 params, so the description is the only source. It adds real meaning for `hops` (traversal depth = metered unit), `relation_type` (unknown value = 400 before charge), and `entity_type`+`entity_id` (pinning, multi-match = 409), but leaves `limit`, `offset`, `as_of`, `search`, and `entity` entirely undocumented. Partial compensation only.

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 immediately names the tool as a deprecated alias for `relationships` and explains why the naming was ruled wrong (billing unit vs. capability), so an agent understands exactly what the tool is. It is distinguishable from the `relationships` sibling 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?

Explicit routing instruction: 'Use `relationships`' with the deprecation rationale, and the condition under which this alias still works. It also states identical behavior/params, so the agent knows migration is safe. Nothing is left to inference.

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

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

No annotations are provided, so the description carries the burden. It discloses that the operation is free/read-only, explains the two authentication paths, and notes the returned fields. It doesn't explicitly state failure modes or rate limits, but the free-read disclosure and endpoint details are strong behavioral 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?

The description is dense but well-organized, front-loading the key fact (free read) and then explaining the two credential paths. Every sentence adds value, though the parenthetical about the graph/map meter could be seen as slightly tangential. Overall, it's efficient and informative.

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

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

Given the tool has an output schema and only one optional parameter, the description covers the essential usage scenarios. It explains the two authentication modes, the endpoints, and the return fields. It doesn't mention error cases or what happens with an invalid wallet_id, but for a simple balance-check tool, the coverage is strong.

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 0% and the only parameter (wallet_id) has no description in the schema. The tool description compensates by explaining when wallet_id is needed (JoulePAI/ENYAL credentials) and when it is not (agent keys). It doesn't describe the exact format of wallet_id, but the conditional usage is clearly explained.

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 reads a wallet balance, distinguishes between two credential types (GreenlandAI agent key vs JoulePAI/ENYAL), and specifies the exact endpoints and return shapes. It names the resource (wallet balance) and the verb (reads/checks), making it unambiguous.

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

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

The description explicitly explains when to use this tool: an agent checks its own wallet before calling graph/map meter operations. It also clarifies that no wallet_id is needed for agent keys, while JoulePAI/ENYAL credentials require wallet_id. This provides clear context and differentiates from sibling tools like wallet_transfer and joules_deficit.

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 discloses that it reads balance via specific API endpoints, is free, and returns a structured result. However, it does not mention whether the operation is read-only (though implied), any error behavior, or rate limits. It provides moderate transparency but lacks some edge-case 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?

Two sentences with no waste. The purpose, return value, and credential handling are all front-loaded, making it efficient and easy 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?

The description covers the tool's purpose, return structure, credential types, API endpoints, and parameter nuances. It is complete for an agent to decide when and how to call it, given that an output schema exists and the description already explains the returned fields.

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 0%, so the description must fully explain parameters. It does: cost is the planned cost, and wallet_id is optional with behavior described (omit to resolve via /wallet/me, or pass for a specific wallet). This adds significant meaning beyond the bare schema 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?

The description clearly states the tool reads a balance for a planned cost and returns a structured decision object {needed, have, shortfall, tool_to_call_next}. It uses specific verbs and resources, and distinguishes itself from siblings like joules_balance by focusing on affordability decision rather than just balance reading.

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 explains when to use the tool (to decide if the agent can afford the next call) and provides context on credential types and wallet_id optionality. It does not explicitly name alternatives or state when not to use it, but the context is clear enough for an agent to select it appropriately.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the data is public, requires no auth, and is independently checkable, which are useful behavioral traits. It doesn't mention read-only status, but for a zero-parameter verification tool this is implicitly read-only; the disclosed traits add value beyond the name.

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 that front-loads the purpose and includes key traits (public, no auth, independently checkable) with no waste. Perfectly concise and well-structured.

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

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

For a zero-parameter tool with an output schema, the description is complete: it states what is returned, the auth requirement, and verifiability. The output schema covers the return structure, so nothing essential is missing.

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

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

The tool has zero parameters, so there is nothing to document. The description does not need to explain parameters; a baseline of 4 applies since the description correctly omits irrelevant parameter 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?

The description states exactly what the tool returns: recent public ledger anchors with transaction IDs and credit supply. It is specific and unambiguous, and while it doesn't name siblings, the content is distinct enough to avoid confusion with other ledger-related 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?

The description notes that it is public and requires no auth, which implies when it can be used, but it gives no explicit guidance on when to prefer it over alternative tools like verify_proof or balance_proof. There are no exclusions or when-not-to-use conditions.

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 description carries the full burden and does so richly: agent-keys-only restriction, billing/refund semantics, metering states (settled_zero, settle_failed, released), replay/idempotency rules, and the crucial 'don't claim stronger than provenance' guidance. This is exactly the behavioral 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?

Front-loads the core purpose well, but then balloons into a very long metering/provenance essay with heavy formatting (caps, ⚠, multiple em-dash clauses). Much of it is valuable but the density and length hurt scannability.

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 metered image tool with an output schema and no annotations, it covers return shape, provenance fields, error/refund behavior, and metering. Slightly over-complete on billing narrative relative to what a single call requires.

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 0%, so description must compensate: it explains as_of as 'newest scene on/before that date', max_cloud as 0-100 default 20, and the mutual-exclusion pose (lat/lng OR entity_type+id). The id/entity_type pair is somewhat implicit but recoverable from context.

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

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

States a specific verb+resource ('Satellite still of a place — a Sentinel-2 ARCHIVE image') and distinguishes it from the sibling by naming `look_from` and describing the 'pose' it shares. The agent can tell what it returns (jpeg) and what it's not.

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

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

Gives explicit conditions: pose can be lat/lng OR entity_type+id, and tells the agent to quote first with billing_quote. It doesn't spell out when to use this vs look_from or look_through beyond the pose note, so not a full 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 fully discloses metering and settlement behavior: debited from the calling agent's wallet, top-level `charged_joules` as all-in price, 0.5% rail surcharge, reservation/settle cycle, 4xx releases, replay policy requiring same credential+key, and settlement states. It also exposes the `entity_type` dual behavior and the 400-on-unknown-type before charge, leaving no ambiguity about side effects.

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

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

The description is front-loaded with the core purpose and covers essential operational detail, but it is verbose and somewhat redundant—e.g., the all-in price and 0.5% rail surcharge are stated both in the first paragraph and again in the 'WHAT YOU PAID' section. With careful trimming it could be tightened without losing 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 the tool's complexity—7 optional params, metering, settlement states, idempotency—the description covers all necessary context for correct invocation: parameter semantics, charging workflow, error behavior, response indicators, and companion tools. The presence of an output schema covers return structure, and the description adds the behavioral context that the schema cannot.

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

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

With 0% schema description coverage, the description compensates by explaining every parameter: `lat`/`lng`/`radius_km` as the point and radius, `entity_type` with its filtering vs anchoring dual behavior, `id` as the anchor, `energy` for fleet infrastructure, and `include_country_centroids` for placeholder pins. The interaction between `entity_type` and `id` is made explicit, which is critical and absent from the schema.

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

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

The description opens with a specific operation—'pins near a point (lat/lng + radius_km)'—and names the resource (pins) and geographic inputs. It clearly distinguishes itself from the billing/wallet siblings it references, though it does not explicitly contrast itself with geospatial siblings like `look_at` or `nearby`. The core purpose is unambiguous.

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

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

The description gives clear context for pre-call steps (use `billing_quote`, `joules_deficit`, etc.) but does not explicitly state when to use this tool instead of other geospatial tools like `look_at` or `nearby`. There is no when-not or alternative selection for the geospatial lane, so usage guidance is implied from the 'Map lane' label rather than explicit.

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

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

No annotations are provided, so the description carries the full burden and does so richly: read-only with no side effects beyond charge, cache keyed by pose + scene date, reserve-then-settle charging, 4xx releases the reservation, and idempotency semantics ('a retry here is always a new charge'). It also discloses the auth requirement ('AGENT KEYS ONLY, a browser session is refused BEFORE any charge'). This is far beyond what structured fields supply.

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

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

Front-loads the core concept before parameters and billing, which is the right order. It is long and dense with heavy parentheticals and ALL-CAPS emphasis, and a few clauses are redundant (the 'never a fabricated image, never a scene borrowed' point is restated), but given zero schema/annotation help most sentences earn their place.

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

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

Despite an output schema existing (so return values needn't be explained), the description covers the frame fields, the available:false behavior, and the full billing/verification workflow. Combined with no annotations and 0% schema coverage, this is complete enough for an agent to call and interpret results 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?

With 0% schema description coverage across 8 params, the description fully compensates: t0 format (YYYY-MM-DD, on/after 2015-06-23), t1 default today, max_frames range 1-12 default 6 and its windowing semantics, max_cloud 0-100 default 20, and the lat/lng OR entity_type+id pose rule. Ranges, defaults, and formats are all supplied.

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 ('ordered stack of dated Sentinel-2 archive stills of ONE site across a date range') and immediately scopes it against the sibling look_at ('the same pose rule as look_at'). An agent can distinguish it from look_at/look_from without opening either schema, and it explicitly notes what it does NOT do ('does NOT say what changed between frames').

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: the pose rule, date-range bound, and a mandatory charging workflow ('Quote first: billing_quote("/api/v1/look.through")'). It references look_at's pose and cache, implying the sibling relationship, but never explicitly states when to choose this over look_at for a single still. No explicit exclusions beyond the 'does not say what changed' note.

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

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

With no annotations provided, the description carries the full burden, and it handles it exceptionally well. It discloses the 403-before-meter billing behavior, the gating flags, the fact that nothing is charged, the temporary closure rationale, and the condition under which it reopens as metered. This is far beyond typical behavioral disclosure.

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

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

The description is front-loaded with the critical status ('CLOSED — do NOT call') and every subsequent sentence earns its place: rationale, billing impact, alternatives, enumeration-stability reason, and reopen condition. Despite carrying many details, it remains tightly organized and scannable.

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

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

Given the tool's current disabled state, two parameters, and existing output schema, the description covers everything an agent needs: it must not call this tool, it will not be charged, and it has concrete replacements. The conditions for future reopening are also specified, making the context complete.

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

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

Schema description coverage is 0%, so the description needed to compensate for the two parameters. It only names 'layers + include_country_centroids' without explaining valid values for layers, what include_country_centroids affects, or how the parameters interact. The parameter titles in the schema already provide roughly the same shallow 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?

The description explicitly identifies the tool as 'the bulk map-layers surface' and immediately states its current status: 'CLOSED — do NOT call.' It also distinguishes itself from siblings by naming map_viewport and look_from as the alternatives for bounding-box and pose queries, so an agent can tell exactly what this tool is and is not for.

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

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

The description gives explicit when-not-to-use guidance ('do NOT call') and concrete when-to-use-alternative guidance: use map_viewport for a bounding box and look_from for a pose. It even explains that the tool is kept only for enumeration stability, leaving no ambiguity about the correct action.

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?

Even though no annotations are provided, the description carries the full burden and does so comprehensively. It discloses that pins are a sample while counts are true totals, explains charging mechanics (reservation, settlement, idempotency), rate limits, auth requirements (agent keys only), and even details the metering block states (settled, settled_zero, settle_failed, released). It also notes that pins do not count against entity caps and that energy, pipelines, and centroids are excluded unless specified. This is exemplary behavioral transparency.

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 verbose, with several long paragraphs dedicated to billing and metering edge cases. While it is structured and front-loaded with the core purpose and parameters, much of the metering detail could be condensed without losing critical information. It earns its place in terms of necessity but is not concise; it could be trimmed for clarity.

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

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

Given the tool's complexity—billing, sampling, multiple response fields, auth, and rate limits—the description is exceptionally complete. It covers authentication, rate windows, response structure (pins, counts, charged_joules, metering block), and even error states like settle_failed. The output schema exists but the description still adds valuable context that an agent needs to call the tool correctly and interpret results.

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

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

With 0% schema description coverage, the description fully compensates by explaining each parameter's meaning, defaults, and constraints. It clarifies that the four bbox parameters must be provided together, describes the default for entity_type (all four types), energy (False), and include_country_centroids (False). This adds essential meaning beyond the bare schema, which only lists names and types.

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

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

The description clearly states the tool's purpose: mapping everything inside a bounding box, relaying a specific API endpoint. It specifies the verb (map), resource (viewport), and scope (bounding box). However, it does not explicitly differentiate this tool from sibling tools like look_at or mapdata, which also provide map-related data, so it lacks sibling 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?

The description provides no guidance on when to use this tool versus alternatives. It does not mention when not to use it or what other tools might be more appropriate. There is no explicit exclusions or context for choosing this over look_at, nearby, or mapdata. This is a significant gap for an agent deciding between tools.

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 discloses the critical effect 'releases escrow to the provider' and notes the backend enforcement of buyer role. It does not elaborate on idempotency behavior or potential error outcomes, but the key side effect is clearly stated.

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 with no unnecessary words. The main action is front-loaded, and the role constraint is succinctly appended. Every sentence contributes 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?

Given an output schema exists, return values are not required. The description covers the purpose, the required role, and the main side effect. It lacks details about idempotency usage or error conditions, but for a simple accept action, it is sufficiently complete.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies match_id via the endpoint path, but provides no explanation of idempotency_key. The parameter names are self-explanatory, but the description adds limited value beyond the schema itself, especially for the optional parameter.

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

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

The description states a specific verb ('Accept'), a resource ('a delivery on a match'), and includes the HTTP endpoint. It clearly distinguishes this from sibling tools like market_provide or market_request by focusing on the acceptance action and the buyer role.

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

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

It explicitly states the condition 'You must be the buyer party; backend enforces it,' which guides when to use this tool. It does not explicitly mention alternatives or when not to use it, but the role constraint makes the context clear.

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

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

With no annotations provided, the description discloses the authentication requirement (needs a bearer) and confirms read-only operation (no write scope). It also notes the default active=True and limit<=200. However, it does not mention pagination beyond offset/limit, return format, error handling, or rate limits, leaving some behavioral gaps.

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 concise, with two sentences covering purpose, parameters, defaults, and auth. It is front-loaded with the primary purpose and packs significant information efficiently without 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?

Given the output schema exists, the description covers essential aspects: kind selection, parameter list with defaults, limit constraint, auth, and read-only status. It does not explain every parameter's semantics in depth, but for a browse tool with an output schema, the coverage is adequate for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It lists the query parameters (frontier, resource_type, oracle_verified, active, limit, offset, sort) and gives some defaults and constraints (limit<=200, default 50, sort default 'price_asc'). It adds context beyond the schema names but does not explain the meaning of frontier or resource_type, so compensation is partial.

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

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

The description clearly states it browses the RAREEAI marketplace and distinguishes two kinds (providers and oracles). It uses the verb 'browse' with a specific resource, making the purpose obvious. It does not explicitly compare to sibling tools like market_accept or market_request, but the contrast is implied.

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

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

The description provides clear usage context: which kind to specify, the available query parameters, defaults, and the limit constraint. It implicitly indicates this is the read/browse tool versus the action tools, though it does not explicitly state when to use it over alternatives.

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

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

With no annotations provided, the description carries the full burden, and it delivers: it signals a read-only operation, discloses auth and access requirements, and clarifies that dispute_window_end is only populated on oracle-path trades and represents the dispute deadline. This is rich behavioral context beyond the schema.

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 core action and then adds only high-value details: access condition, auth requirement, and an important field nuance. Every sentence earns its place, and the trade_settlement pointer is a compact way to avoid misuse.

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

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

For a one-parameter read tool with an output schema, the description is complete: it covers authentication, required party status, field-specific behavior, and the relevant sibling alternative. Nothing invocation-critical is missing.

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

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

Schema description coverage is 0%, so the description must compensate for the single match_id parameter. It adds that the id refers to one marketplace match, but it does not explain the id's format, origin, or how an agent should obtain it. The property name and title already carry much of the semantic weight.

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 'Read one marketplace match by id', clearly identifying the verb, resource, and scope. It also names trade_settlement as the sibling for whole-trade settlement legs, which distinguishes this tool from related siblings.

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

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

It explicitly states the requirement that the caller must be a party to the match, that Bearer auth is required, and it directs the agent to trade_settlement when the whole trade's settlement legs are needed. This gives concrete when-to-use and when-not-to-use guidance.

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

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

With no annotations provided, the description carries the full burden, and it delivers: it discloses the mutation effect (create/update), the non-refundable fee, the typed-body strictness (extra fields refused), and the optional oracle_verified opt-in semantics. It also notes the idempotency_key, which hints at retry behavior. This is rich behavioral context beyond the schema.

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

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

The description is dense but efficient: it front-loads the action, then packs permission, fee, body shape, and caveats into a compact block. The parenthetical asides and inline field list are information-dense rather than padded. It loses one point for being somewhat long and requiring careful parsing, but every sentence earns its place.

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

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

Given the tool's complexity (create/update, fee, permissions, optional fields, idempotency), the description covers the critical operational facts: auth requirements, cost, strict body typing, and the optional oracle opt-in. The output schema exists, so return-value details are not needed. An agent has enough to call this correctly and avoid common mistakes.

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 0%, so the description must compensate. It lists all body fields with inline type/constraint hints (e.g., price_joules_per_unit int >=0, sla dict, timeout_hours/timeout_minutes alternatives) and clarifies the oracle_verified field's meaning ('opt in to oracle checks'). It doesn't explain every field's purpose in depth, but it adds meaning well beyond the bare schema.

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

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

The description opens with a specific verb phrase 'Create/update a marketplace listing' and names the exact endpoint (POST /provide), which clearly distinguishes it from sibling tools like market_accept, market_request, and market_quote. It also enumerates the resource types and fields involved, leaving no ambiguity about what the tool does.

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

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

The description explicitly states the required permission (marketplace:write, verified account) and the failure mode for unverified/under-scoped tokens (backend's real 403). It also contrasts the 1,000-joule fee with an oracle stake, clarifying when this tool is appropriate versus oracle_register/oracle_deregister. This is strong when-to-use guidance.

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

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

Annotations are absent, so the description carries the full burden. It discloses that the route requires ownership (Bearer required), and clarifies that escrow_terms is a generic prose block, not specific to this trade. It also explains what fields are NOT included and where to find them, which is transparent about limitations.

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 detailed but front-loads the essential purpose, then adds necessary clarifications. Every sentence serves a purpose, distinguishing this tool from alternatives. Slightly verbose but still efficient given the complexity of the domain.

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

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

Given the output schema is present, the description doesn't need to list all fields, but it does, which is helpful. It covers the key context: ownership, data availability, and where to get missing data. It lacks details on error cases or response format specifics beyond the schema, but it is sufficient for a single-parameter read 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?

With schema description coverage at 0%, the description must compensate. The description doesn't explicitly elaborate on request_id beyond the schema, but it does explain the context of the request (ownership, route). Since there is only one parameter and it is self-explanatory, the description doesn't need much more, but it could have clarified the format (e.g., UUID), so a 4 is reasonable.

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

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

The description clearly states it reads a single marketplace REQUEST by id and lists the fields returned, distinguishing it from siblings like market_match and market_listings. It uses a specific verb (Read) and resource (marketplace REQUEST), and mentions the ownership requirement, which adds clarity.

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

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

It provides clear context: use when you need the raw request data and own the request. It explicitly directs the agent away from using it for match-specific fields (like fee_joules, escrow_expires_at) and points to market_match instead, offering a clear alternative for those cases.

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: auth model (Bearer + verified account, marketplace:write, real 403 on under-scoped tokens), the side effect (escrow debited on match), typed-body strictness (extra fields refused), and the full escrow-lane behavior including the default ledger lane, the opt-in contract lane, oracle-dependency, and the fallback with contract_note. This is well beyond what structured fields supply.

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

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

The purpose and auth/escrow consequences are front-loaded, and every section (body, physical trades, escrow lane) maps to a real decision the caller must make. It is dense and long, but given the tool's complexity the length is mostly earned 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?

An output schema exists, so return values need not be explained, and the description covers everything else an agent needs: auth/scope, error behavior, the full body contract, physical-claim prerequisites, and escrow-lane outcomes. Nothing required to invoke it correctly is missing.

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

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

Schema description coverage is 0% at the top level, so the description must compensate and largely does — it enumerates every body field and gives semantics for the important ones (wallet_id pays escrow, units_needed int >0, max_price_per_unit int >0 in joules, ttl_seconds as expiry). It is docked because several fields (speed, priority, privacy_mode, requirements) are listed with no meaning beyond their names.

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

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

States a specific verb and resource ('Post a marketplace BUY request (POST /request)') and immediately clarifies direction: 'you want to buy a resource; providers match against it.' This lets an agent distinguish it from the sell-side sibling market_provide 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 an explicit workflow rule — 'Quote a specific request with market_quote before accepting a match' — naming the sibling and the condition that selects it. It also scopes when physical_claim is mandatory. It stops short of a full when/when-not contrast against market_provide or market_accept, so it is not a 5.

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

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

The description goes into exceptional detail about the metering and charging behavior: reservation, settlement, what happens on empty results, partial traversal, 4xx responses, abandoned calls, and replay conditions. It also explains the `metering` block and `charged_joules` fields. Since no annotations are provided, this thorough disclosure of cost behavior is highly valuable and exceeds the burden of transparency.

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

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

The description is long and heavily weighted toward billing details, which are important but could be summarized more concisely. It is structured into sections (params, metering, payment) which aids readability, but the length may overwhelm an agent looking for core functionality. Every sentence is informative, but the overall density reduces conciseness.

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

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

The description thoroughly covers the billing and metering aspects, but it omits functional details such as what the returned entity data looks like (beyond the metering block), how results are ordered, and what entity_type values are valid. Given the tool has an output schema, the description does not need to enumerate the full response, but it should at least mention the nature of the entities returned. The billing focus leaves the core query behavior underdescribed.

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

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

The description lists all six parameters and adds constraints (radius_km default 100, limit <=100 default 20, include_country_centroids default False). However, it does not explain what entity_type accepts (no enums or examples) or what include_country_centroids actually does. With 0% schema description coverage, it partially compensates but leaves key semantics unclear.

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 the tool returns 'Entities near a location' and references it as the primitive `look_from` builds on, which gives a general sense of purpose. However, it lacks a direct verb like 'find' or 'list', and does not specify what constitutes an entity or what the response looks like beyond the metering fields. It also does not differentiate it from sibling tools like `look_at` or `hops`.

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

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

The description provides no guidance on when to use this tool versus alternatives. It mentions that `look_from` builds on it but does not explain when to choose `nearby` over `look_from` or any other related tool. There is no statement about use cases, exclusions, or preferred conditions.

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 full behavioral burden and excels: it discloses the 409 late-verdict semantics, the auto-dispute threshold, the oracle fee split and clamping, consensus majority behavior, expiration of remaining assignments, and the provider-reputation gate. This is precisely the non-obvious behavior an agent needs to avoid costly mistakes.

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?

Although long, every sentence adds operational value: endpoint, body shape, fee economics, deadline, error handling, consensus, and edge-case reputation logic. The critical 409 warning is front-loaded, and no filler exists.

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

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

The description is complete for a high-stakes write tool: it covers request shape, side effects, failure modes, timing constraints, and economic consequences. Since an output schema exists, not detailing the success response is acceptable; the operational edge cases are thoroughly documented.

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 0%, and the description fully compensates by explaining each parameter: verdict values, quality_score range, notes length, and the optional execution_trace dict. It goes beyond the schema by adding the behavioral consequence that a quality_score below 40 auto-opens a dispute.

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

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

The description opens with a specific verb and resource: 'Post your verdict on a delivery you were assigned' and even gives the endpoint. It clearly distinguishes this from sibling oracle tools like oracle_register and oracle_assignments by focusing on submitting an assessment for an existing match.

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 explicit when-to-use guidance ('Assess within the 48-hour deadline'), prerequisites ('Requires being the assigned oracle + marketplace:write'), and when-not-to-use behavior: on a 409 late response, 'do NOT retry, read the match instead.' It also explains consensus rules so the agent knows it is not required to wait for all oracles.

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

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

No annotations are provided, so the description carries full responsibility for behavioral disclosure. It goes beyond the obvious by revealing wallet scoping, the 48-hour lapse rule for deadlines, the fact that each assignment may already carry a verdict/quality, and the auth prerequisite. These are meaningful behavioral traits an agent needs to know before calling, and they are all present.

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 efficient and front-loaded, placing the primary action first. It packs endpoint, scoping, parameters, return fields, deadline behavior, and auth into a compact block. It is slightly dense with multiple parentheticals, but every sentence contributes useful information and there is 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 an output schema present and only 2 optional parameters, the description covers everything needed to invoke the tool correctly: what it returns (match_id, deadline, fee_earned, verdict/quality), the parameter constraints, the auth requirement, and the behavioral scoping. No essential context for a filtered-read tool 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 0%, so the description must compensate. It does: 'limit (1-200, default 50)' adds the valid range and explicitly notes the default, and 'status (filter)' explains the purpose of the otherwise unannotated parameter. It doesn't enumerate possible status values, which is a minor gap, but it adds substantial meaning beyond the bare schema.

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

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

The description opens with a specific verb+resource: 'List YOUR oracle assignments — the deliveries you have been assigned to assess.' It clearly distinguishes itself from the sibling 'oracle_assess' (which presumably performs the assessment) by stating this is a listing operation scoped to the caller's own wallet, with the explicit 'you never see another oracle's queue' boundary.

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 clear context for when the tool is appropriate: when you want to see your assigned deliveries for assessment, with optional status filtering. It also communicates the authentication requirement ('Authenticated read — no marketplace:write needed'), which is useful for routing. However, it does not explicitly name alternatives or state when not to use this tool, 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?

No annotations are provided, so the description carries full burden. It discloses the return (staked joules from escrow, less slashed amounts), failure condition (pending assessments), parameter placement (query parameter), and authentication requirement (marketplace:write). This is thorough and leaves no ambiguity about side effects.

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

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

The description is dense but every clause adds value: purpose, return, failure condition, parameter specifics, and auth. It is front-loaded with the core action and avoids redundancy, making it efficient and well-structured.

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

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

Given the presence of an output schema, the description need not detail return values. It covers the endpoint, authentication, parameter format and constraints, and failure conditions, which is sufficient for correct invocation. It also mentions behavioral differences from sibling tools, making it contextually complete.

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

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

The input schema has no description for wallet_id (coverage 0%), but the description compensates by explaining it is the UUID of the oracle wallet, required, and sent as a query parameter. This adds critical meaning that the schema lacks.

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 action: 'Deregister as an oracle and unstake' and identifies the specific endpoint. It also distinguishes from sibling tools by noting that wallet_id is sent as a query parameter unlike register/assess which take a body, making the tool's role unambiguous.

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

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

The description provides concrete conditions: requires wallet_id, requires marketplace:write permission, and fails if pending assessments. It implicitly guides usage by contrasting with register/assess, but does not explicitly list when not to use the tool or mention alternative tools beyond the contrast.

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

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

With no annotations present, the description carries the full behavioral burden and fully discharges it: the invite-only gate returns a STRUCTURED response rather than an error, the stake is held in escrow and refunded on deregister, dispute overturns slash 10%, and specific auth scopes are disclosed. This far exceeds what annotations would typically 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?

The core purpose is front-loaded in the first sentence, and every subsequent sentence earns its place: gate behavior, parameter contracts, escrow/dispute consequences, and auth scope. It is long, but the tool involves an invite gate, strict validation, and financial stakes — there is no 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?

An output schema exists, so return-value documentation is unnecessary. For a tool of this complexity, the description covers all needed ground: what it does, who is eligible, how the invite gate behaves, every parameter constraint, financial consequences (refund vs. slash), and required permissions. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 0%, so the description must compensate — and it does comprehensively. It supplies the exact allowed enum values for specialisations (code, translation, data, general, content, research, infrastructure), the 1-to-7 count bound, the 422 error for invalid values, the UUID-ownership requirement for wallet_id, and the integer-and-unit semantics for stake_amount (joules). All of this exceeds what the bare schema provides.

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

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

The opening sentence states a specific verb ('Register'), resource ('as a RAREEAI oracle'), and mechanism ('by staking joules') with the exact endpoint. It also implicitly distinguishes from the sibling set by contrasting the refundable oracle stake with the non-refundable provider listing fee, and references deregistration, which separates it from oracle_deregister.

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

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

The description gives clear application context: INVITE-ONLY at launch, the application path for non-whitelisted wallets, and the access requirement (verified account + marketplace:write). It contrasts the refundable stake with a provider listing fee, which implies the provider-registration alternative, though it never explicitly names that sibling or states a when-not-to-use condition.

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

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

No annotations are provided, so the description carries the full burden and meets it: it discloses party-gated 404 behavior (hiding match existence), the meaning of settled and all_anchored, the broadcast-vs-confirmation timing of txid, that a null txid is not a failure, and the ledger-lane 'contract: null' case as normal. It also differentiates contract legs from settlement legs and states auth requirements.

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 purpose and is organized into a main results section and a contract section, but it is exceptionally long and repeats some information (e.g., role explanations in legs and contract). While the density is justified by the tool's complexity, it could be tightened by leaving field-level return details to the output schema.

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

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

The description is complete for an agent to call it safely: auth, gating, error semantics, field interpretations, polling guidance, escalation paths, and relation to verify_proof and deposit_status are all present. With an output schema present, the description goes beyond what is required and covers edge cases like dead-lettered anchors and no-contract trades.

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 schema description coverage at 0%, the description is the only source of parameter meaning. It clarifies that match_id is the trade identifier from the marketplace and that passing a match_id you are not a party to yields a 404, so the parameter semantics are workable. It doesn't provide an example or acquisition path, but the context from siblings (market_match) fills that gap.

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

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

The description names a specific verb and resource: retrieving the settlement legs of a marketplace trade the caller was buyer or seller of. It explicitly scopes to 'YOUR OWN trade' and contrasts with deposit_status and a single transfer's status, distinguishing this tool's trade-wide view from siblings. The relayed endpoint is even cited.

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

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

It clearly states when to use the tool: for the trade-wide settlement view, not just one leg, and only for own trades, with bearer or agent key required. It advises polling when anchor is queued/confirming/confirmed, using verify_proof for on-chain verification, and escalating on failed/cancelled anchors, and contrasts with deposit_status and single-transfer status for narrower views.

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 discloses a great deal: required wallet:transfer scope, role-based destination rules, live-read limits, fee, 202 bridge block fields, and verbatim backend errors. It even warns against planning on remembered config values and against minting settlement-shaped idempotency keys.

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

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

The text is long, but the complexity of a live-configured, role-restricted money movement endpoint justifies it; the core action and scope appear first. All-caps flags and explicit anti-instructions are dense but purposeful, though tighter formatting would improve scannability.

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 financial write endpoint with no annotations and an opaque body parameter, the description covers auth, eligibility, limits, fees, response payload expectations, and failure behavior. An output schema exists, and the description largely makes the tool safe and correct to 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?

Although schema_description_coverage is 0%, the description enumerates the typed body, marks optional fields with ?, and clarifies the to_wallet_id | to_handle alternative and registration_id's role for agent-class quoted transfers. It doesn't deeply explain platform, privacy_mode, and include_proof, but their names and optional markers give reasonable semantic grounding.

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 'Direct wallet-to-wallet transfer' plus the endpoint POST /wallet/transfer, naming a precise verb, resource, and HTTP operation. This is enough to distinguish it from sibling tools like deposit, market_*, or trade_settlement, even though it doesn't explicitly name them.

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

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

It lays out explicit eligibility rules (verified-human vs agent-class), required registration_id for agent-class transfers, and hard 'refused 403' cases with instructions not to retry and to use a fresh opaque key. It doesn't name sibling tools as alternatives, but the when/when-not conditions are concrete and actionable.

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