Dryos

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

Annotations already declare the operation read-only, idempotent, and non-destructive. The description adds concrete behavior beyond those hints: values are distinct, ordered by frequency, search is a case-insensitive substring, and limits are constrained to 1–500. It also signals the output can be used as filter values, which is useful for downstream planning.

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 in a single line, followed by a tight argument list where every line adds necessary information. There is no filler or repetition of schema defaults.

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 listing tool with an output schema, this is complete: all parameters are covered, safety is fully disclosed by annotations, and cross-tool references fill in syntax details. An agent can invoke it correctly without additional lookup.

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 carries the full burden, and it succeeds. Every parameter gets a meaningful explanation: slug is the stream, column must be a text column from describe_stream, where follows query_stream syntax, search takes column:text format, and limit is bounded 1–500.

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

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

The description states a specific operation: listing the distinct values of one text column, ordered by frequency. It also scopes the resource precisely by saying 'one text column' and 'most rows first', which distinguishes it from generic stream/list tools. The title and description align without tautology.

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

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

It gives explicit routing guidance: columns must come from describe_stream, entities should use find_entities instead, and where syntax matches query_stream's. This tells an agent when to use this tool and which siblings to use for adjacent cases.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds value beyond this by disclosing that the output covers columns, primary key, source, health, and recent collector changes, including the subtle warning that a collector change can affect the data series.

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

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

The description is front-loaded with the core purpose and stays compact. The second paragraph about collector changes is useful but somewhat cryptic ('a step in a series may be one'), preventing a perfect score for clarity of structure.

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 read-only tool with a provided output schema, the description covers what the tool returns, how to obtain the slug, and the relevant behavioral nuance about collector changes. Nothing essential is missing 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 coverage is 0%, but the description compensates with the 'Args' block: it explains slug identifies the stream, gives a concrete example ('ercot-realtime-lmp'), and tells the agent where to get valid slugs (list_streams). This is sufficient for a single simple 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 verb and resource: 'describe_stream' returns one stream 'in full' with every column, primary key, source, and health. It also points to a sibling ('list_streams names them'), distinguishing the tool from a plain list and from query/column 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?

The description gives clear context: use this for complete metadata about one stream, and obtain valid slugs via list_streams. It does not explicitly state when not to use it or name all alternatives, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral details beyond those: search is case-insensitive substring, entity_type allows only one type, limit has a 1-2000 range, and names are verbatim (exact match). It also notes the historical depth aspect. No contradictions with annotations.

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

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

The description is tight and well-structured: a one-sentence purpose, a usage directive, a note on `facets`, then a clean bulleted args list. It front-loads the most critical information (purpose and usage) and keeps each sentence purposeful. No fluff or redundancy.

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 details are already covered. The description supplies everything else needed to call the tool correctly: when to use it, how parameters behave, and the constraint that names are verbatim. It also hints at the `facets` output feature. The description is fully self-sufficient for an agent.

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 carries the full burden for parameter meaning. It explains each parameter with concrete examples: slug (the stream), search (case-insensitive substring with examples like 'HOUSTON'), entity_type (single type with enumerated examples), and limit (max count with range). This goes well beyond the bare schema titles and makes invocation error-prone-free.

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 states the tool looks up nodes, zones, stations, or fuels in a stream, and adds a specific behavior ('with how far back each goes'). It names the resource and verb explicitly, and distinguishes itself from query_stream by positioning itself as a prerequisite. This is a precise, unambiguous purpose.

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 explicit usage guidance: 'Use it before query_stream: names are verbatim and never to be guessed.' This tells the agent when to invoke this tool and why it matters for downstream use. It also mentions `facets` for counting, which aids selection. No alternatives are needed beyond this clear directive.

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 behavior. The description adds that each stream includes an entity column and headline measure, but says nothing about filtering, ordering, 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?

The description is a single short sentence with no filler, front-loading the core content. However, the grammar is awkward and it omits a main verb, making it slightly less clear than it could be.

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 tool with optional filters, the description gives a minimal sense of output but omits parameter meaning and usage context. It has an output schema but the description does not leverage or summarize it sufficiently.

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?

None of the three parameters (domain, search, operator) are described; the description does not explain how they filter or affect results. Since schema coverage is 0%, the description carries the full burden and fails to meet it.

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

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

The title and description together indicate this returns all streams collected by the system, with each stream's entity column and headline measure. It is distinguishable from siblings like describe_stream or query_stream, but the description is a fragment and does not explicitly state 'list' or 'return'.

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 guidance is provided about when to use this tool over find_entities or query_stream, nor about combining the optional filters. The only hint is the title itself.

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, so the safety profile is covered. The description adds valuable behavioral context beyond that: the result carries a restUrl for the same request as a plain GET, the 'stamp' parameter's timezone rationale ('noon labels a daily bucket at noon UTC so its date reads right in US zones'), and the 'vintages' semantics (latest vs all publications). It doesn't describe pagination or error behavior, but for a read-only query tool with strong annotations, this is solid.

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 compact and front-loaded: the first sentence states the core purpose and modes, then the restUrl note, then a tight parameter list. Each parameter line earns its place with a meaningful semantic. It's slightly long (13 parameters) but that's proportionate to the tool's complexity. The only minor issue is that the parameter list is dense and could benefit from grouping (e.g., time parameters vs. aggregation parameters), but it's still highly scannable.

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 13-parameter read tool with an output schema present, the description is nearly complete. It explains the three query modes, the meaning of every parameter, the restUrl return value, and the timezone nuance. The output schema presumably documents the return shape, so the description doesn't need to. Minor gaps: no mention of pagination or how errors surface, and the 'agg' parameter's interaction with 'interval' is implied but not spelled out. Still, an agent has enough to call this correctly in most cases.

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 carries the full burden — and it delivers. Every parameter is explained with concrete semantics: 'start: Inclusive, ISO-8601 or relative to now (-24h, -7d). UTC', 'interval: Bucket size — 5m, 15m, 1h, 1d, 7d, or all for one bucket. Absent means raw rows', 'where: Filters as column=value on text columns. Repeat a column for OR.' This goes well beyond the bare schema types and defaults, giving an agent the exact vocabulary and constraints needed to construct valid calls.

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 opens with a specific verb ('Read rows from a stream') and immediately distinguishes three modes: raw newest-first, per-entity newest, and rollup. It names the resource ('stream') and the key parameter (slug), and the sibling tools (describe_stream, list_streams) are clearly different operations, so an agent can tell this is the data-reading tool without opening the schema.

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

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

The description gives clear context for when to use each mode (e.g., 'newest: One reading per entity — each one's most recent interval, so "the price at every hub right now" is one call. Not with interval.'). It doesn't explicitly say 'use describe_stream for metadata' or 'use list_streams to enumerate streams,' but the mode-level guidance is strong and the sibling names make the alternative obvious. It lacks an explicit when-not-to-use statement, so not a 5.

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