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 real value by explaining what each kind returns (fee caps, health factor, request allowance, TWAP fills), but says nothing about defaults for limit/offset, pagination behavior, or rate-limit implications of the rateLimit kind.

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 kind list and each value's meaning in a single dense sentence, with no filler. It is appropriately sized for a four-mode tool, though the opening 'Smaller address-page widgets' is slightly vague framing rather than an earned statement.

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 must carry the return-shape burden, and it does by naming what each of the four kinds returns. It is nearly complete, missing only pagination/default behavior for limit/offset on the list-style kinds.

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. The description does add meaning beyond the schema's terse 'Which widget to return' by defining each enum value's payload, but contributes nothing for limit, offset, fields, or address beyond what the schema already documents.

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 ('smaller address-page widgets') and enumerates the four exact kinds with what each returns, so an agent knows precisely what data comes back. However, it uses no verb (list/get/return) and never differentiates this multi-widget tool from the many sibling address tools (flowscan_address_summary, flowscan_address_fills, flowscan_address_staking), so routing among them is left to inference.

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. 'Smaller address-page widgets' weakly implies a secondary/complementary role versus the address summary tools, but the description never states that the four kinds here are the ones not covered elsewhere, nor names an alternative for any of them.

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/openWorldHint already covering safety, the description adds substantial behavioral detail beyond annotations: 50/page default, a ~2000-row cap, maxPages follow-through, the `capped`/nextStartTime continuation rule, and the key insight that `totals` aggregates ALL matched fills in coveredRange rather than being a per-row sum.

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?

Extremely dense and front-loaded, leading with what the tool returns before the pagination rules. The telegraphic phrasing (e.g. 'startTime[/endTime]') is compact but slightly compressed, costing a touch of 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?

There is no output schema, so the description carries the return-shape burden itself, listing the row fields and the `totals` sub-structure (count, closedPnlUsdc, fees, volumeUsd, byCoin) plus the pagination edge cases. Nothing an agent needs to call 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%, so baseline is 3, but the description meaningfully extends it: startTime/endTime trigger a different query path, maxPages controls pages past the 2000-row cap (default 5), and aggregateByTime merges partial fills. It adds semantics the schema 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 ('Address Trades tab: fills') plus the ordering and page size, and enumerates the returned row columns. An agent can distinguish this from flowscan_address_orders or flowscan_address_ledger without opening the 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?

Gives explicit conditional behavior: no startTime returns the latest ~2000 fills, while startTime/endTime switches to the time-range query and follows pages past the cap. It also tells the agent to quote `totals` and never sum rows. It stops short of naming sibling alternatives, so not a 5.

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, but the description adds meaningful behavior: page sizes (50/page ledger, 100/page funding), the 2000-row cap, maxPages follow-through, and nextStartTime continuation. Crucially it warns that totals cover ALL matched rows and must be quoted rather than re-summed, preventing an aggregation error. Auth/rate-limit context is absent, 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 front-loaded with the tab scope and default kind, then layers pagination and totals semantics efficiently in a dense telegraphic style. The heavy abbreviations (timeIso, coveredRange, nextStartTime) are compact but assume familiarity, slightly reducing 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?

With no output schema, the description carries the return burden well by naming the totals fields (byType {count, sumUsdc, inUsdc, outUsdc} for ledger, {netUsdc, paidUsdc, receivedUsdc, byCoin} for funding). Combined with pagination caps, continuation logic, and the totals-must-be-quoted rule, an agent has what it needs to call and interpret results 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 description coverage is 100%, so the schema already documents all nine parameters, including kind's default, startTime's per-kind defaults, and maxPages' default of 5. The description largely restates those same defaults rather than adding new syntactic or format meaning, 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?

The description names the specific resource ('Funding' / 'Ledger' tabs) and the row shape (timeIso, newest first), so the agent knows this returns address funding/ledger activity. It doesn't explicitly differentiate from close siblings like flowscan_address_fills, flowscan_address_orders, or flowscan_address_extras, leaving the agent to infer the boundary from the tab names.

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 usable context for the internal choice: kind='ledger' (default) covers deposits/withdrawals/sends/transfers/vault-staking moves, while kind='funding' covers hourly payments, with distinct default windows. However, there is no guidance on when to prefer this tool over any sibling (fills, orders, staking, extras), so routing to alternatives 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?

Adds substantial context beyond the readOnly/openWorld annotations: upstream cap of 100 for openDetailed with a 'capped' flag, historical limited to newest ~2000 with countsByStatus and coveredRange semantics, and page-size defaults (100 open / 50 rows). This is exactly the operational behavior an agent needs and is not derivable from the 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?

Information-dense with zero filler; the mode breakdown is front-loaded after a one-line purpose statement. Jargon ('oid', 'TIF', 'coveredRange') assumes domain familiarity, but nothing 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 return burden well, disclosing count, countsByStatus, coveredRange, per-mode row shape, and ISO time twins. An agent has enough to call it correctly and interpret the response.

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 baseline would be 3; the description goes further by explaining kind defaults, per-kind paging defaults, and the coin-substring filter intent. It adds real meaning over the raw schema without fully restating every parameter.

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 specific resource ('Open Orders' / 'Order History') and enumerates the three retrieval modes with the fields each returns (coin, side, price, size, oid for open; trigger/TP-SL/reduce-only for openDetailed). It clearly reads as an order-listing tool, distinct from sibling fill/position tools, though it never names a sibling 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?

Gives effective selection guidance by labeling kind='open' as the default and describing the distinct scope of each mode, so an agent can pick the right kind from the task. It lacks explicit when-not/alternative-tool steering, but the mode semantics are strong enough to imply usage.

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 genuinely useful behavior the annotations cannot: the data is a snapshot that 'refreshes every few minutes' (staleness), it returns totalNotional/totalPositions aggregates, and results are sorted by notional desc. That staleness caveat is the key operational trait for this tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One dense sentence carries the scope, field list, freshness, sort and totals, followed by a short routing sentence — front-loaded with the tool's identity and no filler. The parenthetical field list is long but earns its place given there is no output schema.

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 does the heavy lifting by enumerating the returned position fields and aggregate totals, plus refresh cadence and sort order. Filter-parameter semantics are left entirely to the schema, which is acceptable at 100% coverage, but a brief note on pagination/limit interplay would round it out.

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 side, limit, fields, market, offset and address are all self-documented in the schema. The description adds no filter syntax or semantics beyond the schema (the 'incl. HIP-3' note describes return scope, not parameters), 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?

Names a specific verb+resource ('open perp positions' for an address) and immediately scopes it as a homepage snapshot lookup across all markets incl. HIP-3. The parenthetical enumeration of returned fields makes it clearly distinguishable from siblings like flowscan_address_summary and flowscan_address_orders.

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 routes the agent: 'For live margin/account state use flowscan_address_summary,' which is a concrete alternative with a selecting condition. It does not, however, distinguish itself from the closely-named sibling flowscan_perp_positions (market-wide rather than address-scoped), leaving one plausible confusion unresolved.

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). The description adds a useful behavioral detail, that history is returned 'newest first', plus the exact composition of the response, but says nothing about pagination behavior or the historyLimit cap's practical effect.

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 front-loaded sentence that immediately places the tool on the address page's Staking section, then lists contents. It is dense but every clause carries information; only the parenthetical field list is slightly heavy.

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 largely meets it by enumerating the returned fields and history event types. It leaves the 'fields' projection and pagination semantics unaddressed, but the core picture is complete enough to call 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 description coverage is 100%, so address, fields, and historyLimit are already documented in the schema and the description need not repeat them. It adds no param-specific syntax or defaults beyond what the schema provides, which is the expected baseline.

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 (address 'Staking' section) and enumerates the exact contents returned: totalDelegatedHype, per-validator delegations, and staking history. It distinguishes an address-scoped view from chain-wide siblings like flowscan_staking_overview, 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?

