GreenlandAI

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

With no annotations, the description carries the full burden, and it delivers: it discloses authentication, the absence of a wallet_id parameter, batched anchoring identical to transparency_latest, and the meaning of bsv_txid reading 'pending'. It also clarifies that not-yet-batched is not unanchored, which is a non-obvious behavioral detail.

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

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

The description is dense but every clause earns its place: the first sentence defines the output, the second explains authentication and parameter absence, and the third covers anchoring semantics. It front-loads the core purpose and layers nuance without repetition.

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

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

Given zero parameters, no annotations, and no output schema, the description is remarkably complete. It enumerates the returned fields (leaf hash, Merkle sibling path, root, txid, verification), explains the pending state, and directs the agent to transparency_latest for the latest anchored root.

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 description adds semantic value by explicitly explaining why there is no wallet_id argument: the backend resolves the wallet from the bearer token. This removes any ambiguity an agent might have about how to identify the wallet.

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

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

The description states a specific resource and purpose: a cryptographic inclusion proof for the caller's wallet balance in the latest hourly transparency attestation. It distinguishes this tool from siblings by noting the wallet is resolved from the credential, not passed as an argument, and by referencing transparency_latest for anchored-root needs.

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 context: bearer auth is required, no wallet_id is accepted, and the backend resolves the wallet from the token. It also routes the user to transparency_latest.last_anchored when they need the most recent anchored root, though it does not explicitly contrast with verify_proof or bridge_proof.

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

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

With no annotations, the description carries the full burden and does so well: free of charge, no website needed, bearer required but no verification needed to price, the rail surcharge is rolled into joules_all_in, and graph paths refund unused hops. These are non-obvious behavioral facts an agent could not infer otherwise.

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

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

It front-loads the value proposition ('exact per-caller price ... BEFORE you make it') and every clause carries information, including the relay endpoint. It is dense and slightly example-heavy, but nothing is truly wasteful.

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

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

With no output schema, the description still names the fields the agent must read (joules_all_in, joules, rail_fee_joules, refund_on_empty, quote_is_maximum) and explains what each means relative to funding the call. Nothing needed to call and interpret this 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 0%, so the description must compensate, and it does: `path` is explained as the API path the call would hit with concrete examples, and `hops` is defined as graph depth (1-20) applicable only to relationships paths. This directly supplies meaning absent from the bare schema.

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

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

States a precise verb and resource: it returns the exact per-caller price of a metered call before the call is made. It also disambiguates itself from the sibling tools by mapping example API paths to their corresponding tools (relationships, look_from, map_viewport, company, nearby).

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 clearly frames the correct moment to use it ('BEFORE you make it') and shows how to derive the `path` argument from the tool you intend to call, which is actionable context. It stops short of an explicit when-not/alternative clause, so it's a strong 4 rather than a 5.

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

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

With no annotations, the description carries the burden of disclosure, and it does well: it explains the data source (reads stored attestation, not computed on request), the anchoring process with pending status, and the auth requirement (bearer). It doesn't mention error handling or rate limits, but for a read-only proof tool it is quite transparent about its behavior and data provenance.

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

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

The description is a single, dense paragraph. Every sentence adds meaningful information about output shape, pending behavior, or auth. It is longer than a terse one-liner but appropriately so given the complexity of the anchoring logic. No redundancy or fluff.

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 complexity of the output (fields, pending logic) and the lack of an output schema, the description explains all relevant fields and the anchoring rationale. It doesn't cover failure cases or integration details, but for a read-only, no-argument tool it is largely complete. Minor gaps on error semantics don't detract significantly.

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 schema is trivial and there is nothing for the description to add. The baseline of 4 for 0-parameter tools applies, and the description does not need to compensate for any schema gaps because none exist.

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

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

The description states a specific resource (Bridge Ledger rows) and a specific functional output (cryptographic inclusion proofs in a defined shape), and distinguishes it from siblings like balance_proof and verify_proof by naming the exact data domain and endpoint shape. The verb 'prove' is implied but the purpose is unambiguous and not a tautology.

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

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

The description gives clear context on when to use it: to obtain proof for bridge contribution/fee events, and notes that it is scoped to the token holder with no argument. It doesn't explicitly name alternatives or exclusions, but the domain specificity makes the usage context clear. However, it could have stated 'use balance_proof for balance rows' or similar to fully differentiate.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states that the tool is metered and debits from the caller's wallet, with a specific surcharge formula, which is valuable. However, it does not explicitly confirm that the operation is read-only, does not describe the output format or size, and does not mention any side effects beyond cost. The cost transparency is strong, but other behavioral aspects remain under-specified.

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 sentence with a dash, front-loading the purpose before diving into billing details. It is not overly long, but a significant portion (roughly half) is devoted to pricing mechanics, which, while useful, could be condensed. The structure is logical and efficient, but the focus on billing might distract from the core functionality.

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

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

Given the tool's simplicity (one parameter, no output schema, no annotations), the description should at least outline the return structure or mention any limits on the graph neighbourhood. It does neither. The description explains cost thoroughly but leaves the agent guessing about what data will be returned and whether there are any restrictions (e.g., depth of neighbourhood, pagination). This is a significant gap for an agent deciding whether to call the tool.

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

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

The input schema has a single required 'id' string, and the description mentions 'by id' but does not elaborate on what the id represents (e.g., a company identifier, UUID format, or any constraints). With schema coverage at 0%, the description fails to compensate by clarifying the parameter's purpose or format beyond the schema itself. The phrase 'by id' is minimal and does not add meaningful semantic value.

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

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

The description states 'One company's record and graph neighbourhood by id', which conveys the core action of retrieving a company's data and its connections. It is specific about the resource (company) and the scope (record and graph neighbourhood), and it distinguishes itself from siblings like 'relationships' or 'nearby' by focusing on a single company's full neighbourhood rather than a general graph operation. However, it lacks an explicit verb like 'fetch' or 'get', making it slightly less direct than ideal.

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

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

