HEY Research Lab

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

Annotations already mark the tool read-only and open-world; the description adds meaningful behavioral detail about what is returned, including derived vs unknown values, winning source, rule version, lineage, and evidence ids, and notes what HEY does not know for build.change. It does not cover permissions, rate limits, or pagination, but those are secondary given the annotations and 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?

Three sentences, front-loaded with the user-facing question and then output and mode details; no filler. The dense fragments and question format are slightly less direct than a plain verb-first statement, but the description remains compact.

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 four-parameter read-only provenance tool with complete input schema coverage and an output schema, the description covers purpose, output shape, list mode, and conditional parameters. It could be stronger by routing among sibling tools, but nothing essential to invoking it correctly 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?

Schema coverage is 100% and each parameter already has a description, so the description's parameter guidance is mostly reinforcement. It adds cross-parameter context for source.counted and build.change but does not give syntax beyond the schema, so the 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 ('explain') and resource ('fact') and details the output components such as value, derivation, rule/version, winning source, lineage, and evidence ids. It clearly distinguishes listing facts from explaining a specific fact, but does not explicitly differentiate itself from sibling evidence or change 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?

Provides conditional usage for optional parameters: omit fact to list what can be explained, source.counted takes a source id, and build.change explains one change via event id or the latest. It does not say when to prefer this tool over get_evidence, get_changes, or other siblings, leaving alternative selection 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, but the description adds real behavior: results are 'newest first by first arrival', 'one event per change with its own time and precision, when HEY first knew', and that a retraction means the claim is withdrawn. It also states the epistemics ('Facts, never causes'). Missing are rate limits or error behavior, but the added semantics go well beyond the annotations.

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 scoping question is front-loaded before the ledger definition and cursor instructions, and the phrasing is dense but purposeful. A few fragments ('Facts, never causes.') and the em-dash list are stylistic load rather than wasted space, though they slightly slow comprehension.

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 10-parameter, zero-required read tool with an output schema, the description covers scope, ordering, cursor/sync protocol, and retraction semantics, which is what an agent needs to call it correctly. It leaves the query-mode selection (since vs detectedSince vs after) partially inferable rather than fully spelled out, keeping it from a 5.

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 100% schema coverage the baseline is 3, but the description earns more by explaining the ordering model ('newest first by first arrival') that governs the after/before cursors and by clarifying the distinction between an event's own time and 'when HEY first knew it' (since vs detectedSince). That resolves the trickiest ambiguity in the parameter set.

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 concrete question ('What changed on Robinhood Chain today or this week, or for one project or contract?') and defines the resource as a 'change ledger' enumerating releases, ships, status moves, deploys, verification, sources and unlocks. 'Without market readings' carves out scope, but no sibling tool (get_project_timeline, get_evidence, explain_fact) is named for contrast, so the agent must infer the boundary.

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?

Clear invocational guidance is given: 'for today pass detectedSince; to sync, pass after=c1.0 and keep each cursor', which tells the agent exactly which mode to pick. There is no explicit when-not guidance or routing to alternatives like get_project_timeline for the same project view, so it stops short of full alternative coverage.

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?

Beyond readOnlyHint/openWorldHint, the description discloses real behavioral quirks: an unread proxy is reported as 'not read' rather than 'not a proxy', method names are withheld and selector signatures are explicitly guesses, and it disclaims being a safety verdict. These are exactly the kind of data-caveats an agent needs and cannot get from annotations or 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 lead question is front-loaded well, but the body is a dense comma-spliced list that is hard to parse, and much of it re-enumerates return fields already covered by the output schema. It is information-rich but not efficiently structured.

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?

Given an output schema exists, the return enumeration is partly redundant, but the description still covers inputs, key interpretive caveats, and the limits of the data. The main gap is routing guidance relative to the seven sibling 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?

