Starwell: World Data & Statistics

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

Beyond the readOnlyHint:false annotation, the description discloses many behavioral traits: real Python runs in a sandbox, returns a computed answer (nothing estimated by a model), refusal when no served series can answer, 10-40 second latency, series_limit error, and key_required error for missing API key. This is far richer than the annotation alone.

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 long but information-dense; every sentence provides useful details such as auth, latency, or error modes. It could be improved by using bullets or clearer section breaks, but the content is economical and avoids fluff.

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 description covers crucial operational aspects: authentication (API key, header, environment variable), latency, error types (series_limit, key_required, refusal), return contents, and cross-source joining. It is complete for a complex tool with no output schema, and the absence of an output schema is not a gap because the description names the returned artifacts.

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

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

Schema coverage is 75%, with start/end described as 'YYYY-MM-DD' and series described in the schema. The description adds value by explaining the series limit ('How many series one question may join is set by the caller's plan') and the resulting series_limit error, which is not in the schema. It does not explain start/end defaults, but the schema already provides 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 the tool's purpose: 'ask a natural-language question about the served official statistics' and specifies what it returns (computed answer, Plotly chart, code, citations, verification badge). It distinguishes itself from siblings by positioning as 'the flagship' and highlighting cross-source joining, which other tools like get_observations or get_series do not offer.

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 usage context by explaining when cross-source joins are relevant ('one question may join series from DIFFERENT agencies') and mentions the series limit based on the caller's plan. However, it does not explicitly name alternative tools or state when NOT to use this tool, relying on the sibling list to imply differentiation.

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 mark it as non-read-only and idempotent. The description adds meaningful context: the webhook fires on new or revised series values, includes payload details (value, verification status, citation), and imposes auth and transport constraints (API key required, https only). This goes beyond the structural annotation hints.

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

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

Three sentences front-load the core behavior, then add requirements and management. Every sentence carries distinct information, with no repetition of schema or annotation fields.

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 description explains the trigger condition, payload contents, auth requirement, URL scheme constraint, and management operations, all without an output schema. This is sufficient for an agent to understand the tool's role and constraints for a 3-parameter creation endpoint.

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?

Input schema descriptions cover 100% of parameters with concrete examples ('fred', 'DGS10', https URL). The description adds no new parameter-specific details beyond reiterating https, so the schema is the primary source of parameter semantics.

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

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

The description opens with 'Create a monitor' and specifies the exact triggering condition (new period or revised value) and effect (series.updated webhook to your URL). This distinguishes it from fetch tools like get_series/get_observations and management siblings list_monitors/delete_monitor.

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 indicates this tool is for setting up webhooks and refers to management via list_monitors/delete_monitor. It doesn't explicitly contrast with pull-based alternatives, but the event-driven behavior and requirements (API key, https) provide clear usage context. It lands below a 5 because no explicit 'use when...' guidance or exclusions are stated.

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

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

Beyond the minimal annotation (readOnlyHint: false), the description discloses significant behavioral traits: it runs real Python in a sandbox, cites and verification-badges every number, can join series from different agencies, returns a series_limit error when exceeding plan width, and requires an API key with a specific keyless error (key_required). This substantially exceeds the annotation's coverage.

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 longer than the calibration 'high' example but is densely packed with relevant information. Each sentence contributes to core understanding (what, how, constraints, comparison, authentication). It is front-loaded with the main value and uses semicolons to keep related ideas together, though it could be slightly more 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?

Given the tool's complexity and no output schema, the description covers most key aspects: process, time behavior, error conditions, auth requirements, and comparison to siblings. It lacks a detailed description of the report structure, but 'decision-ready report' gives a reasonable expectation. Overall, it is quite complete for an analysis tool, but a bit more output detail would make it fully self-contained.

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% (start, end, series have descriptions; question does not). The description adds meaningful parameter semantics by explaining the series joining across agencies and the series_limit cap tied to the caller's plan width. It also implies the 'question' parameter is the analysis prompt. This goes beyond the schema's simple type constraints.

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 and resource: 'a PLANNED multi-section report on a question' and details the engine's behavior (designs 3-4 orthogonal analyses, runs Python, synthesizes one report). It clearly distinguishes from sibling tool 'answer' by stating 'use the answer tool for a single direct question.' This is a precise, differentiated 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 explicitly states when to use the tool: 'use it for "analyze", "break down", "give me a full picture" asks' and when not to: 'use the answer tool for a single direct question.' It also provides contextual constraints like plan width limits and slower execution time (60-180 seconds), giving the agent clear decision 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 agent knows it's safe. The description adds valuable behavioral context: every value carries provenance (source URL, retrieval time, connector version) and the envelope includes verification status and citation. It also discloses the default 60-point window and the ability to override it, which is beyond what annotations provide.

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-loaded with the core purpose, then adding concise detail on provenance, verification, and window control. Every sentence contributes value; 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?

Given the tool's simplicity (read-only, 5 params, no output schema), the description covers key aspects: what data is returned (provenance, verification status, citation), default behavior (60 points), and how to control the window. It could mention pagination or response size limits, but the schema already documents the maximum 'latest' value.

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% (start, end, latest have descriptions; source and seriesId do not). The description reinforces the window semantics ('start/end (YYYY-MM-DD) or latest') but does not identify or explain source or seriesId. It partially compensates but does not fully cover all parameters.

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

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

The description clearly states the tool's purpose: 'Observation values for one series.' This is a specific verb+resource pairing that distinguishes it from siblings like get_series (metadata) and get_series_stats (statistics). The additional detail about provenance and verification status further clarifies scope.

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 for use: it retrieves observation values for a single series, with control over the time window via start/end or latest. It does not explicitly state when not to use it or mention alternative tools, but the use case is unambiguous given the sibling names.

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 declare readOnlyHint=true, and the description adds meaningful context by explaining the verification status comes from 'golden-value + freshness checks against the live source' and that recent check records are included. This goes beyond the annotation to inform the agent of the tool's internal behavior without 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?

The description is a single, informative sentence that uses a colon and list to convey a wealth of detail without being redundant. Every item adds value, but it is slightly dense; a more structured presentation could improve scanability.

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 metadata-only tool with two well-described parameters and no output schema, the description thoroughly enumerates the return contents, covering the core aspects (metadata fields, verification status, check records, citation). It does not discuss edge cases or error handling, but these are not essential for this simple retrieval operation.

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 provides complete descriptions for both parameters (source and seriesId) with examples, achieving 100% schema coverage. The tool description does not add additional parameter semantics beyond what the schema already covers, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool returns 'Full metadata for one series' and enumerates specific fields (indicator, unit, frequency, geography, coverage, verification status, check records, citation). This distinguishes it from sibling tools like get_observations (data) and get_series_stats (statistics), establishing a specific verb+resource+scope.

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 use when you need comprehensive metadata and verification details for a single series, but it does not explicitly mention alternatives or scenarios where another tool should be used. There is no exclusion or comparison to sibling tools, though the phrase 'Full metadata' hints at the intended use.

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; the description adds beyond that by disclosing the data source ('verified store'), the presence of a citation, and the specific statistics computed. This is more context than typical, though no details on pagination or edge cases are provided.

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 concise sentences pack all necessary information: the statistics list, data source, citation, and usage guidance. No wasted words and the key facts are front-loaded.

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 tool with two parameters and no output schema, the description covers the return statistics, data scope, citation, and use case. It lacks an explicit return format, but the overall context is sufficient for an AI agent to select and invoke the tool successfully.

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 documents both parameters (source and seriesId) with examples, achieving 100% coverage. The description adds no additional parameter-level meaning, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool computes summary statistics for a series, enumerating the exact statistics included (latest value, previous, min/max, mean, changes). It distinguishes itself from siblings by positioning as a lightweight alternative to a 'full analysis run', making its purpose specific and unambiguous.

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 guidance on when to use this tool: 'the cheap way to answer what is it now and how has it moved without a full analysis run.' It implies alternatives like deep_analysis but doesn't name them explicitly, which prevents a 5 but still provides clear context.

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 indicates a safe read operation, and the description adds valuable context about the output (coverage dates, links to official pages). It does not contradict the annotation and clarifies the scope, though it omits details like pagination or authorization.

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, front-loaded sentence that conveys the purpose, scope, and key output features without any wasted words. It is efficient and immediately informative.

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 list tool with one parameter, a readOnly annotation, and no output schema. The description sufficiently explains what is listed and how it is scoped, making it fully usable for an agent without further elaboration.

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

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

Schema coverage is 100% and the only parameter 'source' is adequately described in the schema as a slug. The description reinforces that the source parameter narrows the listing, but it does not add new semantic detail beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description uses a specific verb 'List' and clearly identifies the resource as 'datasets (official releases/tables) available in one source'. It distinguishes this tool from siblings like list_sources by scoping to datasets within a specific source and mentioning coverage dates and links.

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 'in one source' implies the tool requires a source parameter, but it does not explicitly state when to use this tool instead of search_catalog or list_sources. No exclusions or alternative suggestions are provided, leaving the usage context 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 include readOnlyHint=true, and the description adds scope and return content. It does not discuss pagination, response format, or authentication details, but for a straightforward list operation the provided context is adequate.

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, front-loaded sentence with no wasted words. It efficiently conveys the resource, scope, and return content.

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

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

The tool has no parameters, no output schema, and is a simple list operation. The description covers the essential return content, making it sufficiently complete, though it could have mentioned any default filtering or possible absence of monitors.

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 has zero parameters, so the baseline is 4. The description adds no parameter info, which is appropriate since there are none to describe.

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

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

The description clearly identifies the resource (monitors), the scope (API key), and the included delivery health details (last fired, failures, active). This is specific and distinguishes the tool from siblings like create_monitor and delete_monitor.

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 its use for listing monitors associated with the API key. It doesn't explicitly mention alternatives, but the context is clear and the tool is a simple read-only list, so no exclusions are needed.

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 safe read nature is established. The description adds useful behavioral context by specifying the output includes 'dataset/series counts, cadence notes, and terms links,' and clarifies the scope ('official statistical sources served by this data layer'). This goes beyond the annotation without 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?

The description is two sentences, front-loaded with the main action and resource, followed by a concise list of output contents and a clear directive. No wasted words; every element 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 simple, parameterless list tool with a readOnly annotation, the description fully covers what the tool does, what it returns, and when to use it. No output schema is present, but the description provides enough detail about the returned information to set expectations.

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 is empty (no parameters), which gives a baseline of 4. The description does not need to explain parameter meaning since there are none; it correctly focuses on what the tool returns rather than input requirements.

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 ('List') and specific resource ('official statistical sources served by this data layer'), with concrete examples (Statistics Canada, FRED). It distinguishes itself from sibling tools by focusing on 'sources' rather than datasets, monitors, or catalog search, and positions itself as the entry point.

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 a clear usage context: 'Start here to see what exists.' This implies it is the first tool to use when exploring available data. However, it does not explicitly mention when to use alternatives like list_datasets or search_catalog, so it falls short of fully explicit exclusion 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 that search is case-insensitive, returns specific fields (units, coverage, verification status, license), and includes datasetMatches with fetch-on-first-call behavior. This adds meaningful context about what happens and what is returned, without contradicting 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 front-loaded with the core purpose ('Find series across ALL sources in one call') and is two sentences total. The second sentence is dense but packs essential return details and dataset behavior, justifying its length.

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

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

For a search tool with four parameters and no output schema, the description adequately covers purpose, return contents, datasetMatches semantics, and the fetch-on-first-call behavior. Combined with complete schema documentation, the agent has enough context to invoke the tool effectively.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining that the query parameter searches across series ids, indicator names, geographies, and dataset titles, with concrete examples, which enriches the schema's generic parameter descriptions.

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 finds series across ALL sources in one call, specifying searchable fields (series ids, indicator names, geographies, dataset titles) with examples. It distinguishes itself from sibling tools like get_series and list_datasets by emphasizing cross-source search and the fastest path to a series id.

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 when to use it: for cross-source search and as the fastest path from a question to an exact series id. It does not explicitly name alternatives or state when not to use it, but the context is clear enough to guide an agent.

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