The description provides extensive billing guidance, pointing to tools like 'billing_quote' and 'joules_deficit' for cost checks, but it never explains when to use this tool versus its many siblings. There is no mention of scenarios where 'relationships' or 'hops' would be preferable, nor any exclusion criteria. The pricing context is useful but does not substitute for usage direction.

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

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

With no annotations, the description carries the safety burden and does so well: it states 'Read-only', 'append-only', 'Own rows only', and 'no staff fields'. It also reveals the API key header requirement and the presence of claim_sha256, giving useful behavioral context beyond a bare list operation.

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

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

The description is dense and mostly front-loaded with the resource, ownership, and read-only nature. There is minor redundancy ('Your OWN' vs 'Own rows only') and a slightly metaphorical phrase ('what the door holds'), but every major fact is useful.

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 simple read-only receipt lookup with two conventional pagination parameters, the description covers endpoint, auth, scope, and return intent (claim hash verification). It omits explicit return format and error behavior, but no output schema exists and the tool is low-complexity.

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

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

Schema description coverage is 0% and the description never mentions 'limit' or 'offset'. The parameter names and defaults carry some intrinsic meaning, but the description does not compensate for the missing schema descriptions or explain pagination behavior.

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?

Clearly identifies a specific resource: the caller's own contribution receipts. The endpoint 'GET /api/v1/contribute/receipts' plus 'Read-only' supplies the verb, and 'Own rows only, no staff fields' scopes it away from related contribution or staff tools.

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

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

Gives an explicit use case: verifying that the canonical claim hash matches what was submitted. It also sets an ownership boundary ('Your OWN', 'Own rows only') and includes the auth prerequisite, though it does not name sibling tools or explicitly state when not to use it.

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

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

Even without annotations, the description thoroughly discloses behavioral traits: authentication requirements (own key, not agent ID), the need for prior enabling, the asynchronous nature (nothing written immediately, queued for nightly judge), and the various per-item statuses that indicate different outcomes (queued, duplicate, unmapped, unresolved, rejected). It even explains that a HELD item is not a failure. This goes beyond basic mutation disclosure and sets clear expectations.

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

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

The description is dense but well-organized: it front-loads the purpose, then covers auth, prerequisites, per-item requirements, optional entities, process, and statuses. Every sentence conveys necessary operational detail without redundancy. It is long but earns its length given the complexity; no fluff.

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

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

For a tool with no annotations and no output schema, the description covers all necessary context: input requirements, auth, error behavior (403 naming enable endpoint), post-submission workflow, and how to follow up (via contribute_submissions and receipts). It even directs to config endpoint for weights. Nothing critical is missing for correct invocation.

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

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

Although schema coverage is 0%, the description compensates by detailing what each parameter must contain: 'relations' items must have subject, relation, object, source_url, quote (with minimum length), and optional subject_type/object_type. It also explains the 'entities' parameter's purpose and its special constraint (only alongside a relation referencing it). This gives the agent full understanding of how to construct valid input.

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

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

The description clearly states the tool submits evidenced graph relationships to a specific contributor program, with a specific verb ('Submit') and resource ('GreenlandAI contributor door'). It distinguishes itself from related tools like contribute_stats, contribute_submissions, and contribute_receipts by detailing its specific action. The purpose is unambiguous and differentiates from siblings.

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

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

The description explicitly states when to use this tool (to submit relations for contribution) and provides clear requirements (auth key, enabled identity, each item must carry specific fields). It also gives criteria for what will be rejected (missing source/quote) and what happens on submission (queued for nightly judge), guiding the agent on proper usage conditions.

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

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

With no annotations provided, the description carries the full burden, and it does well: it explicitly states 'Read-only', identifies the authentication mechanism (X-API-Key), names the HTTP method/endpoint, and enumerates the return fields. It does not mention rate limits or pagination, but for a zero-parameter status endpoint this is not a significant omission.

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

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

The description is compact and information-dense, with no filler. It front-loads the core purpose, then covers authentication, response content, read-only behavior, and the endpoint in just a few sentences. 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?

For a zero-parameter, read-only status tool with no output schema, the description is complete: it states the operation, the auth requirement, the endpoint, the read-only nature, and the full set of returned metrics. An agent has enough to invoke it correctly and interpret the response.

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

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

The input schema has zero parameters and 100% description coverage, so there are no parameter semantics to explain. The description still adds relevant context by explaining that identity is derived from the API key rather than from request parameters, which is useful 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 resource ('contributor standing') with a clear verb ('Returns'), names the exact fields returned, and distinguishes this as the caller's own status rather than a general or aggregated view. It also names the endpoint and HTTP method, making the operation unambiguous.

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

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

The phrase 'Your OWN' implies this is for checking your own contributor stats, and 'Read-only' signals a safe query, but there is no explicit statement about when to choose this over sibling tools like contribute_submissions or contribute_receipts. Usage context is implied rather than fully articulated.

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

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

The description discloses that the operation is read-only and explains the meaning of pending_review, accepted, rejected, and HELD items, including the judge's reason verbatim in review_note. It also mentions the nightly judging time (21:15 UTC). However, no annotations are provided, so the description carries the full burden; it does not mention pagination behavior, rate limits, or what happens when the API key is invalid.

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

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

The description is compact and front-loaded with the key purpose, then details the item fields and endpoint. It is dense but not bloated; every sentence adds useful context. The structure is a bit list-heavy, but it remains readable and efficient.

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

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

For a read-only list endpoint with two simple parameters and no output schema, the description covers the main return fields and the authentication requirement. However, it does not explain pagination behavior, error cases, or how the limit/offset parameters interact with the response, which an agent might need for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate for the two parameters, limit and offset. The description does not explicitly explain limit and offset, but the names are self-explanatory and the schema provides defaults. The description adds no additional meaning beyond the schema, so a baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: it lists the user's own per-item submission outcomes and explicitly names the endpoint GET /api/v1/contribute/submissions. It distinguishes itself from siblings like contribute_receipts and contribute_stats by focusing on per-item submission outcomes, though it does not explicitly name those siblings.

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

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

