Starwell: World Data & Statistics

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

The description goes well beyond the annotations (readOnlyHint=false) by disclosing that real Python code executes in a sandbox, returns computed output rather than model estimates, includes citations and verification badges, may take 10-40 seconds, requires an API key, and returns key_required without one. No contradiction with the annotation 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?

The description is a single dense paragraph that front-loads the core purpose and then efficiently lists return values, failure mode, latency, and authentication. Each clause contributes useful information, though a bit more structure could improve scannability.

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 (executing code, returning multi-part results), the description covers the essential context: computed vs. estimated, sandbox execution, refusal semantics, latency, and authentication. Without an output schema, this is sufficient to guide an agent's 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?

The schema already provides descriptions for end, start, and series (75% coverage). The description adds meaning for 'series' by explaining it pins exact series and skips AI resolution, but doesn't clarify how end/start constrain the answer or what question formatting is expected. It relies on the schema for 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 clearly states the tool's function with a specific verb ('ask a natural-language question') and a resource ('the served official statistics'). The phrase 'flagship' and the contrast with lower-level sibling tools like get_observations and get_series establish its distinct 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 implies its usage scenario (natural-language queries) and includes a refusal condition when no data can answer. However, it does not explicitly name alternative tools or exclusionary criteria, though the sibling list implies it's the high-level query tool.

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 readOnlyHint annotation (false), the description discloses key behaviors: it runs real Python in a sandbox, pulls from a verified store, takes 60-180 seconds, requires a free API key, and returns 'key_required' for keyless calls. This is rich context about execution environment, performance, and auth failure modes that the annotations alone do not provide. No contradiction with the annotation is present.

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 lengthy but each segment earns its place: purpose, method, output characteristics, latency, usage guidance, and auth requirement. The 'moat' branding is slightly extraneous but not distracting. The structure is clear and information-dense, though it could be tightened slightly.

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 four parameters and no output schema, the description covers the return value in qualitative terms ('decision-ready report', 'every series cited and verification-badged'), the execution environment, timing, auth prerequisites, and failure mode. This is a thorough and self-sufficient description for an agent to select and invoke the tool 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 schema descriptions cover the series parameter ('Optional: pin exact series and skip AI resolution') and date formats, but the description itself adds no detail about start, end, or series parameters. It only references 'a question' in passing. With schema coverage at 75%, the description does not enhance parameter understanding, but the schema is sufficient for a baseline 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 clearly states the tool produces a planned multi-section report with 3-4 orthogonal analyses (trend, statistics, outliers, cross-series relationships) and synthesizes a decision-ready report. It uses specific verbs and resource references, and distinguishes itself from the sibling 'answer' tool by describing its deeper, multi-angle 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 explicitly says to use this tool for 'analyze', 'break down', 'give me a full picture' asks, and to use the answer tool for a single direct question. It also mentions the tool is slower than answer (60-180 seconds), providing clear when-to-use and when-not-to-use guidance with an alternative named.

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 case-insensitive matching, the exact search fields, and the return content (units, coverage, verification status, license, datasetMatches). It also explains the datasetMatches behavior: datasets are requested by source-native id and fetched from the official source on first call, which is valuable context not inferable from the annotation.

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, well-structured, and front-loaded. It opens with the core action, gives concrete examples, lists return fields, and closes with a value statement. Every sentence contributes new information without redundancy or 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?

Even though there is no output schema, the description specifies return fields and the behavior of datasetMatches. It covers search semantics, scope, and use-case, making it self-contained for an agent to select and invoke correctly. The richness of the description compensates for the lack of an output schema.

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 value by elaborating what 'query' searches over (series ids, indicator names, geographies, dataset titles) and provides examples. It also clarifies the effect of 'source' by contrasting 'ALL sources' with the restrictive nature of the parameter. Limit is adequately covered by the schema's default 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 states a specific verb ('Find') and resource ('series catalog'), and goes further by enumerating search fields (series ids, indicator names, geographies, dataset titles) and the cross-source scope ('ALL sources'). This clearly differentiates it from sibling tools like list_datasets and get_series, which have narrower 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 usage context: 'The fastest path from a question to the exact series id to fetch or pin in the answer tool' suggests this is the primary search entry point. It does not explicitly name alternatives or state when-not-to-use, but the positioning is clear enough for an agent to choose it for cross-source series lookup.

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