sample_record

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

With no annotations, the description fully discloses the key behavior: it is a paid operation ($0.001, x402 USDC on Base), returns the full record plus provenance, and payment is automated via x402 handshake. It also notes that the record is 'verified,' adding context about data quality. This is substantial for a read-like 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?

Four sentences, each carrying distinct information: cost/operation, return value, use case, and prerequisite. The most critical detail (cost and paid nature) is front-loaded. No fluff or repetition; every sentence earns its place.

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

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

For a single-parameter tool with no output schema, the description covers purpose, cost, payment mechanism, return contents (full record + provenance), and relationship to free browsing. It gives an agent enough to invoke correctly and understand the financial implications.

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 only parameter, record_id, is explained as the identifier for an OSF record, and the description tells users to obtain valid IDs from get_catalog. Schema coverage is 0%, so this context is valuable, though the description doesn't explicitly mention the integer type or any constraints beyond what the schema already shows.

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 action ('Sample one verified OSF record'), the resource (record), and the method (by record_id). It also distinguishes this tool from siblings by highlighting its low cost ($0.001) as a 'try-before-you-buy' option, contrasting with paid standard per-record/search and free get_catalog.

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

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

Explicitly says when to use: 'low-cost try-before-you-buy for autonomous agents evaluating OSF data quality before buying at the standard per-record or search price.' It also gives direct alternative guidance: 'Browse get_catalog first (free) to find record_ids,' clearly steering agents to a sibling tool for a prerequisite step.

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