TILLA - market data on one clock

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 structurally. The description adds one genuinely useful behavioral fact beyond annotations: no API key is required to call it. It says nothing about the form of the response (text vs structured), which would matter with no output schema.

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

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

Two short front-loaded sentences with zero filler: the content of the tool first, the access precondition second. Nothing could be trimmed without losing information.

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

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

For a zero-param informational tool with no output schema, the description tells the agent what topic coverage to expect and that no credential is needed. The only missing piece is whether the result is prose/markdown or structured data, which would help an agent decide how to consume 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. No misleading param claims are present.

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, understandable purpose: what TILLA is, who it's for, and how to get started. It reads as an introductory/onboarding resource, which is clear enough to select, but it never distinguishes itself from the sibling tilla_docs, which plausibly covers overlapping documentation.

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?

'How to start' implies an onboarding use case, and 'No API key needed' hints that it's safe to call before authenticating. But there is no explicit when-to-use versus tilla_docs or tilla_status, and no stated 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 cover safety (readOnly, idempotent, non-destructive, open-world), so the remaining burden is light. The description usefully adds cursor chaining (feed `until` back in) and an auth prerequisite ("Needs a key"), but leaves unclear what a 'key' scopes, whether results are truncated, and how large a delta can be returned.

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 run-on sentence with a mid-sentence hyphen and clause nesting ("since `since` ... that the key holds") that forces re-reading. The critical format hint is buried mid-sentence and the prerequisite is tacked onto the end as "Needs a key."

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 should explain the response shape, but it only mentions an `until` field that appears nowhere in structured data and never defines what the returned entries contain. The vague term 'the key' leaves a core requirement undefined for an incremental-sync 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 0%, so the description must carry the parameter meaning, and it does supply the accepted format 'YYYY-MM-DD HH:MM:SS' and the role of `since` as the window start. It doesn't clarify timezone or boundary inclusivity, and it references an `until` field that isn't a declared parameter or documented in any output 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 conveys that this returns a delta of repaired values since a timestamp, which is more specific than the title alone. But phrasing like "Every value our checks repaired since `since` ... that the key holds" is opaque about what 'checks' and 'the key' are, and it never clearly states the resource being returned (a change 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?

It does give a usable pattern: apply the returned values to keep a copy correct, and pass the response's `until` back as the next `since`. However, it names no alternative sibling tool (e.g. tilla_latest, tilla_window) and gives no conditions under which not to use it.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds a genuinely non-obvious behavioral fact — 'no key needed' — plus the scope of what the single call returns, which is exactly the kind of extra context that earns credit 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?

Two sentences, front-loaded with the payoff ('whole API manual in one call'), followed by the content inventory and the call-to-action. Every clause carries information; nothing is 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?

For a zero-parameter documentation fetch with no output schema, the description tells an agent both what it retrieves and when to reach for it. The only mild gap is that the shape/format of the returned manual is not hinted at, though that is low-stakes for a docs dump.

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 per the baseline this scores 4; the schema is trivially complete. The description confirms the no-argument, no-key nature ('in one call, no key needed'), which reinforces rather than adds new parameter detail.

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

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

States a specific resource (the whole API manual) and enumerates the content covered: every call, parameter, plan, and the paging/tick/resume/changes/bulk mechanics. It is clearly distinct from sibling data tools like tilla_markets or tilla_tick, though it does not explicitly say how it differs from the neighboring tilla_about.

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

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

"Read this first when you need to know how to do anything" gives an explicit trigger condition and implies precedence over the sibling tools. It does not name an alternative or state when not to use it (e.g. when you already know the endpoint), so it falls short of a full routing rule.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds one useful operational fact, 'No API key needed', which is authentication context not present in the annotations. It says nothing about cost, latency, or what the check actually returns.

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

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

It is a single compact sentence with no filler, and the core question is front-loaded. The brevity comes at some cost, because the 'lane' and 'layer' vocabulary is never grounded.

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 absence of an output schema means the description should hint at what a health check returns, such as a per-lane currency verdict; it only poses the question. For a zero-parameter read tool the annotations carry most of the weight, but the jargon leaves a real gap.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool 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 phrase 'is the data current?' together with the tool name 'tilla_health' signals a freshness or health check, but 'lane' and 'layer' are unexplained in-house jargon, so what exactly gets checked is unclear. It does not distinguish itself from close siblings such as tilla_status or tilla_latest.

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 statement of when to call this tool instead of tilla_status, tilla_latest, or tilla_changes, and no precondition or exclusion is given. The agent must infer the routing from the title 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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds value annotations cannot: the authentication requirement ('Needs TILLA_API_KEY') and the fact that omitting arguments yields an aggregate summary rather than a flat list. It does not discuss pagination or result size limits for large inventories.

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?

Roughly three dense sentences, front-loaded with the tool's identity and then the two parameter modes, with the prerequisite last. The telegraphic style ('No arguments:', 'layer=raw|derived|node') is efficient rather than padded, though the clipped phrasing takes a re-read.

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

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

With no output schema, the description must describe returns, and it does: aggregate lane-per-layer counts in the default case, series names in the filtered case. Combined with the auth note and the ordering guidance, an agent has enough to call this correctly; only edge-case behavior (invalid layer/lane, combined filters) is unaddressed.

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

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

Schema description coverage is 0%, so the description must carry the load, and it largely does: it defines the default (no arguments) behavior and enumerates the accepted values for layer (raw|derived|node) and lane (1min|hour|daily|...). It does not state whether the two filters can be combined or what happens with an invalid value, so it falls short of full 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?

The description states a concrete verb+resource: it enumerates every lane per layer with series counts, or every series name within a given layer/lane. The two modes (no-arg aggregate vs. filtered listing) are spelled out, which no sibling does. The lead sentence 'Exactly what the caller's key holds' is slightly indirect, but the following clauses remove ambiguity.

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 an explicit ordering instruction: 'Call this before tilla_latest / tilla_window and use the names it returns,' naming the two siblings it feeds. That is both a when-to-use rule and the reason the tool exists, leaving nothing 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, non-destructive, and openWorld behavior, so the main behavioral gap is lower. The description adds useful auth context by stating that TILLA_API_KEY is required, but it does not describe error behavior, rate limits, or return characteristics.

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 two short, front-loaded sentences with no filler. The core purpose appears first, followed immediately by the API-key requirement.

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?

This is a simple read tool with annotations, but the schema has 0% description coverage and there is no output schema. The description leaves the layer parameter undocumented and does not explain what a returned bar contains, which leaves meaningful gaps for correct 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 description coverage is 0%, so the description must carry parameter meaning. It mentions the named series and one lane, which maps to two parameters, but it says nothing about the layer parameter, its default, or allowed values.

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: the newest bar of a named series on one lane. It clearly identifies a read operation and avoids tautology, though it does not explicitly differentiate itself from siblings such as tilla_window or tilla_sample.

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

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

The description gives only a prerequisite (TILLA_API_KEY) and does not say when to use this tool versus siblings like tilla_window, tilla_sample, or tilla_tick. No when-not-to-use guidance or alternative selection criteria are provided.

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

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

Annotations already declare read-only, idempotent, non-destructive, open-world behavior, and the description adds valuable operational context: API key requirement, a 200-column response cap with series_next_offset pagination, and the effect of related=True. It still leaves the meaning of `lane` values and the clock behavior somewhat vague.

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

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

Dense but front-loaded: the core operation comes first, followed by layer, related, period, pagination, and auth. Some phrasing is cryptic ('on one clock', backticked identifiers) but no sentence is obviously wasteful.

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

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

For a six-parameter, no-output-schema read tool, the description covers the important call-shaping details: id source, layers, periods, related expansion, pagination cap, and API key. Missing lane enumeration and limit meaning keep it from being fully complete.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains market, layer values, period values, and related well, but leaves `lane` values (only the default 1min appears in schema) and `limit` semantics undefined, so compensation is partial.

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: fetch one whole market's every series in a single call, and names the id source (tilla_markets) with examples. This clearly distinguishes it from list-oriented siblings like tilla_markets and point-query siblings like tilla_tick.

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?

Establishes clear context: use this when you want the complete set of series for one market across layers and periods, with related=True for connected markets. It does not explicitly state when to prefer siblings such as tilla_window or tilla_latest, so exclusions and alternatives are only implied.

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 safety is covered; the description adds the auth note ('No API key needed') and, with no output schema present, carries the burden of disclosing what comes back: category, related markets, per-plan series counts, and lanes. It does not mention ordering, pagination, or overall result size, which would matter for a full catalog listing.

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

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

Two sentences, front-loaded with the resource and scope, with the sibling hand-off placed last where an agent looks for next steps. The middle enumeration of returned fields is long but each item is substantive rather than filler.

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

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

With no parameters and no output schema, the description does the necessary work of describing the return shape and the follow-up call, which is sufficient for a simple catalog endpoint. Minor gaps: 'lanes' is undefined jargon, and nothing is said about result ordering or size for what is presumably a large 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 zero parameters, so there is nothing to disambiguate and the baseline applies. The description's mention of `id` correctly clarifies that the identifier is an *output* field consumed by `tilla_market`, not an input 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?

The description names a specific resource (every market TILLA carries) and enumerates the coverage (crypto, US stocks and ETFs, FX, macro) plus the metadata returned per market (category, related markets, series per plan, lanes). It also explicitly routes to the sibling `tilla_market` for single-market lookup, so an agent can distinguish the two 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?

It gives a concrete usage pattern — take the `id` from this listing and pass it to `tilla_market` — which is exactly the workflow an agent needs. The 'No API key needed' line removes an authentication prerequisite. It stops short of stating when this listing is *not* the right entry point (e.g. vs `tilla_latest` or `tilla_tiers`), so no explicit exclusions.

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

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

Annotations already declare read-only, idempotent, open-world, non-destructive behavior. The description adds useful context beyond that: no key is needed and the full one-tick files are available at specific sample paths named in the answer. It does not discuss rate limits or caching, but the safety profile is already well covered.

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 two efficient sentences with the core purpose front-loaded and no wasted text. File path details are useful and placed after the main behavior.

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 read-only sample tool with no output schema, the description explains the return content and file locations well enough to call it correctly. Some output-shape detail, such as what exactly a lane entry looks like, is left implicit.

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

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

Schema coverage is 0% and the single tier parameter has no enum or description in the schema. The description compensates by enumerating the allowed plan values (free, builder, pro or max) and linking the tier to the sample output, though it does not explicitly name the parameter.

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

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

The description states a specific resource and scope: a sample for one plan, with per-lane series counts and one aligned 1-minute row of real values. It is clear what the tool returns, though it does not explicitly distinguish itself from siblings such as tilla_tiers or tilla_market.

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

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

The description implies usage by saying it is a free sample requiring no key, which helps an agent understand when to preview data. However, it gives no explicit when-to-use/when-not guidance or named alternatives among the many 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is well covered. The description adds a useful auth detail—no API key needed—but does not mention rate limits, freshness guarantees, or error behavior.

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

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

The description is two short sentences: payload first, then the auth note. Both sentences add information and there is no filler.

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

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

For a zero-parameter read-only feed-status tool, the description covers the returned data and the API-key requirement, while annotations cover safety and idempotency. It could be stronger if it clarified why 'status' differs from sibling health/latest/tiers tools, but no critical calling information 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?

There are zero parameters, so there is no parameter meaning to explain, and schema description coverage is 100%. The baseline for a no-parameter tool is 4.

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

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

The description names the concrete payload—the newest 1-minute bar plus the tiers served—so an agent knows what data to expect. However, it does not state a verb or explicitly distinguish this from overlapping siblings like tilla_latest, tilla_tiers, or tilla_health.

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 or comparison to alternatives; the only condition given is 'No API key needed,' which is authorization information rather than a selection rule. The agent must infer that this is the feed-status check rather than one of the similar 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, open world), so the bar is lower. The description still adds real value: an auth requirement ('Needs a key'), the default value of `at` ('the minute just closed'), and the per-lane response shape ('bar, complete, series, values') — useful 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 with no filler; the default-value detail and response shape are packed in efficiently. The leading tagline ('Your whole plan, live') is marketing rather than specification and pushes the substantive scope to second position, which is the only real structural weakness.

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 0% schema coverage, no output schema, and fully custom domain terms ('lane', 'bar', 'complete', 'series'), the description is the sole source of meaning and leaves core concepts undefined. An agent can form a rough idea of the call but cannot confidently construct `lanes` or interpret the returned keys.

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% and the schema only offers titles ('At', 'Lanes'). The description compensates for `at` with a format and default, but says nothing about `lanes` — not its syntax (list? comma-separated? glob?), not its filtering behavior, and not what happens when it is null. Half the parameters remain opaque in both schema and description.

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 says it returns 'every series the key holds on every lane that closed at a boundary', which conveys a read of time-bound series data, but the verb is implied ('in one call') and the domain vocabulary ('lane', 'bar', 'series') is never grounded. It does not distinguish itself from close siblings like tilla_latest, tilla_window, or tilla_sample, so an agent cannot tell which of these to pick from the text 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?

