Kellian

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered and the description's job is lighter. It adds useful scope context (that this is descriptive content rather than live connection state) but says nothing about how the content is delivered or how it relates to actually opening a socket versus subscribing via webhook. It does not contradict any annotation.

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 sentence, no filler, and it front-loads the primary subject before the secondary topics. The title and description overlap almost verbatim, though, so the enumerated topics are effectively stated twice without adding new information the second time.

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

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

With an output schema present, the description needn't explain return values, and with no parameters there is little surface area to cover. What remains slightly under-specified is how the content overlaps with kellian_discover_webhooks and list_webhook_event_types, which an agent would need to pick correctly among these sibling tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters and the schema confirms an empty object, so there is nothing parameter-level to document; baseline 4 applies. The description correctly frames the tool as a parameterless topic explainer.

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 ("Describe") plus a well-defined resource (the Agent WebSocket transport) and enumerates exactly which subtopics are covered: URL, auth schemes, message shapes, reconnect/replay, and the WS-to-webhook taxonomy bridge. It is clearly distinct from data-fetching siblings like kellian_get_market or kellian_list_webhook_event_types, but it never explicitly contrasts itself with kellian_discover_webhooks, which covers adjacent territory.

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: "webhooks as the async fallback" hints at the retrieval-vs-fallback distinction, but there is no explicit "use this when you need transport details, use kellian_discover_webhooks when you need subscription setup" routing. No prerequisites or exclusions are stated, so the agent must infer the boundary against three or four discover/list 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 declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds genuinely useful context beyond that: it clarifies this returns descriptive lane information rather than live data, and that quote/order-book tool calls remain authoritative for execution — a distinction an agent could otherwise get wrong.

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 the scope list (query params, channel catalog, message shapes, SSE, control-plane) tells the agent what the output will cover. The parenthetical enumeration is dense but each item is informative rather than padding.

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 zero parameters, full annotation coverage, and an output schema that carries the return structure, the description needs only to establish purpose and scope — which it does. The one remaining gap is that it does not route the agent relative to the other discover_* tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the baseline is 4; there is no argument surface the description needs to explain. Nothing in the description misleads about inputs.

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: 'Describe the canonical market-data lanes' and enumerates the lanes covered (public WebSocket, REST snapshot/quote/orderbook, consumer SSE, control-plane WebSocket). It also distinguishes itself from the data-fetching siblings by noting that quote/order-book tool calls remain the execution-authoritative path, so an agent can tell this is documentation rather than a data call.

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 'this describes the realtime/display lanes alongside them' implies the tool is for orientation before/alongside real data calls, but it never says explicitly when to call it versus kellian_discover_events, kellian_discover_webhooks, or kellian_list_capabilities. No when-not conditions or prerequisites are given, leaving routing 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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered. The description adds that the result is a catalog with schemas and examples, but says nothing about size, pagination, or stability of the renderer list; with an output schema present, this is an adequate but not rich 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?

Two sentences, zero waste, and the primary purpose is front-loaded before the routing hint. Every clause earns its place.

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

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

An output schema exists, so return values need no prose explanation, and the description covers what the tool yields plus where to go next. The only missing piece is any hint about catalog scale or freshness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies and nothing in the text contradicts or muddies the empty 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: 'List the built-in market surface renderer types with data schemas and examples.' That clearly separates it from the get_* market data siblings, though it doesn't explicitly contrast itself with the other kellian_discover_* catalog 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?

Routes the agent onward by naming alternatives and their audiences: beginners to `kellian_publish_market_surface`, advanced users to the raw `kellian_push_content` envelope path. It gives clear context for the workflow but doesn't state exclusions or when *not* to call the catalog at all.

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, idempotent, openWorld and non-destructive, so safety is covered. The description's one added fact — there is no closed enum, so `type` values are agent-invented — is genuinely useful and non-obvious behavioral context, but it stops there, with no guidance on validation, naming collisions, or how invented types are interpreted downstream.

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 short sentences, front-loaded with the resource and immediately followed by the single caveat that matters. Nothing is padded or repeated from the name.

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 zero params, a present output schema, and full annotation coverage, the description supplies the one thing structured fields cannot: that `type` is open rather than enum-bound. Only a pointer to sibling discover_* tools for adjacent catalog needs 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 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 (describe) and specific resource (the `resolutionSource` envelope shape plus the conventions agents use), which is more precise than a generic catalog listing. It doesn't explicitly contrast itself with the other discover_* siblings, but the resource is named concretely enough that an agent knows what it returns.

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 note that agents invent their own `type` values suggests this should be consulted before constructing a resolutionSource, and the 'discover' prefix implies a pre-flight lookup. There is no explicit when-to-use/when-not statement nor a named alternative for related questions.

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

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

Annotations already establish that this is a read-only, idempotent, non-destructive operation, so the safety profile is covered. The description adds the meaningful behavioral fact that this returns static specification content (a scheme and handshake) rather than live per-endpoint state, which is what an agent needs to decide whether to call it.

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 sentence, front-loaded with the verb and resource, with the enumerated contents and the caller benefit packed into the same clause. Nothing is padded and nothing is redundant with the title.

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

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

