Starwell: World Data & Statistics

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

Discloses a lot beyond the single annotation: 10-40 second latency, refusal behavior when no served series match, the series_limit error tied to the caller's plan, and the key_required error with instructions for obtaining and passing a free API key. It also explains that share=true creates a permanent public page, consistent with readOnlyHint=false rather than contradicting 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?

Front-loaded with the core purpose and the computed-answer guarantee; each following sentence carries distinct information (cross-source, plan cap, refusal, latency, auth). It is dense and reads as one long run-on block rather than being broken into scannable segments, which costs some readability.

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

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

There is no output schema, so the description carries the return-value burden and does so fully (answer, Plotly chart, Python code, citations, per-series verification badge). Combined with auth requirements, latency, and failure modes, an agent has everything needed to invoke it correctly.

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

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

Schema coverage is high (80%), so the baseline is 3, but the description adds real meaning: it explains that series pins exact series across sources and skips AI resolution, that the joinable-series count is plan-limited, and that share produces a meta.permalink the caller should hand to the user. It does not clarify start/end date semantics beyond the schema's YYYY-MM-DD.

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

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

States a precise verb+resource: answer a natural-language question over served official statistics, returning a computed answer, chart, code, citations, and verification badges. It distinguishes itself from read-oriented siblings like get_series or search_catalog by emphasizing cross-source joins and AI resolution, so an agent can tell what unique role this 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 clear usage context: use it for cross-source joins (e.g. BLS + Statistics Canada + UK ONS in one call), and the optional series param lets callers pin exact series and skip AI resolution. It doesn't explicitly name a sibling alternative or state when NOT to use it, so it stops short of full when/when-not routing.

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

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

The description goes well beyond the readOnlyHint/idempotentHint annotations by disclosing authentication requirements, the https constraint, the trigger condition, and the webhook payload contents (new value, verification status, citation). This gives an agent meaningful operational context for a write operation.

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 concise and well-structured: it front-loads the core action, explains the behavior, lists requirements, and points to related tools—all in three focused sentences with no filler.

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

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

For a simple three-parameter creation tool with no output schema, the description covers purpose, trigger behavior, payload, authentication, protocol, and lifecycle management via siblings. Nothing essential for correctly invoking the tool 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 input schema already fully documents all three parameters with descriptions and examples. The description reinforces that webhookUrl must be https and clarifies what the webhook carries, but it does not add substantial parameter-level semantics beyond the schema. Baseline 3 applies given 100% schema description 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?

Description opens with 'Create a monitor' and states exactly what the tool does: a series.updated webhook fires to the user's URL when the store's refresh lands a new period or revised value. It also distinguishes itself from list_monitors and delete_monitor by mentioning management via 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?

The description clearly conveys the intended use case: monitor a series and receive webhook notifications on updates. It also states prerequisites (API key, https webhook) and points to list_monitors/delete_monitor for management. It does not explicitly discuss alternatives like polling or when not to use this tool, but the usage context is clear.

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

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

The description goes well beyond the sparse annotations: it explains execution in the sandbox, verification badges, cross-agency series joining, slower latency (60-180 seconds), error responses, and API key requirements. There is no contradiction with `readOnlyHint: false`.

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?

Every sentence earns its place: core behavior, output characteristics, error behavior, routing guidance, and auth requirements. The description is dense but well-structured and front-loads what the tool is before diving into operational constraints.

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 complex tool with no output schema, the description covers what matters: the report nature, verification, the sandbox execution model, latency, error cases, and authentication. An agent has enough information to select, invoke, and interpret the result of this 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 75%, so the description still carries some parameter burden. It clarifies the `question` parameter through example phrasings and explains `series` behavior via cross-agency joining and plan-width limits. It does not add detail on `start`/`end` defaults, but the schema already documents their format.

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 a specific capability: a planned multi-section report with 3-4 orthogonal analyses computed via real Python in the sandbox over verified data. It also distinguishes itself from the `answer` sibling by latency and use-case phrasing, so an agent can tell which tool fits.

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 trigger phrases ('analyze', 'break down', 'give me a full picture') and explicitly says to use `answer` for a single direct question. It also discloses the series_limit error for exceeding plan width and the key_required error for missing auth, giving clear routing and failure 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?