'default the minute just closed' implies the intended polling/tick use case and 'Needs a key' flags a prerequisite, so usage is inferable. However, no alternative sibling is named and there is no when-not guidance, so the agent must guess between this and tilla_latest/tilla_window for adjacent needs.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context the annotations do not: that no API key/authentication is required. It stops short of saying whether the data is static or cached.

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 zero filler, and the most decision-relevant fact (what you get) is front-loaded before the auth note. 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?

For a zero-parameter, read-only public endpoint with no output schema, the description conveys enough to call it correctly and to know what the payload covers. Minor gap: it does not say how the tier data is structured or whether it changes over 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?

The tool takes zero parameters, so the baseline is 4; there is nothing the description needs to disambiguate, and schema coverage is 100%.

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

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

Names the specific resource (public plans) and enumerates the fields returned: price, history cap, request limits and size. That is enough to distinguish it from siblings like tilla_usage or tilla_status, though it never states a verb ("returns" / "lists") and never explicitly contrasts 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?

"No API key needed" implies this is a safe, unauthenticated call an agent can make up front, but there is no explicit when-to-use or when-not-to-use guidance and no routing to alternatives such as tilla_usage or tilla_about. Usage is inferable 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 the safety profile (readOnly, idempotent, non-destructive), so the description's real contribution is 'Needs TILLA_API_KEY' – an authentication prerequisite not captured by annotations, which is exactly the kind of context that matters. It also signals the data is current rather than cached, but says nothing about failure behavior if the key is missing or invalid.

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 clauses with zero filler: the return contents come first, the auth prerequisite second. Every phrase carries 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 no output schema, the description correctly takes on the job of naming the returned fields, and with zero parameters and full annotation coverage there is little else required. It could still note the response shape or units (how 'limits' and 'used today' are expressed) for an agent that needs to parse the result.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. The description does not waste words on arguments, which 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 resource ('the caller's plan and budget right now') and enumerates exactly what it returns: tier, history days, limits, used today. That field list separates it from siblings like tilla_tiers (presumably a tier catalogue) and tilla_status, though no sibling is named 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?

Usage is only implied: the mention of 'limits' and 'used today' suggests a quota/headroom check, and 'right now' implies a freshness-sensitive call. There is no explicit when-to-use, no when-not-to-use, and no routing to tilla_tiers or tilla_status as 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 read-only, idempotent, non-destructive and open-world, and the description adds materially new operational facts: an API key requirement ('Needs TILLA_API_KEY'), a hard cap ('limit <= 50000'), UTC-only timestamps, inclusive bounds, and a continuation mechanism via `more`/`next_start`. It does not describe what an individual bar looks like or how deep/node layers differ behaviorally, which is the remaining transparency gap for a no-output-schema tool.

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

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

Purpose and payload-shape are front-loaded, and nearly every clause carries a fact an agent needs (formats, caps, pagination, auth). The dense bullet-in-prose formatting and mid-sentence line breaks make it slightly harder to scan than a cleanly segmented list would be, but there is no filler.

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

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

For a 9-parameter, zero-required tool with no output schema, the description covers query modes, formats, limits, auth and continuation, which is what a caller needs to avoid malformed calls. The residual gap is the response shape itself — no output schema exists and the description never states what a returned bar contains or how `layer` changes it, leaving the caller to discover the payload structure after the 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 coverage is 0% and the description compensates almost entirely: it enumerates layer values (raw|derived|node|deep), lane values (1min, 5min, hour, daily, ...), the accepted timestamp format ('YYYY-MM-DD[ HH:MM[:SS]]' UTC inclusive), period syntax (30d, 2m, 6m, 1y, all), series wildcard patterns and the 200-name cap, the markets+fields cross-product with a worked example, and the limit ceiling. This is far beyond what the bare JSON schema conveys and resolves the mutual exclusivity of the two selection modes.

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

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

States a concrete resource ('a window of bars') with the selectable axes (layer, lane, time range, series/markets+fields), so the agent knows exactly what a call yields. It does not name or contrast any of the close siblings (tilla_latest, tilla_tick, tilla_sample, tilla_market), so the agent must infer the boundary between a window query and a single-point/latest query.

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 operative selection rules: 'Name exactly what you want, one of: series ... or markets + fields', start/end versus period, and 'no start = the newest bars'. It also documents the pagination loop ('When `more` is true, call again with start = `next_start`'). What it lacks is any exclusion guidance against the sibling tools, so a caller choosing between tilla_window and tilla_latest gets no explicit steer.

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