An output schema exists, so return values need not be explained, and annotations cover the safety profile. For a zero-parameter documentation tool the description is essentially complete, though it could note whether the content is static/versioned spec text versus server-specific configuration, which would matter to a caller implementing verification.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, which is the baseline-4 case per the rubric. The empty schema and the description's framing agree that no input is required, and no parameter semantics are needed.

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 verb ("Describe") and a precise resource (the Standard Webhooks signing scheme), then enumerates the exact contents: headers, HMAC-SHA256 algorithm, envelope shape, replay tolerance, and the url_verification handshake. It is unmistakably distinct from sibling tools like kellian_discover_events or kellian_list_webhook_event_types, which enumerate events rather than explain signing.

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 phrase "so a receiver can verify deliveries without reading source" gives a clear use context — implement or validate a webhook receiver. It stops short of explicit routing guidance (e.g., "call this before registering an endpoint; use list_webhook_event_types to choose subscriptions"), so no true exclusions or alternatives 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?

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely new behavior: where each balance comes from (a committed collateral is a venue ledger balance published to Base in batches, an onchain collateral is ERC-20 balanceOf), which tells the agent about freshness and provenance of the numbers.

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 purpose and default behavior, then the provenance model, then the unit note. Every sentence carries information; only the slight overlap between the description's include explanation and the schema's enum description is redundant.

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

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

With an output schema present, the description needn't document the response shape, yet it still explains the raw-integer/decimals convention, which is the detail most likely to cause misuse. Given three simple parameters and full annotation coverage, little an agent needs is missing beyond sibling differentiation.

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 walletAddress, chainId, and the include enum, giving a baseline of 3. The description's only contribution is restating the include semantics and explaining the returned units; it adds nothing for chainId beyond what the schema already says.

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 ('Get collateral balances for a wallet') with a clear default scope plus the include="all" variant. It never names or contrasts a sibling such as kellian_list_collateral or kellian_get_positions, so an agent must infer the boundary between 'collateral balances' and 'positions' or 'supported collateral list'.

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 through the include="default|all" distinction and the note that chainId is optional only when one chain is active, which is helpful context for calling it. There is no explicit when-to-use versus when-not, and no routing to alternatives like kellian_list_collateral, so the agent is left 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?

Beyond the read-only annotations, the description discloses access-tier behavior: without a key or on a free account it returns a limited Free preview of 5 markets, only the analysts' average, and 1 headline, with meta indicating what was withheld. It also explains that Pro accounts include named top traders with side, shares, tier, entry price, and last move.

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 and dense, with the key 'one call per market' summary first. It is somewhat run-on due to the long parenthetical field list, but every part communicates useful scope or access behavior, and the disclaimer is brief.

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

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

