HEY Research Lab

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

Annotations declare readOnlyHint and openWorldHint, so safety is covered; the description adds real behavioral context beyond that: answers are grounded only in the project record, every line is tagged FACT/DERIVED/UNKNOWN with its source, and coverage is limited to building with no view on price. It does not discuss limits, failure modes, or latency.

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 tight sentences with zero filler: scope first, then grounding and output tagging, then the two hard constraints. Front-loaded and each sentence carries distinct 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?

With no output schema, the description carries the return-format burden and does so by explaining the FACT/DERIVED/UNKNOWN tagging. Scope constraints (one project, building only, no price) round it out. An agent has enough to invoke correctly, though sibling routing remains unaddressed.

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 only two required params (slug, question), so the schema already does the heavy lifting. The description adds only the language allowance (English or Malay) and confirms single-project scope; the 280-char cap and slug format live in 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 concrete verb+resource: HEY answers a free-text question about one project's record. The grounding rule ('answers only from that record') is specific. It does not explicitly distinguish itself from siblings like explain_fact or get_evidence, 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?

Usage is implied — use it when you have a natural-language question about a single project, not a structured lookup. There is no explicit when-not guidance or pointer to the sibling tools (explain_fact, get_evidence, get_contract) that handle fact-level or evidence-level queries.

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 a genuine behavioral trait beyond that: 'Aggregates only; nobody is named,' which tells the agent results are privacy-preserving and contain no per-entity attribution. It also notes unlocks come 'with proof.' It does not address freshness or result shape, but the annotations lower the bar.

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 scope ('Robinhood Chain as a whole') before the view enumeration. The second sentence is dense but each clause carries distinct content; there is no filler. Slightly cryptic phrasings ('a map', 'beside market attention') keep it from a 5.

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 compensates by describing what each view surfaces, and it covers the view modes plus the default. Remaining gaps are the concrete response shape and the effective default for `view` (only implied). For a read-only, zero-required-parameter aggregate tool, this is close to sufficient.

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%, and the enum for `view` carries no per-value descriptions in the schema, so the description does the heavy lifting by explaining what each mode returns (per-day metrics, the weekly rollup, an archived ISO week, scheduled HoodLock unlocks, build momentum vs market attention). It also clarifies that 'days' is the default and how its meaning shifts per view. This adds meaning well past the schema text.

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 the resource unambiguously: chain-level ('Robinhood Chain as a whole') versus the project/token-level siblings like get_project_snapshot or lookup_token. It is an overview/aggregate tool, so the lack of a strong action verb is acceptable; an agent can tell it apart from siblings. It stops short of a crisp verb framing but the scope is clear.

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 enumeration of views (days, this-week, weekly-report, unlocks, build-market) implies what each mode is for, which is real routing help. However, there is no explicit when-to-use/when-not and no sibling is named as the alternative to reach for (e.g., get_project_timeline for per-project data). Usage is implied 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 and openWorldHint, so the safety profile is covered. The description adds genuine behavioural context beyond that: every line is tagged FACT, DERIVED or UNKNOWN, and the tool deliberately produces no ranking. That tells the agent how to interpret and present the result, which is real added value.

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 sentence with an em-dash list, front-loaded with the core action and scope before the facet enumeration. Every clause carries information; the closing exclusion is compact. Slightly dense but no 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?

No output schema exists, so the description must convey the return shape, and it does at a high level by naming the compared dimensions and the FACT/DERIVED/UNKNOWN labelling. For a one-parameter read-only tool this is close to sufficient; only the absence of any sibling routing leaves a small 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 there is only one parameter, so the schema already carries the semantics. The description restates the 2-to-4 bound that minItems/maxItems enforce but adds no format or syntax detail beyond it. 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 (compare, side by side) and resource (Robinhood Chain projects) with an explicit cardinality (two to four). It enumerates the compared dimensions, so the agent knows the output facets. It stops short of explicitly contrasting itself with the near-neighbor project_diff or get_project_snapshot, so it is clear but not sibling-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?

