Hive Zk Attestation

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

No annotations are provided, so the description carries the burden of behavioral transparency. It discloses the HTTP method (GET), the endpoint URL, the real settlement detail, and a graceful failure message ('returns "rails not yet live" gracefully if upstream is not yet deployed'). It does not mention response format or side effects, but the operation is a safe read and the graceful error adds transparency.

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

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

The description is three sentences, each earning its place: purpose, endpoint/URL, and graceful failure behavior. It is concise, front-loaded with the main purpose, and contains 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 simple tool with one optional parameter and no output schema, the description covers the essential usage including the endpoint and error handling. However, it does not describe the return structure (e.g., fields like agent addresses and amounts), which would be helpful for the agent to know what to expect. Still, it is nearly complete for the tool's simplicity.

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

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

Schema coverage is 100% with a clear enum and default, so the baseline is 3. The description adds value by showing the URL template with ?window=<window>, connecting the parameter to the actual request. This goes beyond the schema's basic documentation of the enum values.

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: 'Top earning agents on the Hive Civilization, by attribution payout in USDC.' This uses a specific verb ('list' implied) and a distinct resource (leaderboard), and it is distinguishable from siblings like hive_earn_me (individual earnings) and hive_earn_register (registration).

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 implies when to use the tool (to view top earners) and the context is obvious. However, it does not explicitly mention alternatives or when not to use it, unlike a perfect score. Sibling tool names provide differentiation, but the description itself does not reference them.

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

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

With no annotations, the description carries full disclosure burden. It specifies the HTTP GET endpoint, the real data nature ('Real Base USDC, no mock data'), and the graceful failure mode ('returns "rails not yet live"'). However, it doesn't explicitly state prerequisites like registration or behavior for non-registered/invalid DIDs, which would be useful.

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

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

Three sentences, each earning its place: the first states purpose and returned data, the second confirms data authenticity, and the third provides endpoint and error handling. Front-loaded with the action and fully informative without waste.

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

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

Despite having only one parameter and no output schema, the description is complete for the tool's complexity. It names all returned fields, explains the endpoint, and covers the main failure case. No critical information is missing for an agent to correctly invoke 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 schema only says 'Agent DID to look up. Required.' The description adds critical semantic context: the DID is the caller's own agent DID, and shows the URL template where it's inserted. This clarifies exactly what value to pass, going beyond the schema's generic 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 clearly states the tool's purpose with a specific verb ('Look up') and resource ('caller agent's registered earn profile'), and enumerates the exact data returned. It distinguishes itself from sibling tools by emphasizing it's for the caller's own profile, not the leaderboard or registration.

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 this tool: when you need the caller agent's own earn profile, as opposed to hive_earn_leaderboard or hive_earn_register. It doesn't explicitly state exclusions or name alternatives, but the 'caller agent's' phrasing and sibling names provide sufficient contextual 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 full burden. It discloses that the tool makes a POST call on behalf of the caller, includes the exact URL, and describes the cold-start resilience behavior. It omits details about the successful response or reversibility, but the key side-effects and error resilience 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 concise, front-loaded with the core purpose, and every sentence contributes useful details (settlement, kickback, endpoint, resilience). It is well-structured for quick parsing.

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 has no output schema, and the description only specifies behavior in the cold-start case, leaving the successful response shape unclear. It also does not mention idempotency or prerequisites, which are relevant for a registration tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context linking parameters to the program economics ('5% kickback', 'attributed traffic'), which enriches the understanding of payout_address and attribution_url beyond the 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?

The description opens with a specific verb and resource: 'Register an agent for the Hive Civilization attribution payout program.' It further distinguishes the tool from siblings by detailing the program specifics (Base USDC settlement, 5% kickback, weekly payout) and the HTTP endpoint, making its role unique among the listed tools.

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

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

The description clearly implies that this tool is for registering into the earn program, contrasting with siblings like leaderboard or me. However, it does not explicitly state alternatives or when not to use it, so it falls short of a full 5.

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

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

With no annotations provided, the description fully discloses key behavioral traits: it anchors only, does not move state, has a specific cost, and returns 'backend_pending' until rails land. This goes beyond the schema and gives the agent essential expectations about side effects and current reliability.

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 three sentences, front-loaded with the core purpose, then adds critical constraints, cost, and status. Every sentence provides value with no redundant content, making it appropriately concise for the tool's complexity.

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

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

Despite having no output schema, the description covers return behavior ('backend_pending'), cost, scope limitations, and the relationship to Aleo snarkVM. This fully equips the agent to understand the tool's operational context and limitations, exceeding what is typical for a write operation with three parameters.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds limited parameter meaning beyond the schema, such as reinforcing that proof_commitment is a 32-byte hash, but overall it does not significantly enhance the parameter understanding beyond what the JSON schema already provides.

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

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