Schema coverage is 100%, so address/slug/chainId are already fully documented, and the description largely restates them (chainId default 4663, slug returns all of a project's contracts). It adds no format or constraint detail beyond the schema, so the baseline of 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?

The opening question ('Who made this Robinhood Chain contract, and is it a known project's?') plus the enumerated outputs (deployer, source provenance, Sourcify answer, proxy history, method call counts) make the retrieval target unambiguous. It does not, however, distinguish itself from siblings like get_evidence or get_project_timeline, which could plausibly overlap with provenance and history.

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 by the field list; there is no explicit 'use this when' or named alternative. The closing 'Not a safety verdict' functions as a when-not hint, steering agents away from treating it as an audit tool, but no positive selection criteria are offered.

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 declare readOnlyHint and openWorldHint, and the description adds real context beyond them: the event taxonomy returned, the fact that each event carries a timestamp-precision signal ('how precisely HEY knows its time'), and that results are cursor-paged via 'before'. It stops short of describing ordering direction or what an empty page means.

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 as a question that frames intent, followed by one dense but purposeful sentence on event coverage and lenses, then the paging note. Every clause carries information, though the long run-on enumeration is slightly harder to scan than a short list.

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, return values need not be explained, and annotations cover the safety profile; the description fills in the event taxonomy and paging model that the schema does not. The main residual gap is routing guidance among the several sibling read tools, but nothing needed to invoke it correctly 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?

Schema coverage is 100% and all four parameters are already documented, including defaults for lens and limit and the cursor meaning for before, so the baseline applies. The description only restates the lens set and the cursor paging, adding no syntax or semantic detail the schema lacks.

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 opening question 'What did this project ship, and when?' plus the enumeration of event types (builds, releases, code, contract deploys, upgrades, locks/unlocks) makes the resource and returned content specific. It does not name or exclude a sibling such as get_changes or get_evidence, so an agent cannot fully distinguish overlapping read tools from the description alone.

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 notes 'Lenses: build (default), code, onchain, locks', which implies which lens to pick for which interest, and states paging behavior. However, there is no explicit when-to-use guidance versus get_changes, get_evidence, or explain_fact, and no prerequisites or exclusions are given.

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?

The annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description does add genuine behavioral caveats beyond the annotations: project attribution is reported only while listed and never resolves to a creator account, and declared callbacks are explicitly 'not a safety verdict'. However, it says nothing about lookup failure behavior or what 'unknowns' means operationally, so the added context is partial.

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 a single compact sentence with no filler, and the resource is front-loaded. But the sentence is overloaded with stacked parentheticals and a trailing 'and unknowns', which makes the returned fields harder to parse on first read than a short enumerated list would be.

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 is simple (one required address parameter), an output schema exists so return shape needn't be explained, and annotations cover the read-only profile. The description supplies the attribution caveats an agent would otherwise get wrong (listed-only naming, callbacks not being a safety judgment), leaving only sibling routing as a gap.

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% and the single parameter 'address' is fully documented with a pattern in the schema, so the description carries no additional burden. It does not add format or disambiguation detail (e.g., which chain to assume), so the baseline of 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 names the concrete resource (a Uniswap v4 hook on Robinhood Chain, keyed by address) and enumerates what is returned: builder/project attribution, declared callbacks, source, hooklist entry, and pools by week. An agent can tell this is a provenance/attribution lookup rather than a generic contract fetch, though the interrogative phrasing ('Who built this...?') leaves the verb implicit and no sibling is named for 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?

There is no explicit when-to-use or when-not-to-use guidance and no routing to alternatives such as get_contract or find_projects. The only conditional language ('named only while listed; never a creator account') constrains what the output will contain, not when to call the 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds genuinely non-obvious behavior: claims are labeled FACT/DERIVED/UNKNOWN with evidence ids, and 'not_found is a status, not isError', which tells the agent how to interpret an empty result rather than treating it as a failure. It also notes that a shared name lists candidates 'never a guess', and that `detail` controls whether capability data is dropped from the JSON.

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 questions it answers, then capability/argument pairs, then behavior and exclusions — a sensible order with no filler sentences. The telegraphic style ('q: a name or $TICKER, or address, or project: a slug') is dense to the point of being slightly cryptic on first read, but every clause carries 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 10-parameter, 7-capability tool with an output schema, the description covers the capability routing, the claim taxonomy, error semantics, and scope exclusions, which is most of what an agent needs. The remaining gap is cross-tool routing against its many overlapping siblings, which is not addressed at all.

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, but the description adds cross-parameter meaning the schema cannot express: which capability consumes which argument, the 1–30 day window for what_changed, and the 2–4 / 'no winner' constraint on compare_builders. The capability-to-argument coupling is the key missing piece in the flat schema and the description supplies it.

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 concrete research questions ('is this project still being built, what did it ship, what changed, is this contract its own') and promises 'One cited answer', which pins down both the verb and the deliverable. It also enumerates the capability modes (research_project, what_changed, verify_project, compare_builders, unknowns) so the tool's scope is legible. What it lacks is explicit differentiation from siblings like find_projects, get_changes, and get_evidence, which cover overlapping ground.

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 maps each capability to its required arguments ('what_changed (project or chain, 1–30 days)', 'compare_builders (2–4, no winner)'), which is useful internal routing, and states exclusions ('Not price advice or a safety verdict'). However, it never says when to use this tool instead of the seven siblings, and the overlaps are severe — `what_changed` vs `get_changes`, `research_project` vs `find_projects`, cited claims vs `get_evidence`. Usage is implied rather than prescribed.

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