The only usage signal is the negative constraint 'No winner and no recommendation', which tells the agent what not to expect rather than when to pick this tool over project_diff or a sequence of get_project_snapshot calls. No prerequisites, no when-to-use framing.

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 only declare readOnlyHint=true and openWorldHint=true; the description goes further by disclosing the shape of the returned explanation (value, status classification, canonical rule/version, winning source and rationale, lineage, evidence ids). With no output schema present, this carried disclosure is genuinely useful. It stops short of permissions, errors, or rate context.

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-loads the 'why' purpose, then two short usage sentences in a logical order with no filler sentences. The first sentence is a long enumerated list that is slightly dense but every item is informative rather than redundant.

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 3-param, no-output-schema, open-world read tool, the description covers purpose, output contents, and the special fact/source interaction. Combined with schema descriptions for slug and source, an agent has enough to call it correctly; only alternative-routing guidance is thin.

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% (fact has an enum but no description), and the description fills that gap by explaining that omitting fact lists explainable facts, and that fact=source.counted requires a source id. This adds operational meaning beyond the bare enum. slug semantics are left entirely 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 verb ('explain') and resource ('a fact about one project') and enumerates what the explanation contains (value, FACT/DERIVED/UNKNOWN status, canonical rule + version, winning source, inputs, lineage, evidence ids). It is clearly distinct in intent from lookup-style siblings, though it never names a sibling to differentiate. Clear but no explicit sibling routing.

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 the fact parameter ('Omit fact to list what can be explained') and a usage note for source ('source.counted takes a source id'), which is real guidance. However, there is no when-to-use-this-vs-alternatives guidance relative to siblings like get_evidence or ask_hey, so usage stays at the implied level.

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 substantial behavioral context: eligibility rules for each surface, that shipping-in-silence and accelerating take no other argument and return at most 100 rows, that builder-radar accepts query/radar/limit/offset, and that results are not ordered by price. These details go well beyond what the annotations provide.

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 one long, dense paragraph that packs all surface definitions and rules together. While the purpose is front-loaded, the remaining information is hard to scan and would benefit from bullet points or clearer segmentation. Given the tool's complexity, the length is somewhat justified, but the structure is poor.

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 tool with 12 surfaces and 18 parameters, the description covers the surface semantics thoroughly and notes key constraints like max rows for certain surfaces. It does not explain return format or pagination beyond offset, but the absence of an output schema means that is less critical. Annotations already cover read-only and open-world behavior, so overall the description is nearly 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?

Schema description coverage is already 83%, so the baseline is 3. The description goes further by defining each surface enum value in detail and clarifying which parameters apply to which surfaces (e.g., builder-radar takes query, radar, limit, offset; shipping-in-silence and accelerating take no other argument). This adds meaningful semantics 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 description states a specific verb and resource: 'Find Robinhood Chain projects by name, ticker or contract, or browse one of HEY's surfaces.' It also distinguishes itself from lookup_token by explaining that a full 0x address is answered as lookup_token would. An agent can tell this is a project search/browse tool, not a token lookup or market tool.

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 when to use it by listing surfaces to browse, and it notes that a full 0x address is handled like lookup_token. However, it never explicitly says when to choose this tool over siblings like ask_hey, compare_projects, or lookup_token. The guidance is implicit rather than explicit.

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 safety (readOnlyHint) and reach (openWorldHint), so the bar is lower. The description adds real behavioral context: one event per change with its own time and precision, a recorded 'when HEY first knew' timestamp, attached evidence, newest-first default ordering, and retraction semantics ('HEY no longer makes that claim').

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-loads the resource definition, then usage triggers, then pagination mechanics. Dense but mostly earns its space; the closing aphorism 'Facts, never causes' is stylistic rather than operational and is the one expendable fragment.

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 read tool with no output schema, the description covers purpose, filtering intent, ordering, pagination/cursor persistence, and even the shape of returned events (time, precision, first-known, evidence). It leaves the remaining filter parameters (domain, type, project, since/until) and the response envelope largely to the schema.

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 baseline is 3, and 10 parameters include several undocumented in the schema (until, domain, type, project). The description compensates for the hardest ones by explaining the cursor/sync model for after and before and explaining that facts are timestamped by their own time — meaning beyond the schema's terse 'Sync forward from this cursor'.

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?

