Spirit Cards

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

With no annotations, the description carries the full burden and does well: it discloses the live threshold dependency, a ~20 s wall-clock cap, and the non-deterministic failure mode (found:false) along with recovery advice. It does not state cost/rate-limit or whether the cap is enforced server-side, but the key runtime behaviors are surfaced.

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

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

Two dense sentences with the purpose, formula, threshold, and failure/retry advice front-loaded, and zero filler. Every clause carries 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?

There is no output schema, so the description must describe returns; it covers found:true/false and the nonce but not the full response shape (e.g., attempts used or achieved bits). For a two-parameter search tool with a stated time cap, it is otherwise complete enough.

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, and the description adds a real tradeoff beyond the schema: lowering maxAttempts when difficulty is high. The miner address and nonce role are also embedded in the hash formula, giving contextual meaning to the 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?

States a specific verb and resource (grind a proof-of-work nonce for a miner address), gives the exact hash construction (keccak256(chainId ‖ core ‖ miner ‖ nonce)) and the acceptance criterion (requiredBits leading zero bits). This is precise enough to separate it from the sibling verify_nonce, which would check rather than produce a nonce.

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

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

Explains the goal ('so it can mint immediately') and gives failure handling ('may return found:false — retry or lower maxAttempts'). It does not name sibling tools or state when to prefer verify_nonce / get_mining_guide, so it stops short of explicit 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 does disclose useful behavioral context (the seed is deterministic and on-chain, and the profile is 'full'), but it never states that this is a read-only operation nor what happens for an unminted or invalid token id. Adequate but leaves the failure mode undisclosed.

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

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

One sentence, front-loaded with what the tool fetches, then the returned field list, closed by the scope caveat. No filler or repetition of the title.

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

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

With no output schema, the description usefully enumerates the returned fields so the agent knows what to expect, and one required param is fully schema-documented. The remaining gap is error/edge behavior for unknown token ids, which is minor for a straightforward one-param lookup.

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% for the single tokenId parameter, so the schema already documents type and meaning. The description adds only the scope note 'any minted token id', which lightly implies that unminted ids are out of range but adds no syntax beyond the schema. Baseline 3 applies.

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

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

States a specific verb (get) and resource (Spirit Cards token by id) and enumerates exactly what the payload contains: species, element, rarity, stats, and the on-chain seed. An agent can distinguish this read tool from the nonce/leaderboard/pool siblings without opening the schema.

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

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

The clause 'Works for any minted token id' gives a mild scope hint, implying it is not limited to a subset of tokens, but there is no explicit when-to-use or when-not-to-use guidance and no named alternative. Usage is only implied.

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

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

With no annotations and no output schema, the description carries the disclosure burden, and it does usefully enumerate the returned data (mint price, difficulty bits, cooldown, merge fee, paused flag, chainId, contract). However it says nothing about freshness guarantees beyond the word 'Live', caching, units for fee/cooldown, or failure modes, leaving real gaps for a tool with zero structured coverage.

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

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

A single front-loaded sentence with no filler; the field list is dense but efficient. It is slightly run-on as a comma-separated enumeration rather than grouped, but nothing is wasted.

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

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

Because no output schema exists, the description must explain what comes back, and it does so by listing every field. Minor omissions remain (currency/units for merge fee and cooldown, and how paused/chainId should be interpreted), but the agent has enough to call and interpret the result.

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

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

The tool takes no parameters, so the baseline of 4 applies. The description correctly avoids inventing arguments and instead spends its text on the return payload.

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 ('Live collection statistics for Spirit Cards') and enumerates the exact fields returned, which implicitly separates it from siblings like get_card, get_pool, and get_leaderboard. It stops short of explicitly naming which sibling answers a different question, so it is clear but not fully differentiated.

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

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

There is no statement of when to call this tool versus get_project_info, get_pool, or get_card, and no prerequisites or exclusions. For a zero-argument read tool the intent is somewhat self-evident, but no guidance is actually provided.

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

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

With no annotations, the description carries the full burden. It implies a read-only ranking query but never states the sort order, tie-breaking, whether it's global or scoped, or whether any auth is needed. The points-category enumeration is the only real behavioral context added.

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

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

A single compact sentence with the core resource and scope front-loaded. It is efficient, though the parenthetical point-category list is slightly dense for the amount of value it adds.

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 one-parameter, no-output-schema read tool, this is roughly adequate: it says what is ranked and what is returned. However, ranking metric, sort direction, and tie-breaking remain unstated, which an agent may need to interpret results correctly.

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

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

Schema coverage is 100%, so the sole 'limit' parameter is fully documented in the schema. The phrase 'top N wallets' loosely maps to it but adds no syntax or default nuance beyond what the schema already provides. Baseline 3 applies.

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

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

States a specific resource (on-chain activity-points leaderboard) and the metric breakdown (mine/merge/stake/pvp-win points) with the scope (top N wallets). It's clear what the tool returns, though it does not explicitly differentiate itself from siblings like get_recent_activity or get_collection_stats.

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

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

No guidance on when to use this tool vs alternatives. The reader must infer from the name alone that this is a ranked-list query distinct from get_recent_activity or get_collection_stats. No prerequisites, no when-not conditions.

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

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

No annotations are provided, so the description carries the full burden, and it does disclose substantive behavioral content: that the guide surfaces live values (difficulty, price, cooldown, chip discount) and includes the exact contract call. It does not mention auth requirements, rate limits, or response format, which is a modest gap for a documentation-fetch 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?

A single front-loaded sentence that opens with the purpose and then enumerates the guide's contents. It is information-dense rather than padded, though the long comma-separated list makes it slightly dense to parse.

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

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