The description implies usage context: it is a read-only endpoint for the user's own submission outcomes, and it mentions forwarding the gai_ key as X-API-Key. However, it does not explicitly state when to use this tool versus alternatives such as contribute_receipts or contribute_stats, nor does it provide exclusion criteria.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It transparently states the tool does not move money, returns honest availability (including a 503 error for the deposit endpoint), and is not a website to visit. This clearly communicates side effects and limitations, though it does not mention authentication or rate limits, which are less critical for a read-only status tool.

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

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

The description is concise and front-loaded, with the key purpose and the critical warning ('NEVER a website to visit') at the start. Each sentence adds value: purpose, availability, and explicit non-action. It is slightly verbose but not padded, earning a high score for structure.

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

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

The description explains the tool's return value (shortfall context and availability) and clearly states it does not move money, covering the main behavioral aspects. However, it does not explain the parameters, nor does it mention any prerequisites or conditions for calling the tool. Given the moderate complexity and absence of an output schema, this is a notable gap that keeps it from being complete.

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

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

The schema has 2 parameters with 0% description coverage, and the description does not explain wallet_id or needed at all. The parameter names are only partially self-explanatory; 'needed' is ambiguous (likely the shortfall amount but not specified). The description fails to add any semantic value beyond the schema, which is a significant gap given the low 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 the tool's specific purpose: the in-band funding step for a joule shortfall, returning shortfall context and funding-route availability. It distinguishes itself from a browser path and from money-moving tools by explicitly stating it does not move money. The verb 'prepare' plus the resource 'funding' is specific and unambiguous.

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

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

The description implies when to use the tool (when there is a joule shortfall and the agent needs to know what funding options are live), but it does not explicitly name alternative tools or state when not to use it. It warns against visiting a website, which is a usage boundary, but lacks explicit routing to sibling tools like wallet_transfer or billing_quote.

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

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

No annotations are provided, so the description carries the burden. It discloses key lifecycle behavior — deprecated, still functional, slated for removal — plus that behavior/params are identical to `relationships`. It does not describe return format, pagination, or read-vs-write semantics, but the deprecation and equivalence disclosures are the traits an agent actually needs here.

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

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

The first sentence front-loads the actionable routing information, which is good. However, the operator-ruling rationale about billing units vs. capability naming is background justification that does not help an agent invoke the tool, making the description longer than its functional payload warrants.

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 deprecated alias with no annotations and no output schema, the description gives the agent everything needed to act: don't use it, use `relationships`, behavior is identical. It does not stand alone as documentation, but standing alone is not required when it correctly redirects to the canonical 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 0% across 6 parameters, and the description only gestures at `hops` (traversal depth is what gets metered). It defers all other parameter meaning to `relationships`, leaving `limit`, `entity`, `offset`, `search`, and `relation_type` undocumented in both schema and description.

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

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

The description states exactly what the tool is — a deprecated alias for `relationships` with identical behavior and params — and names the sibling it duplicates. An agent can immediately tell it apart from `relationships` and knows not to treat it as a distinct capability.

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

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

It explicitly says 'Use `relationships`' and explains the tool is 'kept working, to be removed at a future major.' The when-to-use (never, prefer the sibling) and the migration path are both spelled out with no inference required.

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

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

The description discloses key behavioral traits: it's a free read (checking costs nothing), it returns different response shapes depending on credential type, and it explicitly notes that the graph/map meter debits this same wallet. Since no annotations are provided, the description carries the full burden, and it does well by explaining the read-only nature and the wallet relationship. It doesn't mention rate limits or error cases, but the core behavioral context is strong.

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

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

The description is dense but well-structured, front-loading the key fact that it's a free read. It packs a lot of information into a few sentences, including credential types, endpoints, and return shapes. It's slightly long but every sentence earns its place. The parenthetical about the graph/map meter is useful context, though it could be trimmed.

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

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

Given the tool has one optional parameter, no output schema, and no annotations, the description is quite complete. It explains the two credential paths, the return shapes, and the relationship to the graph/map meter. It doesn't describe error cases or what happens with invalid credentials, but for a simple balance check, the description covers what an agent needs to call it correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It does: it explains that wallet_id is not needed for GreenlandAI agent keys (reads own wallet) but is used for JoulePAI/ENYAL credentials. This adds meaning beyond the bare schema, which only shows wallet_id as an optional string with a default of null. The description could be more explicit about what happens if wallet_id is omitted for a JoulePAI credential, but it's largely sufficient.

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

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

The description clearly states the tool's purpose: checking a wallet balance. It specifies the verb ('reads', 'checks'), the resource (wallet balance), and distinguishes between two credential types (GreenlandAI agent key vs JoulePAI/ENYAL credential) with different behaviors. It also differentiates from siblings by noting this is the wallet check before calling the graph/map meter.

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

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

The description explicitly explains when to use this tool: to check your own wallet balance before calling the graph/map meter. It also explains the alternative paths based on credential type: a GreenlandAI agent key reads its own wallet with no wallet_id needed, while a JoulePAI/ENYAL credential reads by wallet_id. This is clear usage guidance with no 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?

With no annotations, the description carries the burden and does so well: it reveals the backing endpoints, credential types, wallet_id resolution behavior, and that the operation is a read ('read a balance', 'FREE'). It does not discuss failure modes or rate limits, but the core behavioral surface is 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?

The description is dense and front-loaded with purpose and return format, followed by credential-specific details. The phrases 'no website, no guessing, FREE' add some rhetorical color but do not seriously bloat the 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?

For a 2-parameter tool with no output schema and no annotations, the description covers the essential operation, return keys, credential branches, and wallet_id behavior. Minor gaps like cost units and exact error behavior are not critical for an agent to call it correctly.

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

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

Schema coverage is 0%, yet the description compensates fully: cost is explained as the planned cost, and wallet_id is explained as optional, omitted for GAI, auto-resolved via /wallet/me for JoulePAI, or passed for a specific wallet. This adds meaning far beyond the bare schema.

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

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

States a specific verb ('read a balance') and a concrete output contract ({needed, have, shortfall, tool_to_call_next}) with an explicit purpose: deciding in-band whether the next call is affordable. This clearly distinguishes it from a plain balance query such as joules_balance.

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

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