Specific verb+resource ('canonical change ledger: what changed on Robinhood Chain or one project') with an enumerated scope (releases, ships, status moves, deployments, verification, unlocks). It is distinguishable from siblings like project_diff, get_project_timeline, and get_evidence by framing itself as the per-event ledger rather than a comparison or rollup.

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 names trigger utterances ('what changed', 'what happened since', 'anything new on X') and gives concrete how-to-use guidance for pagination (browse newest first; pass after=c1.0 or a kept cursor; keep the cursor each answer gives). It lacks any when-not-to-use or named alternative for overlapping cases.

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 behavior is covered. The description adds meaningful behavioral context beyond annotations: it distinguishes 'not read' from 'not a proxy', explains that selector signature candidates are guesses and never names, and separates creation calls from other calls. It does not cover auth, rate limits, or response format, but it adds substantial interpretation guidance.

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 an extremely long, dense paragraph that front-loads returned field details instead of the tool action. Key invocation guidance is buried at the end, and the structure is difficult to parse. It is over-specified for a concise tool definition rather than appropriately sized.

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 only sparse annotations, the description carries the burden of explaining return values, which it does in extensive field-level detail. It covers contract identity, verification metadata, proxy history, interface changes, and activity counts. It is still unstructured and omits some edge cases, but it is complete enough for an agent to understand the data shape.

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 67%, and the address parameter has no schema description. The description compensates by explaining that chainId plus address selects one contract, while slug returns all contracts for a project. This clarifies the intended parameter combinations and adds meaning beyond the schema, though it does not address what happens when no required parameters are supplied.

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 identifies the resource (a contract as a research entity) and says it can be fetched by chainId/address or project slug, but it never states a clear retrieval verb up front. Most of the text enumerates returned fields rather than what the tool does, and it does not differentiate itself from sibling tools. An agent can infer the purpose, but it is buried and vague.

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 explicit parameter combinations: chainId and address for one contract, or slug for every contract in a project. That is useful invocation guidance, but there is no when-to-use context, no exclusion criteria, and no routing to sibling tools such as get_project_coverage or get_project_snapshot. Usage is implied rather than fully specified.

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 readOnlyHint and openWorldHint already declared, the description adds useful behavior beyond the annotations: the record's lifecycle state ('A withdrawn record says so') and the shape of the returned receipt. It does not mention auth, rate limits, or errors, but the safety profile is already covered by 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?

Front-loaded with the verb and resource, then progressively fills in return content and id provenance. The long prefix enumeration is dense but load-bearing for correct invocation; nothing is wasted, though the single paragraph could be split for 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?

No output schema exists, but the description enumerates the receipt's contents, which roughly substitutes for one. Combined with the id-provenance routing and the withdrawn-record note, an agent has enough to call it correctly; only exact field names and error behavior are absent.

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 documents the id pattern, so the baseline is 3. The description goes further by enumerating the accepted type prefixes (ship:, signal:, abi:, impl:, lock:, source:, claim:, state:, method:, sourcechange:, security:), giving meaning the regex alone 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 and resource ('Open one published record by its typed id') and details what the result is ('a receipt: what it claims, its source URL, when it happened at what precision, when HEY knew, how it is backed'). This distinguishes it from lookup/search siblings by framing the tool as a single-record receipt fetch.

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 explicitly routes the agent to where ids originate — get_changes, get_project_timeline, explain_fact, and the snapshot — which tells the agent when this tool is the right next step. It does not state when NOT to use it versus explain_fact or ask_hey, so it falls short of full when/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?

Annotations already cover safety (readOnlyHint, openWorldHint), and the description adds genuinely new behavioral context: the exact set of coverage states returned and the caveat that results are 'never a score'. It stops short of describing pagination or lookup-failure behavior, but materially exceeds what the annotations convey.

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 core meaning is front-loaded, but the middle clause is a 15-item dimension dump and a 9-item state dump that reads as schema restated in prose. It is dense rather than wasteful, yet the enumerated lists do not all earn their space in a description.

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 takes on the burden of explaining what comes back, and it does so via the state enumeration and the per-dimension framing. An agent knows the shape of the answer and the recommended timing; run-time errors and lookup-miss handling remain unaddressed.

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 slug parameter, so the schema already carries parameter meaning. The description adds nothing about slug format or resolution, which is the baseline expectation at full 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 states a clear verb+resource: reporting what is and is not known about one project, broken down per dimension, with an explicit output vocabulary of coverage states. It is distinguishable from ingestion-oriented siblings like get_evidence or get_project_snapshot, though it never names a sibling directly to sharpen 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?

