Aperiodic Market Data

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

Annotations already cover the safety profile (readOnly, idempotent, closed-world, non-destructive), so the description's job is to add content context, which it does by enumerating exactly what metadata comes back, including the plan requirement and free preview window. With no output schema, this return-content disclosure is genuinely valuable; it stops short of 5 because it says nothing about behavior for an invalid or unknown dataset id.

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 tightly packed sentence with no wasted words, and the most distinctive item (field definitions) is front-loaded. The fragmentary noun-phrase style costs a little clarity versus a proper verb-led sentence.

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

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

For a simple one-parameter read tool with rich annotations and no output schema, describing the returned fields is the main requirement, and that is largely met. Gaps remain around error behavior and sibling differentiation, which an agent needs to select this tool 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 coverage is 100% and the single parameter is fully documented in the schema, including an example id format and the list_datasets provenance. The description adds no additional meaning about the dataset identifier, so the baseline of 3 applies.

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

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

The description is a noun phrase listing returned content (field definitions, intervals, exchanges, plan, preview window) rather than a verb+resource statement; the verb 'describe' comes only from the title. It is clear that this retrieves metadata about one dataset, but it never distinguishes itself from siblings like get_data or list_datasets, which also concern dataset data.

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 and no exclusions. The only workflow hint, that the id comes from list_datasets, lives in the schema rather than the description, and nothing tells the agent when to pick this over get_data or list_datasets.

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 closed-world, so the safety profile is covered outside the description. The description usefully adds that the payload is the full text and which document types can come back, which distinguishes it from a snippet-returning search. It says nothing about what happens with a stale or unknown id, or about response size, so the added behavioral context is modest.

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 tight sentence with the resource front-loaded and the document types enumerated after the colon. There is no filler, though the elliptical fragment style omits an explicit verb, which costs it a point relative to a fully formed lead sentence.

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

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

For a one-parameter lookup with no output schema, the description supplies the essentials: the result is full text and can be one of three document types. Rich annotations cover the safety and idempotency profile. Only failure behavior for unknown ids is unaddressed, which is a minor gap at this complexity level.

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% for the single id parameter, so the schema already documents it as 'An id from search.' The description reinforces that the id must originate from a search result but adds no format, length, or error semantics. Baseline 3 is appropriate when the schema carries the parameter burden.

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 concrete resource (the full text of one search result) and enumerates the document kinds it can return: a dataset with all its fields, a category, or the plans guide. That goes beyond a tautology and implicitly separates it from the search tool that produces the id. It stops short of naming siblings explicitly, 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?

'One search result' and the schema note 'An id from search' together imply the intended workflow: call search first, then fetch by id. There is no explicit when-not guidance and no alternative tool is named, so usage is only implied rather than stated.

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

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

Annotations already cover readOnly, idempotent, non-destructive and closed-world, so the description's job is to add context. It does: results are capped at 50, matching requires every query word (AND semantics), ids have a specific format, and only one free preview symbol is available on binance-futures — a real behavioral/access constraint not expressed anywhere in the structured fields.

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

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

Three short sentences, front-loaded with the core behavior and the result cap, then the id format, then the access caveat. No filler, though the id-format example is somewhat redundant with the preview-symbol sentence that follows it.

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

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

There is no output schema, and the description compensates by showing the exact id shape a caller will receive, plus the result cap and the preview limitation. For a two-parameter lookup tool this is close to sufficient; the main gap is any statement of ordering or what happens when a query word matches nothing.

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%: query is documented in-schema, but exchange is a bare enum with no explanation. The description adds AND-matching semantics and the 50-result cap that the schema's 'Words to match' does not convey, but it leaves the exchange parameter entirely unexplained (which venue each enum value represents, whether coverage differs). Partial compensation only.

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+resource: it returns symbol ids on one exchange matching every word of a query, capped at 50. That is concrete enough to distinguish it from generic siblings like search and fetch, though it never explicitly contrasts itself with those 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?

Usage is implied by the semantics of the query (find symbol ids before fetching data), and the free-preview note hints at an access tier restriction. However there is no explicit when-to-use or when-not-to-use guidance, and no mention of an alternative for cases where this tool is insufficient.

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, yet the description adds material behavior: signed URLs expire in one hour, payloads must not be pasted into the conversation, and all arguments except dataset fall back to a free preview requiring no API key. It stops short of stating whether handles can be re-requested cheaply or whether any quota applies.

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 key distinction ("not the data"), then the payload contents, then the usage constraint and the fallback tool. Three dense sentences with no filler; the enumerated return contents earn their space because no 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?

With no output schema, the description correctly carries the burden of explaining return values and does so thoroughly, plus the never-paste and no-API-key constraints. Remaining gaps are minor: no note on size/row limits, error behavior, or what happens when a handle's URLs lapse.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: every argument other than dataset resolves to the free preview, and that preview needs no API key. That clarifies the defaulting behavior and its access implications in a way the schema alone does not.

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?

"A handle to one slice of a dataset, not the data" is a precise verb+resource statement that immediately separates this from a tool that returns data itself, and it enumerates exactly what the handle contains (signed Parquet URLs, schema, row counts, column stats, samples, snippet). It also explicitly names the sibling (summarize) it is not to be confused with.

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

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

