Access Statistics Canada data via the Web Data Services API
Scored across 17 tools
Most tools have clearly distinct roles: discovery (search_cubes_by_title, get_all_cubes_list*), metadata (get_cube_metadata, get_code_sets, get_sdmx_structure, get_series_info*), and data retrieval (get_sdmx_data, get_sdmx_vector_data, query_sdmx, get_bulk_vector_data_by_range). The riskiest pairs are the changed-series trio and get_series_info vs get_series_info_from_vector, but descriptions explicitly state the input discriminator (cube+coordinate vs vectorId, release-date vs reference-period). Some overlap remains between the two cube-list tools and search_cubes_by_title, though the descriptions steer selection.
The set overwhelmingly follows a snake_case verb_noun get_*/query_*/search_* pattern (get_cube_metadata, get_sdmx_data, get_series_info_from_vector, search_cubes_by_title). Minor deviations are very long compound names (get_changed_series_data_from_cube_pid_coord) that still follow the same convention, and query_sdmx/search_cubes_by_title break the get_ prefix but remain readable and consistent in style.
17 tools is toward the upper end but justified by a genuinely broad surface: two API families (WDS and SDMX), cube discovery, metadata/structure, change tracking, and multiple data-retrieval strategies. Each tool maps to a distinct endpoint or capability rather than being redundant filler.
Coverage is solid across the lifecycle: find cubes (search/list), inspect structure and metadata (get_cube_metadata, get_sdmx_structure, get_code_sets), resolve vectors (get_series_info*), fetch data (get_sdmx_data, get_sdmx_vector_data, get_bulk_vector_data_by_range, query_sdmx), and track updates (changed cube/series tools). Gaps are minor — no full-table bulk CSV download endpoint and no explicit listing of vector dimensions beyond metadata; agents can work around these via the existing tools.
Provides a complete inventory of data tables available via the API, including dimension-level details. Disables SSL Verification. Corresponds to: GET /getAllCubesList
Results are paginated. Default returns first 100 cubes. Use offset/limit to page through. Prefer search_cubes_by_title if you know what you're looking for.
IMPORTANT: In your final response to the user, you MUST cite the source of your data. For cubes, this means including the ProductId (pid) and the Title.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max cubes to return. Default 100. | |
| offset | No | Number of cubes to skip (for pagination). Default 0. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full weight. It discloses critical behavioral traits: SSL is disabled (a security-relevant warning), results are paginated, and the final response must cite the ProductId and Title. This is exemplary transparency for a listing tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded: it states the core purpose first, then adds endpoint mapping, behavioral notes, pagination, alternative, and a final citation requirement. Every sentence contributes new information without redundancy. It is compact yet complete.
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?
Despite the lack of annotations and output schema, the description covers all essential operational aspects: what the tool returns, pagination with defaults, the SSL warning, the preferred alternative, and citation requirements. For a list endpoint with only two parameters, this is remarkably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents both parameters (limit and offset) with defaults and descriptions. The description only reiterates the pagination pattern already captured in the schema, adding no new semantic meaning. Baseline 3 is appropriate because the schema handles parameter semantics completely.
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 provides a complete inventory of data tables with dimension-level details, and it explicitly distinguishes itself from the sibling search_cubes_by_title by positioning itself as the broad-list alternative. The specific verb 'provides' and resource 'data tables' make the purpose 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 clear usage context: it is for browsing the full inventory, with pagination instructions. It explicitly says to prefer search_cubes_by_title when looking for a specific cube, providing an alternative. This exceeds the minimum and fully clarifies when to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Provides a complete inventory of data tables available via the API, excluding dimension or footnote information (lighter version). Disables SSL Verification. Corresponds to: GET /getAllCubesListLite
Results are paginated. Default returns first 100 cubes. Use offset/limit to page through. Prefer search_cubes_by_title if you know what you're looking for.
IMPORTANT: In your final response to the user, you MUST cite the source of your data. For cubes, this means including the ProductId (pid) and the Title.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max cubes to return. Default 100. | |
| offset | No | Number of cubes to skip (for pagination). Default 0. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosure. It reveals important behaviors: disables SSL verification, excludes dimension/footnote info, paginates with defaults, and mandates source citation. However, it omits details about response structure or error semantics, which would further enhance transparency.
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 well-structured: it opens with the main purpose, then key caveats, then pagination details, followed by a clear alternative, and ends with an important citation requirement. Every sentence earns its place, and the information is 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 two-parameter listing tool with no output schema, the description is complete. It covers the tool's scope (inventory of tables), exclusions (dimension/footnote), pagination behavior, a relevant alternative, and a required citation practice. No critical gaps remain.
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 description only reinforces the existing parameter documentation (offset/limit for pagination). It adds no new meaning beyond the schema's own descriptions, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's primary function: 'Provides a complete inventory of data tables available via the API', and differentiates it from siblings by noting it excludes dimension/footnote information ('lighter version'). It also explicitly mentions the corresponding endpoint, reinforcing its specific 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 provides explicit usage guidance by stating 'Prefer search_cubes_by_title if you know what you're looking for,' which names an alternative and gives a clear condition for choosing it. It also explains pagination usage with offset/limit, giving actionable context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetches bulk data for multiple vectors filtered by release date range (YYYY-MM-DDTHH:MM), NOT by reference period. Use this when you want data released within a specific date/time window (e.g., "all updates released yesterday").
*** IMPORTANT: release date vs reference period ***
Use THIS tool when you want: "data released between date A and date B"
Use get_sdmx_vector_data (startPeriod/endPeriod) when you want: "data for the time period YYYY to YYYY" get_sdmx_vector_data is more reliable and filters by reference period, not release date.
*** LARGE RESPONSE WARNING *** This tool can return hundreds of flattened data points. If the response exceeds context limits, narrow the request: use fewer vectorIds, or use offset/limit pagination to page through results in smaller chunks.
Response is pre-flattened: each element is one data point with vectorId, productId, coordinate, and all value fields injected at the top level.
Disables SSL Verification. Corresponds to: POST /getBulkVectorDataByRange
Returns: List[Dict[str, Any]]: Flat list of data point dicts, each tagged with vectorId, productId, and coordinate. Raises: httpx.HTTPStatusError: If the API returns an error status code. ValueError: If the API response format is unexpected or no vectors return SUCCESS. Exception: For other network or unexpected errors.
IMPORTANT: In your final response to the user, you MUST cite the source of your data. For vector data, this means including the VectorId and Release Time.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max rows to return. Default 50. Set higher to get more rows. | |
| offset | No | Number of rows to skip (for pagination). Default 0. | |
| vectorIds | Yes | List of integer vector IDs (e.g. [42076, 41690973]). | |
| endDataPointReleaseDate | No | ||
| startDataPointReleaseDate | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses that SSL verification is disabled, describes the response pre-flattened format, lists all raised exceptions (HTTPStatusError, ValueError, Exception), and mandates citing VectorId and Release Time in responses. This is thorough for a read-only data fetch tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively long but every section adds value: warnings about release-date confusion, large responses, SSL, return format, exceptions, and citation requirement. The use of headings and bullet points improves scannability, making the length justified.
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 is fully self-contained for a complex tool: it explains the core distinction from siblings, the response structure, error conditions, pagination advice, and a mandatory citation rule. Since there is no output schema and no annotations, this description provides all necessary context 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?
Schema description covers 60% of parameters (limit, offset, vectorIds). The description adds crucial semantic clarity for the two date parameters (start/endDataPointReleaseDate) by explaining they are release dates formatted as YYYY-MM-DDTHH:MM, and clarifies how limit/offset relate to pagination. This compensates well for the schema gap.
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 fetches bulk data for multiple vectors filtered by release date range, explicitly distinguishing it from get_sdmx_vector_data which filters by reference period. The verb 'fetches' is specific and the resource/scope is well-defined.
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 explicit guidance on when to use this tool (data released within a date/time window) versus when to use get_sdmx_vector_data (reference period), and even notes that get_sdmx_vector_data is more reliable. It also warns about large responses and recommends narrowing with fewer vectorIds or using offset/limit pagination.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the list of data tables/cubes that were updated on a specific date (YYYY-MM-DD). Disables SSL Verification. Corresponds to: GET /getChangedCubeList/{date}
Returns: List[Dict[str, Any]]: A list of dictionaries describing changed cube objects.
IMPORTANT: In your final response to the user, you MUST cite the source of your data. For changed cubes, this means including the ProductId (pid) and Title.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses important behavioral traits including disabled SSL verification, the corresponding REST endpoint, and a mandatory citation requirement with ProductId and Title. With no annotations provided, this information is valuable for safe and correct use.
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 well-structured with a clear lead sentence, endpoint mapping, return type, and an important usage note. Every line contributes meaningful information without 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?
For a simple one-parameter GET tool, the description adequately covers the operation, return type, and data attribution requirements. It lacks explicit alternative guidance and error handling details, but is otherwise complete for the tool's complexity.
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 only specifies a date string, while the description adds the required format (YYYY-MM-DD) and clarifies that the date refers to the update date. This compensates for the 0% schema coverage and provides essential context for the single parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a list of data tables/cubes that were updated on a specific date, using a specific verb and resource. The 'changed' qualifier distinguishes it from sibling tools like get_all_cubes_list and get_changed_series_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for date-specific changed cubes but does not explicitly mention alternatives or when not to use this tool. There is no direct comparison with sibling tools such as get_all_cubes_list or get_changed_series_list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves changed series data (data points that have changed) using Cube ProductId and Coordinate string. Coordinates are automatically padded to 10 dimensions. Disables SSL Verification. Corresponds to: POST /getChangedSeriesDataFromCubePidCoord
Returns: Dict[str, Any]: A dictionary containing the changed series data object. Raises: httpx.HTTPStatusError: If the API returns an error status code. ValueError: If the API response format is unexpected or status is not SUCCESS. Exception: For other network or unexpected errors.
IMPORTANT: In your final response to the user, you MUST cite the source of your data. For changed series data, this means including the VectorId, ProductId (pid), and Coordinate.
| Name | Required | Description | Default |
|---|---|---|---|
| productId | Yes | ||
| coordinate | Yes | Coordinate string (e.g., '1.1'). Padding to 10 dimensions is handled automatically. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses several notable behaviors: automatic padding to 10 dimensions, disabling SSL verification, the return type (Dict[str, Any]), and specific exceptions (httpx.HTTPStatusError, ValueError, Exception). It also includes an important citation requirement for the final response. This is strong transparency for a read operation, though it does not mention any potential side effects or permission requirements.
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 well-structured and appropriately sized for a tool with error handling and usage notes. It starts with the core purpose, then lists the endpoint, return type, exceptions, and an important usage note. The only redundancy is the coordinate padding mention, which also appears in the schema, but this does not significantly detract from the overall clarity.
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 tool with no output schema and no annotations, the description provides a good amount of context: it explains the purpose, endpoint, return type, error conditions, and a critical citation requirement. It lacks a concrete example of the return value and does not discuss rate limits or pagination, but given the tool's simplicity and the presence of exception documentation, it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%, with coordinate having a description but productId having none. The tool description adds semantic meaning by clarifying that productId is a 'Cube ProductId' (a cube identifier) and mentions coordinate padding, which partially compensates for the schema gap. However, it does not explain how to obtain or validate productId, leaving some ambiguity. The coordinate format is already covered in the schema, so the description adds limited extra value.
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 action: 'Retrieves changed series data (data points that have changed) using Cube ProductId and Coordinate string.' This is a specific verb and resource, and the mention of using both ProductId and Coordinate distinguishes it from sibling tools like get_changed_series_data_from_vector and get_changed_series_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by specifying the input method (ProductId and Coordinate) and references the corresponding POST endpoint. However, it does not explicitly state when to use this tool over alternatives such as get_changed_series_data_from_vector, nor does it provide exclusions or alternative suggestions. The guidance is mostly implicit from the tool name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get changed series data (data points that have changed) for a series identified by Vector ID. Disables SSL Verification. Corresponds to: POST /getChangedSeriesDataFromVector
Returns: Dict[str, Any]: A dictionary containing the changed series data object. Raises: httpx.HTTPStatusError: If the API returns an error status code. ValueError: If the API response format is unexpected or status is not SUCCESS. Exception: For other network or unexpected errors.
IMPORTANT: In your final response to the user, you MUST cite the source of your data. For changed series data, this means including the VectorId.
| Name | Required | Description | Default |
|---|---|---|---|
| vectorId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and discloses key behaviors: it 'Disables SSL Verification,' notes the HTTP endpoint, specifies return type, and lists possible exceptions. It also includes an important instruction about citing the VectorId, which is useful context beyond basic functionality.
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 well-structured with sections for purpose, endpoint, returns, raises, and an important note. It is slightly verbose but each sentence serves a purpose, though the phrase 'data points that have changed' is redundant with the tool name.
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 tool with one parameter, no annotations, and no output schema, the description covers purpose, security behavior, endpoint, return type, exceptions, and a usage instruction. It lacks parameter semantics and detailed return structure, but overall provides a solid context for invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description does not explain the 'vectorId' parameter beyond its name. It repeats 'Vector ID' without providing details on format, range, or how to obtain it, adding no semantic value over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get changed series data (data points that have changed) for a series identified by Vector ID,' specifying a distinct verb, resource, and identifier. It differentiates from siblings like get_changed_series_data_from_cube_pid_coord, which uses a different identification method.
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 no guidance on when to use this tool versus alternatives, nor mentions any sibling tools or exclusions. It only describes the operation itself, leaving the agent to infer applicability from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the list of series (vectorId, productId, coordinate, releaseTime) updated today. Statistics Canada publishes this list after 08:30 ET; the endpoint does not accept a date. For a historical release date, use get_changed_cube_list(date) to list the cubes updated on that date. Disables SSL Verification. Corresponds to: GET /getChangedSeriesList
Returns: List[Dict[str, Any]]: A list of dictionaries describing changed series objects. Raises: Exception: If the API returns an unexpected status code or network error. ValueError: If today's list has not been released or the response format is unexpected.
IMPORTANT: In your final response to the user, you MUST cite the source of your data. For changed series, this means including the VectorId.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden, and it discloses important traits: the 08:30 ET publication timing, no date parameter, disabled SSL verification, and specific error conditions. It does not cover authentication or rate limits, but for a simple read-only list endpoint it provides substantial operational context.
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 tool's purpose, followed by timing and alternative guidance, then return and error behavior. The Returns/Raises sections are somewhat boilerplate, but they still add useful information for an agent and do not overwhelm the core instructions.
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 with no annotations or output schema, the description is complete: it states what is returned, which fields are included, when the data is available, what error conditions exist, and a citation requirement. Nothing critical is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero parameters, so there are no parameter semantics to explain and the baseline is 4. The description appropriately reinforces that the endpoint does not accept a date, which is useful because callers might otherwise expect one.
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: get the list of series updated today, with the exact fields vectorId, productId, coordinate, and releaseTime. It also distinguishes the tool from get_changed_cube_list by explaining that this one is for series while the sibling is for historical cube dates.
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 explicitly says the list is for today, that the endpoint does not accept a date, and that a historical release date should use get_changed_cube_list(date). That gives both the use case and the concrete alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves definitions for various code sets used by the API (e.g., frequency, units of measure). Corresponds to: GET /getCodeSets
Returns: Dict[str, Any]: Dictionary containing code set definitions (scalar, frequency, etc.). Raises: httpx.HTTPStatusError: If the API returns an error status code. ValueError: If the API response format is unexpected. Exception: For other network or unexpected errors.
IMPORTANT: In your final response to the user, you MUST cite the source of your data. For code sets, this means specifying which code set table or definition is being used.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses return type and possible exceptions (httpx.HTTPStatusError, ValueError) and a citation requirement, but does not explicitly state read-only behavior or any auth requirements.
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 moderately sized with a clear first sentence and structured sections for returns/raises/notes. It is not overly verbose but includes standard exception boilerplate.
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 lack of annotations and output schema, the description provides return type and error types, but does not detail the dictionary structure or list available code sets, leaving some gaps for a complete understanding.
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 has 0 parameters, so baseline is 4. The description adds no parameter-specific information, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Retrieves definitions for various code sets used by the API' with examples, making the purpose unambiguous and distinguishing it from sibling tools that deal with cubes, tables, or SDMX.
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 no explicit when-to-use guidance or alternative tools, though the purpose implies usage for code set definitions. No exclusions or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves detailed metadata for a specific data table/cube using its ProductId. Includes dimension info, titles, date ranges, codes, etc. Disables SSL Verification. Corresponds to: POST /getCubeMetadata
Start with summary=True (default). The summary strips noise (French translations, archive codes, footnotes) and shows only 3 sample members per dimension with _next_steps guidance. Safe for all context window sizes. Set summary=False only if you need the full raw member list or all API fields.
To browse dimension codes for get_sdmx_data key construction, use get_sdmx_structure. To resolve a coordinate to a vectorId, use get_series_info.
Returns: Dict[str, Any]: The metadata object for the specified cube on success. Raises: httpx.HTTPStatusError: If the API returns an error status code. ValueError: If the API response format is unexpected or status is not SUCCESS. Exception: For other network or unexpected errors.
IMPORTANT: In your final response to the user, you MUST cite the source of your data. For cubes, this means including the ProductId (pid) and the Title.
| Name | Required | Description | Default |
|---|---|---|---|
| summary | No | When True (default), returns a compact summary: essential cube metadata, dimension names, 3 sample members per dimension, and _next_steps guidance. Set to False only when you need the full raw member list or all API fields. | |
| productId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses a notable behavior: 'Disables SSL Verification.' It also explains the summary mode's behavior (strips French translations, shows 3 sample members, adds _next_steps) and explicitly warns about safe context window sizes. It lists exceptions and even adds a mandatory citation instruction. While it could explicitly state read-only intent, the retriever verb and non-mutating nature are clear enough.
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 reasonably sized for the tool's complexity and front-loaded with the primary purpose. Each section (endpoint mapping, summary guidance, alternatives, return/raises, citation note) adds value. It is slightly verbose with repetitive emphasis (e.g., summary=True repeated), but overall well-organized and efficient.
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 and no annotations, the description compensates well. It describes the return type (Dict[str, Any]), explains the summary vs. full modes, lists exceptions, and provides situational guidance (e.g., safe for all context window sizes). The mention of _next_steps guidance and citation requirements gives operational completeness. Nothing essential is missing for an agent to invoke and use 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?
Schema description coverage is only 50% (summary is described, productId is not). The description goes beyond the schema by thoroughly explaining the summary parameter: 'strips noise (French translations, archive codes, footnotes) and shows only 3 sample members per dimension with _next_steps guidance.' The productId parameter is only mentioned as 'using its ProductId', but the endpoint mapping and citation note ('including the ProductId (pid) and the Title') give additional context. Given the strong added meaning for summary, this is above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear statement of purpose: 'Retrieves detailed metadata for a specific data table/cube using its ProductId.' It lists specific content (dimension info, titles, date ranges, codes) and maps to a concrete endpoint (POST /getCubeMetadata). Sibling differentiation is also explicit via references to get_sdmx_structure and get_series_info, making it easy to distinguish from related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: 'Start with summary=True (default)... Set summary=False only if you need the full raw member list or all API fields.' It also names alternatives for adjacent tasks: 'To browse dimension codes... use get_sdmx_structure. To resolve a coordinate to a vectorId, use get_series_info.' This covers both usage context and exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch filtered time-series observations from a StatCan table via SDMX REST.
Filtering is done server-side — only the requested slice is returned. Call get_sdmx_structure first to see dimension positions and valid codes.
Key syntax (dot-separated codes in dimension position order): "1.2.1" = Geography=1 (Canada), Gender=2 (Men+), Age=1 (All ages) ".2.1" = all geographies, Gender=2, Age=1 (wildcard — preferred for multi-geo) "1+2.2.1" = Geography 1 or 2, Gender=2, Age=1 (OR)
IMPORTANT — key position codes:
Use member IDs from get_cube_metadata(), NOT SDMX codelist positions from get_sdmx_structure(). Member IDs and SDMX codelist codes are the same numbers.
Wildcard (omit a position) returns EVERY member of that dimension, including totals and parent aggregates — on large dimensions (e.g. 309 NOC occupations) that can exceed the 500-row cap here; use query_sdmx or fetch_sdmx_to_database instead.
To sum or rank across a hierarchy without double-counting totals, use leaf codes: get_sdmx_key_for_dimension(productId, dimension_position) returns them as an OR key.
Time filtering (use one or the other, not both): lastNObservations=12 → last 12 periods (e.g. 1 year of monthly data) startPeriod="2020" → from 2020 onwards (annual); "2020-01" for monthly endPeriod="2023-12" → up to Dec 2023
LIMITATION: StatCan rejects combining lastNObservations with startPeriod/endPeriod (returns 406).
Output rows contain: dimension values, "period", "value", SCALAR_FACTOR, UOM, VECTOR_ID, STATUS, and other SDMX attributes.
Rows are returned inline, capped at MAX_SDMX_ROWS (500). For larger result sets, narrow the key or use startPeriod/endPeriod/lastNObservations.
IMPORTANT: In your final response to the user, you MUST cite the source of your data. This means including the _sdmx_url, table information and productId/key in your response.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Dot-separated dimension codes in position order (e.g. '1.2.1'). Use '+' for OR ('1+2.2.1' = Geography 1 or 2). Omit a value for wildcard ('.2.1' = all geographies, Gender=2, Age=1). Code numbers match WDS memberIds — no translation needed. Call get_sdmx_structure first to see dimension positions and valid codes. | |
| endPeriod | No | End period in YYYY or YYYY-MM format. | |
| productId | Yes | ||
| startPeriod | No | Start period in YYYY or YYYY-MM format. | |
| lastNObservations | No | Return only the last N observations per series (e.g. 12 for one year of monthly data). |
| Name | Required | Description |
|---|---|---|
| data | Yes | Observation rows: dimension columns, period, value, and SDMX attributes. |
| _message | No | Truncation guidance, when truncated. |
| _sdmx_url | Yes | SDMX request URL — cite as the data source. |
| row_count | Yes | Total rows returned by StatCan (before truncation). |
| _truncated | Yes | True if data was capped at 500 rows. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the readOnly/openWorld annotations: server-side filtering semantics, the 500-row MAX_SDMX_ROWS cap, the wildcard behavior that includes totals and parent aggregates, and the concrete 406 error when lastNObservations is combined with startPeriod/endPeriod. It also lists the columns returned, so the agent knows what to expect.
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 purpose, then organized into labeled sections (key syntax, time filtering, limitation, output), which makes the length scannable. It is somewhat long and the closing citation mandate is boilerplate, but nearly every section carries decision-relevant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers key construction, time filtering, limits, and error conditions thoroughly, and an output schema exists so return-value detail is not required. The one material omission is how to discover the required productId, which an agent needs before it can call the tool at all.
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 description adds substantial meaning over the 80%-covered schema: concrete key examples for positional, wildcard, and OR syntax, the member-ID-vs-codelist warning, and leaf-code guidance via get_sdmx_key_for_dimension. The gap is productId, which is required but has no schema description and no explanation in the description of what it is or where to get it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Fetch filtered time-series observations from a StatCan table') plus the transport (SDMX REST), which cleanly separates it from siblings like get_sdmx_vector_data and get_cube_metadata. An agent can identify the operation without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a clear prerequisite ('Call get_sdmx_structure first') and explicitly routes large result sets to query_sdmx or fetch_sdmx_to_database, which is strong when-to-use guidance. However, it never explains how to obtain the required productId (presumably via search_cubes_by_title/get_all_cubes_list), and it names fetch_sdmx_to_database, which is not among the listed siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return all leaf member IDs for a single dimension as a ready-to-use OR key string.
Use this before get_sdmx_data when a dimension has many codes (e.g. 162 NOC minor groups, hundreds of CMA geographies). Avoids the need to call get_cube_metadata and manually parse a large JSON response.
Leaf codes are codes with no children — the lowest-level members in a hierarchy. For flat (non-hierarchical) codelists every code is a leaf.
Example: get_sdmx_key_for_dimension(productId=98100452, dimension_position=6) → { "dimension_id": "Occupation_...", "dimension_name": "Occupation - Minor group - NOC 2021", "position": 6, "leaf_count": 162, "total_count": 309, "or_key": "7+11+12+13+16+18+21+23+...", "note": "Paste or_key at position 6 in your get_sdmx_data key." }
Then use the or_key directly: get_sdmx_data(productId=98100452, key="7.3.1.1.1.<or_key>.1", ...)
| Name | Required | Description | Default |
|---|---|---|---|
| productId | Yes | ||
| dimension_position | Yes | 1-based position of the dimension in the SDMX key (use get_sdmx_structure to find positions). E.g. position=6 for the 6th dot-separated slot. |
| Name | Required | Description |
|---|---|---|
| note | Yes | |
| or_key | Yes | '+'-joined leaf codes, ready to paste at `position` in the key. |
| position | Yes | |
| leaf_count | Yes | |
| total_count | Yes | |
| dimension_id | No | |
| dimension_name | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the read-only/open-world annotations by defining leaf codes, noting that flat codelists make every code a leaf, and showing the returned fields including leaf_count, total_count, and or_key. It also explains how the or_key should be inserted into a get_sdmx_data key.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose and usage guidance are front-loaded, followed by leaf-code semantics and a concrete example. The example output and follow-on get_sdmx_data usage are directly useful rather than filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter helper with an output schema, the description supplies enough context to call the tool correctly and to use its result in get_sdmx_data. It fills the main semantic gap around leaf membership and key construction.
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 only 50%, so the description must carry more weight. It provides a concrete example using productId and dimension_position and explains that dimension_position is the 1-based slot found via get_sdmx_structure, though productId itself is only demonstrated rather than explicitly defined.
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: return all leaf member IDs for a single SDMX dimension as an OR key string. It clearly distinguishes this tool from get_sdmx_data, get_cube_metadata, and get_sdmx_structure by explaining its preparatory role.
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 explicitly says to use this before get_sdmx_data when a dimension has many codes, and explains that doing so avoids calling get_cube_metadata and parsing a large JSON response. The schema also points agents to get_sdmx_structure for finding dimension positions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the Data Structure Definition (DSD) for a StatCan table via SDMX REST.
Returns dimension codelists with code IDs, names, and parent hierarchy. Use this BEFORE get_sdmx_data to understand the key syntax for that table.
Each dimension entry includes:
id: dimension identifier (e.g. "Geography")
position: its slot in the dot-separated key string (1-based)
codelist: the SDMX codelist ID (e.g. "CL_Geography")
codes: list of {id, name, ?parent} — truncated to 10 for large codelists
_code_count / _truncated: total size and truncation flag
Key construction rules:
"1.2.1" = position-1 code 1, position-2 code 2, position-3 code 1
".2.1" = wildcard position 1 (all geographies), Gender=2, Age=1
"1+2.2.1" = Geography 1 or 2 (OR syntax)
WDS memberIds == SDMX codelist codes — no translation needed
IMPORTANT: In your final response to the user, you MUST cite the source of your data. This means including the _sdmx_url.
| Name | Required | Description | Default |
|---|---|---|---|
| productId | Yes |
| Name | Required | Description |
|---|---|---|
| name | Yes | |
| _sdmx_url | Yes | |
| productId | Yes | |
| dimensions | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint and openWorldHint already declared, the description adds genuinely new behavior: large codelists are truncated to 10 codes and flagged via _code_count/_truncated. That truncation caveat is exactly the kind of trap an agent needs warned about. It stops short of noting error/failure behavior or whether truncation can be bypassed.
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 purpose and the usage rule, then well-structured bullets for the return shape and key syntax. The trailing IMPORTANT citation mandate is useful but slightly off-topic for tool selection and adds bulk; otherwise nearly every line 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?
An output schema exists, yet the description still supplies the key-construction grammar ("1.2.1", wildcards, "1+2.2.1" OR syntax, WDS/SDMX code equivalence) that no structured field conveys, which is the critical missing piece for downstream use. The productId meaning and truncation escape hatch remain unexplained, so it's strong but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% — the single productId parameter has only a bare type and no description. The description refers to "a StatCan table" but never states that productId is that table's product ID or where to obtain it (e.g., from get_all_cubes_list or search_cubes_by_title). It compensates only indirectly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Fetch the Data Structure Definition (DSD) for a StatCan table via SDMX REST") and names the exact deliverable (dimension codelists with code IDs, names, hierarchy). This distinguishes it cleanly from get_sdmx_data, query_sdmx, and get_sdmx_key_for_dimension.
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?
Explicitly says "Use this BEFORE get_sdmx_data to understand the key syntax for that table," naming the alternative and the sequencing condition. An agent can decide between this and get_sdmx_key_for_dimension / query_sdmx without further inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch time-series observations for a single StatCan vector via SDMX REST.
Simpler alternative to get_sdmx_data when you already know the vectorId. Use get_series_info_from_cube_pid_coord or get_cube_metadata to find vectorIds.
Time filtering (use one or the other, not both): lastNObservations=5 → last 5 periods startPeriod="2020-01" → from Jan 2020 (monthly); "2020" for annual endPeriod="2023-12" → up to Dec 2023
LIMITATION: StatCan rejects combining lastNObservations with startPeriod/endPeriod (returns 406).
Output rows contain: dimension values, "period", "value", SCALAR_FACTOR, UOM, VECTOR_ID, STATUS, and other SDMX attributes.
IMPORTANT: In your final response to the user, you MUST cite the source of your data. This means including the _sdmx_url,and vectorId in your response.
| Name | Required | Description | Default |
|---|---|---|---|
| vectorId | Yes | ||
| endPeriod | No | End period in YYYY or YYYY-MM format. | |
| startPeriod | No | Start period in YYYY or YYYY-MM format. | |
| lastNObservations | No | Return only the last N observations (e.g. 5 for last 5 periods). |
| Name | Required | Description |
|---|---|---|
| data | Yes | Observation rows: dimension columns, period, value, and SDMX attributes. |
| _message | No | Truncation guidance, when truncated. |
| _sdmx_url | Yes | SDMX request URL — cite as the data source. |
| row_count | Yes | Total rows returned by StatCan (before truncation). |
| _truncated | Yes | True if data was capped at 500 rows. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint/openWorldHint annotations, the description discloses a real failure mode (StatCan returns 406 when lastNObservations is combined with startPeriod/endPeriod) and enforces a one-or-the-other rule. It also lists the output columns and imposes a citation obligation, none of which are derivable from 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?
Front-loads the purpose and the sibling comparison, then uses a clean bulleted block for the time-filter rules. The IMPACT citation paragraph is slightly directive/prompt-like in tone, but every section carries distinct information an agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists and annotations already declare the read-only profile, the description still supplies the missing pieces: how to obtain a vectorId, how to filter by time, the invalid-parameter combination, and what the response rows contain. Nothing an agent needs in order to call this correctly is absent.
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% and the schema already documents endPeriod, startPeriod and lastNObservations. The description adds concrete format nuance not in the schema ("2020-01" for monthly, "2020" for annual) and the mutual-exclusivity constraint between lastNObservations and the period range, leaving only vectorId's integer semantics thin.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (fetch time-series observations), a specific resource (a single StatCan vector), and the access protocol (SDMX REST). It also explicitly distinguishes itself from the sibling get_sdmx_data ("Simpler alternative to get_sdmx_data when you already know the vectorId"), so an agent can route between them without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit precondition for use (already knowing the vectorId) and names the sibling tools that produce that prerequisite (get_series_info_from_cube_pid_coord or get_cube_metadata). It also names the mutually exclusive time-filter options, which is precisely the kind of when/how guidance that prevents bad calls.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve one or more {productId, coordinate} pairs to series metadata (vectorId, titles, frequency, UOM, etc.) in a single API call.
Use this to find vectorIds before fetching data with get_sdmx_data or get_sdmx_vector_data. Pass one item or many — same tool either way. Coordinates are automatically padded to 10 dimensions. Corresponds to: POST /getSeriesInfoFromCubePidCoord (accepts array)
NOTE: Response fields like scalarFactorCode, frequencyCode, and memberUomCode use StatCan numeric codes. Call get_code_sets() to decode them (e.g. frequencyCode 6 = "Monthly", scalarFactorCode 0 = "Units").
Returns: List of series metadata dicts, paginated with _guidance if >50 results. Raises: httpx.HTTPStatusError: If the API returns an error status code. ValueError: If no items return SUCCESS. Exception: For other network or unexpected errors.
IMPORTANT: In your final response cite the ProductId and Coordinate for each series.
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | List of {productId, coordinate} pairs to fetch series info for in a single batch call. | |
| limit | No | Max results to return. Default 50. | |
| offset | No | Number of results to skip (for pagination). Default 0. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it delivers: it discloses batch behavior (one or many), automatic coordinate padding, pagination via _guidance, numeric code decoding requirements, and specific exception types. This goes beyond basic expectations and gives the agent a reliable mental model of the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with sections for purpose, usage, notes, returns, raises, and an important reminder. It is slightly verbose for an agent-facing description, but every section adds meaningful value and no sentences are purely filler, so it earns a 4 rather than a 5.
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?
Despite having no output schema, the description fully explains what the tool returns (list of series metadata dicts, paginated with _guidance) and explicitly lists all error types with conditions. This makes the tool self-contained for an agent to invoke and interpret results correctly, especially with the important note about citing ProductId and Coordinate.
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 item and coordinate descriptions already stating the batch and padding behavior. The description repeats 'Coordinates are automatically padded' and 'Pass one item or many', but adds no new parameter-level semantics beyond what the schema already provides, 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 uses a specific verb ('Resolve') and clearly defines the resource as '{productId, coordinate} pairs' mapped to 'series metadata' including vectorId, titles, frequency, and UOM. It explicitly states the primary use case ('find vectorIds before fetching data'), effectively distinguishing it from sibling tools like get_series_info_from_vector.
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 provides clear context: 'Use this to find vectorIds before fetching data with get_sdmx_data or get_sdmx_vector_data.' This tells the agent when to use the tool, but it does not explicitly mention when not to use it or suggest alternative tools for exclusion scenarios, so it falls short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Request series metadata (productId, coordinate, titles, frequency, etc.) by Vector ID. Disables SSL Verification. Corresponds to: POST /getSeriesInfoFromVector
Returns: Dict[str, Any]: A dictionary containing the series metadata object. Raises: httpx.HTTPStatusError: If the API returns an error status code. ValueError: If the API response format is unexpected or status is not SUCCESS. Exception: For other network or unexpected errors.
IMPORTANT: In your final response to the user, you MUST cite the source of your data. For series info, this means including the VectorId, ProductId (pid), and Coordinate.
| Name | Required | Description | Default |
|---|---|---|---|
| vectorId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full transparency burden. It uniquely discloses 'Disables SSL Verification', documents expected return type, and lists error scenarios. It does not address auth or rate limits, but the safety profile is reasonably conveyed.
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 well-organized with a lead sentence, endpoint, return, exceptions, and a prominent citation note. No filler; each section adds operational value.
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 parameter-light tool with no output schema, the description is thorough: it explains what metadata is returned, the output type, exceptions, transport behavior (SSL), and a mandatory citation requirement. This is sufficient for successful 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 provides only an integer 'vectorId' with no description (0% coverage). The description adds that this ID selects the series and must be cited in the final response, giving it a functional role. It does not explain how to obtain or validate a vectorId.
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 action—requesting series metadata—and identifies the resource/identifier (Vector ID). It also specifies the endpoint, making it distinct from sibling get_series_info even without an explicit comparison.
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 used when you have a Vector ID to fetch metadata, but it does not explicitly state when to prefer it over siblings like get_series_info, nor does it list exclusions/alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch SDMX observations and run ONE read-only SQL query over them server-side,
returning only the query result. Nothing is stored — the data is loaded into a
temporary in-memory table named data and discarded after the query.
*** Use this for compute/compare/rank questions ("which province grew fastest", "average since 2020", "year-over-year change") instead of pulling raw rows with get_sdmx_data and doing arithmetic yourself. It is not limited to 500 rows. ***
Same productId, key and time parameters as get_sdmx_data (see that tool for key syntax and wildcard rules). lastNObservations cannot be combined with startPeriod/endPeriod.
Table data columns: one per dimension (names sanitized: spaces/punctuation → '_'),
"period" (TEXT, e.g. "2024" or "2024-03"), "value" (REAL, NULL = suppressed),
plus SDMX attributes like VECTOR_ID, UOM, SCALAR_FACTOR, STATUS.
Quote mixed-case column names with double quotes.
Example — CPI growth by province since Jan 2020: productId=18100004, key="2+3+5+6.2", startPeriod="2020-01", sql: SELECT "Geography", MAX(CASE WHEN period = '2025-12' THEN value END) / MAX(CASE WHEN period = '2020-01' THEN value END) - 1 AS growth FROM data GROUP BY 1 ORDER BY growth DESC
If the SQL fails, the response includes table_columns — fix the query and retry.
Limits: one statement, SELECT only, ~2s execution time, result capped at 500 rows.
IMPORTANT: In your final response, cite the _sdmx_url, productId and key used.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | Dot-separated dimension codes in position order (e.g. '1.2.1'). Use '+' for OR ('1+2.2.1' = Geography 1 or 2). Omit a value for wildcard ('.2.1' = all geographies, Gender=2, Age=1). Code numbers match WDS memberIds — no translation needed. Call get_sdmx_structure first to see dimension positions and valid codes. | |
| sql | Yes | One read-only SELECT (WITH/CTEs and window functions allowed) against table 'data'. Columns: one per dimension (spaces/punctuation -> '_', e.g. "Products_and_product_groups"), period, value (REAL), VECTOR_ID, UOM, SCALAR_FACTOR, STATUS, etc. Quote mixed-case names: SELECT "Geography", ... | |
| endPeriod | No | End period in YYYY or YYYY-MM format. | |
| productId | Yes | ||
| startPeriod | No | Start period in YYYY or YYYY-MM format. | |
| lastNObservations | No | Return only the last N observations per series (e.g. 12 for one year of monthly data). |
| Name | Required | Description |
|---|---|---|
| rows | Yes | SQL result rows (max 500). |
| columns | Yes | Columns of the SQL result. |
| message | No | Present when the result was truncated. |
| _sdmx_url | Yes | SDMX request URL — cite as the data source. |
| table_columns | Yes | Columns available in table 'data'. |
| fetched_row_count | Yes | Rows loaded into the temporary 'data' table. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true; the description goes well beyond them by disclosing that nothing is persisted, that data lands in a temporary in-memory table named `data` and is discarded, that execution is capped at ~2s and one statement, and that the result is capped at 500 rows while the underlying pull is not. It even documents the failure path: a failed SQL returns `table_columns` so the agent can correct and retry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose and the get_sdmx_data contrast are front-loaded in bold, and the remaining blocks (table shape, example, limits) are chunked rather than buried. It is on the long side and the column list partially repeats the `sql` schema description, but the example and limits each earn their space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained, and the description still covers dialect, column naming, timeouts, row caps, and the retry signal on error. For a six-parameter SQL-execution tool whose main failure mode is a malformed query, nothing an agent needs to call it correctly 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?
Schema coverage is already 83%, yet the description still adds meaning the schema lacks: key/time parameters are declared identical to get_sdmx_data (deferring to that tool for wildcard syntax), the resolved `data` table shape is spelled out with period formats and NULL-as-suppressed semantics, mixed-case quoting is mandated, and a full worked example shows the expected SQL dialect. This substantially lowers invocation errors beyond what the schema conveys.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-plus-resource statement: fetch SDMX observations and run one read-only SQL query server-side, returning only the result. It explicitly distinguishes itself from the sibling get_sdmx_data ('instead of pulling raw rows ... and doing arithmetic yourself'), so an agent can route between them without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It names the exact question class that selects this tool (compute/compare/rank, with three concrete example questions) and the alternative that does not (get_sdmx_data). It also states a hard exclusion — lastNObservations cannot be combined with startPeriod/endPeriod — which is the kind of when-not guidance most definitions omit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Searches for data cubes/tables where the English or French title contains the provided search term (case-insensitive). Returns a list of matching cubes in the 'lite' format (excluding dimensions/footnotes).
Multiple keywords use AND logic (e.g., "tobacco smoking age" finds cubes containing ALL three words). Results are capped at max_results (default 25).
IMPORTANT: In your final response to the user, you MUST cite the source of your data. For cubes, this means including the ProductId (pid) and the Title.
Raises: httpx.HTTPStatusError: If the underlying API call fails. Exception: For other network or unexpected errors during the fetch.
| Name | Required | Description | Default |
|---|---|---|---|
| max_results | No | Max matching cubes to return. Default 25. | |
| search_term | Yes | Text to search for in cube titles. Multiple keywords use AND logic. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It reveals important traits: case-insensitive matching, lite format exclusion, AND logic, result capping, error types, and a mandatory citation requirement. This is substantial coverage beyond the basic search functionality, though it doesn't cover authentication or rate limits.
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 well-structured with distinct paragraphs for purpose, behavior, citation requirement, and errors. Each sentence contributes unique information without fluff or repetition. It is appropriately sized for the complexity.
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 explains the return format (lite format, excluding dimensions/footnotes) and error conditions. It doesn't enumerate the lite format fields, but that is a known concept from sibling tools. The description is complete enough for an agent 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 coverage is 100% with both parameters described, so baseline is 3. The description adds extra semantics for search_term (English/French title, case-insensitive) and reiterates AND logic, which adds value beyond the schema. It also clarifies the default behavior of max_results.
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 'searches' and the resource 'data cubes/tables', specifying that it searches English or French titles case-insensitively. This distinguishes it from sibling tools like get_all_cubes_list_lite, which return full lists without search capability. The scope is 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 provides clear context for when to use this tool: when searching for cubes by title. It explains AND logic and the max_results cap, which informs usage. Though it doesn't explicitly name alternatives, the context is sufficient to guide selection among sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
get_changed_series_list2 fields changedInput schema / properties / dateRemoved value: -{
- "type": "string"
-}Input schema / requiredPrevious value: -[
- "date"
-]New value: +[]get_all_cubes_listget_all_cubes_list_liteget_bulk_vector_data_by_rangeget_changed_cube_listget_changed_series_data_from_cube_pid_coordget_changed_series_data_from_vectorget_changed_series_listget_code_setsget_cube_metadataget_sdmx_dataget_sdmx_key_for_dimensionget_sdmx_structureget_sdmx_vector_dataget_series_infoget_series_info_from_vectorquery_sdmxsearch_cubes_by_titleStatistics Canada (StatCan) WDS MCP — Canadian official statistics (no auth)
Curated gateway to snapshot-versioned Canadian public data services with source provenance.
StatCan MCP — Statistics Canada (StatCan) via the Web Data Service (WDS).
Query and explore Nova Scotia open datasets via the Socrata SODA API.
Add one secure layer between your agents and this server.