'Read it before concluding anything from an absence' gives a concrete trigger condition for calling the tool and a rationale. What's missing is explicit routing against similar siblings (get_project_snapshot, get_evidence), so the agent must infer relative ordering rather than being told 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?

Annotations already cover safety (readOnlyHint) and open-world scope, so the description correctly spends its budget elsewhere: it discloses measurement boundaries ('distinct caller addresses per day — addresses, not people'), freshness, 'what HEY does not know', and why data may be withheld. These are genuine behavioral caveats an agent cannot get from the structured fields.

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 clause is well front-loaded, but the remainder is a dense recursive inventory of return-field domains ('context blocks, never building: paid promotion…, DefiLlama protocol economics…, developer footprint…') that reads like a spec dump. For a selection decision, most of these phrases do not change whether an agent picks this tool, so much of the length is not earning 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?

There is no output schema, so the description must carry return-shape information — and it does so thoroughly, covering each context block and even the absence cases. Given the breadth of the snapshot, this is close to complete; only ordering/pagination-style details are absent, and those appear unnecessary for a single-project read.

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?

Only one parameter (slug) with 100% schema description coverage including an example, so the schema already does the work. The description adds no syntax, format, or resolution guidance beyond it, which is acceptable at this coverage level.

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 — 'everything important about one project in one read' — and enumerates the domains covered (identity, build status, market context, on-chain use, product usage, verification, locks, changes). It does not name any sibling tool, so the agent must infer its boundary against get_project_timeline, ask_hey, or get_project_coverage 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?

The closing clause 'Use this first for "tell me about X"' is a real usage cue and implies precedence over conversational siblings, but no explicit alternatives or when-not conditions are named. With fourteen siblings, the routing burden falls almost entirely on that one sentence.

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, openWorldHint). The description adds real behavioral context beyond them: results carry a time-precision signal ('how precisely HEY knows its time') and the response is paginated via the before cursor returned by each answer. It stops short of stating rate limits or auth requirements.

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 resource scope before the lens and pagination details. Every clause carries information, though the first sentence is a long comma run that could be tightened.

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 carries the return-value burden and does so partly: it names the event categories, the per-event time-precision metadata, and pagination. An agent can call it confidently, with only the missing default-limit detail (already in the schema) and lens-selection logic left unaddressed.

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% (slug, limit, before documented in the schema). The description meaningfully adds to the one undocumented param by enumerating the lens values and tying them to event categories, and it explains the before cursor's origin. It says nothing extra about slug or the default limit.

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 and verb ('One project's research timeline') and enumerates the event types it aggregates: builds, releases, code, contract deploys, upgrades, token verification, locks, unlocks. It is distinguishable from siblings like get_changes or get_project_snapshot by that enumeration, though it never explicitly names an alternative.

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 when-to-use, when-not-to-use, or alternative routing. The listed lenses (everything, build, code, onchain, market, locks) hint at scope selection but the description never says which lens suits which question or when to prefer this over get_changes/project_diff. Guidance is entirely left 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 cover the safety profile (readOnly, openWorld), so the bar is lower, and the description adds real context: the supply-concentration summary exposes shares only (no addresses), and it explicitly frames "moves" as a sequence, never a cause. That causal disclaimer is genuinely valuable behavioral disclosure 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?

Front-loaded with the purpose, then a dense but purposeful enumeration of returned sections. It is long only because there is no output schema, and each clause maps to real returned data rather than 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?

With no output schema, the description carries the return-value burden and does so thoroughly (valuation kind, price, liquidity, volume/trades, lifecycle, pools, concentration, contract checks). Combined with the readOnly/openWorld annotations, an agent has enough to call it 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 75%, so the schema already documents days, slug, and min_change_pct. The description adds meaning the schema does not carry, explaining what include=["moves"] actually returns and how it relates to the day-on-day valuation moves.

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+resource: one token's market data from HEY's daily index, and scopes it as a single-project read. It clearly differs from siblings like get_project_snapshot and lookup_token by its market/depth/lifecycle focus, though it never names an alternative explicitly.

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 guidance on when to reach for this tool versus siblings such as lookup_token or get_project_snapshot. The only usage-like note concerns include=["moves"], which is really parameter behavior rather than tool-selection 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, so the safety bar is low; the description still adds real value by disclosing that unpublished addresses return "unknown" with a scan link rather than erroring, and by scoping out risk/score/verdict output. That is exactly the kind of edge-case behavior an agent needs before calling.

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 action and the trigger condition, then output contents, then the unknown-address edge case. Dense but every clause carries information; the em-dash construction 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?

No output schema exists, so the description bears the burden of describing returns — and it does list the key result fields plus the not-found case. A little more on response shape/ordering would make it complete, but nothing essential to correct invocation 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 description coverage is 100%, so both the address pattern and the chainId default (4663, Robinhood Chain) are already documented. The description adds no format or constraint detail 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 concrete verb+resource: it resolves one project from a contract address and enumerates what it returns (activity status, 30-day ship records, last ship with source, name binding). That content list does implicitly separate it from siblings like get_contract or get_project_snapshot, though it never names an alternative to disambiguate explicitly.

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?

"Use this whenever the user pastes a contract" is a clear, actionable trigger condition. It also clarifies the negative boundary (no risk reading, score or verdict), but stops short of saying which sibling to prefer for those other questions.

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, openWorldHint), and the description adds real behavioral context on top: this is a descriptive analysis that deliberately withholds verdicts about rugs, safety, or whether development halted. That boundary is genuinely useful for an agent deciding whether to trust its output as an assessment.

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 with no filler, and the scope (one project) plus the analytical pairing are front-loaded. The phrasing 'beside its builder activity, and where the two disagree' is slightly convoluted to parse, but no sentence 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?