The 'Address page Staking section' framing implies when this applies, but there is no explicit when-to-use, when-not-to-use, or routing against siblings such as flowscan_staking_overview or flowscan_staking_events. An agent must infer the selection condition on its own.

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 readOnly/openWorld annotations cover the safety profile, but the description adds useful behavioral context beyond them: default section fetching, position/balance caps, largest-first ordering, and rejection of unknown dex names. It does not mention rate limits or response envelope behavior, but it is informative for a read-only composite tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with a dense list of returned sections, followed by a short dex caveat. It is efficient and has no filler, though the long run-on enumeration is slightly hard to parse.

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 must carry the return-value burden. It names role values, PnL summary fields, perp-position fields, and spot-balance behavior, which is enough for an agent to call the tool correctly, though it does not describe the overall response envelope.

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. The description adds meaningful dex semantics not fully captured in the schema: prefix or display-name matching and rejection of unknown names, plus the main-DEX default when dex is omitted.

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 clear resource (/address page) and enumerates the four sections it aggregates (role, PnL summary, perp state, spot balances). This scope clearly separates it from narrower siblings such as flowscan_address_perp_positions or flowscan_address_orders.

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 never says when to use this overview versus the other address-specific tools, nor does it set exclusions or prerequisites. Usage is only implied by the title and the word 'overview'.

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 adds what categories of data are returned, but says nothing about pagination, rate limits, or handling of addresses with no vaults/sub-accounts.

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 dense sentence that front-loads the resource and then lists the returned fields. Efficient with no filler, though the parenthetical enumeration is heavy.

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 by enumerating vault (vault, equity, lock-up) and sub-account fields. It is largely complete for a read tool whose annotations cover the safety profile, though behavioral details remain 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 description coverage is 100%, so both parameters (address and fields) are fully documented in the schema. The description enumerates returned fields rather than adding meaning to the parameters, so the baseline 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 a specific resource set (vaults and sub-accounts) scoped to an address and enumerates the data returned, so an agent can tell what it retrieves. However, the verb 'Address' is awkward and it does not differentiate itself from the many sibling flowscan_address_* 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?

There is no statement of when to use this tool versus alternatives such as flowscan_address_summary or flowscan_address_staking. No prerequisites or exclusions are given, leaving 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 and openWorldHint, so the description focuses on adding value: the fixed window anchored to yesterday UTC, USD denomination, and the default 90-day daily series. It does not mention pagination or return shape, but with annotations covering safety the added window and currency context is meaningful.

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 and the window constraint, then lists outputs, then the parameter hint, then the sibling routing. Dense and mostly waste-free, though the long output enumeration makes it slightly heavy.

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 describe the three returned groupings. It is complete enough to call correctly, though finer details of the stats payload are only listed by name.

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 all six parameters (including defaults and accepted builder formats) are already documented in the schema. The description restates the window options and builder formats but adds no format or syntax detail beyond what the schema provides, matching the baseline for 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?

States a specific resource (the /builders/{id} dashboard) and enumerates exactly what it returns: stats, daily series, and volume/revenue by asset. It explicitly names the sibling flowscan_builder_revenue as the tool for arbitrary ranges, so an agent can distinguish it without opening either 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?