The description clearly states the specific action: 'Write an attestation commitment (32-byte hash) to Base via the Hive gateway.' It also distinguishes this from related operations by explicitly noting what it does not do ('does not bridge value or move state to Aleo'), differentiating it from sibling tools like zk_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 on when to use the tool: for anchoring attestations only, with explicit exclusions (no bridging). It also adds practical usage constraints like cost and backend maturity ('RFC-stage returns backend_pending'). However, it does not explicitly name alternative tools or provide a direct 'use this when' statement, though the exclusions imply the boundary.

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 transparency burden. It discloses cost ($0.05 USDC on Base), the proof-not-token semantics, that no value crosses chains, and the backend RFC-stage status with backend_pending behavior. This is rich, non-obvious behavioral information.

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 four sentences, front-loaded with the main purpose, followed by target, semantic caveat, cost, and status. Every sentence contributes essential information with 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?

The description covers purpose, verification target, semantic behavior, cost, and backend status. It mentions backend_pending as a return value but does not describe a successful response shape; however, no output schema exists, and the description is otherwise comprehensive for a complex 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 already provides 100% coverage with descriptions for all four parameters. The description adds no param-specific syntax or format details beyond naming the key inputs (state hash and DID) in the purpose statement. Thus baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Produce a zero-knowledge attestation of an agent state hash + DID.' This clearly distinguishes the tool from siblings like zk_verify_proof, zk_query_attestation, and zk_anchor_to_base.

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

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

The description provides concrete context for when to use the tool (e.g., when targeting Aleo snarkVM) and a clear boundary ('Attestation-only — emits a proof, not a token; no value crosses chains'), which implicitly tells the user not to use it for token transfers. However, it does not explicitly name alternative tools or include formal 'use X instead' 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 full burden and explicitly states 'Free' and 'Read-only', disclosing cost and side-effect profile. It also lists supported circuits, giving a preview of expected content, though it doesn't detail return format or error handling.

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

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

The description is extremely concise, with the key action front-loaded. Every sentence adds valuable information: enumeration scope, circuit categories, cost, and safety. No wasted words.

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

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

For a simple list tool with no parameters and no output schema, the description is quite complete: it states what is listed, the specific circuits, that it's free and read-only. It could mention the structure of the output (e.g., list of circuit names and fingerprints), but is otherwise contextually sufficient.

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 meaning by explaining what the tool enumerates, which is more than the empty schema provides. No parameter explanation needed.

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 enumerates supported circuits and verification key fingerprints, with specific circuit names (Varuna, Groth16, Plonk, Risc0, Plonky2). This distinguishes it from sibling tools that perform anchoring, attestation, querying, or verification.

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 categorizing circuits as primary, research-stage, and future, indicating the maturity and availability of each. It doesn't explicitly state when to use this over alternatives, but the context is sufficient for an agent to understand it's a listing/exploration tool.

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

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

With no annotations provided, the description carries the full burden of safety disclosure. It explicitly states the operation is read-only and free, which are key behavioral traits. It also lists the return fields, giving the agent a clear picture of the output without an output schema.

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

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

The description is two succinct sentences, front-loaded with the primary verb and object, followed by return values and cost/safety notes. Every word adds value and there is no redundant information.

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

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

For a single-parameter, read-only query with no output schema, the description covers all essential aspects: the exact retrieval key, the returned fields, and the free/read-only nature. This is sufficient for an agent to select and 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 input schema already fully describes the single parameter tx_hash as 'Base L2 transaction hash of the anchored attestation', so schema coverage is 100%. The description's phrase 'previously-anchored' reinforces the schema but does not add new semantic meaning beyond what is already provided.

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 (fetch), the resource (a previously-anchored attestation), and the lookup method (by Base transaction hash). It is distinct from sibling tools such as zk_anchor_to_base, which creates the anchor, and zk_verify_proof, which verifies a 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 establishes when to use the tool: to retrieve an attestation after it has been anchored, given its transaction hash. It does not explicitly name alternatives or exclusions, but the context is clear and the sibling tool names help differentiate use cases.

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

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

With no annotations, the description carries the full burden. It discloses read-only behavior (no settlement, no on-chain write), free execution, and the return format (boolean validity + fingerprint). It doesn't cover error handling or permission requirements, but for a verification tool this is fairly transparent.

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

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

Three sentences: purpose, target detail, and return/behavior. Front-loaded with the main action, no redundant words, and each sentence adds value.

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

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

The description is adequate for a verification tool: it states inputs, return values, and side-effect profile. It could mention how to obtain verification_key_id or what happens with invalid proofs, but the schema covers parameters and the behavior is reasonably 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?

Input schema has 100% coverage, so baseline is 3. The description adds minimal new parameter meaning beyond the schema; it mentions Varuna/Groth16/Plonk research-stage for proof, but that is already in the schema description. No extra detail for verification_key_id or public_inputs.

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

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

The tool's purpose is clearly stated: 'Verify a submitted attestation against a known verification key.' It identifies the primary technical target (Aleo snarkVM) and distinguishes itself from sibling tools focused on attestation creation or queries.

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 context that this is read-only and free, but does not explicitly say when to use this over alternatives (e.g., zk_query_attestation). It implies usage for verifying proofs, but no exclusions or alternative recommendations are provided.

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