Get pending EIP-712 bids that include a specific CryptoPunk. Returns bids from the CryptoPunks Bids API. Rate limit: 10 per 10 min (read bucket — shared with browse_types, browse_traits, get_punk_details, get_listings, get_floor_price, get_bids_for_merkle_root).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max bids to return (default 5) | |
| punkId | Yes | Punk ID to look up bids for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, and the description adds valuable behavioral context: it specifies the rate limit (10 per 10 min) and shared read bucket, which is beyond what annotations provide. It also clarifies the bid type (pending EIP-712) and API source.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose, followed by the rate limit. Every word earns its place with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with complete schema and annotations, the description is sufficient. It includes purpose, data source, and rate limit. No output schema exists, but the description indicates it returns bids, which is adequate for this tool's 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 100%, with both parameters documented. The description adds context about the bid type and API but does not add new meaning to the parameters themselves. Baseline 3 is appropriate given full schema 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 a specific verb ('Get'), a specific resource ('pending EIP-712 bids that include a specific CryptoPunk'), and differentiates from the sibling tool get_bids_for_merkle_root by focusing on punkId. It also clarifies the data source (CryptoPunks Bids API).
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 (you need a specific punkId to look up bids), but it does not explicitly state when to use this tool versus alternatives like get_bids_for_merkle_root or provide exclusions. The rate-limit sharing info is useful but not a usage guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
Every tool targets a distinct resource or action: trait/type browsing, punk metadata, listings/floor price, bids by root/punk, Merkle computation/filtering/resolution, and bid recommendations. The related Merkle tools have clear boundaries: compute builds a root from IDs, filter returns IDs for a trait selection, and resolve reverses a root only if it has bids.
All tool names follow a consistent `verb_noun` pattern in snake_case (e.g., browse_traits, get_floor_price, resolve_merkle_root). The two bid lookup tools use the same `get_bids_for_X` structure, reinforcing predictability.
Eleven tools is well within the ideal 3-15 range and each covers a necessary facet of the CryptoPunks domain—from market data (listings, floor) to trait-based bid analysis (merkle roots, recommendations). No redundancy or bloat.
The tool surface covers the full read-side lifecycle: viewing traits/types/punks, checking market prices/listings, analyzing existing bids, and supporting trait-based bid strategies through Merkle root operations and recommendations. It lacks write actions (e.g., placing bids), but the server's purpose is clearly analytical, so no obvious operational gap exists.