Tool has no description.

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?

Tool has no 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?

Tool has no description.

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?

Tool has no 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?

Tool has no description.

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?

Tool has no description.

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, so the safety profile is covered. The description adds meaningful behavioral detail beyond that: every value carries provenance (source URL, retrieval time, connector version) and the envelope includes verification status and citation, which helps set expectations for the return payload.

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 with no redundancy. The core purpose is front-loaded, and the window-control behavior is placed within the same compact 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?

Given no output schema, the description does a good job of summarizing the return shape (values with provenance, envelope with verification/citation). It is adequate for a read-only retrieval tool, though it omits details like ordering, error cases, or how source relates to seriesId.

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 60%, so the description is not the sole source of parameter meaning. It adds useful window-control semantics ('defaults to the latest 60 points' and 'start/end (YYYY-MM-DD)') but says little about the required source and seriesId parameters beyond implying 'one series'.

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 returns observation values for one series, with a specific resource ('observations') and a scope ('one series'). It does not explicitly contrast with related tools like get_series or get_series_stats, so it stops short of full sibling differentiation.

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

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

The description gives concrete usage context: defaults to the latest 60 points and explains how to control the window using start/end or latest. It does not mention when to prefer this tool over siblings, but the window-control guidance is clear and actionable.

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

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

Annotations already declare readOnlyHint=true, and the description adds meaningful context by explaining that verification status comes from golden-value and freshness checks against the live source. This reveals live comparison behavior beyond static metadata lookup and does not contradict 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?

The description is a single well-structured sentence that leads with the core function ('Full metadata for one series') before enumerating contents. Every element earns its place with no filler 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?

With no output schema, the description thoroughly enumerates return contents (fields, verification status, recent checks, citation), giving an agent a solid understanding of the result shape. It could mention error handling or unknown-series behavior, but coverage is strong for a read-only metadata tool with two documented parameters.

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?

Both parameters are fully described in the schema with concrete examples ('fred', 'UNRATE', 'v41690973'), so schema coverage is 100%. The description adds no parameter-level details beyond that, warranting the baseline score of 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 description specifies a unique resource ('metadata for one series') and a clear action, then enumerates the payload components (indicator, unit, frequency, geography, coverage, verification status, check records, citation). This clearly differentiates it from siblings like get_observations and get_series_stats without requiring schema inspection.

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 the tool is for metadata and verification retrieval, giving clear context for when to use it. However, it does not explicitly state when not to use it or name alternatives such as get_observations for data points, 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 mark the tool as read-only. The description adds useful behavioral context: results are computed over the 'verified store,' a citation is attached, and the operation is cheap. These details go beyond the raw readOnlyHint and help set expectations about provenance and cost.

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 output contents and followed by a concise usage rationale. No filler or repetition of schema details; 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?

There is no output schema, so the description carries the burden of explaining what is returned, and it does so by enumerating the statistics and citation. It leaves minor ambiguity about exact response structure but is complete enough for a simple, read-only stats 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 100%, with both parameters described and exemplified. The tool description does not add new meaning about source or seriesId, but it clarifies that these parameters identify the series whose statistics are returned. This is adequate but not additive.

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 exact resource (a series) and the specific statistics returned: latest, previous, min/max, mean, and comparisons. It also distinguishes itself from heavier analysis by billing itself as the 'cheap way' to answer a focused question, separating it clearly from deep_analysis.

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 explicitly frames when to use it: for quickly checking current value and movement 'without a full analysis run.' It does not name sibling alternatives like get_observations, but the use case and cost framing give an agent enough context to select this tool over a heavier analysis.

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 readOnlyHint annotation already covers the safety profile, and the description adds useful output expectations (coverage dates and links to official pages). However, it does not disclose potential pagination, volume limits, or behavior for sources with no datasets; these are minor gaps given the read-only nature.

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, focused sentence with no filler or redundant restatement of the tool name. It front-loads the primary action and resource, then appends the key output details efficiently.

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 tool has only one fully documented required parameter, no output schema, and a readOnlyHint annotation, the description provides sufficient context: what is returned, the scope, and the source input. An agent can correctly select and invoke this tool without missing critical information.

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 input schema fully documents the single 'source' parameter, including an example format ('fred' or 'statcan'). The description reinforces that the tool is scoped to one source but adds no new parameter-level meaning beyond what the schema already 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 uses a specific verb ('List') and identifies the exact resource ('datasets (official releases/tables)') scoped to a single source, which distinguishes it from siblings like list_sources and search_catalog. It also clarifies the output contents: coverage dates and links to official pages.

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 clearly indicates that this tool is for listing datasets within one source, and references 'official releases/tables' to set expectations. It does not explicitly name alternatives or exclusions, but the scope is clear enough that an agent can decide when 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?

