HEY Research Lab

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context by disclosing the derivation model (FACT/DERIVED/UNKNOWN) and that lineage and evidence ids are surfaced, but says nothing about auth needs, rate limits, or failure modes.

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 opening rhetorical question is front-loaded and effective, but the middle sentence is a dense enumeration of return fields that largely duplicates what the existing output schema already provides, so not every clause 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?

With an output schema present, the description need not restate return values, and it correctly focuses on purpose, the discovery mode, and the fact/source dependency. What remains missing is differentiation from sibling lookup tools, which matters given seven related tools.

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?

Beyond the schema (67% coverage), the description explains the cross-parameter dependency that the schema cannot express: 'fact' may be omitted to enumerate explainable facts, and 'source' is only meaningful with fact=source.counted. It does not annotate each enum member individually, but the conditional logic is genuinely additive.

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 explains the facts behind HEY's claims (why a project is 'Shipping', 'Dormant' or 'Still Building', or why a figure is shown), and names the returned concepts (value, rule, version, source, lineage, evidence ids). This is concrete and distinguishable from generic read tools, though it never explicitly contrasts itself with siblings like get_evidence or get_contract.

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 one real usage rule — 'Omit fact to list what can be explained' — which tells the agent how to enter discovery mode. However, it offers no guidance on when to choose this tool over the many siblings (get_evidence, get_contract, research_answer), leaving the selection decision to inference.

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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds real behavioral detail beyond that: results are capped at eight rows, output is identity-only, and a full 0x address changes the response to activity status, 30-day ship records, last ship with source, and whether the project names the contract. It does not describe no-match or ambiguity 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?

Two dense sentences, front-loaded with the identity question and then the scope/cap and the 0x-mode behavior. No filler, but the phrasing is compact to the point of being terse ('give the slug to research_answer'), which costs a little readability.

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?

An output schema exists, so return values need no explanation, yet the description usefully summarizes both response modes and the row cap. Gaps remain around fuzzy matching, result ordering, and empty-result handling, but for a single-parameter lookup tool it is largely 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?

With one parameter at 100% schema coverage, the baseline is 3; the description exceeds it by explaining that a full 0x address produces a materially different answer shape than a name/ticker query. It adds semantic meaning the schema does not convey, though it never defines what counts as a 'full' address.

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 frames the tool as resolving a name/$TICKER/0x contract to a Robinhood Chain project identity, listing the exact return fields (name, ticker, contract, slug). This is specific enough that an agent can tell it apart from get_project_timeline or research_answer, though it opens with a question rather than a verb, which makes the core action slightly less immediate.

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 a clear downstream routing instruction ('give the slug to research_answer') and describes a distinct usage mode for full 0x addresses. It stops short of stating when NOT to use it (e.g., for contract data, use get_contract), so it is strong context without explicit exclusions.

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?

Annotations already declare readOnlyHint and openWorldHint, so safety is covered; the description adds genuine operational context beyond that — newest-first by first arrival, one event per change with its own time and precision plus when HEY first knew and its evidence, and the retraction semantics ('HEY no longer makes that claim'). It does not discuss rate limits or result-volume behavior, so it falls short of a 5.

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 is dense but front-loaded: the rhetorical question establishes scope first, then the event inventory, then the pagination/sync mechanics. A few phrasing choices ('when HEY first knew') cost tokens, but every sentence carries routing or behavioral 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?

Output schema exists, so return values need no explanation, and the description covers ordering, evidence, retractions, and cursor semantics for a 10-parameter tool. Minor gaps remain: `until` is undocumented in both schema and description, and there is no note on default page size behavior beyond the schema's 'Default 30.'

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 ~70%, so the schema documents many parameters already (after, before, since, limit, project, contract, detectedSince). The description still adds value by explaining the sync workflow — after=c1.0 as the start cursor, keep each cursor, detectedSince for today — which the bare schema descriptions do not spell out as a procedure.

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?

It names a concrete resource (the change ledger) and enumerates the event families it covers — releases, ships, status moves, contract deploys/upgrades, verification, sources, unlocks — so the agent knows exactly what comes back. The contrast clause 'without market readings' and 'Facts, never causes' carve out scope against neighboring tools, though no sibling is named by name the way a 5 would require.

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 real selection guidance: use it for today / this week / one project / one contract, pass detectedSince for today, and for incremental sync pass after=c1.0 keeping each cursor. It stops short of naming an alternative (e.g. when to prefer get_project_timeline or explain_fact), so it is clear context rather than full when-not routing.

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?

Annotations already cover readOnly/openWorld, but the description adds real caveats: an unread proxy is reported as 'not read' rather than 'not a proxy', selector signature candidates are 'a guess, never a name', and 'Not a safety verdict.' These are genuine interpretation guardrails beyond structured 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 main clause is front-loaded, but the body is a dense run-on of parentheticals (counts, names withheld; template, bytecode match or its own) that is hard to parse in one pass. Every clause carries information, but the structure hurts scanability.

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 an output schema present, the description need not explain return values, yet it usefully characterizes them and flags that no parameter is required (address or slug). For a 3-param open-world read tool it is largely complete, with only sibling-routing guidance 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 67% (address has only a pattern, no prose). The description compensates by clarifying the address-vs-slug duality and that a slug returns all of a project's contracts, plus the chainId default of 4663, adding 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 title/description clearly frames the tool as answering 'who made this contract' and enumerates the provenance payload: deployer, verified source, proxy history, call counts. A specific verb+resource is evident, though it never explicitly names a sibling to differentiate from, so it stops 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?