Gives clear context (fixed window 7d/30d/90d/all ending yesterday UTC) and routes arbitrary-range needs to flowscan_builder_revenue, which is an explicit alternative. It does not spell out when NOT to use it beyond that single exclusion, so it falls short of a full 5.

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 establish readOnlyHint=true and openWorldHint=true, so this description earns credit on top of that by disclosing the ~11 MB payload size, the paging behavior (50 top-level, 20 nested), and that address lists are reshaped to {count, sample}. That is meaningful behavioral context an agent needs to avoid blowing up its context window.

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 sentence order is sensible: what the report contains, then the size/sections caveat, then paging and list reshaping. It is dense but mostly earns its words; the long enumeration of report contents in sentence one could be trimmed since `sections` already lists them.

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 read-only report tool with no output schema, the description covers the important gaps: what comes back, how large it is, how to shrink it, and how lists are paged/reshaped. Safety is covered by annotations. An agent has enough to call it correctly without guessing.

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 adds value beyond the schema: it names example builderId values ('phantom', 'pvp'), confirms the default section set, and quantifies paging as 50 top-level / 20 nested. These details are not fully present in 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 a specific resource (a /builder-intelligence report for one builder) and enumerates its content: user status, revenue, cohorts, lifecycle, retention, daily activity, top users, heatmap. It also points to the sibling flowscan_builder_intelligence_list as the source of builderId, helping separate it from list/summary variants. The purpose is clear, though the opening sentence is more a content dump than a crisp verb+resource statement.

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 gives operational guidance (payload is ~11 MB, so narrow with `sections`; results are paged) and notes where builderId comes from. It does not, however, say when to use this tool versus flowscan_builder_intelligence_summary or the dashboard, leaving that routing choice 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 value beyond that: it warns that '7d new users' comes from a different dataset than the leaderboard's and user_series', and instructs the agent to state which source it quotes — a data-provenance caveat that prevents incorrect cross-tool comparisons.

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 dense sentences, front-loaded with the resource and its returned fields before the routing and provenance notes. No filler; 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 compensates by listing the returned fields and the categories list, and it covers chaining to detail/summary plus the cross-dataset caveat. Pagination and filtering are fully documented in the schema, so nothing an agent needs to call this 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 description coverage is 100%, so the schema already documents limit, fields, offset, search, sortBy, category and includeCategories, including the total_revenue default and the enum. The description adds only the indirect point that 'ids feed detail' and 'category ids feed summary', which is chaining rather than parameter semantics. 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 the exact resource (the /builder-intelligence index) and enumerates the fields returned for each builder (id, name, category, users, revenue/volume, 7d new users) plus categories. It is clearly distinguishable from siblings flowscan_builder_intelligence_detail and flowscan_builder_intelligence_summary, which it explicitly names.

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 steers the agent: 'Prefer this for user-status/retention questions,' and explains that returned ids feed detail while category ids feed summary, giving concrete chaining guidance. It does not, however, state when this tool should NOT be used versus the many other builder siblings (leaderboard, dashboard, 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 cover the read-only/open-world safety profile, so the bar is lower, and the description adds real behavioral context beyond them: cohort member address lists are reduced to {count, sample}, which tells the agent output is truncated rather than complete. It still omits pagination, caching or auth behavior, but the truncation disclosure is a meaningful addition.

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 essentially one front-loaded sentence that leads with the resource and scope before enumerating returned data. The metric enumeration is dense but each item maps to actual returned content, so little is wasted, though the long list makes it heavy to scan.

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 carries the burden of explaining return values, and it does so thoroughly (metadata, totals, weighted averages, cohort reduction). Combined with the read-only annotations and fully documented schema, an agent has enough to call it correctly, with only usage routing left implicit.

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 and the schema already documents each parameter. The description adds meaning by giving concrete category values (wallet, copytrading, desktop_trading, mobile_trading) and the 'overall' default, which clarifies the category parameter beyond the schema's terse wording.

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 specific resource and its scope: 'the /builder-intelligence aggregate view for a category ... or overall', which is a clear verb+resource and distinguishes it from the sibling list/detail tools by labeling it the aggregate view. It stops short of explicitly contrasting itself with flowscan_builder_intelligence_detail, but the purpose is unambiguous.

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: the 'aggregate view' framing and the default 'overall' suggest when to reach for it, and the schema notes the category id comes from flowscan_builder_intelligence_list. There is no explicit when-to-use / when-not-to-use statement or a named alternative such as detail for per-builder drill-down.

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 real behavioral detail beyond that: case-insensitive matching across id/name/address, exact-then-substring ordering, and revenue-based ranking. It stops short of describing error behavior or empty-result handling, so not 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?

Front-loaded with the purpose, then the workflow, then matching rules, then the return shape. Dense but every sentence carries information; the field enumeration is slightly list-like but earns its place given no output schema.

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, and the description compensates by enumerating returned fields (id, name, category, address, revenue/volume windows, total_users). Combined with the matching and routing guidance, an agent has everything needed to call and interpret this 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 100%, so the schema documents both parameters (baseline 3). The description still adds semantics the schema lacks: what `query` matches against (id, name, address), the case-insensitivity, and the substring allowance, which materially informs query construction.

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 precise verb+resource: resolving a builder name to id/address. It also explicitly separates itself from siblings by naming flowscan_builder_revenue and flowscan_builder_dashboard as downstream consumers, so an agent can place it 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?

Gives explicit ordering ('call this first, then pass the exact id/address to ...'), names the two alternative tools, and gives a decision rule for ambiguity ('if multiple strong matches exist, show them to the user'). Nothing 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 only declare readOnlyHint and openWorldHint; the description adds meaningful behavior beyond that: end dates are clamped to yesterday, future starts error, ambiguous names return candidate lists, results are cross-checked against the dashboard series, and rows come newest first. It stops short of describing pagination or rate-limit behavior, so not a full 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?

A single dense paragraph, front-loaded with the resource and its scope before the parameter rules. Nearly every clause carries information (defaults, clamps, error cases, data source, ordering), though the packed phrasing borders on overload.

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 seven parameters, the description responsibly describes the return shape (total plus daily rows, newest first) and the upstream source. It omits list-control semantics (limit/offset/fields) and the cross-check output fields, but those are secondary for calling the tool 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 description coverage is already 100%, so baseline is 3. The description adds real value on `builder` (0x address preferred, id: or name, ambiguity resolution) and reinforces the `days` default/ending rules. The list-control params (limit, offset, fields) 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 and resource: total and daily revenue (USD) of ONE builder over any range. The explicit 'ONE builder' scope distinguishes it from sibling aggregate tools like flowscan_builders_leaderboard and flowscan_builders_daily_revenue without opening any 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?

Gives clear input-selection guidance: use `days` (complete UTC days ending yesterday, default 30) or startDate/endDate, and notes future starts error. It also tells the agent to ask the user when a name is ambiguous. It does not, however, state when to prefer this tool over siblings such as flowscan_builder_dashboard or flowscan_builders_user_series.

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 (readOnlyHint, openWorldHint), and the description adds real behavioral context beyond them: default window ending yesterday, default top-20 cap, and the id-keying convention (slug for well-known builders, 0x address otherwise). It does not mention rate limits, pagination, or behavior when a builder filter matches nothing beyond what the schema hints at.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences, front-loaded with the resource and output shape, then defaults, then the sibling redirect. Every sentence carries information an agent needs to call it correctly.

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 compensates by describing the return payload precisely: per-UTC-day revenue keyed by builder id, range totals per builder, and a grand total. Combined with annotations and full schema coverage, an agent has everything needed to invoke and interpret the result.

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 the baseline is 3, but the description adds meaning the schema does not: builder keys are slugs for well-known builders and 0x addresses for the rest, and the returned structure is keyed by that id. It restates the top-20 and date defaults that the schema already documents, which limits it to a modest bump above baseline.

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 ('daily revenue chart' per builder over a UTC date range) and immediately pins the output shape (per-day, keyed by builder id). It explicitly contrasts itself with the sibling flowscan_builder_revenue, so an agent can route between them 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?

Gives the when-to-use rule explicitly: 'For one builder's total over a range use flowscan_builder_revenue instead.' It also documents defaults (last 30 days ending yesterday, top 20 builders) that determine when this tool is the right call.

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 and open-world nature are covered. The description adds useful context beyond annotations — approximate scale (~1800 builders), the fixed-window limitation, and the shape of returned rows (rank, id, name, category, value, windows, all-time revenue, users) plus full=true behavior. It stops short of noting pagination behavior, but the return-shape disclosure 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?

Front-loads the resource and ranking model before the routing alternatives; every clause carries information. It is dense and parenthetical-heavy, but there is little true filler, so it stays efficient without being 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 no output schema, the description compensates by describing the returned row fields and the full=true variant, and it resolves the main ambiguity (fixed vs arbitrary windows) by pointing to the correct sibling. Coverage of pagination and default limits is left to the schema, which documents it, so completeness is strong though not exhaustive.

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 the baseline is 3, but the description adds real semantics: the window set is FIXED (1d/7d/30d/90d/all_time), new_users/total_users/avg_revenue_per_user_all_time are all-time only, and full=true returns all metrics. This clarifies cross-parameter behavior the schema cannot express on its own.

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 operation ('Builder Arena' leaderboard of ~1800 builders ranked by one metric) plus scope constraints (fixed window, list of metrics). It explicitly distinguishes itself from the two most confusion-prone siblings by name. An agent can identify what this returns without opening the 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?

Gives explicit routing rules: arbitrary ranges like 'last 45 days' go to flowscan_builder_revenue, and flowscan_hip3_builders is for HIP-3 volume only. It also states the fixed-window constraint that determines when this tool is the right choice. Nothing 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 declare readOnlyHint=true and openWorldHint=true, so the safety profile is already covered. With no output schema, the description usefully discloses the return shape (headline totals, per-category breakdown with builder counts, per-builder list with paging). It does not cover rate limits or data freshness, so it is not 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?

A single dense sentence that front-loads the headline totals and then the per-category and per-builder detail. It is efficient and complete, though the run-on structure makes it slightly harder to scan than a short multi-sentence version.

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 read-only, three-optional-parameter tool with no output schema, the description covers both the aggregates returned and the paging behavior, which is enough to call it correctly. It omits any guidance on data freshness or category semantics but is otherwise adequate.

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 the baseline is 3, but the description adds real value by stating that the per-builder list is paged with limit/offset and that the default is 50 — a default the schema itself only calls 'default per tool'. The fields parameter is not explained in the description, keeping this from a 5.

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 precisely states the resource and scope: all-time builder headline totals (revenue, volume, users, avg revenue/user), overall and per category, plus the per-builder list. The 'all-time' framing implicitly distinguishes it from sibling time-series tools like builders_daily_revenue, but it never names an alternative 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?

Usage is only implied by the 'all-time' scope and 'headline totals' wording. There is no explicit when-to-use, when-not-to-use, or routing among the many sibling builder tools (leaderboard, daily revenue, dashboard, user series), leaving the agent to infer selection.

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 (readOnlyHint, openWorldHint), and the description adds real behavioral context the annotations lack: the data begins 2025-07-27 and new_users.7d from the leaderboard is a separate dataset that can differ. It doesn't discuss pagination or return shape, keeping it just 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?

Two tightly written sentences, front-loaded with the core purpose and follow by the routing caveat and dataset caveat. Every clause carries information; 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?

For a read-only time-series tool, the description supplies scope, start date, and a data-consistency caveat, which is enough to call it correctly even without an output schema. Return format details are the only thing not covered.

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 schema already documents all four parameters with defaults and enums. The description implies the builder and time dimensions but adds no syntax or format 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 specific verb (daily count) and resource (active/new traders per builder), plus the scope (all builders and per builder) and start date. It clearly distinguishes itself from flowscan_builders_leaderboard without the agent needing to open either 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?

Explicitly says to prefer this for daily active/new trader time series and names the alternative (flowscan_builders_leaderboard) for windowed totals. Both the when-to-use and the routing condition are stated directly.

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 and closed-world semantics, and the description adds genuinely useful behavior: the mainnet-only rule, output-shaping conventions, and the servedByThisServer=false flag when only notServed items match. It stops short of return-format or rate-limit detail, but the added context is well beyond the annotation baseline.

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 imperative 'Start here when unsure' is front-loaded, and each subsequent clause adds distinct information. It is dense but every sentence earns its place; a slight run-on in the notServed/servedByThisServer clause keeps it from being a model of tightness.

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 explaining returns, and it does so by detailing the page->tool mapping, the notServed list, and the servedByThisServer flag. Combined with the mainnet-only rule, this is complete for an agent to use it correctly, though pagination/size behavior is unspecified.

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 the baseline is 3, but the description goes further by showing example keywords ('revenue', 'address', 'hip-3') and explaining the filter's dual behavior (matching pages plus matching notServed items), which the schema 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?

The description states a precise role: a coverage map from flowscan.xyz pages to tools, plus what is NOT served. It is clearly distinguishable from the 40+ data-retrieval siblings because it is the router/discovery entry point, not a data 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?

'Start here when unsure' gives an explicit when-to-use condition, and enumerating what Flowscan does NOT serve (block/tx lookups, prices) provides when-not guidance that steers the agent away from futile calls. This is exactly the routing guidance a discovery tool needs.

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 adds real behavioral context beyond that: it discloses the two distinct operating modes (bare list of ~240 symbols vs. single-symbol lookup returning Binance row, daily OI/volume history, and per-DEX HIP-3 side), which materially changes what an agent gets back. It omits pagination/limit behavior, but that is minor against the annotation coverage.

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 list-mode scope before the symbol-mode behavior. It is information-rich with no filler, though the first sentence is heavily packed with parenthetical enumerations that slightly slow parsing.

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 7 optional parameters and no output schema, the description does the important work of describing both result shapes and the asset universe. It leaves the paging/sorting/filter parameters entirely to the schema, which is acceptable given their full descriptions, but a brief note on default paging behavior would have closed the remaining 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%, so the baseline is 3. The description goes beyond the schema by explaining the semantic effect of `symbol` (Binance row + daily Binance OI/volume history + per-DEX HIP-3 metrics) and by characterizing the symbol universe the list mode covers, which the schema 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?

The description names a specific resource (HIP-3 real-world-asset markets compared against Binance USDT-M futures) and enumerates the payload (Binance symbol mapping, OI in USD, 24h volume, last price). It also distinguishes itself from the other HIP-3 siblings by scoping the tool to the Binance comparison, so an agent can tell it apart from flowscan_hip3_markets or flowscan_hip3_overview 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 closing sentence 'Prefer this when comparing HIP-3 with Binance' gives an explicit selection condition. It does not name the alternative tools (e.g. flowscan_hip3_markets) or state when NOT to use this one, so it falls short of full when/when-not/alternatives 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 safety is covered. The description adds scope context ('HIP-3 volume only', ranking window, 800+ rows, per-DEX toggle) but says nothing about rate limits, refresh cadence, or error behavior beyond what structured fields 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?

Two sentences, front-loaded with the data scope and closing with the sibling routing hint. It is dense but every clause carries information, with 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?

With no output schema, the description carries the burden of describing returns, and it does so: builder shares, per-DEX breakdown with top builders, and the ranked builder fields. This is adequate for a read-only metrics tool, though pagination/return-shape nuances are left 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 description coverage is 100%, so the schema already documents all seven parameters, establishing a baseline of 3. The description hints at `dex` (rank by one DEX) and `window` (all-time/30d/90d), which largely restates schema content rather than extending 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 states a specific resource and scope: builder-code routed share of HIP-3 volume, per-DEX builder volume, and a ranked list of 800+ builders. It distinguishes the tool from flowscan_builders_leaderboard by explicitly scoping itself to 'HIP-3 volume only'. The lack of a crisp leading verb keeps it just short of a clean 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 names an alternative and its selecting condition ('For revenue/users across Hyperliquid use flowscan_builders_leaderboard') and clarifies what `dex` does. It gives clear context but stops at one alternative, without covering when-not to use relative to other builders_* siblings.

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 description adds substantial behavioral detail beyond the readOnly/openWorld annotations: it discloses the return shape (dated rows by DEX, or positional for raw=true), the default day window, and the lastDayPartial accumulation flag. It still doesn't mention pagination limits or auth requirements, but the annotations already cover the safety profile.

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 tool's purpose and output shape in a compact sentence, then batches parameter notes efficiently. Slightly dense parentheticals cost a point 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?

For a read-only chart tool with no output schema, the description covers purpose, output format, default behavior, the partial-day flag, and all parameters. It is complete enough for correct invocation; only explicit sibling/alternative routing 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%, so the schema already documents all five parameters, including the enum and format examples. The description adds only marginal clarification (dex accepts display name or on-chain prefix, metric enum values, days default). Baseline 3 is correct when the schema does the heavy lifting.

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: 'HIP-3 page charts: daily values per DEX'. It enumerates the exact metrics (volume, trades, traders, new_users, oi, oi_by_market, collateral_traders, collateral_oi), which distinguishes it from the broader daily/overview siblings. An agent can tell at a glance this is the HIP-3 daily time-series 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?

Usage is primarily implied through the metric enumeration and the 'last N days' behavior, but there is no explicit when-to-use vs when-not-to-use guidance, nor mention of which sibling to choose for different HIP-3 needs. It is adequate but leaves routing to the agent.

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 (readOnlyHint, openWorldHint), so the description is free to add data semantics: today's daily row is flagged partial, market OI is two-sided and volume-sorted, and includeMarketDaily is large/off by default. Those are real behavioral traits an agent needs to interpret results correctly, though nothing is said about 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?

Three sentences, front-loaded with the returned payload, then the parameter hint, then the routing preference. No filler; the densest information (what you get back) comes first.

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 describing the return shape, and it does so concretely (totals, market list, daily rows) for a 7-parameter tool. Minor gaps remain: ordering/pagination behavior for the market list and what happens when `dex` matches nothing are unspecified.

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 carries a description, so the schema does the heavy lifting. The description only restates the `dex` alias mapping and the 'last N days' framing of `days`, adding no format or constraint detail beyond the schema. 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?

The description enumerates the exact payload: collateral, total volume/trades/traders/OI, per-market all-time volume and two-sided OI, plus dated daily-total rows. It carves out a scope ('one DEX') that distinguishes it from the aggregate hip3_overview/hip3_markets siblings, though it never names those siblings 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?

'Prefer this for one DEX's market list' states a clear selection condition and implies a multi-DEX alternative exists, which is useful routing guidance. It stops short of naming the alternative tool or stating when-not to use it (e.g. when comparing DEXes).

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 establish readOnlyHint and openWorldHint, so the safety bar is low. The description adds substantive behavioral detail the annotations cannot convey: what each branch returns (market table columns vs per-DEX OI/DAU/volume/spread/slippage plus trimmed history), and how `days` bounds comparison history. It omits pagination/rate-limit behavior, so not 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?

Three dense sentences, front-loaded with the resource then the mode split then the routing hint; the parenthetical field lists are information-dense rather than padding. Slightly packed, but essentially every clause carries signal.

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 properly compensates by enumerating the returned fields for both modes. Combined with the 100%-covered schema and safety annotations, an agent has enough to call it correctly; only edge details (empty-result handling, pagination interplay with limit/offset) are left implicit.

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 goes beyond it: it gives concrete `symbol` examples ('TSLA', 'GOLD'), explains that the value is a canonical underlying, and clarifies the mode-switching semantics of `symbol` plus the trimming role of `days`. The dex/assetClass/search filters are mentioned as available filters.

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 (HIP-3 market tables) and immediately splits into two explicitly-scoped modes based on `symbol` absence/presence, naming the exact columns returned in each. An agent can distinguish it from flowscan_hip3_dex, flowscan_hip4_markets, and flowscan_perp_markets without inspecting any 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?

Explicitly routes the agent: 'Prefer this to compare one underlying across HIP-3 DEXs', and names flowscan_perp_markets ('xyz:TSLA') for live positioning and flowscan_hip3_binance_comparison for Binance data. This is a textbook when-to-use-this-vs-alternatives statement.

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 data-shape semantics ('OI is two-sided (long + short)') and the dexAliases mapping, but says nothing about pagination, freshness, rate limits, or auth needs. With annotations carrying the safety profile, this is an adequate but not rich behavioral disclosure.

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 dense sentence followed by two short clarifiers, with the headline purpose front-loaded and the routing hint at the end. Efficient, though the parenthetical enumeration is long.

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 carries the burden of explaining returns, and it does so thoroughly by listing every field group returned. What remains missing is any behavioral or timing context, but for a read-only aggregate endpoint this is close to 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 100% for the single `fields` parameter, so the schema fully documents projection paths and the _fieldsNotFound behavior. The description never mentions the fields parameter, so baseline 3 is appropriate when the schema does the work.

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 resource and enumerates exactly what the overview contains (all-time/30d/90d volume, trades, traders, OI, per-DEX and per-collateral market share, builder-routed share, dexAliases). It signals scope ('DEX-level totals and share') but does not name a sibling tool to contrast against, so it stops short of full differentiation.

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 line 'Prefer this for DEX-level totals and share' gives a clear selection condition against the per-market/per-day siblings. It does not, however, name an alternative tool or state when not to use it, so routing is implied 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 declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds value by disclosing the return shape ({labels: {assetId: label}}), which is important because no output schema exists. It does not mention the 100-item cap or error behavior, but that is minor.

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 single sentence giving purpose and examples, followed by the return shape in one clause. No filler; every part earns its place.

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

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

For a simple one-parameter lookup with no output schema, the description supplies the input semantics, output shape, and a reference point for usage — everything an agent needs 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 100%, so the baseline is 3, but the description adds meaning about id semantics — that ids like '#14730'/'#14731' encode YES/NO outcomes — which goes beyond the schema's bare format examples.

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 ('resolve') and resource (HIP-4 outcome asset ids -> readable labels) with concrete input/output examples ('#14730' (YES) -> 'Arsenal · Yes'). An agent can clearly distinguish it from siblings like flowscan_hip4_markets or flowscan_hip4_outcome.

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 (mapping ids to human labels, mirroring the address page's treatment of HIP-4 spot balances) but gives no explicit when/when-not guidance or alternatives. No routing away from sibling tools is provided.

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), so the bar is lower, and the description adds real behavioral context: it discloses the slim-row field set, the default sort (volume24h desc), the meaning of yesMark/noMark as implied probability, and that full=true returns descriptions. It omits any pagination or rate-limit caveat, keeping it from 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?

The page and its sections are front-loaded, and every clause carries information (section semantics, defaults, sibling pointer). It is dense and parenthetical, though, reading as one long run-on rather than cleanly separated points, which costs it a point.

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 an 11-parameter tool with no output schema, the description compensates well by enumerating the returned row fields and explaining defaults and section behavior. It is nearly complete, missing only explicit mention of limit/offset paging interaction and category filtering semantics.

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 a 3 is the baseline, but the description adds genuine meaning beyond the schema: section semantics, the sortBy default, the yesMark implied-probability interpretation, and settledLimit behavior. The fields/search parameters are left to the schema, which already documents them adequately.

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 ('HIP-4 prediction markets' with an enumerated set of sections) and explicitly routes the candle use-case to the sibling flowscan_hip4_outcome. An agent can distinguish it from flowscan_hip3_markets and flowscan_hip4_outcome without opening any 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?

Gives clear context for each section ('active' default, 'settled' with settleFraction, 'questions', 'all') and names the alternative tool for candles. It does not, however, state exclusions or contrast itself against the other market-listing siblings (hip3_markets, perp_markets), so it stops 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 declare readOnly/openWorld, so the bar is lower, and the description adds real behavioral context beyond them: the compact candle row layout, per-side trade stats, the settled-record branch, and the caveat that settled outcomes usually return no candles. It does not mention pagination or rate limits, keeping it at 4.

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 payload description is front-loaded followed by the settled caveat and the id-sourcing note; three sentences, each carrying weight. Slightly dense with parenthetical asides, 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?

With no output schema, the description carries the return-value burden and does it: it defines the row shape, the trade stats, and the settled record, plus defaults and the settled-mode caveat. An agent has everything needed to call it and interpret the result.

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 schema already documents every parameter and the baseline is 3. The description reinforces the YES/NO meaning of asset ids and the settled branch, but that mapping is largely already present in the schema descriptions, so it adds only marginal value.

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 (drill-down of one HIP-4 outcome into YES/NO candles) and enumerates the payload: candles, per-side trade stats, and the settled record. It explicitly names flowscan_hip4_markets as the source of outcomeId, so an agent can distinguish it from that sibling 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?

Gives clear usage context: only outcomeId is required, asset ids default, and settled outcomes 'typically have no candles' with settled=true. It routes the agent to flowscan_hip4_markets for the required id. It stops short of explicit when-not guidance (e.g., when to prefer a market-level tool), so a 4 rather than 5.

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), lowering the bar, but the description adds real context: crawl size (~600 nodes), the default response shape, and that nodes/edges/all are paged. It does not mention rate limits or auth, but for a read-only crawl this is solid disclosure.

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 front-loaded with the resource and information-dense with little filler. The parenthetical packing makes it slightly run-on, but every clause carries usable detail.

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 reasonably by describing the default sections and node fields. Given 9 optional params and open-world data, an agent has enough to call it, though pagination mechanics remain unspecified.

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 baseline is 3, but the description adds meaning beyond the schema by documenting what the section values yield (nodes default 50; all = nodes 30, edges 100) and listing the node fields (IP id, role, operator, state, tier, hops, parent, feeders, geo, ASN), helping the agent choose filters.

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 specific resource (the /peers gossip-network crawl, ~600 nodes) so an agent immediately knows it returns peer/network topology rather than address or revenue data. It is clear but does not explicitly contrast against siblings, which is fine since no sibling overlaps this domain.

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 explains the default output (meta, footprint, sentries) and that nodes/edges/all are paged, which guides section selection. However, it gives no when-to-use vs when-not-to-use guidance or explicit alternatives, leaving usage 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=true and openWorldHint=true, so safety is covered; the description adds genuinely non-obvious context the annotations cannot carry: a refresh cadence ('every few minutes'), snapshotIso/snapshotAgeSeconds freshness fields, and the crucial definition that openInterest is two-sided (2x the one-sided figure some UIs show). It does not mention auth requirements or rate limits, which keeps it 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?