The description makes the use case explicit: before a planned cost, decide whether the agent can afford the next call, described as 'no website, no guessing'. It gives credential-specific routing (GAI key vs JoulePAI/ENYAL) but does not explicitly name when NOT to use it or compare it to sibling alternatives.

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

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

With no annotations provided, the description carries the disclosure burden and does well by stating that the data is public, requires no auth, and is independently checkable. It does not discuss freshness, pagination, or failure behavior, but for a simple read-only query these omissions are 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?

The description is a single, front-loaded sentence that packs in the resource, output fields, authentication status, and verifiability. Every clause earns its place with no redundancy.

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

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

The tool is simple with no parameters and no output schema, yet the description explains what is returned, the authentication posture, and the verifiability property. This is complete enough for an agent to know when and how to invoke 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?

There are zero parameters, so the baseline is 4. The description does not need to explain parameters, and none are referenced.

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 recent public ledger anchors with on-chain transaction ids and the exact credit supply at each anchor. It lacks an explicit action verb like 'list' or 'get', but the resource and output are unmistakable and distinguishable from siblings like 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?

The description provides clear context for when to use this tool: it is public, requires no authentication, and is independently checkable. It does not explicitly name alternatives or exclusions, but the context is strong enough for an agent to infer appropriate use.

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

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

No annotations are provided, so the description carries the full burden. It discloses auth requirements (AGENT KEYS ONLY, refused before charge), cost (150 J metered, all-in 151), refund policy (full refund if no image delivered), failure semantics (available:false is a result, not an error; never fabricated), and output structure. This is comprehensive behavioral disclosure.

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

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

The description is dense but front-loads the core purpose and key parameters well. However, the later sections (RETURNS, unavailable semantics) are somewhat verbose and could be tightened. It includes useful edge-case details but at the cost of length, bordering on over-specification for a tool call description.

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

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

For a 6-parameter tool with no annotations, no output schema, and 0% schema description coverage, the description is remarkably complete. It covers purpose, parameters, auth, cost, refunds, return format, provenance fields, and failure modes — everything an agent needs to invoke and interpret the tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It explains pose via lat/lng OR entity_type+id, as_of format (YYYY-MM-DD, newest scene on/before date), max_cloud range (0-100, default 20), and even clarifies that entity_cap_consumed is 0. This fully compensates for the missing schema descriptions.

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 (satellite still image) and resource (Sentinel-2 archive scene), and explicitly differentiates from the sibling `look_from` by naming it ('same pose family as `look_from`'). Clearly tells the agent this returns an image rather than coordinates or metadata.

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?

Defines when an image is unavailable (cloudy or missing scene returns available:false, refunded) and distinguishes archive from live. However, it does not explicitly state when to choose this over `look_from` — it only notes they share a pose family, leaving the agent to infer the difference (still image vs whatever look_from provides).

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

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

No annotations are provided, so the description carries the full burden and discharges it: metered billing debited from the CALLING agent's wallet, the 400-before-charge wallet-unmoved guarantee, the all-in charged_joules composition, provenance fields on results, and an explicit staleness caveat ('reflect the pin at read time; a held result will not reflect that'). This is exactly the behavioral context an agent needs before a paid call.

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

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

Purpose is front-loaded, but the pricing rail is explained twice in different words ('base + 0.5% rail' then 'the base joule_cost plus a 0.5% rail surcharge rounded up'), and the dense backtick-laden prose makes the routing instructions harder to scan than necessary.

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

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

There is no output schema and no annotations, and the description still covers pricing, failure semantics, provenance, and per-flag behavior for a 7-parameter tool. It stops short of describing the shape of a returned pin, which is the one gap against a completely self-contained definition.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: it enumerates entity_type's four values, explains the id-anchoring interaction, and clarifies the off-by-default flags energy (energy fleet infra) and include_country_centroids (country-centroid placeholders). Those are meaning-bearing semantics the bare schema 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?

The opening 'Map lane: pins near a point (lat/lng + radius_km)' states a specific operation and resource clearly. However, it never distinguishes itself from the many geographic siblings (nearby, look_at, map_viewport, mapdata), so an agent cannot tell from the text alone why it should pick look_from over `nearby`.

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 conditional guidance on the entity_type dual behavior ('ALONE filters the frame' vs '+id ANCHORS and keeps ALL types') and explicit routing to billing_quote/joules_balance/joules_deficit with their purposes. What is missing is when-not-to-use guidance relative to the geographic siblings, so it falls short of a 5.

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

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

With no annotations available, the description carries full behavioral disclosure. It specifies that the backend returns 403 before the meter, so no charge is incurred; both agent and human constraints are named; and it explains the tool is kept only for stable enumeration and will reopen metered if flags change. This fully discloses all relevant runtime behavior an agent needs.

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

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

The description is longer than typical, but every sentence earns its place given the shutdown state, alternatives, and operational details. The critical 'do NOT call' is front-loaded, and the rest logically follows (why closed, what to use, when it may reopen). It is verbose but not bloated.

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

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

For a tool that is deliberately closed to callers, the description is comprehensive. It tells the agent exactly why the tool cannot be called, what the alternatives are, what charging behavior would be, and what the tool did when open. No essential context is missing for an agent to decide correctly not to use this tool and to pick the right sibling.

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

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

The input schema has zero description coverage and the description only mentions 'layers + include_country_centroids' by name. It does not explain what layers values mean (e.g., 'companies'), what include_country_centroids does, or what the defaults imply. Since the description is the only place to convey parameter meaning and it adds almost none, the score stays low.

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

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

The description clearly identifies the tool as the bulk map-layers surface and, even more importantly, states its current closed status with an explicit 'CLOSED — do NOT call.' It distinguishes it from map_viewport and look_from by naming those as the bounding-box and pose-based alternatives, so an agent can immediately tell what this tool is and that it should not be used.

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 guidance is explicit and unequivocal: 'do NOT call' and 'USE INSTEAD: map_viewport for a bounding box ... or look_from for a pose.' It also explains why (backend 403, no charge) and when it might reopen (if the flags flip), so the agent knows both the current exclusion and any future condition to revisit.

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

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