It states an address OR a slug can be supplied ('slug for all of a project's'), which implies how to invoke it, but gives no explicit when-to-use vs siblings like get_v4_hook, get_changes, or find_projects, and states no exclusions.

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?

Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds genuine behavioral context beyond that: what fields the returned receipt contains (claims, source URL, timing precision, when HEY knew, backing) and that withdrawn records are explicitly flagged.

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 motivating question is front-loaded and the payload description is dense but single-pass. The long inline prefix list is necessary information but makes the single sentence heavy; a small structural break would help without losing content.

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 a full output schema and readOnly/openWorld annotations, the description covers purpose, valid input types, returned fields, and the withdrawn-record edge case. An agent has everything needed to call and interpret 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?

Schema coverage is 100% and the schema already shows the id pattern, so baseline is 3. The description goes further by enumerating the valid typed prefixes (ship:, signal:, abi:, claim:, etc.), which the schema's generic pattern does not 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?

States a specific verb ('Open the record') and resource (a typed evidence id cited by a HEY answer), then enumerates the exact id prefixes accepted. An agent can distinguish it from siblings like explain_fact or get_contract without opening a 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 opening question 'What backs this claim?' gives a clear trigger condition for use, and the receipt framing implies verification/provenance workflows. It does not name an alternative tool or state when not to use it, so it stops short of full routing 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?

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=true), and the description adds real behavioral context beyond them: results carry a time-precision qualifier ('how precisely HEY knows its time'), the response is paged, and pagination is driven by the before cursor. It does not cover ordering or behavior when a slug is unknown, so it stops short of 5.

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 question, then event coverage, then lens/pagination mechanics — a sensible information order with no filler sentences. It is dense but every clause carries content; the phrasing around HEY's time precision is slightly awkward 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?

With an output schema present, the description need not explain return values, and it doesn't. For a 4-parameter, read-only, paged read tool it covers the essentials: scope, event types, lens selection, and pagination. Minor gaps (ordering, empty/unknown-slug behavior) are not blocking 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 coverage is 75%, so the schema already documents slug, limit and before. The description still adds value by naming the four lens values and flagging build as the default (which the enum cannot express) and by explaining that before is a cursor from a previous answer, not an arbitrary timestamp. Limit semantics are left to 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?

States a specific outcome (what a project shipped and when) and enumerates the event classes it covers — builds, releases, code, contract deploys, upgrades, interface changes, token verification, locks/unlocks. An agent can tell it is a project-scoped timeline tool. It does not differentiate itself from siblings like get_changes or get_contract, which is the only thing keeping it from 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?

The leading question implies the use case (reconstructing a project's shipping history), and the lens list hints at how to narrow scope, but there is no explicit when-to-use versus get_changes, get_contract, or get_evidence, and no stated preconditions. Usage is inferable rather than stated.

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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description does add genuine caveats beyond the annotations: 'named only while listed; never a creator account' and 'declared callbacks (not a safety verdict)'. These are useful scope limiters, though the phrasing is cramped and omits other operational 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?

The description is a single run-on fragment with nested parentheticals and no front-loaded statement of what the tool does. Several clauses are backward or ambiguous, so the content does not read cleanly despite being short.

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?

An output schema exists, so return values need not be spelled out, yet the description spends its text enumerating returns while omitting input semantics and usage context. It is adequate for a simple single-parameter lookup but leaves the agent guessing about scope and alternatives.

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 the required address parameter or what it should point at. The single parameter is largely self-evident from the tool name and the address regex pattern, which keeps this at a minimum-viable 3 rather than lower.

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 name and title identify the resource (a Uniswap v4 hook) and the description enumerates the content returned (creator/project tie, declared callbacks, source, hooklist entry, pools by week, unknowns). However, it is phrased as a question with no clear verb, and the extraneous 'Robinhood Chain' framing muddies the scope rather than clarifying it. The purpose is inferable but not stated cleanly.

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 use this tool, when not to, or how it relates to siblings like get_contract or get_project_timeline. The reader must guess that this is the hook-specific lookup versus the generic contract lookup.

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?

Annotations already declare readOnlyHint and openWorldHint, and the description adds output-level behavior beyond that: claims are labeled FACT/DERIVED/UNKNOWN with evidence ids, and the tool explicitly declines price advice or safety verdicts. That taxonomy is genuinely useful context an agent cannot get from the annotations, though latency, coverage limits, or rate behavior are not mentioned.

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?

Ten parameters and seven capabilities are compressed into roughly 90 words with no filler sentences; the lead questions and the capability list are front-loaded. The telegraphic parenthetical style is dense but each clause maps to a real routing or parameter decision.

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 an output schema present, the description need not explain return values, and it does add the claim-labeling taxonomy and scope exclusions. However, for a 10-parameter, 7-capability dispatcher with heavy sibling overlap, the missing parameter semantics and absence of sibling routing leave real gaps an agent must resolve by trial.

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 10 parameters, so the description carries the burden. It documents the most important ones (q content types, days 1-30, projects 2-4, full capability enum) but leaves limit, types, detail, and building entirely unexplained, so half the surface remains 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?

The description communicates what the tool produces: a single cited answer to research questions about a Robinhood Chain project, with an enumerated capability list (research_project, what_changed, verify_project, compare_builders, unknowns) that clarifies its scope. It is not a clean verb+resource statement and never mentions the 7 sibling tools, so an agent must infer the boundary versus get_changes, find_projects, or get_evidence on its own.

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 per-capability conditions in parentheses: q accepts a name/$TICKER/address/project slug (a shared name lists candidates), what_changed takes a project or chain over 1-30 days, compare_builders takes 2-4 with no winner. It also states an explicit exclusion, 'Not price advice or a safety verdict,' which acts as a when-not. It falls short of naming the sibling alternatives that cover overlapping ground.

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