GREENLANDAI

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, covering safety. The description adds useful behavioral details: the anchoring BSV txid may be 'pending' until batch broadcast, and it includes verification instructions, which go beyond structured fields.

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

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

Two sentences, front-loaded with the core purpose and followed by key return values and usage note. No wasted words; every clause 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 the output schema exists, the description need not detail return values, yet it helpfully lists them. Annotations cover safety, and the description adds credential context and pending-status behavior, making it complete for an agent to call correctly.

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

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

With zero parameters, the baseline is 4. The description clarifies that no arguments are needed because the wallet is implicitly determined by the caller's credential, adding meaning beyond the empty 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+resource: 'Inclusion proof for YOUR wallet balance in the latest hourly transparency attestation'. It enumerates the returned fields (leaf hash, Merkle path, root, txid) and clarifies it's for the caller's own wallet, distinguishing it from siblings like verify_proof or transparency_latest that serve different roles.

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: it's for the caller's own wallet (credential-owned) and covers the latest hourly attestation. However, it does not explicitly name when to use this tool versus alternatives (e.g., verify_proof for verification or transparency_latest for general attestation data).

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

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

Annotations already declare readOnly/non-destructive/closed-world, and the description adds real context: results are scoped to your own wallet and credential only (no cross-wallet visibility), the status vocabulary is listed, and reserved-vs-settled joules is called out. Pagination defaults are left to the schema rather than contradicted.

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

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

Two sentences, front-loaded with the scoping claim, and the dangling '…' after the status list is a minor sloppiness. Nearly every clause (own wallet, statuses, joules fields, attempt_id join, paging) carries information.

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

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

With an output schema present, the description does not need to explain return shapes, yet it still highlights the fields an agent will care about and how attempt_id links to metering. Combined with annotations covering safety, an agent has enough to call this correctly.

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

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

Schema coverage is 100% and both parameters carry their own descriptions (range, defaults), so 'Paged with limit and offset' is a restatement rather than added meaning. Baseline 3 applies when the schema already does the heavy lifting.

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

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

Names a specific resource and scope: the caller's OWN charge attempts, pulled from their own wallet/credential, with the returned fields enumerated (status, reserved vs settled joules, attempt_id). The read/list verb is only implied by 'Paged with limit and offset', but the resource is unambiguous against siblings like deposits, trade_settlement, and billing_quote.

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 for when to reach for it: inspecting your own billing attempts and resolving an attempt_id seen in a call's `metering.attempt_id`. It never names a competing sibling or an exclusion, so it stops short of full when/when-not guidance.

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

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

Annotations already establish that this is a safe read-only, non-destructive, closed-world operation. The description adds useful behavioral context beyond that: the quote is free, it reports the true debit via joules_all_in, and it indicates when the price is a maximum and when an empty answer is free.

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 short and front-loads the core value proposition: exact pre-call price and free quote. Some phrasing such as 'Fund joules_all_in, the true debit' is slightly compressed and cryptic, but it does not waste space.

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, complete parameter descriptions, and read-only annotations, the description provides enough context for an agent to understand that this is a free preflight cost quote. It could be more complete by clarifying how site-related parameters affect the quote, but the structured fields carry that burden.

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

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

Schema description coverage is 100%, so the schema already documents the parameters in detail. The description adds a useful clarification for `path` and mentions `hops`, but most parameters are left to the schema, which is appropriate given the high coverage.

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

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

The description clearly states that this tool returns the exact price of a metered API call before the call is made, and that the quote itself is free. It is specific about the resource (metered call pricing) and gives a concrete path example, though it does not explicitly distinguish itself from quote-adjacent siblings such as market_quote.

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 implied usage context ('before you make it') and points to funding joules_all_in, but it does not explicitly say when to use this versus alternatives like market_quote or funding_prepare, nor does it state 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?

Annotations already cover read-only, non-destructive, closed-world behavior, and the description adds real value on top: it discloses the exact payload fields and the temporal behavior that the txid reads "pending" until the hourly batch broadcast. It does not discuss rate limits or empty-result behavior, but the core behavior is well disclosed.

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

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

A single front-loaded sentence naming the resource before the detail, with the scope note appended. The parentheticals are dense but each carries information (event types, pending semantics); nothing is redundant.

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

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

For a zero-argument read tool with an output schema and full annotation coverage, the description supplies what structured fields cannot: the credential scoping and the "pending" anchoring state. Return values are explained beyond what is strictly needed, leaving little an agent would still need to ask.

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

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

With zero parameters, the baseline is 4. The description earns that baseline by explaining why there are none — the call is implicitly scoped to the caller's credential — so an agent understands no filters can be 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 resource (Bridge Ledger rows, contribution and fee events) and enumerates the returned artifacts (leaf hash, Merkle path, bridge_root, BSV txid). It implicitly separates itself from balance_proof by scoping to ledger-row inclusion proofs, though it never explicitly contrasts with verify_proof or ledger_verify.

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 arguments: scoped to your credential" implies the usage context (your own rows only), but there is no explicit when-to-use / when-not-to-use guidance and no routing to sibling tools such as verify_proof for verification use cases. Usage is inferable but not stated.

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

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

Annotations already declare readOnly/non-destructive/closed-world, and the description goes beyond them with the metering requirement, the 404 outcome, and the `merged` marker for moved ids. It stops short of saying whether `merged` yields a redirect payload or an error, which leaves one behavioral edge ambiguous.

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?

Four short sentences, all front-loaded and load-bearing: what it returns, the name-based alternative, the 404 behavior, and the billing prerequisite. No filler or restatement of the name.

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

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

An output schema exists, so return values need not be described in detail. The description still covers the access path, the fallback tool, the error case, redirect handling, and the cost/payment workflow — everything an agent needs before calling.

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

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

Schema coverage is 100% and the single `id` parameter is fully documented in-schema, so the description need not repeat it. It only adds that names should be resolved via `company_search` first, which is routing guidance rather than new id semantics.

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

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