With no annotations provided, the description carries the full burden and does so richly: it discloses auth requirements (agent keys only, non-agent refused before charge), rate window, metering/debit from calling agent's wallet, pricing (one basic price, rail surcharge), and the critical sampling behavior (pins are a sample, counts are true totals). It also discloses source_tier/tier_label per pin and the honesty semantics matching look_from.

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

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

The description is dense and information-rich, front-loading the core purpose before diving into params and billing. It is long, but every sentence earns its place given the tool's complexity and the absence of annotations; the structure is logical: purpose, params, return semantics, auth, metering, and per-pin 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 7-parameter tool with no annotations and no output schema, the description is remarkably complete: it covers all parameters, return shape (pins, counts_by_type), the critical sample-vs-total distinction, auth, rate limiting, metering, pricing, and per-pin fields. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: it explains min_lat/min_lng/max_lat/max_lng as the bbox all four together, entity_type with the allowed values (deposit | infrastructure | company | project) and default, energy default False and what it omits, and include_country_centroids default False. This adds meaning far beyond the bare schema titles.

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

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

The description clearly states the tool maps a bounding box to the screen, relays GET /api/v1/map.viewport, and lists the typed parameters. It distinguishes itself from siblings like look_at, look_from, and nearby by emphasizing the bbox/screen framing and the capped pins plus counts_by_type behavior.

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

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

It explicitly says when to use this tool (everything inside a bounding box, the screen) and contrasts with alternatives like look_from for honesty semantics. It also gives clear parameter usage guidance: all four bbox params together, entity_type defaults, energy default, include_country_centroids default.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It clearly discloses the irreversible financial consequence ('releases escrow to the provider') and the enforced authorization constraint ('backend enforces it'). It stops short of describing idempotency behavior or failure modes, but covers the critical safety-relevant traits.

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 deliver the purpose, endpoint, consequence, and role requirement with no filler. The most important fact—the escrow release—is front-loaded in the first sentence.

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

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

For a simple two-parameter tool with no output schema, the description covers the essential operational context: what the tool does, its side effect, and who may call it. The only notable gap is the optional idempotency_key, whose semantics are left unexplained.

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

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

Schema description coverage is 0%, so the description must compensate for parameter meaning, but it does not explain either match_id or idempotency_key. match_id can be inferred from the endpoint path and tool name, yet idempotency_key's purpose and effect are entirely undocumented in both the schema and description.

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

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

States a specific verb and resource ('Accept a delivery on a match') and pins it with the exact endpoint (POST /match/{id}/accept). This clearly differentiates it from sibling market actions like market_provide or market_quote without ambiguity.

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 role requirement ('You must be the buyer party') gives a clear condition for legitimate use, and 'accept a delivery on a match' implies it runs after a match exists. However, it does not explicitly state when not to use it or name alternatives, leaving usage guidance mostly 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?

With no annotations, the description carries the full burden. It discloses auth requirements (bearer token) and read-only nature, which is useful. However, it does not describe the response format, pagination behavior, error handling, or any side effects beyond being read-only. It also does not clarify whether the 'oracles' kind behaves differently from 'providers' in terms of parameters or return data.

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

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

The description is a single, dense paragraph that front-loads the purpose and then lists parameters in a compact colon-separated list. It is efficient with no wasted words, and the key information (purpose and params) appears early. The flow could be improved with clearer separation between the two kinds, but it is acceptable.

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

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

For a tool with 8 parameters, no output schema, and no annotations, the description is only partially complete. It covers the purpose, auth, and most parameter defaults, but it omits explanation of several parameter semantics, does not describe the return structure, and leaves ambiguity about the 'oracles' kind. An agent could call it correctly for basic browsing, but would lack guidance for edge cases or filtering nuances.

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

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

Schema description coverage is 0%, so the description must compensate. It lists seven of the eight parameters (all except kind) and provides defaults for active, limit, and sort, plus a constraint (limit <=200). However, it does not explain the meaning or allowed values of frontier, resource_type, or oracle_verified, leaving agents to guess their semantics. The description adds some value by naming the parameters and their defaults, but it is far from comprehensive.

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

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

The description clearly states the tool browses the RAREEAI marketplace, distinguishes between kind='providers' and 'oracles', and names the endpoint. This is a specific verb+resource that differentiates it from sibling tools like market_accept or market_quote, which imply different actions.

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 context that this is a browse/read operation ('Needs a bearer; no write scope to read') and lists the available query parameters, but it does not explicitly state when to use this tool over alternatives like market_quote or market_request. There is no direct mention of exclusions or conditions that would route an agent to a different sibling.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. 'Read' conveys a non-mutating operation, and the description adds important constraints: party eligibility and bearer authentication. It does not describe error cases or response shape, but for a simple get-by-id tool the core behavioral traits are covered.

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

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

The description is two sentences with no filler. The primary action and resource are front-loaded, followed by relevant field details and prerequisites. Every sentence contributes information an agent needs.

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

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

For a single-parameter read tool with no output schema and no annotations, the description covers purpose, field scope, authorization, and eligibility. It omits only minor details such as not-found or permission-failure behavior, which are not essential for selecting and invoking this tool correctly.

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

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

Schema description coverage is 0%, so the description must add meaning to match_id. The phrase 'by id' clarifies that match_id is the identifier selecting the marketplace match, which is useful beyond the bare schema. With only one, well-named parameter and no enums or nested objects, this is sufficient.

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

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

The description opens with a specific verb ('Read'), a clear resource ('marketplace match'), and an identifying criterion ('by id'). It also names the included fields, making the tool's purpose concrete and distinguishable from sibling tools like market_accept or market_listings.

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 establishes clear context: use this to read a single match by id. It also provides prerequisites ('You must be a party to the match. Bearer required.'), so an agent knows eligibility conditions. It does not explicitly name alternatives or when not to use it, so it stops short of a 5.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It covers authentication (403 for unverified tokens), the fee being spent rather than refundable, and the strict typed body that refuses extra fields. It contrasts the fee with an oracle stake, which adds useful context. However, it does not describe the response format or idempotency behavior, which are relevant for a create/update operation.

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

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