The readOnlyHint annotation already signals safety, and the description adds useful behavioral detail by naming the delivery health fields returned (last fired, failures, active). It does not contradict annotations and gives the agent a concrete sense of what the operation reports.

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, well-structured sentence immediately states the resource and API-key scope, then adds the most useful output detail. Every word earns its place and there is no redundant phrasing.

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

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

For a zero-parameter, read-only list tool, the description covers the key information: what is listed and what health attributes are exposed. It does not fully spell out the exact return shape or possible pagination, but the lack of parameters and the simple listing nature keep this gap minor.

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 has zero parameters and the schema coverage is effectively complete, so there is nothing for the description to clarify. The baseline of 4 applies, and the description appropriately avoids inventing parameter-related guidance.

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: listing monitors. It also adds scope ('on your API key') and a meaningful detail about what is included (delivery health), which clearly distinguishes it from sibling list tools like list_sources and list_datasets.

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 provides clear context: this tool is for viewing monitors tied to the caller's API key, including their health status. It does not explicitly mention when not to use it or name alternatives, but the resource-specific wording makes the appropriate use case evident.

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

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

Annotations already declare readOnlyHint=true, and the description adds useful behavioral content about what the response includes: dataset/series counts, cadence notes, and terms links. It does not contradict the annotations and gives enough context for a simple read-only 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?

The description is two sentences, front-loads the core purpose and output contents, and ends with clear starting guidance. Every sentence adds value with no repetition of already-structured annotation data.

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 listing tool with no output schema, the description provides sufficient context: what is listed, what the entries contain, and where this tool fits in the workflow. Nothing critical is missing for an agent to select and invoke it correctly.

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

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

The tool has zero parameters and the schema has no properties, so parameter semantics are trivially satisfied. The description appropriately avoids inventing parameter details that do not exist, matching the baseline for a zero-parameter tool.

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') and resource ('official statistical sources served by this data layer'), with concrete examples (Statistics Canada, FRED) and output details (counts, cadence notes, terms links). It is clear, though it does not explicitly differentiate itself from the sibling list_datasets, so it stops short of a 5.

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

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

The phrase 'Start here to see what exists' gives clear guidance that this is the initial discovery entry point among the sibling tools. It does not state when not to use it or explicitly name alternatives, so it lacks full exclusionary 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?

Beyond the readOnlyHint annotation, the description discloses case-insensitive search behavior, the fields searched, the contents of the returned candidate series (units, coverage, verification status, license), and the special datasetMatches behavior including on-first-call fetching. This gives the agent a clear model of what will happen.

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 with the core capability, followed by a high-value explanation of the return behavior. Every sentence adds useful 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?

With no output schema, the description compensates by summarizing the return shape (candidate series fields and datasetMatches). It provides enough context for an agent to decide and invoke the tool, though it doesn't describe edge cases like empty result behavior or pagination beyond what the schema already covers.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning by explaining that the query is case-insensitive and what fields it matches, plus concrete examples. It doesn't add much about limit/offset/source, but the schema already documents those adequately.

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

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

The description clearly states the verb ('Find'), the resource ('series across ALL sources'), and the exact scope of the search (series ids, indicator names, geographies, dataset titles). It gives concrete examples and explains what is returned, which distinguishes it from siblings like list_sources or get_series.

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 conveys the intended use case clearly: it is the fast path from a question to the exact series id to fetch or pin, and it searches across all sources in one call. It does not explicitly name alternatives or state when not to use it, but the context is strong enough to guide tool selection.

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