Gives clear when-to-use context ("Load the files in your own code; never paste them into the conversation") and names one alternative with its selection condition ("Without code, use summarize"). It does not differentiate against the other plausible siblings, fetch and describe_dataset, so the routing picture is incomplete.

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 closed-world, so the safety profile needs no restatement. The description's genuine addition is the disclosure that results include the caller's own access tier (full access vs free preview) and the plan required — permission-sensitive behavior an agent could not infer otherwise. It says nothing about ordering, pagination, or catalog size, so this is solid but not rich.

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 two-word call to action, with the catalog scope front-loaded and zero filler. The colon-list phrasing is slightly fragmentary but readable, and no sentence could be deleted without losing content.

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

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

With no input parameters and no output schema, the description carries the burden of explaining return values and does so field by field, including the caller-specific access flag. Missing only ordering/pagination behavior, which is minor for a zero-argument catalog listing.

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; the baseline applies. The enumerated return fields (id, category, plan, description, field count, access level) describe the response rather than parameters, which is useful but belongs to a different dimension.

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 makes clear it enumerates the full Aperiodic dataset catalog (metrics and raw) and enumerates exactly what each entry carries. That is specific and distinguishable from get_data or summarize, though it never names the sibling describe_dataset, which is the nearest neighbor for per-dataset detail.

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

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

'Start here' is an explicit entry-point cue telling the agent to call this before the other tools, which is real guidance rather than implied. It stops short of stating when to move on to describe_dataset or fetch, so there are no exclusions or named alternatives.

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, closed-world), so the bar is lower. The description still adds real context: the response is connection documentation and plan-scoped limits, not market data, and the tool degrades into a discovery listing when dataset is omitted. Plan-tier dependence is noted but not explained.

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

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

Three sentences, front-loaded with what is returned followed by the negative scoping clause and the no-dataset fallback. Dense and nearly waste-free, though the telegraphic phrasing ('Never the stream itself.', 'With no dataset, lists...') reads as clipped fragments.

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

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

With no output schema and only 4 optional parameters, the description carries the burden well by enumerating the return contents and the dataset-absent behavior. It omits auth requirements and how plan limits are surfaced, which matters somewhat for a connection-documentation 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 only 25%, so the description must compensate, and it does: it explains that dataset, exchange, interval and symbols together form the subscribe frame, and that omitting dataset switches to a listing mode. The 19 dataset enum values remain unexplained, but the sibling describe_dataset plausibly covers that gap.

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 precisely what the tool returns: a WebSocket URL, a subscribe frame for a dataset/exchange/interval/symbol combination, plan limits, and a Python client. 'Never the stream itself' sharply separates it from sibling data tools like fetch and get_data. It stops short of naming a sibling outright, so it is a strong 4 rather than a 5.

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

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

It gives a concrete usage rule: with no dataset, the tool lists available streams and the plans that include them, which tells the agent how to use it for discovery. 'Never the stream itself' functions as an implicit exclusion steering the agent to fetch/get_data for actual data. No explicit when-not beyond that.

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 read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description adds real value beyond them by disclosing the searchable corpus (datasets, fields, categories, plans guide) and the return shape (ids, titles, URLs), which matters since no output schema exists.

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, zero waste. The corpus scope leads and the follow-up action is front-loaded at the end.

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

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

For a one-parameter search tool with no output schema, the description covers what is searched, what comes back, and what to do next. Missing are result caps/pagination and matching semantics, which an agent would need for large or ambiguous queries.

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 0% and the single parameter is undocumented, but the description's word 'Keyword' signals free-text matching rather than exact id lookup. That is useful but thin; nothing is said about multi-word behavior, matching rules, or result limits.

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 ('Keyword search over every dataset, its fields, the categories and the plans guide'), and scopes the corpus precisely. It routes the agent onward to 'fetch', though it does not distinguish itself from siblings like list_datasets or find_symbols.

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 follow-up path is explicit: results give ids and 'read one with fetch.' That tells an agent when this tool is the entry point versus fetch. It stops short of naming when-not conditions or contrasting with find_symbols/list_datasets.

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, closed-world), so the description's added value is the disclosure that computation happens server-side and that only the named columns are decoded — a real cost/performance signal. It also sketches what each mode returns (per-column count/mean/std/quantiles/range, a correlation matrix, at most 500 resampled points), which matters because there is no output schema. It stops short of describing result structure or any plan/quota limits it alludes to.

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

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

Two dense sentences with the mode enumeration front-loaded and no filler. Quoting the enum values in parentheses ties the prose directly to the schema, and the caps come last where they belong.

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

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

For an 11-parameter, no-output-schema analytical tool, the description covers the modes, the result types, the column-decoding constraint, and the argument lineage to get_data. Gaps are minor: the shape of the returned objects is only hinted at, and the referenced "plan rules" are never explained.

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 every one of the 11 parameters is already documented inline, including the defaults and the 500-point / 12-column caps that the description repeats. The one genuinely additive phrase is "same slice arguments and plan rules as get_data", which points at constraints the schema does not encode, but the rest largely restates structured fields (numeric-only, default first 6).

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 operation (server-side statistics over a slice) and enumerates the three analysis modes with the exact enum values ("stats", "correlation", "resample"), so an agent knows what it will get back. It references get_data only for argument semantics rather than explicitly stating when to prefer this over get_data, so sibling differentiation is implied rather than spelled out.

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?

"for when you can't run code" gives a clear selection condition against get_data, which is the main competing sibling. It also tells the agent that slice arguments and plan rules are shared with get_data, reducing the need to re-derive them. There are no explicit when-not conditions or limits beyond the code-execution framing.

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