The description is dense but well-structured, starting with the core purpose, then the auth requirement, then the fee detail, and finally the body schema. Every sentence contributes value, and the format is front-loaded with the most critical information. No filler or repetition exists.

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

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

Given the tool's complexity (many optional fields, auth, fee), the description covers the essentials: purpose, auth, fee, and body format. It does not mention the return value or error handling beyond the 403, and some field semantics (e.g., frontier) are left undefined. For a create/update tool, this is nearly complete but has minor gaps that an agent might need to infer.

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

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

The schema coverage is effectively 0% for most fields, so the description must compensate. It lists all parameters with optionality markers (?), clarifies price_joules_per_unit is int >=0, notes sla is a dict, and explains oracle_verified is an opt-in preference. This adds meaning beyond the schema's bare property names, though it does not explain fields like frontier or resource_type beyond their names.

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

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

The description clearly states the action: 'Create/update a marketplace listing (POST /provide).' This is a specific verb and resource, and it distinguishes this tool from siblings like market_accept, market_listings, and market_match by naming the endpoint and operation. The purpose is unambiguous and immediately actionable.

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

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

The description provides clear context for when to use it: requires marketplace:write and a verified account, and it specifies that first-time provider registration incurs a non-refundable fee. However, it does not explicitly name alternative tools or state conditions for choosing this tool over siblings like market_accept or market_request, so it lacks explicit exclusions or alternatives.

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

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

With no annotations, the description carries the full behavioral burden. It discloses that the output is typed fields (not prose) and instructs the caller to parse those fields, which is valuable. It also notes 'Bearer required,' covering authentication. However, it doesn't explicitly state whether the operation is read-only or has side effects, though 'quote' implies read-only.

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

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

The description is a single, dense sentence that front-loads the core purpose and then lists the return fields. It's efficient with no filler, though the field list makes it slightly long. The structure is logical: action, result, parsing instruction, auth requirement.

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 there's no output schema, the description enumerates the exact fields returned, which is highly useful. It also notes auth. It doesn't mention error conditions or edge cases, but for a simple quote-by-id operation, the coverage is strong. The main gap is the lack of usage exclusions, but that's captured under usage_guidelines.

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

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

Schema coverage is 0%, so the description must compensate. It clarifies that request_id is the marketplace request's identifier, which adds meaning beyond the bare 'Request Id' property name. The description effectively explains the single parameter's purpose.

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

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

The description clearly states the action (quote), the resource (marketplace request), and the identifier (by id). It lists specific return fields, which distinguishes it from sibling tools like market_accept or market_match. The verb 'quote' is specific enough given the marketplace context.

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 when you need escrow terms or trade figures for a request, but it doesn't explicitly state when not to use it or mention alternatives. No exclusions or routing guidance is provided, so an agent must infer when this tool is appropriate relative to other market tools.

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

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

With no annotations provided, the description carries the full burden. It discloses key behaviors: escrow is debited on match, the body is TYPED and extra fields are refused, and an under-scoped token gets the backend's real 403. This covers mutation, validation, and auth failure modes well. It doesn't mention rate limits or idempotency behavior, but the core safety and error semantics 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?

The description is dense but efficiently front-loaded with the core purpose and endpoint. The body breakdown is compact and readable. It earns each sentence, though the trailing 'Quote a specific request...' sentence adds useful routing context. Slightly long, but not wasteful.

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

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

For a complex mutation with many parameters, no output schema, and no annotations, the description covers a lot: purpose, auth, error case, parameter meanings, and the quoting workflow. It lacks explicit return value info, but since there's no output schema, that gap is understandable. Overall, an agent can call this correctly with the information given.

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

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

Schema description coverage is 0%, so the description must compensate. It does: it explains wallet_id pays escrow, max_price_per_unit is in joules, units_needed is int >0, ttl_seconds is expiry, and lists optional fields. It adds meaning beyond the schema. However, it omits idempotency_key from the breakdown, leaving that parameter undocumented.

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 ('Post a marketplace BUY request') and resource, with the intent (you want to buy a resource). It clearly distinguishes from siblings like market_provide (sell) and market_match (matching) by specifying the BUY side and the flow (providers match, escrow debited).

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

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

Provides explicit context: requires Bearer + verified account with marketplace:write, and mentions under-scoped token yields a 403. It also directs the agent to use market_quote before accepting a match, which hints at when to use this vs the quote tool. It doesn't explicitly state 'when not to use' but the mention of alternatives and prerequisites gives clear guidance.

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

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

With no annotations, the description carries the behavioral burden and covers metering, wallet debiting, the exact surcharge formula, and response fields source_tier/tier_label. It does not explicitly state whether the call is read-only, but the GET verb and query semantics make that largely inferable.

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

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

The description is dense but every clause adds necessary information for a metered call, and the purpose is front-loaded. The final sentence about source_tier/tier_label is terse but important, so the length is justified rather than padded.

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

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

Because there is no output schema and no annotations, the description must explain both inputs and behavior; it does so for all parameters, the billing model, and some response metadata. It stops short of enumerating the full response shape or entity_type allowed values, but it provides enough to invoke the tool 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?

The schema has 0% description coverage, yet the description names and explains all six parameters: lat/lng required, radius_km default, entity_type optional, limit cap and default, include_country_centroids default. It adds constraints and units that the raw JSON schema does not provide.

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

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

The description opens with 'Entities near a location (the primitive look_from builds on)' and defines the endpoint as GET /nearby with typed query params, so it is immediately clear that this tool returns entities within a radius. It also distinguishes itself from the sibling look_from by labeling itself as the primitive that tool builds on.

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

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

The description gives no explicit when-to-use or when-not-to-use guidance against alternatives like look_from. However, it does provide process guidance: check the caller's own wallet with the joules_balance tool and get an exact price with billing_quote before calling, which tells an agent what to do before invoking it.

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

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

With no annotations, the description fully discloses critical behavioral traits: a quality_score below 40 triggers an automatic dispute, the fee structure (1% of trade value clamped to 50–5,000 joules, split among oracles), and the deduction timing (before provider payment). It also notes the deadline and permission requirements. This exceeds typical descriptions by explaining side effects and constraints.

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

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