With no output schema, the description carries the burden of conveying what comes back, and it does list the substantive content areas (liquidity vs prior level, trading, pool migration, builder activity, divergences). It omits format, depth, and time-window behavior, which is the only notable gap for a single-param analysis tool.

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 slug parameter is fully documented in the schema with an example, so the description owes nothing here. It adds no format, naming, or resolution detail beyond what the schema already provides, making the 3 baseline correct.

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 scope (one project's tracked token market) and a specific analytical framing (market events set against builder activity, and where the two diverge), which separates it from the pure-data sibling get_token_market. It stops short of a crisp verb+resource statement — 'what happened' is abstract — and never names a sibling explicitly, so it falls 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?

There is meaningful negative guidance ('never whether development stopped, and never calls a project a rug or safe'), which tells the agent what questions this tool will not answer. However, it never states when to prefer this over get_token_market, get_project_snapshot, or compare_projects, so the positive routing decision is left 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 cover the safety profile (readOnlyHint, openWorldHint), so the bar is lower, and the description still adds real behavioral context: values come from the nearest persisted point with its date and basis, and gaps are flagged ('none HEY did not persist', 'Never a cause'). This discloses data provenance and an important limitation 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 purpose is front-loaded, which is good, but the body is a single dense run-on held together by parentheticals and semicolons, and the trailing fragments ('none HEY did not persist. Never a cause.') are terse to the point of ambiguity.

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 properly enumerates the returned categories, and it covers the date-range constraint. Combined with the all-required 3-param schema, an agent has enough to call it correctly, with only the sibling-routing choice left unaddressed.

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 only 33% (just the slug), so the description carries the burden for from/to — and it does, specifying the YYYY-MM-DD format and the 400-day maximum span. That is genuine added meaning not present in the schema for those uncommented parameters.

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 operation (a before/after diff for one project between two dates) and enumerates what's included: releases, status, Build Momentum, valuation and liquidity, and recorded changes. The 'one project' scoping implicitly distinguishes it from compare_projects, but the differentiation is never made explicit.

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 the key eligibility constraint ('at most 400 days apart') and the required date format, which is useful usage guidance. However, it never says when to reach for this tool versus compare_projects, get_project_snapshot, or get_project_timeline — the choice is left to inference.

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