Given the output schema, rich annotations, and 100% schema coverage, the description supplies enough context to call the tool correctly. It covers returned data groups, filtering modes, pagination, and free-tier truncation behavior.

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 each parameter is already documented. The description adds a lightweight grouping of filter options and pagination, but does not add syntax, defaults, or constraints beyond what the schema provides.

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: every market's research context in one compact record per market, listing the exact data groups returned. It distinguishes itself from single-market siblings by emphasizing 'Every market's research in one call.'

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 how to filter by segment, category, ids, or all, and how to page with a cursor, but it does not explicitly say when to use this tool instead of siblings like kellian_get_market_research or kellian_list_markets. Usage is implied rather than guided.

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/idempotent/non-destructive/openWorld, so the bar is lower, and the description adds real behavioral context: delta dedup semantics (each change comes once), windowing, and API Pro gating for top-trader moves. It omits rate limits and return-shape details, but the output schema covers the latter.

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 core delta concept and then layers the continuation rule and gating. A few trailing fragments ("Plus and API Pro. Research, not financial advice.") are minor but the whole paragraph stays tight and purposeful.

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 5-param read tool with an output schema and rich annotations, the description covers the essentials: delta semantics, continuation, and availability tiers. The remaining gap is undocumented params like `ids` and `cursor`, which neither schema nor description fully explain.

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 40% schema description coverage, the description must compensate. It reinforces the `since` parameter (set to the answer's `until`) and maps the change categories that `types` filters on, but `ids`, `cursor`, and `segment` get no mention in the description, leaving gaps the schema only partly fills.

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 — only what changed since your last call, newest first — and enumerates the change classes (headlines, analyst views, price moves, new/closing markets, top-trader moves). This clearly distinguishes it from kellian_get_context, which returns full state rather than a delta.

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 continuation protocol ("Call again with since = the answer's until") and explains that each change appears once in the window after it was recorded, which is clear context for polling. It stops short of explicitly saying when to prefer this over kellian_get_context, so no hard 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description still adds substantial context beyond that: addresses are UUPS/stable, approvals are one-time and engine-scoped, they will 'drop out' as approval-free sells ship, and a settlement-committed collateral emits no approval at all. That is meaningful lifecycle and data-stability information an agent could not get from annotations alone, though it is delivered as dense prose rather than structured caveats.

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 enormous run-on sentence with em-dash-nested parentheticals, followed by several loosely connected assertions about settlement ledgers, creator roles, and human identity. The key fact (what you get back) is front-loaded, but the remaining text is bloated and would take several reads to unpack; the final sentence about human identity services reads as tangential.

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

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

An output schema exists, so return shape need not be explained, and the description does cover the substantive semantics (which collaterals need approvals, which emit none, role/creation flags). Missing is any statement of the tool's own call behavior — e.g. what happens when chainId is omitted versus filtered — leaving the description rich in domain lore but incomplete on invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the two optional filters (chainId, collateral) are fully documented in the schema. The description never mentions either parameter or how filtering interacts with the per-chain/per-collateral results, so it adds nothing over the schema — baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The opening clause names the resource concretely (per-chain collateral addresses, MarketRouter proxies, OutcomeToken1155, factories, and required approvals), which is genuinely distinguishable from siblings like kellian_list_collateral. However, the sentence immediately dissolves into approval mechanics and caveats, so the core 'this returns contract addresses plus required token approvals' purpose is buried rather than stated crisply.

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 real guidance embedded ('check the actual /trade/prepare or /trade/simulate response for one market rather than assuming this list is permanent', 'Creator agents must select a collateral with creation=true', 'Cancel and direct market-local claims need no approval'), but it is written as scattered mid-sentence asides rather than explicit when-to-use/when-not-to-use. No sibling is named as an alternative, so the agent must infer routing from domain jargon.

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 (readOnly, idempotent, non-destructive, openWorld), and the description adds the one behavioral trait annotations cannot express: the values are defaults, not authoritative per-market truth, so acting on them without confirmation is risky. It also spells out the ORDERBOOK taker-fee incidence (charged to the economic taker on both wallet-router market orders and operator-matched signed limit fills) plus claim exit treatment, which is real operational 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?

Two sentences, front-loaded with the scope and then the critical caveat; nothing is padding. The first sentence is dense with nested parentheticals, which slightly slows parsing, but every clause carries fee-structure information an agent needs.

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

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

With an output schema present, return values need no explanation, and the description covers the remaining burden: what the two lanes are, who pays the taker fee, and that the figures must be re-confirmed per market. Nothing an agent needs before calling or before relying on the result 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?

The tool takes zero parameters, so the baseline applies and there is nothing for the description to disambiguate. No parameter claims are made or needed.

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 (read) and resource (canonical two-lane protocol fee schedule) and immediately decomposes it into the two lanes, LMSR and ORDERBOOK, with which fee applies where. This is clearly distinguishable from sibling per-market tools like kellian_get_quote and kellian_get_market, which the description itself names as the per-market counterparts.

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 frames these as factory DEFAULT rates and instructs the agent to confirm the per-market value via tradingRules on market detail or fee on kellian_get_quote before executing. That is a clear when-to-use-this vs when-to-use-alternatives rule with a named follow-up tool, not an inference the agent has to make.

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, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds one genuinely useful domain rule beyond that: the verdict is withheld until 12 settled markets, which explains a partially empty result. Beyond that single rule it does not describe pagination behavior or the shape of a partial-vs-complete record.

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 short sentences, front-loaded with the verb and resource, then the identifier rule, then the gating constraint. Every sentence carries information an agent cannot get from the 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 an output schema present, the description needn't document return values, and it does cover the record's contents, the two identifier forms and the settlement threshold. The one gap is that two pagination parameters exist but are only discoverable from the schema, and no sibling routing is given.

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 both the address anyOf forms and the two cursors are documented inline, so the schema does the heavy lifting. The description restates the wallet-or-agent-id distinction without adding format or syntax detail, and never mentions the openCursor/settledCursor paging parameters at all. 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 ('Read a forecaster's public record') and enumerates the contents (score against the price, open and settled forecasts), which is far more informative than the title alone. It never names a sibling such as kellian_list_leaderboard, so the boundary against the aggregate leaderboard view is left implicit.

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 does give usage context in the conditional 'pass a wallet address, or an agent id for an agent with no wallet', which resolves which identifier form to supply. It offers no when-to-use versus when-not guidance and no routing against sibling tools like kellian_list_leaderboard or kellian_get_market_holders.

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, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that — no note on whether an unknown address errors or returns empty, no chain-resolution behavior, no rate/caching context for an open-world read.

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 with no filler, so nothing is wasted. But the brevity here reflects under-specification rather than discipline — there is no additional content that earns its place because there is no additional content at all.

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

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

An output schema exists, so return values needn't be explained. Still, for a 2-parameter tool with 0% schema coverage and 37 sibling tools, the description should at minimum clarify what 'address' is and how chainId affects the lookup; neither is present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% for two parameters: 'address' (a contract address? a market slug?) and an optional 'chainId' with no stated default or behavior when omitted. The description's phrase 'a specific prediction market' only weakly hints that 'address' identifies the market, leaving the required parameter's format and the chainId fallback undocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Tautological: description restates name/title.

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 the many get_market_* siblings, and no prerequisites or exclusions. The agent must infer the routing decision entirely from the name.

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, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description's only added behavioral fact is that window defaults to ALL, which is genuinely useful, but it says nothing about the granularity of the returned history, how 'latest frame' relates to the series, or any size/latency limits on a long ALL 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?

Two short sentences front-loading the core action and the window semantics; nothing is padded. The 'Examples:' line is largely redundant with the description itself and is the one piece that does not earn 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 3-parameter tool with 0% schema description coverage, the description is too thin: chainId is entirely unexplained and the meaning of address is left to inference. The output schema means return values need not be described, but the missing chainId/default-address semantics is a real gap an agent would hit on first call.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry parameter meaning, and it only partially does: it explains the window values and the ALL default (which the enum alone cannot convey, since enums do not express defaults). It says nothing about what 'address' identifies (market address vs. token contract, ambiguous given the large sibling set) or what chainId is for and whether it has a default.

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 ('get price history + latest for a market') and adds the scope detail that a time window applies. It is reasonably distinguishable from siblings like get_market_state or get_market_depth, though the description never explicitly contrasts itself with them; the tools most likely to be confused with it (get_perp_index_bars, get_market_trades) are not mentioned.

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

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

The only guidance is a single trivial example ('Read the 1D price history for a market'), which restates the obvious rather than explaining when to pick this over get_market_state, get_market_depth, get_perp_index_bars, or get_market_trades. No when-not conditions, no prerequisites, and no note on when a caller wants a candle series versus a current snapshot.

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/idempotentHint/openWorldHint, so the safety profile is covered; the description adds genuinely new behavior detail — that depth is capped at 5 levels and that the payload is either a simulated LMSR buy ladder or a live aggregated order-book snapshot. It doesn't mention rate limits or probe behavior for the omitted chainId, but those are minor against an output schema that documents the response.

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, zero filler; the core purpose and the 5-level cap lead, with the sibling routing trailing. Every clause adds information an agent needs.

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 a full output schema, complete annotations, and 100% param coverage, the description only needs to explain the dual response shape and its size limit — both of which it does. Nothing required for a correct call 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% for both params (address, chainId) including the chain-probing fallback, so the schema carries the parameter burden. The description adds nothing about the parameters themselves — its `kind` reference is a response discriminator, not an input — so 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+resource ('5-level market depth for a market') and names the two shapes it can return, discriminated by `kind`. It also explicitly distinguishes itself from the sibling kellian_get_orderbook, so an agent can pick correctly 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?

Explicitly positions itself as the 'discovery-sized view' and points to kellian_get_orderbook for full depth, which is a clear when-to-use-this-vs-alternative signal. It stops short of saying whether the agent selects `kind` or the server derives it from the market type, leaving one inference point.

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, idempotentHint, and destructiveHint=false, so the safety profile is fully covered. The description adds value by clarifying that 'open interest' here means total shares held per outcome, which is a non-obvious semantic. It says nothing about cost, rate limits, or behavior when the address is unknown, but with annotations and an output schema that is a modest gap.

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, front-loaded with the resource and immediately followed by the concrete return fields. No filler; it is a fragment rather than a full sentence, 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 a full output schema and complete parameter coverage, the description needn't explain return values, and it correctly sticks to scope. What it omits is the comparative context in a 30+ sibling server: why an agent would call this instead of the other market-state tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and both parameters (address, chainId) are documented in the schema, including the note that chainId probes enabled chains when omitted. The description adds no parameter-level meaning beyond that, 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 the specific resource (market holders) and enumerates exactly what it returns: distinct holders, verified-human count, whale count, and total shares per outcome. That enumeration differentiates it from siblings like kellian_get_market_state or kellian_get_positions without needing to name them explicitly.

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

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

There is no guidance on when to reach for this tool versus kellian_get_market_state, kellian_get_positions, or kellian_get_market_depth, all of which sit close to this data. The description only says what it returns, leaving the selection decision entirely 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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds real value beyond that by fixing the window ('last 7 days') and ordering ('newest first') and by warning the payload is 'Titles and links only' — no article text — which prevents misuse. It does not mention result-count limits 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?

One dense sentence plus a short scoping clause; window, ordering and field list are front-loaded with no filler. Every phrase carries information an agent can act on.

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

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

An output schema exists, so enumerating return fields is a bonus rather than a requirement, and the time window and ordering are well covered. The gaps are the undocumented `chainId` and defaulting behavior, plus no hint about how many headlines come back or how matching terms are derived.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 50%: `address` is documented in the schema but `chainId` has no description anywhere. The description adds nothing about either parameter — not which chain is assumed when chainId is omitted, which is the one thing an agent most needs here.

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 ('Read a market's recent news headlines') and enumerates the returned fields (title, link, outlet, label, matched terms), which lets an agent distinguish it from kellian_get_market_research. It never names the sibling explicitly, so differentiation is implied rather than stated.

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-to-use guidance and no named alternative, despite kellian_get_market_research being an obvious near-neighbor. 'Research, not advice' is a disclaimer about output, not a selection hint.

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, idempotent, non-destructive, and open-world behavior, so the safety profile is covered. The description adds that results are 'dated' and include 'published AI analyst takes', which is useful context, but it does not say anything about freshness, provenance, pagination, or completeness of the research set.

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 short sentences, front-loaded with what is returned and followed by a one-line caveat. 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?

An output schema exists, so return values need not be described, and annotations cover safety. Still missing is any hint of how this differs from the news/context/rules siblings and any explanation of chainId, leaving a real gap for a two-parameter discovery 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 coverage is 50%: address is well documented with a regex, but chainId carries no description in the schema and no mention in the tool description. The phrase 'for a binary market' only faintly implies that address identifies a market and does nothing to explain chainId's role or default.

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 (read) and resource (dated research, sources, AI analyst takes) scoped to a binary market, which is clearly distinguishable from siblings like get_market_news or get_rules. It stops short of explicitly naming the adjacent tools it differs from, so it lands at 4 rather than 5.

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

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

The only guidance is the disclaimer 'Research, not advice', which is a liability statement, not a selection rule. It never says when to prefer this over kellian_get_market_news, get_context, or get_rules, so an agent must infer the boundary.

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, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds one genuine behavioral fact beyond them: action detail fields are conditionally present. That caveat is useful but left vague — no explanation of what 'public surface' means or how the caller should handle its absence.

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, no filler, with the resource and payload front-loaded. Slightly undermined by jargon ('public surface') that costs clarity without adding 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?

An output schema exists, so return values need not be explained, and the description correctly frames the payload. What is missing is the routing information an agent needs in a 38-sibling toolset: how this differs from get_market_state and when to prefer it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with address (market contract address) and chainId (probes enabled chains if omitted) fully documented in the schema. The description adds no parameter meaning beyond that, 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 states a specific resource (per-market public resolution state) and enumerates its payload: stage, reason, deadlines, action flags, final outcome. That is far more concrete than a tautology. However, it never distinguishes itself from the close sibling kellian_get_market_state or kellian_list_pending_resolution_markets, so an agent must infer the boundary.

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

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

There is no when-to-use guidance: no statement of when this is preferred over kellian_get_market_state, nor when it is unnecessary. The only conditional sentence ('Action details appear only when their public surface is available') describes output shape, not invocation criteria, so selection remains guesswork.

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, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds nothing beyond the field list — no note on freshness, caching, auth, or whether state is derived on-chain versus indexed.

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

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

It is a single zero-waste sentence front-loaded with the verb 'Get', which is good structurally. However, the terseness is under-specification rather than true economy; the sentence does not carry enough weight to earn its place as the whole description.

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

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

An output schema exists, so return values need not be explained, and annotations cover the safety profile. Still, for a two-parameter lookup in a crowded sibling set, the absence of any parameter or disambiguation guidance leaves an agent unable to call it confidently.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% for two parameters, so the description must compensate — instead it mentions neither marketAddress (format, chain scoping) nor chainId (default chain or required when ambiguous). The gap is entirely unmitigated.

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 fields returned (marketState, lifecycleStage, stageDeadline, tradingEndsAt, outcome), so the agent knows this is a market-state field read. But it never states the resource (a market) or scopes itself against the many siblings like kellian_get_market, kellian_get_market_resolution_state, or kellian_get_trade_status, which overlap heavily.

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

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

There is no guidance on when to choose this over kellian_get_market or kellian_get_market_resolution_state, nor any prerequisites. Given roughly 35 siblings, this omission forces the agent to guess from names alone.

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 this a read-only, idempotent, non-destructive, open-world read, so the safety profile is covered. The description adds real value beyond that: the newest-first ordering and the units/semantics of the payload (size in wei, price normalized 0..1), which an agent could not derive from the annotations. It omits any note about how chainId probing or the omitted-chain case affects results, which keeps it off 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 compact sentence, front-loaded with the resource and ordering, then the payload contents. Nothing is redundant, though the second half is a return-value list rather than decision-relevant guidance, which would have been a better use of the space given an output schema exists.

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

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

The output schema covers return values, so the field list is a bonus rather than a necessity. What is missing for a tool with a chainId probe and a limit cap is any note on cross-chain behavior, result truncation at the limit, or how it differs from kellian_list_trade_fills – gaps an agent could stumble on at call time.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 67% – address and chainId are documented in the schema, while limit carries only default/min/max bounds and no prose. The description adds nothing about the parameters themselves (no meaning for limit, no clarification of chainId probing), so this sits at the baseline appropriate to moderate schema 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?

Names a specific resource (recent trades for a market) and enumerates the returned fields (side, size, price, trader wallet), which makes the intent unambiguous. It does not, however, distinguish itself from the adjacent kellian_list_trade_fills sibling, so an agent must infer the difference from the names alone.

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

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

The description offers no when-to-use or when-not-to-use guidance and never mentions the closest alternative (kellian_list_trade_fills). Usage is only implied by the resource name; an agent has no stated rule for choosing between the two trade-oriented 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, idempotentHint, openWorldHint and non-destructive, so safety is covered. The description adds genuine behavioral context beyond them: sampling happens only on whole minutes Kellian observed, gaps yield no bar, and bars are minute-counted rather than uniformly filled. It omits limits on window length / max bar count, which is the main remaining gap.

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

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

Front-loaded with the verb and resource, then the returned fields, then usage and a caveat. Dense but every sentence carries content; the nested parenthetical defining the index is slightly heavier than needed.

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

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

An output schema exists so return values need no explanation, and annotations carry the safety profile. The description covers what a bar is, sparsity, and interval alignment; the missing piece for correct invocation is any bound on window size or result volume.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 75% with from/to and interval already documented (including the 9:30 ET alignment note). The description adds little parameter detail, and notably the un-described `symbol` parameter's `<TICKER>-<QUOTE>` shape is not explained in prose either.

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: read the Kellian Perps index as OHLC bars over a window, with the parenthetical defining the index as the underlying instrument price sampled per minute. It implicitly separates itself from market-price chart siblings (kellian_get_market_chart) by scoping to the index/underlying, though it never names that 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?

"Use it for the real range of a price market's window" gives a positive use context, and "a minute not recorded has no bar" warns about sparsity. But there is no when-not guidance and no named alternative (e.g. market chart vs index bars), so the agent must infer which tool to pick.

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?

Goes well beyond the readOnly/idempotent annotations: it discloses that valuations may lag the chain, that finalized is ~20-24 min behind head on Base, and that provisional rows move share balances only while cost-basis columns and aggregates remain finalized-tier. These are exactly the behavioral traps an agent would otherwise fall into.

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

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

Front-loaded with the core resource before the finality detail, and every sentence carries operational information. It is dense and jargon-heavy but not padded; the tier explanation is long yet justifies its length.

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 tool with an output schema and full annotations, the description covers the hard parts: valuation opt-in, price scale, unit conventions, and finality semantics. The one material omission is pagination behavior for `cursor` and the purpose of `marketAddress`, which an agent must guess.

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 only 17%, so the description is expected to carry the load, but it clarifies only `include` (which the schema already documents) and the role of walletAddress. It says nothing about limit, cursor pagination, chainId, or marketAddress, leaving four parameters with no semantics anywhere.

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 first clause names a specific verb and resource ('Get token positions for a wallet address') and immediately enumerates the payload: share balances, cost-basis ledger, per-outcome cost basis, realized P&L. An agent knows exactly what data comes back. It doesn't explicitly contrast with siblings like kellian_get_balance, but the ledger/cost-basis framing is distinctive enough to infer the split.

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 concrete conditional guidance: pass include="valuation" for mark-to-market, and it explains which tier to consult for settlement truth ('finalized ... is the only settlement truth') versus when a just-made trade shows up ('provisional ... here immediately'). It stops short of naming an alternative sibling tool for the case where you only want plain balances.

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, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered. The description adds only that the facts are 'canonical' and 'public,' which tells the agent these are authoritative reference data rather than live market state — modest added value beyond the annotations.

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

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

Two tight sentences with no filler, and the core scope is front-loaded in the first clause. Minor deduction for the fragmentary construction, which reads as a label rather than a complete statement of what the tool does.

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

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

An output schema exists, so return values need no explanation, and with no parameters the calling burden is low. Still, the description leaves the boundary against overlapping rule/fee/contract tools unstated, and 'actor conditions' plus 'fund flows' are vague enough that an agent cannot confidently predict whether this tool or a more targeted sibling answers a given question.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description does not misleadingly imply any filtering or selector inputs.

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 resource concretely — canonical public protocol facts covering resolution timing, final review, bonds, fund flows, and actor conditions — which is a distinguishable scope from most siblings. It is a noun-phrase fragment rather than a verb+resource statement, so the agent must infer that the tool 'returns' these facts, but the content covered is specific.

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 implicitly routes one case away from this tool by saying publicly available actions are in the capability catalogue and per-market action flags, which is useful disambiguation. However, it gives no explicit guidance on when to call this versus overlapping siblings such as kellian_get_contracts, kellian_get_fees, or kellian_get_market_resolution_state.

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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context by stating 'Unauthenticated', which tells the agent no credential handling or auth-failure path is required — a real behavioral fact not in the annotations. It stops short of noting latency/RTT effects on skew measurement, which would have been the one remaining useful caveat.

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 sentences are tight and front-loaded, but the trailing 'Examples: Current server epoch ms' is a truncated fragment that conveys nothing beyond the first sentence and reads as leftover template text. That dead sentence costs it a point against an otherwise two-sentence description.

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

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

With zero parameters, an output schema, and full annotation coverage, the description carries the remaining burden: what the value means (ms epoch), why to call it (skew), and that it is unauthenticated. Only a note about round-trip latency affecting skew estimation is missing, which is a refinement rather than a blocker.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the schema baseline of 4 applies. The description correctly says nothing about inputs and instead spends its words on the return unit, which is the only semantic worth clarifying here.

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 ('Return the protocol server wall-clock time') plus the exact unit ('Unix epoch milliseconds'), which is the detail that matters for this resource. No sibling tool in the list returns time, so it is trivially distinguishable from the get_market/get_positions family.

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 a concrete usage context: 'Use before quoting to measure client clock skew,' which tells the agent exactly when this belongs in a workflow. No exclusions or alternatives are needed since no sibling offers overlapping capability, so the absence of 'use X instead' guidance is not a real gap.

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, idempotent, openWorld, and non-destructive, so the safety profile is fully covered. The description adds little beyond the field list, which overlaps with the output schema; it discloses no auth, rate-limit, or versioning behavior. With annotations carrying the behavioral burden, a 3 is appropriate.

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 tight sentences with the verb and resource front-loaded and no wasted text. It could be marginally sharper by naming the contrasting sibling, but 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?

An output schema exists, so return-value explanation is not required, and annotations cover the safety profile. For a zero-param read tool, the description is nearly complete; the only real gap is the missing positive usage trigger.

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?

Zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. The empty schema is consistent with the description's claim of returning a single active manifest.

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 (Return) and a well-defined resource: the active versioned participation-token profile, deployment evidence, stage, and distributor release IDs. This is clearly distinct from the market-data/collateral siblings. It doesn't explicitly name the sibling it contrasts with, keeping it from a 5.

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

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

The sentence 'This is separate from live market collateral discovery' provides one exclusion, pointing away from kellian_list_collateral. However, there is no explicit 'use this when...' trigger and no positive framing of the scenario that selects this tool over the other get_* 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 only cover safety (readOnly/idempotent/non-destructive); the description adds substantial behavior beyond them: two result tiers with their latency (~20-24 min behind head on Base), per-fill and envelope `finality` fields, and the guarantee that `status: "not_found"` is never returned for a seen transaction, so polling never regresses.

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

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

Front-loaded with the core verb and purpose, then the tier explanation; no filler sentences. It is dense with domain jargon ('finality-fenced') that may cost a first read, but every sentence carries operational meaning.

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

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

An output schema exists, so return shape needn't be explained, yet the description still covers the two tiers, finality fields, and the not-found edge case — exactly what an agent needs to interpret results and poll 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 both parameters are already documented in the schema (txHash format, chainId discovery). The description adds only indirect context — that the hash must be a mined transaction and that chain affects indexing lag — which is useful but not new parameter-level semantics.

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 ('look up a submitted trade by transaction hash') and immediately frames the access path ('the by-tx path for crash recovery'), which separates it from the fill-enumeration siblings such as list_trade_fills.

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 a clear trigger — crash recovery / polling a known transaction — and an action rule ('Act on provisional; settle on finalized'). It does not name an explicit alternative (e.g., list_trade_fills when you don't have a hash), so it stops short of full routing guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds real context beyond them — that results are scoped to the authenticated agent tier / current key, i.e. auth-dependent output — but says nothing about result size, caching, or whether the catalog changes over time.

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

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

A single sentence with no filler, front-loading the action and immediately qualifying it with scope. Every clause carries meaning.

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?

A zero-parameter, read-only tool with an output schema and full annotation coverage needs little prose, and the description correctly explains the key-scoped behavior and the return category (endpoint catalog). The only gap is routing guidance versus the many discover_* 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The schema is an empty object and needs no compensation.

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 ("List protocol capabilities") with a clear scope qualifier ("available at the authenticated agent tier"). The parenthetical "endpoint catalog for the current key" usefully pins down what the resource actually is, though it does not explicitly contrast with the kellian_discover_* siblings.

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 explicit "use this when" statement or named alternative. Usage is only implied: the tool is framed as an endpoint catalog for the current key, so an agent can infer it is for introspection of what the key permits, but nothing tells it when to prefer a discover_* tool instead.

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, idempotent, non-destructive and open-world behavior, so the safety profile is fully covered and the description carries a lower burden. The description adds nothing beyond them, however - no mention that results are a static platform-level list rather than per-user state, and no caveats about freshness.

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 short sentence with the verb and resource front-loaded and zero filler. It is arguably too terse - one clause on what a chain entry represents (or that the list is static) would earn its place - 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 an output schema documenting the return shape, full annotation coverage, and no parameters, this trivial enumeration tool needs little more than the statement given. The only gap is that the description does not indicate the list's scope or whether it should be cached, which is minor at this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the baseline is 4; there is no parameter semantics for the description to explain. Nothing in the description misleads about inputs.

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 gives a specific verb ('List') and resource ('supported blockchain networks'), making it immediately clear this returns the set of chains the platform supports. No sibling covers the same resource, so no explicit differentiation is required, though it does not state scope details such as ordering or filtering.

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: an agent can infer this is the lookup to call before referencing a chain by name or ID, but the description never says when to use it or what to do with the result. No alternatives or exclusions are named, which is acceptable only because the resource is unique among 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 declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds the scoping rule for chainId, but says nothing about response size, ordering, or whether results are cached/refreshable, which is a modest gap for an open-world read.

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 with the resource and returned fields stated first, followed by the one conditional constraint. 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 an output schema present and the sole optional parameter fully documented in both schema and description, an agent has everything needed to call it. The only missing piece is differentiation from sibling list tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the schema's chainId text is nearly identical to the description's parenthetical, so the description adds little beyond restating it. Baseline 3 applies when the schema carries parameter semantics.

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 uses a specific verb ('List') with a precise resource ('public launch collateral tokens') and previews the returned fields. It is clearly distinct from siblings such as kellian_list_chains or kellian_list_markets, though it never explicitly contrasts with them.

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

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

The only guidance is the conditional 'chainId is optional only when exactly one chain is active', which hints at when the parameter matters. There is no statement of when to use this tool versus alternatives, nor any exclusions.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is fully covered elsewhere. The description contributes the shape of the payload (event type, description, webhook bridge) but says nothing about ordering, volume, or auth, which is modest added value over the annotations.

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

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

Two sentences, no waste, and the core 'what you get back' content is front-loaded ahead of the pointer to the sibling tool.

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 zero params, a full output schema and rich annotations, the description only needs to establish scope and it does so. The remaining gap is that it does not clarify its relationship to kellian_list_webhook_event_types, a natural source of misfires in this sibling set.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes no parameters, so there is nothing for the description to disambiguate; baseline 4 applies. Nothing in the text misleads about inputs.

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 ('List every protocol WebSocket event type') and specifies the returned fields (description, webhook equivalent if bridged). It distinguishes itself from kellian_discover_events, but not from the closely related kellian_list_webhook_event_types, which an agent could easily confuse it with given the 'webhook equivalent' mention.

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?

Names kellian_discover_events as the place for connection details, which implicitly routes the agent for the common adjacent need. However, it offers no exclusion against kellian_list_webhook_event_types or other discover_* siblings, so the routing is partial rather than exhaustive.

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 read-only, idempotent, open-world, and non-destructive behavior. The description adds useful data caveats beyond annotations: amounts may be unavailable, return percentage fields are null, legacy aliases exist, and settledMarkets counts confirmed non-void traded markets.

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

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

The purpose is front-loaded and the paragraph contains no obvious filler. It is dense and semicolon-heavy, but every clause conveys relevant leaderboard behavior or caveats.

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

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

With an output schema and fairly rich parameter descriptions, the definition gives enough context for correct invocation. The description covers the tricky sort and data-availability semantics, though it does not mention pagination or generation-pinning behavior directly.

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 71%, so the schema already documents most parameters. The description still adds meaningful semantics for `sort`, including canonical displayed-price performance, RETURN aliasing PNL, and CREATOR_QUALITY returning creators, though it does not expand on the remaining parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the resource as a ranked public leaderboard and explains what different sort values return, including traders versus creators. It is specific about the data being the same as the public view, though it does not explicitly contrast itself with sibling 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?

Usage is mostly implied by the leaderboard context. The description explains sort-value effects but gives no explicit when-to-use guidance, exclusions, or named alternatives among the sibling 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?

The annotations already declare read-only, idempotent, open-world, non-destructive behavior. The description adds useful behavioral context beyond that: comments are returned newest first and include frozen position/pricing data captured at write time. It does not discuss auth or rate limits, but those are not clearly required here.

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 definition is a single dense sentence, but it is front-loaded with the operation and scope. Most clauses earn their place by describing returned data, though the sentence is long and could be easier to scan if split.

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 rich annotations and an output schema present, the description supplies enough context about ordering and returned fields for an agent to invoke it correctly. Pagination and limit details remain slightly under-explained, but the cursor schema carries some of that burden.

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 partial (67%): address and cursor are documented in the schema, while limit has no description. The description does not clarify parameter semantics, though 'newest first' loosely contextualizes ordering and the cursor 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 names a specific verb and resource: reading human comments on a market. It also scopes the content as newest-first, read-only, and position/reputation-tagged, which makes it distinguishable from sibling market-data tools such as news or research.

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

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

It gives a clear implied use case — position- and reputation-tagged sentiment for trade decisions — but does not explicitly say when to prefer this over sibling tools like get_market_news or get_market_research, nor does it state exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so safety is covered. The description adds useful nuance that rows carry both a canonical state and a derived stage, including the stage deadline, which is not in annotations or the input schema. It says nothing about pagination behavior or rate limits.

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 purpose is stated first, followed by one dense sentence about row contents and a short concrete example. No filler, though the example line adds modest value for an eleven-parameter tool.

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 eleven optional filters, an output schema and rich annotations, the definition is workable but leaves gaps: no default paging note (pageSize 20, max 100), no explanation of the cursor-only-applies-to-`new` constraint at tool level, and no routing versus sibling market-listing tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 73% and the schema documents most parameters well (sort, cursor, search, creator, pricingModel, sourceTokenId). The description adds essentially no parameter semantics beyond implying state/category/chain filtering through the example, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

"List prediction markets on Kellian" gives a specific verb and resource, and the second sentence explains the shape of each row (marketState, lifecycleStage, stageDeadline). It does not, however, distinguish this from close siblings like kellian_list_pending_resolution_markets or kellian_list_related_markets, which also list markets.

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 example "List live CRYPTO markets on Base" implies a usage pattern, and the note to prefer lifecycleStage tells the agent how to interpret results. But there is no explicit when-to-use/when-not guidance versus siblings such as get_market (single fetch) or list_related_markets.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered structurally. The description adds only the notion of a 'canonical resolution pipeline' as scoping context, with nothing about ordering, freshness, or what states are typically returned. With annotations carrying the burden, a 3 is appropriate.

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 short sentences, front-loaded with the core purpose. The second sentence restates the parameter names already present in the schema, which is mild redundancy but not harmful.

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

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

Output schema and rich annotations mean return values and safety need no explanation, and low complexity (a filtered list) keeps the bar modest. The missing piece is disambiguation from kellian_list_markets and clarification of what 'pending resolution' means across the marketState enum (e.g., creator_proposal vs challenge), which the description never ties together.

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 four parameters (category enum, marketState enum, cursor, limit) are fully documented in the schema. The description merely enumerates them by name without adding filtering semantics or defaults, so 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 and resource with scope: 'List markets in the canonical resolution pipeline.' An agent can tell this returns markets, not events or trades. However it never distinguishes itself from the sibling kellian_list_markets or kellian_get_market_resolution_state, so the boundary of 'resolution pipeline' is left implicit.

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, when-not-to-use, or named alternative. With siblings like kellian_list_markets and kellian_get_market_resolution_state in the same namespace, the description should say why an agent picks this one; instead usage is only weakly implied by 'resolution pipeline.'

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, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds little beyond that — it does not explain how 'related' is determined, whether results are ranked, or what happens when the anchor market has no siblings.

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 short sentences with no filler; the scope constraint (same category and chain) is front-loaded. The trailing parenthetical is the only dead weight.

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

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

An output schema exists and params are fully documented, so the main gap is conceptual: 'related' and 'canonical discovery set' are never defined, leaving the agent to guess the selection/ranking logic before deciding whether this beats kellian_list_markets.

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%, including the limit range and default, so the schema carries the burden. The description mentions no parameters and adds no interpretation beyond what the schema states.

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 ('List') and resource ('related markets in the same category and chain'), which distinguishes it from the broader kellian_list_markets and the single-market kellian_get_market. The parenthetical '(canonical discovery set)' is undefined jargon that adds no precision.

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?

Says it's 'useful for context around a market before trading or creating', which implies a pre-trade/pre-creation use case. It never names an alternative tool or states when to prefer kellian_list_markets or kellian_get_context instead.

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

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

Beyond the read-only/idempotent annotations, the description explains the two-tier finality model, provisional-vs-finalized behavior, cursor-page guarantees, publicationState/txHash timing, and ingest freshness.

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 dense and front-loads the key concepts, but the production freshness detail and webhook latency sentence are somewhat extraneous for routine tool selection.

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

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

Given the output schema exists and annotations cover safety, the description supplies the remaining critical context: finality semantics, paging behavior, and publication-state timing.

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 parameters are already documented; the description adds useful cursor behavior by explaining that provisional fills never appear on a cursor page, though it does not elaborate on limit or walletAddress beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb and resource ('List a wallet's fills') plus ordering and cursor semantics, and it distinguishes the tool's role for history and P&L from sibling event lifecycle 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?

It states the primary use case (history and P&L) and redirects order-lifecycle gaps to kellian_list_order_events, but it does not explicitly exclude other sibling tools such as market trades or trade status.

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 read-only, idempotent, non-destructive, and open-world behavior, so the description's job is to add value beyond them. It does so by disclosing that the response carries payload shape hints, the walletFilters matching field, and the source realtime/WebSocket event mapping, which tells an agent what it will actually get back.

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 packs the core purpose and three useful output details without filler. It is slightly dense and lacks a sentence separating the 'when to use' routing, 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 parameters, an output schema available, and safety annotations present, the definition is nearly complete. The one meaningful gap is the absence of any routing signal distinguishing this from the very similarly named kellian_list_event_types and kellian_discover_webhooks 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?

There are zero parameters, so there is no parameter semantics to explain; baseline is 4. The description correctly avoids inventing parameter details and instead spends its words on the result content.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: list the event types a webhook can subscribe to, including payload hints and the bridging source event. It implicitly distinguishes itself from the generic kellian_list_event_types by tying results to webhook subscriptions, but it never names the sibling or explicitly contrasts the two.

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: an agent would infer this is the discovery step before creating or updating a webhook. There is no explicit 'use this when' condition, no exclusion of kellian_list_event_types or kellian_discover_webhooks, and no stated prerequisites.

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