The description is long but information-dense, with each sentence providing essential details: the action, body structure, behavioral consequences, fee calculation, deadline, and permissions. It is front-loaded with the core action and follows a logical flow. While a bit verbose, the content justifies the length, and no sentence 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?

Given the complexity of the fee structure, dispute rule, and permissions, the description covers all necessary context for an agent to invoke the tool correctly. It explains prerequisites, body fields, side effects, and timing. There is no output schema, so no requirement to describe return values; the description provides sufficient context to act.

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?

Even though schema coverage is reported as 0%, the description explicitly explains each body field: verdict with allowed values, quality_score as integer 0-100, notes max length 2000, and execution_trace as a dict for verification details. It adds meaning beyond the schema by clarifying the purpose of execution_trace and the auto-dispute threshold, making the parameters self-explanatory.

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

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

The description clearly states the action (post a verdict) on a specific resource (a delivery you were assigned) and provides the endpoint. It distinguishes itself from siblings like oracle_assignments (which lists assignments) by focusing on the assessment submission action. The phrasing 'Post your verdict' is specific and unambiguous.

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

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

The description indicates when to use the tool: when you are an assigned oracle and need to submit your assessment within the 48-hour deadline. It also lists the prerequisite permissions (assigned oracle + marketplace:write). However, it does not explicitly mention when not to use it or compare with alternative tools, but the context of being assigned is clear enough for correct usage.

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

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

With no annotations present, the description carries the full burden of behavioral disclosure. It reveals wallet-level scoping, the 48-hour deadline before an assignment lapses, the returned fields (match_id, deadline, fee_earned, verdict/quality), and the fact that no write permissions are needed — all beyond what the schema provides.

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

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

Four sentences with no filler; the most important scoping fact ('YOUR', wallet-scoped) leads. Each subsequent sentence adds functional information — parameters, return fields, and authentication — earning its place without redundancy.

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

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

The description covers endpoint, scope, parameters, authentication, and return fields, which is comprehensive for a list tool with no output schema. It falls just short because valid status filter values are not specified, leaving an agent to guess accepted strings.

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

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

Schema description coverage is 0%, so the description must compensate. It does: limit is specified as 1–200 with default 50, and status is identified as a filter. It stops short of enumerating valid status values, which would make the parameter guidance fully self-contained.

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

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

The description begins with 'List YOUR oracle assignments' — a specific verb and resource — and clarifies the scope with 'you never see another oracle's queue,' explicitly distinguishing it from other oracle-related siblings like oracle_assess and oracle_register. It also cites the endpoint GET /oracle/assignments, making the purpose unambiguous.

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

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

The description provides clear context by stating this is an authenticated read that requires no marketplace:write permission, and it explains the optional status filter and limit. However, it does not explicitly compare against siblings such as oracle_assess or state when not to use this tool, stopping 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?

No annotations are provided, so the description carries the full burden. It discloses the return of staked joules less slashed amounts, which is a behavioral detail. It also reveals the failure condition (pending assessments) and the required permission (marketplace:write). This is thorough, though it could mention the exact response format or status codes.

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

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

The description is concise but packed with necessary information. It starts with the action, then the endpoint, then key behavioral details, and ends with requirements. No fluff; every sentence contributes to correct usage.

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 only one parameter successful, no output schema, and no annotations, the description covers all necessary aspects: the purpose, the parameter, the return behavior, failure conditions, and required permissions. It is complete for an agent to invoke it correctly without further information.

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?

While the schema has 0% coverage Geometric, the description explicitly states that wallet_id is required and explains it is sent as a query parameter, adding meaning beyond the schema's bare 'Wallet Id' title. It doesn't explain what a UUID is, but it's clear enough for an agent.

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

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

The description clearly states the action (deregister and unstake), the resource (oracle wallet), and the exact endpoint. It distinguishes from siblings like oracle_register and oracle_assess by noting the different request body style and the specific backend read pattern.

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

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

It explicitly mentions the requirement of pending assessments as a failure condition, which is critical for when to use this tool. It also differentiates from register/assess by noting the query parameter versus body, providing clear context for when this tool is appropriate.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses the refundable stake, escrow parking, 10% slashing on overturned disputes, and even contrasts it with a spent provider listing fee. These are critical consequences an agent must know before making a real call.

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

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

The description is lengthier than a one-liner but every sentence earns its place. The invite flow, body summary, refund/slashing behavior, and auth are all packed with signal. It is not overly verbose, though a small amount of tightening around the 'website bounce' sentence would be possible.

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?

This is a well-covered tool: invite-only, stakeholder economics, exact parameter constraints, and auth requirements are all present. It does not explicitly state the successful response format, but the agent has the endpoint and the request shape, and the schema is present. The only minor gap is that the description's 'list of 1 to 7' for specializations does not note the schema's null/optional default.

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

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

Schema description coverage is 0%, and the description fully compensates by explaining all three fields: wallet_id as a UUID you own, specializations as a constrained 1-7 element list of exact allowed values, and stake_amount as an integer 10000. It also adds out-of-band rules (422 on invalid values), which the schema alone does not provide.

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

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

The description opens with a specific verb and resource: 'Register as a RAREEAI oracle by staking joules (POST /oracle/register).' This directly states the tool's function and distinguishes it from siblings like oracle_deregister and oracle_assess. The endpoint further reinforces a clear, unambiguous purpose.

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 clearly says this is INVITE-ONLY at launch, describes the behavior for non-whitelisted wallets, and states the required auth ('verified account + marketplace:write'). It implicitly tells the agent when registration will succeed and what happens otherwise. It does not explicitly name the alternative deregistration tool, but the gate and context are strong enough.

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

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