Three sentences, front-loaded with what the tool returns; the OI-definition caveat and the sibling routing sentence each earn their place. Slightly dense in the first sentence's field enumeration, but no wasted text.

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 carries the return-value burden and does so by naming the key fields (long/short counts and notional, ratios, OI, avg entry, median leverage, unique addresses, snapshot timestamps). Combined with the routing guidance and the OI semantics note, an agent has everything needed to call and interpret this 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 description coverage is 100% (limit, fields, market, offset, sortBy all documented with defaults like 'openInterest desc'), so the baseline is 3. The description hints at the market-filter use case via the HIP-3 symbol example but adds no syntax or format detail 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?

States a specific verb and resource ('Homepage perp snapshot for every perp market') and quantifies scope (~330 markets, including HIP-3 symbols like 'xyz:TSLA'). It explicitly distinguishes itself from siblings flowscan_perp_positions and the hip3_* tools, so an agent can select it without opening any 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?

Gives an explicit preference rule ('Prefer this for live OI/positioning') and names the alternatives with their distinct domains: hip3_markets/hip3_dex for HIP-3 history, hip3_binance_comparison for the Binance side. Both when-to-use and when-to-look-elsewhere are covered.

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 and openWorldHint, so the description usefully adds that the snapshot carries snapshotIso/snapshotAgeSeconds, that marketSummary is whole-market and unfiltered with OI = long + short notional, and that filteredSideSummary covers only the filtered rows. This is real disclosure of return semantics; it stops short of stating permissions, rate limits, or pagination/refresh 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?