With no output schema, no parameters, and no annotations, the description fully compensates by enumerating what the guide returns and cross-referencing the find_nonce tool an agent needs next. Nothing essential to calling or using 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?

The tool takes zero parameters and the schema is empty, so there is nothing for the description to disambiguate. Baseline 4 applies for a parameterless tool.

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

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

States a specific resource (a step-by-step mining guide for a Spirit Card) and enumerates exactly what the guide contains: the proof-of-work rule, live difficulty/price/cooldown/chip discount, miner locations, contract call, and nonce generation. It is clearly distinguishable from siblings like find_nonce, verify_nonce, and get_pool.

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 the usage context (read this before attempting to mine) and explicitly routes to the sibling tool find_nonce for obtaining a valid nonce. It does not state exclusions or alternative guides, but the context is clear enough that an agent knows when to reach for 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?

No annotations are provided, so the description carries the full disclosure burden. 'Status' strongly implies a read-only, side-effect-free call, and the field enumeration hints at the returned data shape, but there is no explicit statement about read-only semantics, auth requirements, or data freshness.

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

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

A single compact sentence that front-loads the resource ('Staking-pool / dividend status') followed by the exposed fields. It is a noun fragment rather than a full sentence, but it wastes no words.

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

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

With no output schema, the description usefully enumerates the returned data points, which is the main thing an agent needs for a zero-parameter getter. Missing only a note on read-only behavior and any usage context.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. No misleading parameter information is present.

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

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

The description names a specific resource (staking pool / dividend status) and enumerates the exact data it exposes: accrued pool, split shares, vault total weight, undistributed rewards. The verb is only implied by the tool name 'get_pool', but no sibling tool overlaps with this resource, so an agent can distinguish it easily.

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

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

There is no statement of when to call this tool, what preconditions apply, or how it relates to alternatives such as get_collection_stats or get_leaderboard. The agent must infer usage purely from the field list.

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

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

No annotations exist, so the description carries the burden. It discloses that the tool returns static descriptive content (chain, links, supply, fee split) rather than live state, which is genuinely useful, but never states that it is read-only, side-effect free, or whether the data is static versus fetched live.

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

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

One dense enumerative sentence plus a one-line next-step pointer. It is front-loaded on the resource identity and every clause maps to a distinct returned section, though the long comma list is denser than ideal for scanning.

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

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

With no output schema, the description must preview the return contents, and it does so by naming each section (game, loop, chain, links, collection, economy). For a zero-parameter, zero-annotation info tool this is essentially sufficient; only the static-vs-live nature of the data is left ambiguous.

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

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

The tool takes zero parameters, so the baseline is 4; there are no parameter semantics to document and the description correctly spends no effort on them.

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

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

The description states the resource clearly ('What Spirit Cards is') and enumerates the exact content buckets returned: game, five-node loop, chain, links, collection tiers, and economy. It does not differentiate itself from siblings like get_collection_stats or get_mining_guide by scope, though the closing pointer partially covers the guide overlap.

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

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

Usage is only implied: this is the orientation/onboarding read, and the last sentence routes the agent forward ('Call get_mining_guide to start mining'). There is no explicit 'use this when...' statement or exclusion against other info-bearing siblings such as get_collection_stats or get_pool.

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 does disclose one real behavioral fact — results are bounded to the latest blocks, not arbitrary history — and 'get' implies a read-only operation, but there is no statement on ordering, freshness/refresh semantics, or rate limits.

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

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

A single front-loaded sentence with the resource first and the disambiguating examples in a compact parenthetical. Nothing is padded or repeated from the schema.

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

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

For a one-parameter read tool with no output schema, the description covers what the feed contains but not the shape of an event, the ordering, or how 'recent' is bounded in practice. It is adequate to invoke correctly, but not sufficient to set expectations about the response.

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

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

Schema description coverage is 100% for the single 'limit' parameter (range 1–50, default 10), so the schema already does the work. The description adds nothing about the limit parameter, which is the expected baseline when coverage is complete.

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

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

The description names a concrete resource (on-chain activity) and narrows it with concrete event examples (mints / pack opens), so the agent knows exactly what comes back. No sibling covers activity feeds, so no differentiation is needed, which keeps this just short of a 5.

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

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

Usage is implied by the scope phrase 'from the latest blocks' — an agent can infer this is the recency-limited feed and not a historical query tool. However, there is no explicit when-to-use or when-not-to-use statement, and no alternative is named (none of the siblings overlap).

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 and does so well: it specifies the exact recomputation formula and lists the returned hash, leading-zero-bit count, requiredBits threshold, and on-chain acceptance flag. It does not mention side effects, error cases, or permissions, but for a deterministic verification operation it discloses the important behavior.

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

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

A single front-loaded sentence states the operation and formula, then the same sentence efficiently lists the return values. There is no filler, and every clause contributes to selecting or invoking the tool correctly.

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

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

With no output schema and no annotations, the description must cover purpose, computation, and results, and it does so explicitly. Minor gaps remain around error handling and the source of chainId/contract, but the core information needed to call and interpret the tool is present.

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

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

Schema coverage is 100%, so the schema already documents miner and nonce completely. The description references those parameters inside the proof-of-work formula, adding context about their role, but does not provide additional syntax or constraints beyond what the schema already states.

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

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

The description names a specific operation and resource: recomputing proof-of-work for a given (miner, nonce) pair, with the exact hash formula. This is clear enough to separate it from a search tool like find_nonce, though it does not explicitly name that sibling or state the contrast.

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

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

Usage is implied by the phrase 'for a (miner, nonce) pair' and 'whether it would be accepted on-chain,' which indicates this is for validating a known nonce rather than finding one. However, there is no explicit when-to-use statement, no exclusions, and no direct guidance against alternatives such as find_nonce.

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