With no annotations, the description carries the full burden excellently: it discloses billing semantics (metered per hop, debited from calling agent's wallet), surcharge details (0.5% rail surcharge, 100 J -> 101 J), tool routing for price/affordability (billing_quote, joules_deficit), and read-time tier provenance caveats (edges can be demoted). This is rich behavioral context beyond 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 the core purpose and key constraints, then billing details. Dense but every sentence earns its place. Slightly lengthy due to billing tool routing, but necessary for an agent to avoid wallet mistakes.

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

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

Given no output schema, no annotations, and 0% schema coverage, the description is complete: it covers purpose, parameters, billing, sibling tool routing, and output provenance. An agent has everything needed to call correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It does: entity is a case-insensitive substring of name (not id), hops is traversal depth 1-10 default 1, relation_type is one label checked against allow-list, search is free-text, limit <=100 default 50, offset. All six parameters are semantically enriched beyond the schema titles.

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: labelled relationship EDGES between companies/entities (ownership, operates, supplies). Names the capability and explicitly contrasts with the sibling 'hops' (the meter vs the product). An agent can distinguish this tool from siblings without opening schemas.

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

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

Provides clear when-to-use context:

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it excels. It reveals that anchoring is batched and never immediate, that 'pending' is a normal state for up to ~5 hours, defines 'last_anchored' as the most recent on-chain attestation, and states that everything is independently checkable. This gives an agent a precise mental model of the tool's behavior and edge cases, going far beyond a simple 'returns data' statement.

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 paragraph but meticulously organized: it leads with the core purpose and endpoint, then details the payload, then explains the critical batching caveat with clear emphasis ('ANCHORING IS BATCHED, NEVER IMMEDIATE'), then defines last_anchored and anchoring, and closes with reassurance of verifiability. Every sentence adds essential information; there is no filler or redundancy. The structure front-loads the most important facts and progressively deepens 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?

Given the absence of an output schema and annotations, the description must fully equip an agent to call and interpret results. It does: it lists all returned components, explains the 'pending' vs. real txid semantics, defines last_anchored and anchoring, and reassures that results are independently verifiable. An agent can confidently invoke the tool and correctly parse the response without additional documentation.

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 description does not need to explain parameters; instead, it clarifies the output semantics (the meaning of fields like bsv_txid, last_anchored, and anchoring), which is the appropriate focus. Since there is nothing to add about parameters, this score reflects that the description fully satisfies the parameter-semantics dimension by not having any.

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

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

The description states a specific verb and resource: 'returns the latest hourly PUBLIC transparency attestation (GET /transparency/latest — no auth)'. It enumerates exactly what is included (Merkle root over balances, total supply, transaction attestation, state root, Bridge Ledger root, BSV transaction) and distinguishes it from the 'pending' state. No sibling tool overlaps with this purpose, so differentiation is inherent, but the description 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?

It clearly indicates when to use this tool (to obtain the latest transparency attestation) and explains the batching cadence, so an agent knows what to expect. It doesn't explicitly say when not to use it or mention alternatives, but the context is sufficient: the anchoring behavior and the meaning of 'pending' are explained, which guides correct interpretation. It would benefit from naming siblings like ledger_verify or verify_proof for cross-referencing, but that's not strictly necessary.

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 provides an extensive, detailed picture of the tool's behavior with no annotations to rely on. It explains the exact semantics of each status field, warns about inconclusive/degraded results, distinguishes phantom entries, and correctly notes the path is read-only and relays ENYAL's verdicts. This greatly exceeds typical disclosure.

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

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

The description is long but necessary, given the absence of annotations and output schema. It front-loads the purpose and then builds logically through field semantics, coverage, caveats, and comparisons to sibling tools. The bullets and clear separation of warning statements make the structure navigable despite its depth.

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

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

With no output schema, the tool description has to explain the response shape. It does so extensively across all known statuses, enum values, and failure modes. It also includes coverage dates, fallback tool guidance, and explicit statement that missing proof-refs mean non-existence. Nothing necessary for correct use is missing.

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

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

The schema only declares 'identifier' as a string with no description coverage. The tool description provides the complete set of meaningful identifier forms (chunk_id, proof_id, match_id, transfer id, BSV txid) and explains how the identifier interacts with the returned fields, adding essential meaning beyond the schema.

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

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

The description clearly states that the tool looks up one identifier in ENYAL's public verify lookup and lists the accepted identifier types. It distinguishes itself from siblings by explicitly noting that Bridge-Ledger events are routed to bridge_proof and that graph edges are not verifiable here.

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

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

It gives explicit usage scope: lookup for listed identifier types, and explicitly states when not to use this tool (for bridge events, which should go to bridge_proof; graph edges are excluded). It also mentions that no auth is needed, aiding selection and call strategy.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It covers required scope, exact error pass-through behavior, live-config limits that change without deploy, the sender fee, and the 202 bridge block. It even warns against retrying with another destination, which goes beyond typical API documentation.

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

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

The description is long but deliberately organized with capital-led sections such as WHO CAN SEND and LIMITS ARE LIVE CONFIG. Every sentence carries operational consequence, and the most critical constraints are front-loaded before the body schema. There is no filler or repetition.

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

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

For a high-complexity mutation with no annotations and no output schema, the description covers scope, eligibility, error behavior, dynamic limits, fees, response bridge block, and strict body typing. It points to external docs for verified-human caps and fee rates, which is appropriate. An agent has enough information to invoke the tool correctly.

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

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

Schema description coverage is 0%, and the description compensates by enumerating the typed body: {from_wallet_id, to_wallet_id | to_handle, amount, platform?, note?, idempotency_key?, privacy_mode?, include_proof?, registration_id?}. It explains that registration_id is for quoted agent transfers and that any other field is refused. It does not fully define optional fields like privacy_mode or include_proof, but it clarifies the routing-critical parameters.

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

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

The description opens with 'Direct wallet-to-wallet transfer (POST /wallet/transfer)', giving a specific verb, resource, and endpoint. It clearly distinguishes this operation from the sibling tools by scoping it to direct wallet-to-wallet movement rather than proofs, quotes, or marketplace actions.

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

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

The description gives explicit when-to-use eligibility rules: verified human wallets may send to any wallet, while agent-class wallets may only send to registered destinations or their owner-of-record wallet. It also provides strong when-not guidance, such as 'Any other destination is refused 403' and 'do NOT retry with another destination.' It does not name alternative sibling tools, but the context is otherwise unambiguous.

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