A single dense, front-loaded sentence that leads with what the tool is ('Perp snapshot drill-down') before enumerating return fields and summary semantics. It is a long run-on, but every clause carries information and nothing is padded.

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 18 parameters, no output schema, and only readOnly/openWorld annotations, the description does the heavy lifting: it enumerates returned fields, explains both summary blocks and the OI definition, and covers market resolution. Pagination and sort defaults are left to the schema, which is acceptable, but a note on output size or refresh cadence would round it out.

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 the baseline is 3, but the description adds genuine semantics the schema lacks: market matching is case-insensitive and a bare 'TSLA' resolves to 'xyz:TSLA' when unique, plus the meaning of the `filter` scope in filteredSideSummary. That resolves the practical ambiguity around the one required parameter.

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 resource and scope: 'open positions in one market, largest first', framed as a 'perp snapshot drill-down'. That is enough for an agent to know exactly what it returns, though it never names the adjacent siblings (flowscan_perp_markets, flowscan_address_perp_positions) to make the market-scoped vs address-scoped distinction 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?

Usage is implied by 'drill-down' and 'one market', suggesting it follows a market-level tool, but there is no explicit when-to-use, when-not, or named alternative. An agent must infer that this is the per-market position list and not the per-address list.

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 behavioral context: rows are oldest first, values are USDC, default window is 90 complete UTC days ending yesterday, and includeToday appends a partial row. The note that these fees go to deployers and are excluded from headline protocol revenue is useful disambiguation.

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?