States a specific verb+resource (fetch one company's record by id) and enumerates what the record contains: the company, its deposits and infrastructure, relationships with tier and provenance. It is clearly separated from `company_search` (name-based) and from other entity tools.

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

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

Explicit routing: 'Have only a name? Call `company_search` first.' Plus an explicit prerequisite for metered calls (quote first with `billing_quote`, see CHARGING). The unknown-id 404 case is also declared, so the agent knows what failure looks like.

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

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

Annotations only declare readOnly/non-destructive/closed-world; the description adds substantive behavior beyond that: metered billing with a single 'charged_joules' total, cost equivalence to the three constituent calls, lean-by-default payload sizing, and a pointer to server-level CHARGING docs. That is exactly the cost and payload context an agent cannot infer from annotations.

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

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

Three dense clauses, front-loaded with the composite payoff and followed by payload and billing behavior. No filler; every clause carries information an agent needs before invoking.

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 structure needn't be described, and billing, defaults, and the pre-flight quote path are all covered. Minor gap: it never clarifies what 'lean' actually trims, which matters for deciding whether to set include_raw before paying.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it frames the lean-vs-full tradeoff that governs include_raw and implies fields/hops only shape an already-bundled payload. It does not elaborate on hops or fields, leaving those entirely to the schema.

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

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

Names a specific composite resource and enumerates exactly what it bundles: 'company + relationships + entity_history for one company in ONE call.' This implicitly but clearly distinguishes it from the siblings company, relationships, and entity_history, which return only one of those parts.

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

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

Gives concrete usage guidance: 'Lean by default; include_raw for everything' and 'quote first with `billing_quote`', which routes the agent to a sibling before spending. It stops short of explicitly saying when to prefer this composite over three separate calls, though 'billed exactly as the three would be' strongly implies the tradeoff.

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

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

Annotations already declare readOnly, non-destructive, closed-world, so the safety profile is covered; the description adds genuinely new behavior: it is metered, billing is governed by server CHARGING instructions, and a quote should precede the call. Pagination semantics ('one page by limit and offset') are also disclosed, though nothing is said about rate limits or cost magnitude.

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

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

Three sentences, front-loaded with the lookup purpose, followed by return shape and then the metering caveat. No filler and nothing buried.

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

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

For a read-only search tool with a full output schema, this covers everything an agent needs: what it finds, what it returns for chaining, how paging works, and that the call is billed and should be quoted first. The external CHARGING pointer is an appropriate handoff rather than a gap.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema; the description only maps the resource to three of the filters and notes paging. That is a modest restatement rather than added semantic detail (no guidance on combining filters, partial-match limits, or interaction between `fields` and the returned keys).

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 ('Find companies') plus the searchable dimensions (name, sector, country) and the concrete output the caller wants (the id). It also distinguishes itself from the downstream tools that consume that id (`company`, `relationships`, entity tools), so an agent can tell what this tool is for without opening a schema.

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

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

Explicitly frames usage as a lookup step that feeds `company`, `relationships` and the entity tools, and names a prerequisite alternative action ('quote first with `billing_quote`'). It stops short of naming exclusions against similarly scoped siblings (e.g. `company_profile`), but the routing context is clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds real value on top: immutability (append-only), ownership scoping ('your OWN'), and the auth requirement (enabled gai_ key as X-API-Key). It omits ordering guarantees and how paging interacts with an append-only log, which is the one operational detail an agent would want.

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

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

Three short clauses, front-loaded with the resource and its hash, then auth, then paging. The metaphorical 'check the door holds what you sent' is slightly cryptic in a tool description but is not wasted space; the 'Paged.' fragment is efficiently placed.

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 no explanation, and auth plus scoping are covered. Still, with a sibling named `receipts_me` in the same namespace, the definition leaves genuine ambiguity about which endpoint this is versus the alternative — a gap for a low-complexity 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?

Schema description coverage is 100% with only limit and offset, both defaults documented inline. 'Paged.' confirms pagination behaviour but adds no semantics beyond the schema, so the baseline 3 applies.

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

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

States a specific resource (your own append-only contribution receipts) plus the distinguishing payload (canonical claim_sha256 hash) and its purpose (verify what you sent). Clear verb-and-resource identity, but it never distinguishes itself from the close sibling `receipts_me`, leaving an agent to guess which receipt endpoint to call.

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

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

The phrase 'so you can check the door holds what you sent' implies an integrity-verification use case, and the X-API-Key instruction is a useful prerequisite. However, there is no explicit when-not guidance and no routing to alternatives (contribute_submissions, contribute_stats, receipts_me), so selection still requires 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?

Goes well past the annotations by disclosing the asynchronous lifecycle ('Nothing is written on submit: admitted claims queue for the nightly judge'), the evidence bar (real source_url plus verbatim quote), and the auth mechanism (X-API-Key). These are exactly the traits an agent cannot infer from readOnlyHint=false, idempotentHint=false, or destructiveHint=false.

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

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

Four short sentences, front-loaded with the action, then requirements, then the async caveat, then auth. Every sentence carries distinct information with no repetition of the title or 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?

An output schema exists so return values need no explanation, and the description covers auth, evidence requirements, and deferred adjudication. It is only slightly short of complete, omitting rejection handling and the role of the 'entities' parameter, though the schema documents entities.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds value: the schema only types 'relations' as an array of open objects, while the description names the per-item fields (subject, relation, object, source_url, quote) and insists the quote be verbatim, which the schema does not convey.

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

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

'Submit evidenced graph relationships' gives a specific verb plus resource, and the 'contributor door (TEN programme)' scopes it. It is distinguishable from contribute_receipts by the resource named, though the sibling is never explicitly contrasted.

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

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

Usage is implied: the description makes clear this is the submission path for graph relations requiring evidence, and states a precondition (an enabled gai_ key). However, it never routes the agent against alternatives such as contribute_receipts or contribute_submissions, leaving the choice to inference.

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

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

Annotations already declare readOnly/non-destructive/non-open-world, so the safety profile is covered. The description adds genuinely non-obvious behavioral context: it is authenticated and requires the enabled gai_ key sent as the X-API-Key header, which an agent cannot infer from a zero-parameter 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?

Two sentences, no filler. The scope ('your OWN') is front-loaded and the auth requirement trails as a compact operational note.

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

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

For a zero-parameter read tool with an output schema, safety annotations, and full schema coverage, the description supplies the two things structured fields cannot: caller scoping and the auth mechanism. Nothing needed to invoke it correctly is missing.

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

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

There are zero parameters, so the baseline is 4. The description adds transport-level semantics not present in the empty schema — that authentication rides in the X-API-Key header — which is the only 'parameter' an agent must supply.

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

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

States a specific resource ('your own contributor standing') and enumerates exactly what is returned: submitted/accepted/rejected totals, acceptance rate, pending review, and standing status. It's clear which of the contribute_* siblings this is not (receipts/relations/submissions are about items, this is about your aggregate standing), though it never names them explicitly.

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

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

The emphasis on 'Your OWN' implies caller-scoped usage versus broader/company-wide tools, which is a useful implicit cue. However, there is no explicit statement of when to use this instead of contribute_submissions or contribute_receipts, nor any prerequisite or exclusion.

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

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

Annotations already establish readOnly/non-destructive/closed-world, so the safety profile is covered. The description adds genuinely useful non-structured context: the required auth header (an enabled gai_ key as X-API-Key) and that results are paged. It stops short of describing rate limits or paging edge behavior, but that is minor.

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

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

Three short sentences, front-loaded with what the tool returns before the operational details (auth, paging). The fragment 'Paged.' is terse but purposeful. Little waste, though the auth sentence is slightly abrupt in phrasing.

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

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

For a two-param read-only list with a full output schema, the description covers scope, returned fields, statuses, auth, and paging — enough for correct invocation. The only gap is not distinguishing itself from the closely named contribute_receipts/relations/stats siblings, which an agent might confuse.

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

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

Schema description coverage is 100% — limit and offset are both fully documented in the schema. The description's only contribution is the word 'Paged', which confirms the intended usage pattern but adds no syntax or constraint detail beyond the schema. Baseline 3 applies.

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

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

Names a specific resource — 'Your OWN per-item submission outcomes' — and enumerates the possible states (pending_review, accepted, rejected) plus the payload contents (judge's reason verbatim, what was promoted). It implicitly separates itself from contribute_receipts/relations/stats by calling out 'per-item submission outcomes', but it never explicitly says how it differs from those siblings or uses a clear read verb like 'list'.

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

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

The phrase 'Your OWN' signals per-caller scoping, which implies when this is the right tool (checking your own results rather than someone else's). However, there is no explicit when-to-use guidance and no named alternative among the many contribute_* siblings, so the agent must infer routing.

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

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

Annotations already declare readOnly/non-destructive/closed-world, and the description adds genuinely new behavioral context: the call is metered and should be quoted before use via `billing_quote`. It stops short of saying what happens for an unknown id (error vs empty), which is the only notable gap for a lookup.

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

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

Three tight clauses of roughly equal value, front-loaded with what the tool returns. The density of backticked tool names is slightly heavy but every sentence carries actionable 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?

A single-parameter read with an output schema, so return shape needs little prose; the description covers sourcing the id and the cost gate. The only missing piece is failure behavior for a nonexistent id, which is minor given the output schema and read-only annotations.

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

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

Schema coverage is 100% and the `id` property already documents its type flexibility and provenance (from `deposits`, a pin, or a relationship row). The description only reinforces where ids come from, adding no format or validation detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource (fetch one deposit by id) and enumerates the payload (record, commodities[] with {name, role, group}, operators). It also explicitly contrasts itself with the sibling `deposits`, so an agent can distinguish a single-record lookup from the list/search tool 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 recipe: use `deposits(commodity=…)` to obtain ids, then call this tool, and quote cost first with `billing_quote`. It does not mention when to prefer the nearby sibling `deposit_brief`, which is the main remaining routing ambiguity.

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

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

Annotations already declare readOnly/non-destructive/closed-world, and the description adds genuinely new behavioral facts: billing is identical to the three separate calls with a single charged_joules total, and the tool is metered per server CHARGING instructions. It doesn't specify what 'lean' actually trims versus include_raw, leaving that to the output schema and server docs.

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 composite purpose, then cost model, then default behavior, then the quoting prerequisite. No sentence is filler, and the dense phrasing suits a metered aggregation tool.

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

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

With an output schema, annotations, and full param coverage, the description covers the remaining agent-critical concerns: cost equivalence, single-total billing, and the quote-first step. Minor gap: it doesn't clarify how 'lean' truncates relationships/entity_history or whether depth beyond hops is capped.

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

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

Schema coverage is 100%, so id, hops, fields, and include_raw are already documented. The description reinforces include_raw ('for everything' vs lean default) but says nothing about hops or fields beyond the schema, so it adds only marginal semantic value over structured data.

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

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

Names the exact composition ('deposit + relationships + entity_history for one deposit in ONE call'), so the agent knows this is a bundled read of three named sibling tools for a single entity. It is immediately distinguishable from calling deposit, relationships, or entity_history separately.

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?

Strong context: use this to get three facets in one call at the same price, and 'quote first with billing_quote' gives an explicit prerequisite for a metered tool. It stops short of saying when NOT to use it (e.g., when only one facet is needed, or for multiple deposits), so it is clear but not fully routing.

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

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

Annotations already cover the read-only, non-destructive, closed-world profile, and the description adds things annotations cannot: result shape {count, total, deposits[]}, pagination, cost metering with a pointer to CHARGING, and that `commodity` traverses a commodity graph where group matches can be included. That graph-matching behavior is a non-obvious trait an agent would otherwise get wrong.

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

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

Three tight sentences, filter list front-loaded, return shape and billing note after. No filler. The one flaw is the dangling `commodity_filter` reference, which costs a bit of clarity in an otherwise economical definition.

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 available the description need not explain return values, yet it summarizes them, and it flags the metered cost model that any caller must know before invoking. The unexpanded `commodity_filter` mention is the only loose end for a 10-parameter tool with no required params.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: it explains that `commodity` resolves through a graph and that a group match counts, which the schema's "A commodity name" line does not convey. Minor deduction because it references `commodity_filter`, which is not present in the input schema at all, creating ambiguity.

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

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

States a specific verb and resource ("Search resource deposits") and enumerates the actual filter axes, so an agent knows precisely what this retrieves. It does not, however, differentiate itself from the singular `deposit`, `deposit_brief`, or `nearby` siblings, leaving the agent to infer that this is the multi-row search variant.

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 metering workflow is spelled out ("quote first with `billing_quote`"), which is a genuine usage rule. But there is no statement about when to pick `deposits` over `deposit`, `deposit_brief`, or `nearby`, and no exclusions or prerequisites beyond the billing 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?

Annotations already cover safety (readOnly/destructive/openWorld), and the description layers on the operational facts an agent cannot get elsewhere: 15–60 s latency, the async escape hatch (start=true returns a job_id resolved via job_status), and that it is agent-key-only and metered. That is exactly the beyond-annotation context this dimension rewards.

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

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

Five dense sentences, each doing distinct work: output shape, class precondition, latency, async pattern, auth, billing. The critical constraints (precondition, cost, latency) are stated before the agent would commit to a 60-second call.

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

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

For a metered, slow, async-capable read tool with an output schema already covering return shape, the description supplies everything an agent needs to call it correctly: cost gating, auth, latency, job handling, and the class validity rule. No material operational gap remains.

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

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

Schema coverage is 100%, so the schema already documents t0, t1, radius_m, max_cloud, same_season, and entity_type/lat-lng alternatives in detail. The description only adds value on `start` by naming job_status as the follow-up; it says nothing extra about same_season or the footprint override that the schema doesn't already carry.

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

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

The description names a precise resource and scope: the structured change at one site between t0 and t1, broken down per class (water, ice, canopy, pad, stockpile) with per-sensor evidence and confidence. That distinguishes it from snapshot tools like entity_state, but it never contrasts with the closer sibling entity_history, leaving a small ambiguity for an agent choosing among time-based tools.

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

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

It states a hard prerequisite ('Read `height_class` first: only repeat_surface supports a volume change') and a billing precondition ('quote first with `billing_quote`'), which are real routing decisions. It stops short of explicit when-not-to-use guidance relative to entity_state or entity_history.

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

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

Annotations already declare a safe read (readOnlyHint true, destructiveHint false), and the description adds genuinely non-obvious traits: the call is metered, requires agent keys, and returns a short, size-limited newest-first list. It defers cost specifics to 'CHARGING in the server instructions' rather than quantifying, so it stops short of full 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?

Two dense, front-loaded sentences with no filler; the resource scope comes first and operational constraints last. Some phrasing ('our record's versions since record time began', 'world time or our time') is cryptic in an otherwise tight definition.

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, full parameter coverage, and explicit safety annotations, the description supplies the remaining pieces an agent needs: cost model, auth requirement, and the delimitation that no image payloads come back. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, including the entity_type enum values, so the baseline is 3. The description says 'one entity' but never elaborates on `id` or how entity_type interacts with it, adding no meaning beyond the schema.

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

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

Names the resource concretely and enumerates its three return components: imagery scene dates (explicitly without images), record versions, and a newest-first `what_changed` list. The parenthetical '(no images)' implicitly separates it from `look_at`, but no sibling is named outright, so an agent must infer the 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?

Signals this is the 'cheap index' to reach for before richer fetches and states an explicit prerequisite workflow: quote first via `billing_quote`. It stops short of stating when to prefer `entity_state` or `entity_change` instead, so the routing against those siblings 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?

The description adds meaningful behavioral context beyond the annotations: it is charged for parts delivered, requires agent keys, and is metered with a recommendation to quote first via billing_quote. This covers cost and auth needs, which annotations do not provide. It stops short of describing failure modes or rate limits, but the added information is substantial.

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 return contents, followed by billing and auth notes. It is efficient, though slightly dense with multiple sentences. Every sentence serves a purpose, but minor tightening could improve flow.

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

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

Given the presence of an output schema and annotations covering safety, the description is largely complete for correct invocation. It covers billing and auth needs, and the output schema handles return values. The main gap is the lack of usage guidance versus alternatives, but that is scored separately.

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

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

With 100% schema description coverage, the schema already documents all parameters thoroughly. The description mentions as_of and implies the components corresponding to radius_km and max_cloud but adds no new semantic details beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states what the tool returns: a packet for one entity at a specific date, including the entity, pins, relationships, and satellite still. It is specific about the resource and the time dimension, but it does not explicitly differentiate itself from sibling tools like entity_history or entity_change.

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 such as entity_history or entity_change. It mentions billing prerequisites ('quote first with billing_quote') but that is a process step, not a usage guideline for selecting this tool over others.

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 adds context the annotations do not: it clarifies this is a preparation step that 'moves no money' (disambiguating from the deposit siblings) and that values are 'read from the running system' rather than cached. It also warns that the deposit must be tracked separately via funding_status, which is a real behavioral trait. Annotations already cover the read-only/destructive profile, so this is solid added value rather than a repetition.

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, no filler, with the identity of the tool (the funding step) front-loaded before the non-mutation caveat. Minor cost from 'in-band' and 'joule shortfall' requiring domain familiarity, but nothing is wasted.

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

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

For a one-parameter read tool with an output schema and read-only annotations, the description covers what it returns, that it changes nothing, and the required follow-up. The remaining gap is the relationship to the deposit/deposit_brief tools, which an agent would need to resolve on its own.

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

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

Schema coverage is 100% and the single `needed` parameter is fully documented in the schema, including its default and its origin (joules_deficit or a 402). The description body itself does not restate the parameter, so it adds nothing beyond the structured field — baseline 3 is appropriate.

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

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

The description names the resource concretely — it returns the caller's own USDC-on-Base deposit address plus the live minimum — and frames it as the preparation step for a joule shortfall. An agent can distinguish it from funding_status because the description explicitly assigns tracking to that sibling. The only drag is jargon ('in-band funding step') that requires reading the rest of the sentence to decode.

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

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

It states the triggering condition (a joule shortfall) and hands off the follow-up to funding_status, which is clear routing. It does not explicitly exclude the neighboring deposit/deposit_brief tools, so an agent facing both 'deposit' and 'funding_prepare' still has to infer which one initiates money movement.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), so the extra value is in explaining the possible held states and reassuring that 'nothing is lost while held' — genuinely useful context a caller would otherwise worry about. It stops short of describing whether state is live vs cached.

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 compact sentence with the resource front-loaded ('YOUR OWN USDC-on-Base deposit state'), followed by the enumerated states and the reassurance clause — 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 annotations covering safety, an output schema carrying the return shape, and zero params, the description needs only to explain what state means — which it does via the credited/held enumeration. Minor gap: no hint on freshness or when held status would change.

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

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

The tool takes zero parameters, so the baseline of 4 applies; the description correctly states 'no arguments' and that identity comes from the credential, which is the one semantic point worth making.

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

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

States a specific verb+resource — 'your own USDC-on-Base deposit state' — and enumerates outcomes (credited, held below minimum, above maximum, awaiting platform funding). It distinguishes itself implicitly from the deposits/deposit/funding_prepare siblings via 'YOUR OWN' scoping, but never names those siblings explicitly.

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

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

'From your credential, no arguments' makes invocation unambiguous, but the description never says when to call this versus funding_prepare, deposits, or deposit_brief. The timing/usage context is implied by the noun 'status' rather than stated.

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

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

Annotations already declare readOnly/destructive=false, but the description adds genuinely new context: the call is free, it is restricted to the paying wallet, and each state carries specific semantics (done returns the answer plus how the reservation settled; failed means released). That auth and cost disclosure is real value beyond the structured hints.

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?

Very compact and front-loaded with the job identity before states, cost, and access rules. The telegraphic fragments ('Free.', 'released.') are dense but each clause carries information, not filler.

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

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

For a single-parameter status read with an output schema present, the description covers origin, states, cost, and access control adequately. Minor gap: no hint about polling cadence or what to do between running and terminal states, which an agent deciding when to re-call would benefit from.

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

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

Schema coverage is 100% and job_id is already documented as the UUID returned by entity_change(start=true). The description restates that same origin but adds no format, validation, or edge-case detail beyond the schema, so baseline 3 applies.

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

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

The description identifies this as the status read for an entity_change job started with start=true and enumerates the three terminal/running states, so the agent can tell it apart from the mutation sibling entity_change. It never uses an explicit verb like 'check' or 'poll', so purpose is clear but implicitly framed.

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 implies the usage sequence (call after entity_change with start=true) and states the access precondition that only the paying wallet can read it. There is no explicit when-not guidance or named alternative for fetching entity state redo after the job completes.

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

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

Annotations already cover read-only, non-destructive, closed-world semantics, and the description adds genuinely new context: the call is free and 'the graph meter debits this same wallet', which tells the agent the balance is the metered/spendable one. It does not disclose error behavior for mismatched credentials or cross-wallet reads.

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

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

Three short sentences, purpose front-loaded, then the credential branching rule, then the metering note. No filler and nothing repeated from the 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?

With an output schema covering return values and annotations covering safety, the description only needs to supply auth/cost context, which it does. Minor gaps remain around failure modes and whether a wallet other than your own can be read.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns an upgrade by explaining that wallet_id is credential-conditional — required only for JoulePAI/ENYAL, omitted for GreenlandAI agent keys — which the schema's plain 'Wallet id (UUID) to read' does not convey.

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

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

The description states a specific verb+resource ('Your own wallet balance') and adds that it is free of charge, so an agent knows exactly what is returned. It does not explicitly distinguish itself from nearby siblings such as deposits, balance_proof, or joules_deficit, so differentiation is only implied by 'your own wallet'.

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

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

It gives concrete calling conditions: a gai_/gqa_ agent key reads its own wallet with no arguments, while JoulePAI or ENYAL credentials must pass wallet_id. It stops short of naming when to prefer an alternative sibling (e.g. a proof or history tool) or when this call would fail.

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

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

Annotations already cover read-only/non-destructive/closed-world, so the description adds context beyond them: the call is free, agent keys read their own wallet, only JoulePAI/ENYAL credentials may supply wallet_id, and GreenlandAI keys cannot. That credential/wallet-routing detail is genuinely useful and not in the annotations, though nothing is said about rate limits or handling of a nonzero shortfall.

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?

Four short clauses, front-loaded with the decision question, then the required input, the return shape, the free-of-charge note, and the credential caveat. No filler and no repetition of the 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?

With annotations and an output schema already present, the description only needs to establish intent and auth context, which it does. The one gap is what an agent should do when shortfall > 0 (presumably follow tool_to_call_next), which it leaves implicit.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes further by clarifying that `cost` is a planned next-call cost and by stating the credential rules that govern whether `wallet_id` is usable, which the schema only partially expresses ('Not used with a GreenlandAI agent key').

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?

Frames a specific question ('Can you afford the next call?') and names the inputs and exact return fields, so the agent knows this is a pre-flight affordability check rather than a plain balance read. It is distinguishable from joules_balance/billing_quote by intent, though no sibling is named explicitly.

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

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

'Can you afford the next call?' plus 'Give a planned `cost`' establishes the usage context: run this before committing to a paid call. It does not name alternatives (joules_balance, billing_quote) or say when not to use it, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint and non-destructive behavior; the description's genuine contribution is 'public, no auth', which is useful auth context not encoded in annotations. Beyond that it adds nothing about scope, recency window semantics, or result volume — and 'recent' is left undefined.

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 tight sentence with the substantive payload front-loaded and no filler. It is efficient, though the leading noun phrase buries the action the agent is trying to confirm.

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 zero parameters, an output schema in place, and annotations covering the safety profile, the description carries nearly everything an agent needs for correct invocation. The only meaningful omission is how it differs from transparency_latest and verify_proof.

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

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

The tool takes zero parameters, so the schema requires no explanation and the description has no parameter semantics to compensate for. Baseline 4 applies.

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

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

The description names the resource and its contents (ledger anchors, on-chain tx ids, credit supply at each anchor), but it is a noun phrase with no verb telling the agent what operation is performed — read, verify, or list. The name implies 'verify' while the text describes retrieval, and it does not distinguish itself from siblings like transparency_latest or verify_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?

There is no statement of when to call this versus transparency_latest or verify_proof, both of which sit in the same conceptual space. 'Independently checkable' hints at a verification use case but never converts that into an actionable 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?

Goes well past the readOnlyHint annotation: it discloses metering, the credential requirement ('agent keys only'), the zero-cost failure mode for cloudy/missing scenes, and the `available:false` signal. These are exactly the behavioral facts an agent needs before spending credits, and nothing contradicts the annotations.

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

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

Three tight sentences lead with what the tool produces, then the fallback behavior, then the billing gate. Every clause carries information; nothing is restated from the schema or annotations.

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?

Complete for a metered, single-shot read tool: input anchoring modes, cost model, failure semantics, and the provenance contract are all covered. With an output schema present, it correctly leaves return-value structure to that schema.

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

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

Schema coverage is already 100%, so the baseline is 3; the description adds real meaning by stating the as_of semantics ('newest scene on or before') and clarifying that `observed_at` is the scene date rather than the request date. It doesn't add anything for `max_cloud` or the entity_type enum beyond the schema.

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

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

Names a specific verb+resource (satellite still) and pins its data source (newest Sentinel-2 archive image on or before `as_of`), which is far more specific than a bare name. It does not distinguish itself from siblings like `look_from`, `look_through`, or `map_viewport`, so an agent must infer the boundary itself.

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

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

Gives clear operational routing: anchor by lat/lng or entity_type + id, quote with `billing_quote` before spending, and agent keys required. What is missing is explicit when-to-use-this-vs-`look_from`/`look_through` guidance, which matters given three visually similar siblings.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), and the description adds real behavioral context beyond them: the call is metered, must be pre-quoted via billing_quote, and each pin carries source_tier provenance. The only gap is that it defers cost details to server instructions rather than stating them inline.

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?

Four short clauses, front-loaded with the pose mechanism, then the mode rule, then provenance, then cost. Nothing is padded, though the CHARGING pointer is slightly elliptical and requires the agent to go look elsewhere.

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

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

With an output schema present, return shape needs no explanation, and all 8 parameters are schema-documented. The description still covers the mode logic, provenance, and the billing precondition — everything an agent needs to invoke it correctly. Zero required parameters is handled by the implicit pose rule (lat/lng or id+entity_type).

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

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

Schema coverage is 100%, so baseline is 3, but the description adds cross-parameter semantics the schema does not: entity_type alone acts as a filter, while supplying id together with entity_type anchors the pose on that entity. That interaction rule is exactly the kind of meaning a schema of independent property descriptions cannot convey.

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

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

States a specific verb+resource ('Map pins near a point') with the pose mechanism (lat/lng + radius_km), which is far more informative than the bare name. It does not, however, distinguish itself from closely related siblings like look_at, look_through, map_viewport, or nearby, so an agent still has to guess which view tool to pick.

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 conditional usage for the two modes ('entity_type alone filters... with id it anchors'), which is genuinely useful. It also states a workflow prerequisite (quote first with billing_quote). But it never says when to choose this over the sibling view/nearby tools, which is the harder decision for an agent.

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

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

Goes beyond the readOnly/openWorld annotations by disclosing that empty windows are explicit empty frames and are not charged, that the tool is metered under CHARGING in server instructions, and that agent keys are required. No destructiveness or side effects contradict the read-only annotations; the only gap is that response shape is left to the output 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?

Front-loaded with what the result is, then constraints, then the billing pointer — four short sentences with little waste. Minor density from jargon such as 'explicit empty frame' and the CHARGING reference, but nothing extraneous.

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, read-only imagery tool with a full schema and an output schema, the description covers the behavior an agent most needs: windowing, empty frames, cost, and auth. The missing piece is sibling comparison, which leaves selection ambiguous among look_at, look_from, and site_reconstruction.

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

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

Schema description coverage is 100%, so parameter meaning is already fully documented. The description echoes max_frames and its default 6 and clarifies that the range is cut into equal windows with one still each, which is modest added semantics over the schema's own wording.

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

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

States a concrete verb and output artifact: an ordered stack of dated Sentinel-2 stills for one site between t0 and t1, one per window. It is distinguishable from a single-image tool only by inference; the sibling tools look_at and look_from are never named, so the boundary between 'look through a range' and 'look at a site/moment' is not made explicit.

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

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

The description implies usage through 'quote first with billing_quote' and 'Agent keys only', which gives real preconditions, but it never states when an agent should pick look_through over look_at, look_from, or site_reconstruction. Usage is implied by the window/time-series framing rather than stated.

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

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

Goes well beyond the annotations: discloses that the call is metered, that a billing quote must precede it, that keys are agent-scoped, and that results are a capped sample while counts are exact for the full box. The exact cap size and whether it is paginable are left unstated, keeping this short of a 5.

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

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

Front-loaded with the bounding-box scope and the return shape, then the access and billing constraints. The telegraphic fragments ('Agent keys only.', 'Metered: see CHARGING...') are dense rather than padded, though the CHARGING reference is slightly cryptic without external context.

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

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

For an 8-parameter, read-only tool with a full output schema and rich annotations, the description covers the gaps that matter: exact-vs-sampled results, metering, auth scope. Sampling behavior (cap size, pagination) and the all-four-edges requirement are handled by the schema, 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 100%, so the schema already documents all eight parameters including the four bbox edges and their validity. The description merely restates the four edge names and adds no format, ordering, or edge-case meaning beyond the schema's 'Send all four edges together' note.

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

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

The description specifies the resource and its scope precisely: a bounding-box query returning per-type counts plus a capped pin sample. That is enough to distinguish it from generic siblings, but it never names or contrasts it with the geo-adjacent siblings (nearby, look_at, look_from, look_through), so an agent must infer the split.

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 one hard prerequisite — quote with `billing_quote` first and consult CHARGING — which is genuinely actionable. It does not say when to choose map_viewport over the point/line-of-sight tools in the sibling list, so the when-vs-alternatives rule is only implied.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false; the description adds real value beyond them by disclosing the consequence (escrow released to the provider) and an authorization constraint enforced server-side. It stops short of saying the release is irreversible or what happens on a rejected accept.

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 tight sentences: action and effect first, then the permission constraint. No restated boilerplate and nothing that could be cut.

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 needn't be described, and the mutation's safety profile plus auth requirement are covered. The only gap is failure/irreversibility behavior for a destructive escrow-releasing 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?

Schema coverage is 100%, so both match_id and idempotency_key are fully documented in the schema, including the buyer-ownership requirement and the single-use key rule. The description adds nothing parameter-specific beyond that, so baseline 3 applies.

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

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

States a specific verb ('Accept'), resource ('a delivery on a match'), the underlying endpoint, and the material effect ('releases escrow to the provider'). This is clearly distinguishable from siblings like market_provide or market_match without opening a schema.

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

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

It gives a hard precondition ('You must be the buyer party; the backend enforces it'), which implies when the tool is callable, but it names no alternatives and no explicit when-not-to-use case (e.g. dispute, rematch paths such as market_request_rematch).

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds only that results are paged and that some filtering applies to providers, without stating pagination limits, cap behavior, or that certain filters are ignored in oracles mode.

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 short sentences with the mode switch front-loaded and no filler. The clipped fragment "Paged." is efficient but leaves the reader slightly under-served given there are eight parameters.

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 annotations handle the safety profile. The description covers the mode split and paging but is thin about how limit/offset interact with the provider-only filters, which is the main remaining gap for an eight-parameter browse tool.

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

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

Schema description coverage is 100%, so every parameter including kind, sort, limit and the provider-only filters is already documented. The description only restates kind values and paging, adding no format or default semantics beyond the schema; baseline 3 applies.

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

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

States a concrete verb (Browse) plus resource (RAREEAI marketplace) and enumerates the two modes, kind="providers" vs "oracles". It does not distinguish itself from near-siblings such as market_match or company_search, so an agent must lean on the name alone to rule those out.

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 two kind values imply when each mode applies, and "filterable and sorted" hints at the listing path, but there is no explicit when-to-use guidance and no mention of alternatives such as market_request or company_search. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint, destructiveHint=false and closed-world scope, so safety is covered; the description adds the meaningful access-control constraint that the caller must be a party to the match and names the data classes exposed, useful for judging sensitivity. It says nothing about what happens if you are not a party (error vs. empty), which is the one behavioral 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 short sentences, front-loaded with the verb and scope, with the sibling hand-off in the trailing clause. No filler and nothing buried.

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 needn't be enumerated, and annotations carry the safety profile; with one required param fully documented, the definition is nearly sufficient. The only shortfall is not stating the failure mode for non-party or unknown match ids.

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?

Single parameter with 100% schema coverage, where the schema already documents both the UUID format and the party requirement. The description's 'you are a party to it' restates the schema rather than adding format, sourcing, or lookup semantics, so it lands at the baseline for fully-covered schemas.

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

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

States a specific verb (read) and resource (one marketplace match) plus the exact field families returned: escrow_terms, fee, timeout, dispute window and dispute state. It also bounds scope to matches 'you are a party to', which separates it from listing/browsing siblings like market_listings and market_request.

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

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

Explicitly routes the agent to trade_settlement for settlement legs, which is a real exclusion rule rather than vague guidance. It does not address the other plausible alternatives (market_quote, market_accept, market_request_rematch), so the alternative-mapping is partial rather than exhaustive.

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

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

Adds real context beyond annotations: it discloses the auth/scope requirement and a one-time registration fee, and frames the operation as create-or-update rather than a plain create. It does not explain what the declared destructiveHint=true means here (whether an update replaces or clears prior listing terms).

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 tight sentences with the verb and resource front-loaded and the precondition and cost appended where they belong. The 'Typed body:' enumeration is partly redundant with the fully described schema, but it earns its place as a fast required-field summary.

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 a rich schema, an output schema, and annotations carrying the safety profile, the description covers purpose, auth, and cost adequately. The remaining gap is that a destructive, non-idempotent upsert does not say what an update does to existing listing terms or stakes.

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

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

Schema description coverage is 100%, so the schema already documents every body field, including idempotency_key and the timeout_hours/timeout_minutes pair. The description only summarizes the required fields and lumps the rest as 'optional capacity, limits, SLA and oracle opt-in', which adds grouping but no new semantics.

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

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

States a specific verb pair and resource: 'Create or update a marketplace listing'. The scope hint '(verified account, marketplace:write)' plus the listing vocabulary separates it from read-side siblings like market_listings and buyer-side ones like market_request, though no sibling is named explicitly.

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

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

Usage is implied by the upsert framing and the 'verified account, marketplace:write' prerequisite, and the fee note flags a cost gate. But it never says when to choose this over market_request, market_quote, or market_listings, nor when a caller should update versus register fresh.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds genuine context beyond them: the record is scoped to requests you own, and the `escrow_terms` returned are generic rather than deal-specific — a distinction an agent would otherwise get wrong. It doesn't mention behavior on a bad or foreign id, which would have made it a 5.

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

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

Two dense sentences, front-loaded with what is returned and followed immediately by the sibling pointer for the data this tool omits. Nothing is padding.

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

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

With an output schema present the description needn't enumerate return fields, yet it still summarizes them, and it flags the important caveat that trade fee and deadlines live on the match. Complete for a single-record read; only missing an error case for ids you don't own or that don't exist.

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

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

Schema coverage is 100% and the single parameter already documents that request_id is the UUID posted with market_request, so the schema carries the parameter burden. The description repeats the same ownership/identity framing without adding syntax, format, or failure semantics.

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

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

States a specific verb (read), a specific resource (one marketplace REQUEST you own), the lookup key (by id), and even the payload (terms, status, units matched, generic escrow_terms). It explicitly separates itself from market_match, so an agent can pick between them 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?

Usage is implied precisely: you call this to inspect a single request you own, and the description names market_match as the place to go for trade-specific fee and deadlines. That is a clear routing rule, though it stops short of stating exclusions such as when to use market_listings or market_request instead.

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

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

The annotations only declare the safety profile (not read-only, not destructive, not idempotent); the description adds the material fact that escrow is debited on match, which is a real financial consequence not covered by any structured field. It could say more about what happens to the escrow if the request expires unmatched (ttl_seconds), which is the natural follow-up question.

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

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

Three tight sentences, front-loaded with the action and its auth scope, then the escrow consequence, then the physical-claim caveat. The required-field enumeration is mildly redundant given full schema coverage but functions as a fast pre-flight checklist.

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 no explanation, and the description covers auth, cost, and the physical_claim condition. Minor gaps remain around escrow refund/expiry behavior and the idempotency contract, both of which are only discoverable in the nested schema.

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

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

Schema description coverage is 100%, so the schema already documents wallet_id, frontier, resource_type, unit_type, units_needed and max_price_per_unit. The description merely re-enumerates those names and lumps everything else into "options," adding no format, default, or constraint detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ("Post a marketplace BUY request") and thereby implicitly distinguishes itself from the sell-side sibling market_provide. The buying intent plus the required-field list makes the operation unambiguous, though it never names the sibling it contrasts with.

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

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

Supplies the gating conditions an agent needs before calling: verified account, marketplace:write scope, and the rule that a physical trade must carry physical_claim. It stops short of explicit when-not-to-use guidance or naming alternatives such as market_provide or market_match.

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

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

Goes meaningfully beyond the annotations: it discloses that matching escrows funds from the wallet immediately under machine speed versus deferring to provider approval under human speed, and documents the 409 failure condition. It omits the non-idempotency consequence (idempotentHint=false implies a repeat call may escrow a second time) and any amount/limit context, which for a money-moving call is a notable 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?

Three compact sentences with zero filler; the action is front-loaded and the escrow/approval and error details follow in priority order.

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 no explanation, and the single parameter is fully documented in the schema. What remains thin is the cost/escrow magnitude and repeat-call behavior for a mutation tool, though the core behavior is adequately covered.

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

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

Only one parameter and schema coverage is 100%, so the schema already carries the meaning. The description reinforces ownership ('YOUR') and openness of the request, but adds no format, sourcing, or lookup guidance beyond the schema.

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

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

States a specific verb ('Match') and scoped resource ('one of YOUR open requests'), which separates it from the generic market_match and from market_request. The 'rematch' framing and the 'now' emphasis imply re-triggering a match, but it never explicitly contrasts with market_match or market_request, so the sibling boundary is left partly to inference.

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 possessive 'YOUR open requests' and the 409 note imply the precondition (you must own an open request) but do not state it as a rule or name alternatives such as market_match or market_request_rematch_withdraw. Usage is inferable rather than prescribed.

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

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

Annotations already declare non-read-only, non-destructive, non-idempotent, and the description adds genuine context beyond them: already-escrowed matches are left untouched, so the agent knows the blast radius is limited to future auto-matching. It omits whether the withdrawal can be reversed (re-enabling via the sibling) and any 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?

Two sentences, zero filler, with the action and its endpoint front-loaded and the side-effect caveat immediately after. Every clause 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?

With an output schema present, return values need not be explained, and the description covers the action, endpoint, and effect on existing matches. The main residual gap is the absence of any mention of reversibility or permission requirements for a mutation 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?

Only one parameter and schema coverage is 100%, so the schema already explains request_id as the marketplace REQUEST UUID. The description adds nothing further about the parameter (no format, no ownership constraint), which is the expected baseline here.

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

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

States a specific verb+resource: withdrawing a request's automatic re-matching consent, reinforced by the DELETE endpoint path. It is distinguishable from the sibling market_request_rematch (the enable counterpart) through the verb 'withdraw', though it never names that sibling explicitly.

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

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

'Withdraw ... now' implies immediacy, and the second sentence scopes the effect, but there is no explicit statement of when an agent should call this versus market_request_rematch or market_match, nor any prerequisites (e.g., ownership of the request).

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

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

Annotations already declare readOnlyHint, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds context the annotations cannot: the call is metered/billed and must be quoted via billing_quote beforehand, and results carry a source_tier. That is meaningful behavioral disclosure beyond structured fields.

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

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

Two compact sentences, front-loaded with what the tool returns, then the billing prerequisite. No filler. The telegraphic style is slightly abbreviated but every clause carries information.

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

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

An output schema exists, so return shape need not be explained, and the billing gate plus source_tier are called out. For a read-only spatial query with fully described parameters, the description covers what an agent needs, though a pointer to when to prefer a sibling 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 coverage is 100%, so all seven parameters are already documented, including defaults for radius_km, limit, and include_country_centroids. The description only restates names (lat, lng, radius_km, entity_type, limit) without adding format or interaction semantics. Baseline 3 is appropriate.

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

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

The description states the resource precisely: entities near a lat/lng within radius_km, with optional entity_type and limit, and notes each row carries source_tier. That is a clear, specific spatial-query purpose. It does not distinguish itself from nearby siblings like place_index or look_at, which keeps it from a 5.

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

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

The one real guideline is procedural: this tool is metered, so quote first with billing_quote. That is a valuable precondition. However, there is no guidance on when to choose this over place_index, look_at, or map_viewport, so usage selection is only implied.

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

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

Goes meaningfully beyond the annotations by disclosing a side effect ('A low score opens a dispute') and a specific failure contract ('A 409 means the match has moved on — do not retry'), which matters given idempotentHint=false and destructiveHint=true. It does not clarify whether a submitted verdict can be amended or what authorization/registration is required, leaving some 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?

Three compact clauses, front-loaded with the action and payload, then the dispute consequence, then the conflict rule. No filler sentences and nothing redundant with the 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?

With an output schema present, return values need not be described, and the description covers the mutation's consequence and its main error path. It is slightly short on what a successful response looks like at a workflow level (e.g., whether the match closes or the verdict is final).

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

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

Schema description coverage is 100%, so the schema already documents verdict, quality_score bounds, notes length, and execution_trace. The description mostly restates those fields and adds no format or syntax detail beyond them, so the baseline 3 applies.

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

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

States a specific verb and resource ('Post your verdict on a delivery you were assigned') and enumerates the payload fields (verdict, quality_score, notes, execution_trace). It is clearly distinguished from the sibling oracle_assignments, which fetches assignments rather than submitting verdicts.

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

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

The phrase 'a delivery you were assigned' establishes the precondition for calling it, and the description gives concrete when-to-act guidance on the 409 case ('do not retry; read the match'). It does not explicitly name oracle_assignments as the place to obtain the match_id, so the routing to alternatives is only implicit.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds the useful scoping fact that results are limited to the caller's own assignments and that already-given verdicts are included. It says nothing about ordering or what an empty result means.

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

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

A single front-loaded sentence that identifies the resource first, then the payload fields, then the optional controls. No filler and nothing repeated from structured fields.

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

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

For a read-only, two-parameter list tool with full schema coverage, an output schema and complete annotations, the description supplies everything needed to call it correctly. Return values need not be explained because 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 100%, with both `limit` (range 1-200, default 50) and `status` fully documented inline. The description only restates "Optional status filter and limit" without adding valid status values or ordering semantics, so the baseline 3 applies.

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

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

"List YOUR oracle assignments" gives a specific verb and resource with an ownership scope, and enumerating the returned fields (match_id, deadline, fee, verdict) makes the shape concrete. It does not name the sibling it complements (oracle_assess), so the distinction from the other oracle_* tools must be inferred.

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

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

The phrase "each delivery to assess" implies the workflow (list here, then assess), and "Optional status filter" hints at filtering use. But there is no explicit when-to-use, no exclusion, and no pointer to oracle_assess or oracle_register as the alternative 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?

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is covered. The description adds real context the annotations don't: the stake is refunded minus slashed amounts, and the call is blocked while assessments are pending. It omits reversibility (whether you can re-register afterwards) and what happens on repeated calls.

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

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

Two short sentences, front-loaded with the action and its payoff, then the precondition. Nothing is redundant except the minor restatement of requiredness that the schema already enforces.

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 no explanation, and the description covers the key effect and the blocking condition for a simple one-parameter destructive tool. A note on irreversibility or re-registration would make it fully complete.

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

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

Schema coverage is 100% and the single parameter already carries the description 'Your oracle wallet's UUID (the one that holds the stake).' The description only restates that wallet_id is required, adding no syntax or selection guidance beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('deregister as an oracle') and immediately names the outcome (stake returned from escrow, less slashed amounts). It is clearly the inverse of the sibling oracle_register, though it never names that sibling explicitly, so differentiation is inferred rather than stated.

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

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

Gives a concrete precondition: it fails while you have pending assessments, which functions as an explicit when-not-to-use signal and points the agent at oracle_assignments/oracle_assess as a prerequisite check. No alternative tool is named for the failure case, so it stops short of a full when/when-not/alternatives treatment.

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

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

Annotations already declare the write, non-idempotent, non-destructive profile, so the description's job is added context — and it delivers the two facts annotations can't: the call is gated by an invite, and the stake is recoverable on deregister. It doesn't state whether a successful registration is immediately active or whether specialisations can later be changed, which keeps it below a 5.

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

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

The core action and its stake mechanism come first, eligibility caveat second, body shape third, refund note last — every sentence adds something and nothing is repeated for filler.

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

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

For a state-changing registration with full annotations, complete schema coverage and an output schema, the description covers what matters: cost, gate, refund path and payload. Remaining gaps (post-registration state, whether specialisations are mutable) are minor for a tool whose return value is separately 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 description coverage is 100%, so wallet_id, stake_amount (with its 10,000 minimum and refundability) and the specialisations enum list are already fully documented. The description restates the same facts ("1–7 from a fixed list", "stake is returned") rather than adding syntax or constraints beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ("Register as a ... oracle") plus the mechanism (staking joules), which distinguishes it from oracle_deregister and the read-only oracle_* siblings. It stops short of naming a sibling explicitly, but the registration/stake framing 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?

Gives a real prerequisite rather than generic advice: invite-only at launch and uninvited wallets are told how to apply, which tells an agent what to expect and when this call will fail. It does not contrast this with alternatives such as oracle_assignments or oracle_deregister beyond implying the deregistration counterpart.

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

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

Annotations already declare readOnly/non-destructive/closed-world, so the safety profile is covered. The description adds genuinely new behavior: newest-first ordering, offset/limit paging, metered charging governed by server instructions, and the presence of both valid_on (world time) and recorded_at (our time) per row. It stops short of describing cost magnitude or error/empty-result behavior.

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

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

Two sentences, densely packed but zero waste: content, anchor mode, ordering, row timestamps, filters, paging and metering each get a clause and the core purpose is front-loaded.

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

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

For a 12-parameter, zero-required tool with a full output schema and complete annotations, the description covers the dual anchoring modes, ordering, paging, metering workflow and temporal semantics. Remaining specifics (radius default and cap, per-kind enum values) live in the schema, so nothing critical is missing, though the ambiguity of passing neither coordinates nor entity could have been addressed.

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

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

Schema coverage is 100%, so the baseline is 3. The description does add value by explaining that the spatial anchor is either lat/lng or an entity's site (id + entity_type), which is a relationship the schema documents only piecemeal, and it clarifies date filtering semantics. But it adds no detail on kinds, fields projection, or limit/offset beyond what the schema already says.

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 concrete resource and scope: dated stills, quotes and measurements within a radius of a lat/lng or an entity's site, returned newest first. That is specific enough to distinguish it from generic listing tools, but it never names a sibling (e.g. nearby, signals, look_at), so the boundary is left to inference.

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

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

It gives clear operating context: filter by dates and kinds, results are paged, and the call is metered so the agent must quote first with `billing_quote`. That is a real prerequisite that changes how the tool is invoked. It does not, however, say when to prefer a sibling such as `nearby` or `map_viewport` instead.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds useful context by stating the tool is 'Free' and that it reports on 'THIS key' and its owner, going beyond what the annotations provide.

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

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

The description is a single, front-loaded sentence that conveys the core purpose, scope, and cost without any 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?

With an output schema present and no input parameters, the description supplies enough context for an agent to understand what the tool returns and when it is useful. Minor gaps remain around whether 'how its owner turns them on' is returned as instructions or just described.

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 the baseline is 4. The empty schema fully covers inputs, and no parameter semantics are needed beyond what is already structured.

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

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

The description clearly states that the tool returns receipt opt-in status for the caller's key and explains how the owner can enable receipts. It is specific about the resource (receipts) and scope (THIS key), though it does not explicitly name sibling tools or use a strong verb like 'check' or 'get'.

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 usage for checking whether the current key is opted into receipts and finding out how to enable them. However, it does not explicitly say when to use this tool versus alternatives like contribute_receipts or transparency_latest, nor does it provide 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?

Annotations already cover read-only and closed-world safety; the description adds genuinely non-obvious behavior: the call is metered and priced per hop, and an ambiguous name fails without charge and returns candidate names. It does not quantify cost, rate limits, or default result size, but the core behavioral risks are disclosed.

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

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

Three tight sentences that front-load the resource and its one-entity scope before traversal mechanics and billing. No filler, though the 'Metered: see CHARGING' pointer is somewhat compressed and depends on external server instructions.

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

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

For a 10-parameter read tool with an output schema, full schema descriptions, and annotations, the description covers everything an agent needs: how to anchor the traversal, how deep, how to filter, historical queries, ambiguity handling, and the billing precondition.

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

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

Schema coverage is 100%, and the description largely restates what the schema documents (hops as traversal depth, as_of as a past date, relation_type as an edge label filter). Its only marginal addition is framing entity_id as the unambiguous identifier versus name lookup, which the schema already hints at.

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

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

States a concrete resource (labelled relationship edges: owns, operates, supplies) and a clear scope constraint ('around ONE entity'), which separates it from broad lookups like nearby or company_search. It does not name a specific sibling tool it is the alternative to, so it stops short of a 5.

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

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

Gives an explicit entry recipe (start from entity_type + entity_id, or a name in `entity`), options for depth and relation filtering, and a concrete workflow rule: quote first with `billing_quote` before spending. It never states when NOT to use it versus entity_state, entity_history, or look_through, so no exclusion guidance.

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

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

Annotations already declare this a read-only, non-destructive, closed-world read, and the description still adds substantive behavior: the tool is metered, pricing is governed by CHARGING in server instructions, billing_quote should be called first, empty results are free, and results are gated on armed card types. It also sets expectations that output is observational, not advisory. These are exactly the cost, auth, and gating facts annotations cannot convey.

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

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

Five short sentences, front-loaded with the identity and payload, followed by gating semantics, then cost and the billing_quote pointer. Nothing repeats the schema or annotations, and the telegraphic style ('Observations, not advice. Agent keys only.') is efficient rather than vague.

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

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

With an output schema present, return format need not be described, and the description covers payload identity, cost behavior, auth, and gating. The remaining gap is the arming concept: it never says how a card type becomes armed or how to check arm state before paying for a possibly empty call. For a metered tool that gap matters, though the billing_quote pointer partially mitigates it.

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

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

Schema description coverage is 100%, with kind, limit, and country all documented in the schema, so the baseline is 3. The description reinforces the family names and the 'entities they name' notion that underlies the country filter, but adds no format or interaction detail beyond that. It does not explain whether kind and country combine or how arming interacts with kind selection.

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

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

The description says exactly what the tool returns: live signal cards, described as compiled, provenance-carrying observations with severity and named entities, and it enumerates the three families (lead_lag, network, signature). That is a specific resource statement rather than a restatement of the name. It stops short of contrasting itself against nearby siblings such as oracle_assess or transparency_latest, so an agent must infer which is the right read surface.

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 real preconditions: cards appear only while their type is armed, an empty answer costs nothing, agent keys are required, and the caller should quote first with billing_quote. That is clear context for when to call it and in what order. It gives no explicit exclusions or named alternatives among the many siblings, so the negative case is left implicit.

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

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

Annotations already declare readOnly/openWorld/non-destructive, and the description layers on the details an agent actually needs: metered billing via server CHARGING, a quote-before-charge step, the pre-charge tier decision (lidar_2m vs dem_30m), agent-key auth requirement, and a 15–60 s latency warning. This is exactly the extra behavioral context annotations cannot carry.

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

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

Front-loads the deliverable, then terse clauses on tier, latency, auth, and billing, with the quote-first routing at the end. Dense and largely waste-free, though the telegraphic style ('Agent keys only') is slightly compressed versus plain prose.

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, slow, open-world read tool with a full schema and an output schema, the description covers cost, latency, auth, tier behavior, and both input modes. Error semantics and partial-failure behavior for the binary model are not addressed, which is the only remaining gap.

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

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

Schema coverage is 100% and every parameter including include_model's ~5 MB base64 note is already documented in the schema, so baseline 3 applies. The description only restates the two addressing modes and the tier names; it adds no format or default detail beyond the schema.

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

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

States a concrete resource and modality: a dated, georeferenced 3D site model with terrain measurements (extent, elevation, slope, pits, heaps with volumes). The input-mode disjunction (entity_type + id, or lat + lng) further pins down what it produces. It does not name a sibling such as look_at or deposit_brief to differentiate, so it stops short of a 5.

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

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

Gives explicit operational guidance: quote first with `billing_quote`, tier is decided before any charge, agent keys only, expect 15–60 s. It never states when-not to use it or names the sibling that handles a nearby need, so no true alternatives routing.

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

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

Beyond the readOnly/destructive/openWorld annotations, the description adds that the call is 'free and not metered', which matters for an agent deciding whether to spend a call on documentation. It also discloses the shape of the response (description, per-parameter text, return fields). No contradictions with annotations.

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

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

Two sentences, front-loaded with the payoff (what you get) and closed with the decision rule (short contract vs. the rest). The 'free and not metered' aside earns its place as a cost signal, 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?

An output schema exists, so return values need not be spelled out, yet the description still summarizes them at a useful level. For a one-parameter read-only documentation tool, nothing an agent needs in order to call it correctly is missing.

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

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

There is a single required parameter with 100% schema description coverage ('A tool name from tools/list, e.g. relationships'). The description adds no further constraint on the argument, such as whether unknown names error or how names outside tools/list are handled, so it does not go 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+resource: it returns the full guide for one named tool, enumerating what that guide contains (complete description with edge cases and examples, full parameter descriptions, returned fields). It is unmistakably a documentation-lookup tool rather than a domain tool, though it never explicitly contrasts itself with the sibling tools it documents.

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

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

It gives a clear trigger: the listed description of each tool is only its 'short contract', so read this 'when you need the rest'. That tells the agent when to escalate from the tool list to this tool. It stops short of saying when it is unnecessary (e.g. simple calls that the short contract already covers).

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real behavioral value beyond that: the shape of the returned legs and, importantly, the 404 semantics for non-parties, which an agent needs to interpret errors. It is silent on rate limits or any auth-policy nuance, so not a 5.

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

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

Two sentences, zero waste. The scope/ownership constraint is front-loaded with emphasis, the payload is enumerated compactly, and the 404 note is placed last where it belongs.

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 tool is simple (one required param) and has an output schema, so return-format explanation is not required — yet the description still summarizes the leg structure and covers the notable failure case. An agent has everything it needs to call this 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?

There is only one parameter and schema description coverage is 100% — the schema already explains that match_id is the marketplace match UUID and that you must have been its buyer or seller. The description reinforces the buyer/seller authorization condition but adds no format, syntax or edge-case detail beyond the schema, so the baseline 3 applies.

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

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

The description names the exact resource (your own trade's settlement, as buyer or seller) and enumerates its contents: every leg — payout, fees, refunds — with role, amount, ledger status and on-chain anchor state, plus escrow legs. This is far more specific than the sibling tools (ledger_verify, balance_proof, receipts_me) and lets an agent distinguish it without opening the schema.

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

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

It gives clear preconditions — you must be the match's buyer or seller, and a 404 means you were not a party — plus the implied context of inspecting settlement after a match. It does not name an alternative tool or state when NOT to use it (e.g., when to prefer ledger_verify or balance_proof), so it stops short of a 5.

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