Dense but front-loaded: the endpoint path and core return shape come first, then defaults, units, and the revenue-scoping caveat. Every clause carries information, though the enumeration of all ten on-chain DEX names is somewhat list-heavy.

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 does the work of explaining the return shape (totalFee, byDex entries, rangeTotals overall and per DEX), units, and ordering. Combined with a fully documented input schema and read-only annotations, an agent has enough to call it correctly; only filtering/pagination behavior is left implicit.

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 schema already documents all ten parameters. The description only reinforces `days` (default 90, complete UTC days ending yesterday) and `includeToday` (today's partial row) plus DEX naming; it says nothing about limit, offset, fields, or the start/end time variants. Baseline 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?

States a specific verb+resource (HIP-3 deployer fees per UTC day) and even names the field set returned (totalFee, byDex, rangeTotals). This clearly differentiates it from sibling revenue tools like flowscan_revenue_hypercore_fees or flowscan_revenue_summary.

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 by the topic (deployer fees, not headline protocol revenue), but there is no explicit when-to-use guidance or naming of the alternative revenue tools the agent should pick instead. The closing clause hints at scoping but does not route to a sibling.

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 and openWorldHint, so the description carries real weight and delivers: rows are per UTC day oldest-first, fees are USDC strings, rangeTotals is included, the `days` window ends yesterday rather than today, includeToday yields a partial:true row, and history begins 2026-03. That is rich, non-obvious behavioral 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 resource identity and return shape before the parameter mechanics, and every sentence carries information. It is information-dense to the point of near-cramped phrasing (multiple parentheticals), which slightly reduces readability but wastes nothing.

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 naming the returned fields and their types, the row ordering, and the totals object. Combined with the time-window semantics and history start date, an agent has everything needed to call and interpret this 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 100%, so the 3 baseline applies, but the description exceeds it by giving the semantic edge cases: `days` counts COMPLETE UTC days ending yesterday, includeToday appends a partial current-day row, and time ranges may be passed as ms epoch via startTime/endTime. These interpretations are not derivable from the schema alone.

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 (daily fee revenue) and precisely what each row contains: nativeHypercoreFee for non-HIP-3 markets and hip3HypercoreFee for HIP-3 markets, plus rangeTotals. This cleanly distinguishes it from sibling revenue tools like revenue_priority_gas and revenue_deployer_fees, which it doesn't overlap with.

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?

Explains the two selection modes concretely: `days` for the last N complete UTC days, or explicit startDate/endDate / startTime/endTime. It also anchors expected behavior by naming revenue_summary and the builder tools. However it stops short of an explicit when-to-use-this-vs-those rule or a when-not condition.

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 declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: rows end yesterday by default, includeToday appends a partial row, and includeTopUsers adds per-day top-5 lists (schema notes it defaults false to keep output small). No rate-limit or pagination disclosure, but the temporal/optional-output behavior is well conveyed.

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 output content is front-loaded and the description is dense without obvious filler. It is a single long sentence with several nested clauses, which slightly taxes readability 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?

With no output schema, the description compensates by naming the return shape (totalGas in HYPE, count, top-5 payers, rangeTotals). Combined with full schema coverage of the 10 parameters, an agent has enough to call it correctly; a brief note on pagination via limit/offset would round it out.

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 all 10 parameters are already documented in the schema. The description restates the days default and the includeToday semantics, adding only marginal meaning beyond what the schema provides. Baseline 3 is appropriate when the schema does the heavy lifting.

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 resource ('Daily Priority Gas'/'Top Users') and enumerates the returned metrics (writePriority/readPriority totalGas in HYPE, count, top 5 payers, rangeTotals). It is clearly scoped to priority-gas revenue, but it does not explicitly distinguish itself from sibling revenue tools like flowscan_revenue_summary or flowscan_revenue_hypercore_fees.

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 states the temporal default (last 90 complete UTC days ending yesterday) and the effect of includeToday and includeTopUsers, which implies when to toggle them. However, it gives no explicit guidance on when to pick this tool over the other revenue siblings, leaving 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 and openWorldHint, and the description adds real behavioral context beyond them: the exact time windows (last 1/7/30 complete UTC days), the separate current partial day, the trailing-7-day annualized run-rate, and a clarifying note that deployer fees are paid to deployers, not protocol revenue. It also discloses the underlying data source (three /api/gossip/info series), which helps an agent trust staleness/coverage.

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 dense sentence that front-loads the purpose and the source, with no promotional filler. It is somewhat long and packed, but every clause (metrics, windows, partial day, run-rate, source) 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?

With no output schema, the description does most of the work by enumerating the metrics and windows returned, giving an agent a good picture of the response. The only gap is the projection/fields mechanism, which the schema already covers, so the definition is largely complete for a read-only aggregate.

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 single `fields` parameter and its _fieldsNotFound behavior are already documented in the schema. The description adds no parameter-level guidance, 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 description states a specific verb (convenience aggregate) and resource scope (native HyperCore fees, HIP-3 HyperCore fees, deployer fees, priority gas over 1/7/30 days), and positions itself as the aggregate of the three component series that appear as siblings. It distinguishes itself functionally from the individual flowscan_revenue_* tools, though it does not name those siblings 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?

Calling it a 'convenience aggregate' implies you use this when you want a combined overview rather than the individual fee series, but the description never states when to prefer this over flowscan_revenue_hypercore_fees / _deployer_fees / _priority_gas, nor any exclusions or prerequisites. Usage 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?

readOnlyHint=true already establishes this as a safe read; the description adds useful context by enumerating what each section returns (volume, holders, liquidity depth, top holders). It stops short of disclosing pagination, rate limits, or auth requirements, so with annotations carrying the safety profile this is only modest 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?

Front-loads the resource and its section semantics; every sentence contributes. The long token enumeration is informative but slightly inflates the opening sentence.

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 read-only, no-output-schema tool with a fully documented schema, the description covers the resource, its tokens, and all four section behaviors adequately. Missing only return-format/pagination detail, which is minor here.

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 the schema documents all six parameters. The description goes beyond it by explaining what each section value means and how days applies to timeseries vs liquidity, adding genuine semantic value over the raw enum.

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 (tokenized stocks on Hyperliquid spot) with concrete token examples and the four data views it serves. An agent can distinguish it from the perp/staking/revenue siblings, though the '/spot-stocks page' framing is slightly URL-flavored rather than task-oriented.

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 section descriptions imply how each mode is used (current for summary, timeseries for daily metrics, etc.), but there is no explicit when-to-use/when-not or named alternative. Usage is left to inference from the section list.

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, and the description adds no behavioral context beyond that — no note on freshness, snapshot vs. time-series, auth needs, or how the HyperCore aggregation is scoped. With annotations covering the safety profile the bar is lower, but this adds essentially nothing behavioral.

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 one dense, front-loaded fragment that crams parentheticals ('with unique holders/traders') and a trailing unit token ('USD.'), which reads awkwardly and buries the unit at the end. No wasted sentences, but structure is list-like rather than explanatory.

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 describing returns, and it does so reasonably: it enumerates the breakdown (total vs. per-token), the metrics (holders, average/median, market share), and the unit (USD). Only gaps are the absence of any usage context and of temporal granularity.

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 optional 'fields' parameter, so the schema does the work. The description says nothing about path syntax or the _fieldsNotFound fallback, 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?

The description names a specific resource (stablecoin value on HyperCore split into spot balances and perp margin) and enumerates the dimensions returned (per-token balances, holders, average/median, market share). It is clear what the tool retrieves, though it never explicitly differentiates itself from sibling tools like flowscan_perp_positions or flowscan_address_summary.

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 versus alternatives, no prerequisites, and no exclusions. The words 'Homepage' imply a dashboard role but do not route the agent to or away from any sibling.

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 (readOnlyHint, openWorldHint), so the description's added value is real: it discloses ordering (newest first), the return fields, and a valuable data caveat that the upstream `currency` field reads 'USDC' but staking amounts are actually HYPE. That caveat would otherwise cause misinterpretation of results.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the core purpose and ordering before the currency caveat. Dense but every clause (fields returned, ordering, currency trap) earns its place; the field enumeration is slightly listy but useful given no output schema.

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 steps in to enumerate the returned fields (user, amount in HYPE, isUndelegate, tx hash, time ms + ISO), which is exactly what an agent needs. It also flags the currency mislabeling. Minor gap: no pagination/limit behavior beyond what the schema states.

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 schema already documents limit, fields, and validator. The description only restates that `validator` accepts an address or name, adding nothing beyond the schema; baseline 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?

States a specific verb-and-resource pairing: most recent delegation/undelegation events for one validator, with explicit ordering (newest first). It implicitly separates itself from sibling flowscan_validator_stakers and flowscan_staking_overview by scoping to events rather than stakers or aggregate stats, though it never names those siblings outright.

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 framing 'Staking page validator activity' implies the context in which the tool applies, but there is no explicit when-to-use, when-not-to-use, or named alternative. An agent must infer that this is for per-validator event history versus the staker-list or overview siblings.

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 establish readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuine context beyond that: the scale (~35 validators) and the conditional behavior that descriptions are returned only when includeDescription is set, which tells the agent how output volume varies.

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 resource and its return fields, then filters, then a single illustrative example; every clause carries information. It is a long, dense sentence, but nothing is redundant with the schema beyond brief field naming.

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, and the description compensates by enumerating both the page-level aggregates and the per-validator record shape. Combined with the filtering/sorting guidance and the schema's 100% parameter coverage, an agent has everything needed 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?

With 100% schema description coverage the baseline is 3, and the description goes further by tying parameters to intent: search filters by name/address, excludeJailed drops jailed validators, and the worked example combines sortBy, order and excludeJailed into a real query. It leaves limit/offset/fields unmentioned, but those are well covered by 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?

It names the exact resource ('The /validators (Staking) page') and enumerates the concrete aggregates and per-validator fields returned (total HYPE staked, delegator count, commission bps, jailed flag), which lets an agent distinguish it from staking_events and validator_stakers 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?

It supplies a concrete usage scenario ('sortBy=commission_bps, order=asc, excludeJailed=true finds the cheapest active validator') and describes the available filtering/sorting operations, giving clear context for when this tool applies. It stops short of explicitly naming alternatives such as flowscan_validator_stakers, so no exclusions are 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?

The annotations already declare readOnlyHint and openWorldHint, and the description adds genuinely new behavior: results are returned 'largest first', the staker row shape is {address, amount HYPE}, and large validators can have thousands of stakers. This ordering, result-shape and scale information is 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?

Two dense sentences, front-loaded with the drill-down purpose and return shape before the pagination advice. Every clause carries information, though the field enumeration is slightly list-heavy.

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 most of it: summary fields, staker row format, ordering, and pagination strategy. The only gap is the concrete default for `limit` ('default per tool' is left opaque).

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 adds meaning: `validator` accepts an address OR a name, with a concrete example ('Hyper Foundation 2'), and it explains the role of search (address substring filtering) alongside limit/offset for paging.

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: a single validator's summary plus its delegator list, and enumerates the summary fields (name, commission, total delegated, staker count, jailed). The phrase 'validator drill-down' distinguishes it from flowscan_staking_overview without opening either 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 'Staking page validator drill-down' framing plus the warning that large validators have thousands of stakers, with the directive to 'use limit/offset or search', gives clear context for how to call it. It stops short of explicitly naming the sibling it supersedes (e.g. flowscan_staking_overview) or stating when-not to use 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 the safe-read (readOnlyHint) and open-world profile, and the description adds real value beyond them: newest-first ordering, symbol auto-resolution behavior, and ISO timestamp twins. It stops short of describing pagination or row limits, but the added behavioral context is substantive.

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 the core computation front-loaded, followed by scoping caveats and output notes. Dense but every sentence carries weight; 'ISO twins' is jargon but is the only slightly opaque phrasing.

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 reasonably: pct and dollar values per tracked weekend, newest first, timestamps as ISO pairs. A short note on pagination or empty-result handling would round it out, but nothing essential for 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 coverage is 100%, so baseline is 3, but the description adds meaning the schema omits: the symbol-resolution rule ('TSLA' -> 'xyz:TSLA') and which symbols are valid. The `fields` parameter is covered by its own schema description rather than by the prose.

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?

Names a specific verb+resource+computation: one HIP-3 TradFi market's Friday-close -> Sunday-close move (pct and dollar) across every tracked weekend. This distinguishes it from siblings like flowscan_weekend_weeks (all markets) and flowscan_weekend_prices (price series), so an agent can route without opening schemas.

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?

Clearly states applicability constraints: only DEX-prefixed TradFi markets have data, bare symbols are auto-resolved ('TSLA' -> 'xyz:TSLA'), and crypto like 'BTC' yields nothing. Strong when-to-use context, but it never names an alternative sibling tool to use instead for crypto or non-weekend data.

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 safe-read profile is covered. The description usefully adds the data scope (long/short counts and notional at two timestamps, new/closed positions, optional top-5 address changes), but says nothing about auth needs, latency, or pagination.

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 dense sentence that front-loads the panel scope and enumerates what it returns. It is information-rich and mostly earns its place, though it reads as a run-on that could be split for 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?

With no output schema, the description carries the return-value burden and does so by enumerating the fields returned per market, including the optional top address changes. Missing only default/pagination behavior, which the schema already covers.

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 schema already documents all 7 parameters with types and defaults. The description only hints at includeTopAddressChanges ('optionally the top 5 address-level position changes per market'), which is marginal added meaning over 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/resource: a 'positioning panel' showing long/short counts and notional per perp market between Friday close and the latest snapshot. The scope (~330 markets, crypto and HIP-3 TradFi) is concrete. It does not explicitly name the sibling weekend tools it differs 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?

There is no when-to-use/when-not guidance and no reference to alternatives such as flowscan_weekend_prices or flowscan_weekend_coin_changes. The agent must infer from the name alone that this tool is for positioning rather than price/coin changes.

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 and openWorldHint, so the description carrying the stateful behavior adds real value: which price columns exist depends on whether a weekend is active or finished. It also discloses the weekendChanges {pct, dollar} shape and the presence of status/price counts, which the annotations do not cover.

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 dense sentence, but it front-loads the resource and then enumerates fields, so a reader gets the core identity immediately. No filler or repetition; the long parenthetical list is the only cost to 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?

With no output schema, the description usefully enumerates the returned rows and fields, and annotations already cover the read-only/open-world safety profile. Given only three well-documented optional params, an agent has enough to call it correctly; the missing piece is guidance on when to choose it over siblings.

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 week/fields/market semantics are already documented (fridayCloseTs or YYYY-MM-DD, path filtering with _fieldsNotFound, substring market match). The description adds no further parameter guidance beyond schema baseline, so 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?

Names the resource precisely ('Weekend page price table' for HIP-3 TradFi perps) and enumerates the specific data columns returned: Friday-close, Sunday-close, live current, weekendChanges, status, counts. It is clearly distinguishable from flowscan_weekend_weeks or flowscan_weekend_positions, though the opening phrase 'Weekend page price table' is slightly jargon-y rather than a clean verb.

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 statement, no prerequisite, and no alternative named. The temporal conditions ('once the weekend is over', 'during an active weekend') describe data availability rather than telling an agent when to pick this tool over sibling weekend tools.

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 adds real behavioral context beyond that: results are sorted 'newest first' and includeSchedule expands the payload with ~12 upcoming weekend/holiday sessions. It says nothing about pagination behavior or return size, which the limit/offset params imply exist.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the resource and selector role, then the optional schedule behavior. The parenthetical field list is dense but packs genuine information; very little waste overall.

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 no nested objects, the description usefully compensates by enumerating the returned fields and status signals, and it explains the one non-obvious param (includeSchedule). Only pagination/ordering volume limits from limit/offset remain unaddressed, so it is close to complete for a read-only list 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%, so limit/offset/fields are already documented and baseline is 3. The description clarifies includeSchedule's effect ('adds the next ~12 weekend/holiday sessions'), a modest addition beyond the schema's terse 'Also return the upcoming session schedule', but it does not touch the other three params.

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?

Names a specific resource (tracked weekends) with a detailed enumeration of the columns returned (fridayCloseTs week id, sundayCloseTs, status, avg % change, market count), so the agent knows exactly what this list tool yields. It is distinguishable from weekend_prices/positions/coin_changes by being the week-level selector. It stops short of naming a sibling explicitly, so it does not earn 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 only implied: it is 'the /weekend-trading selector' and 'newest first', and includeSchedule is flagged as an optional addition. There is no explicit statement of when to reach for this versus flowscan_weekend_prices or the other weekend siblings, and no exclusions or prerequisites.

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