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

No annotations are provided, so the description carries full burden. It explains the tool produces URLs and returns a structured result, but does not explicitly disclose whether any network request is made, whether validation occurs, or any permission requirements. This is acceptable for a URL-building tool but lacks deeper behavioral detail.

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 structured with an Args/Returns format appropriate for an 8-parameter tool. The first two sentences are slightly redundant ('Generate final SDMX REST API URLs...' and 'Creates URLs...'), but they add useful detail about formats and direct download use.

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 moderate complexity, the description covers all parameters, indicates the return type, and situates the tool as the final step in a pipeline. The output schema exists, so detailed return values are less critical. It does not explain every sibling relationship, but enough context is provided.

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 parameter titles with no descriptions (0% coverage), so the description's Args section is essential. It explains each parameter, including the distinction between key and filters, format options, and the endpoint override concept. Some descriptions are brief (e.g., 'Start of time range') but generally sufficient.

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

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

Description states a specific verb ('Generate'), resource ('SDMX REST API URLs'), and purpose ('for data retrieval'). It also positions itself as 'the final step in the SDMX query construction process,' which clearly distinguishes it from siblings like build_key and probe_data_url.

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

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

The description explicitly frames when to use the tool ('final step in the SDMX query construction process') and mentions using build_key() to construct the key, providing a clear alternative. However, it does not explicitly state when NOT to use it or contrast all sibling tools.

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?

With no annotations, the description carries the full burden. It discloses key behaviors: 'Unspecified dimensions are left empty (meaning "all values")' and 'constructs the key string with dimensions in the correct order according to the dataflow structure.' It also mentions the structured result. However, it does not disclose error handling or validation behavior (e.g., what happens if a dimension value is invalid), which would have made it fully transparent. Hence a 4 rather than 5.

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 concise introduction, a key behavioral note, an explicit usage direction, and a formatted Args list. Every sentence adds value; there is no fluff or repetition. It is appropriately sized for a non-trivial helper tool.

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 role as a helper, the description covers its purpose, usage sequence relative to build_data_url, handling of unspecified dimensions, and return value. The output schema exists, so the description need not detail the return structure. It is suitably complete for an agent to invoke it correctly.

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

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

Despite 0% schema description coverage, the description includes an Args section that richly explains each parameter: dataflow_id is 'the dataflow identifier', filters is 'Optional dict mapping dimension IDs to values', agency_id 'uses session endpoint if not specified', and endpoint is explained with examples ('FBOS', 'ECB') and defaulting behavior. This fully compensates for the schema's lack of descriptions.

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

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

The description clearly states 'Build a properly formatted SDMX key from dimension values' and elaborates that it 'constructs the key string with dimensions in the correct order.' This specific verb+resource distinguishes it from sibling tools like build_data_url and validate_query, especially with the explicit 'Use this before build_data_url()' guidance.

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 tells the agent when to use it: 'Use this before build_data_url() to ensure your key has the correct format.' It also clarifies optional endpoint and agency overrides, providing clear context for when to employ the tool versus alternatives. This is strong usage 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?

With no annotations provided, the description carries the full burden. It discloses how the tool works internally (Actual ContentConstraint), its limitation ('The constraint only tells us what CAN'T exist'), and exactly what 'plausible' means ('worth querying', not guaranteed). This is excellent behavioral 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 organized with a lead summary, then methodology, usage, result semantics, and args. Each section is information-dense and the content is front-loaded. No sentence is wasted; the structure makes it easy to scan.

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

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

The description covers the tool's purpose, usage context, result values, parameters, and even notes the return type. Even though an output schema exists, the added context about the three-valued result and its implications makes this complete 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 coverage is 0%, so the description must compensate. It does so thoroughly: the Args section explains every parameter, gives concrete query_period examples ('2010', '2010-Q1', '2010-01'), and clarifies the endpoint/agency_id defaults. This adds significant meaning beyond the bare 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 opens with a specific verb+resource: 'Check whether a specific time period is likely to have data in a dataflow.' It clearly distinguishes this tool from siblings by explaining that it uses the Actual ContentConstraint to rule out impossible periods, and contrasts it with build_data_url() for confirmed availability.

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

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

The description explicitly states when to use it: 'Use after identifying a dataflow and before building a data URL.' It also tells the agent when not to rely on it ('For confirmed availability, query the data directly via build_data_url()'), and explains the meaning of each result value so the agent knows how to act on the output.

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?

With no annotations provided, the description carries the full burden. It discloses default endpoint behavior ('When endpoints are omitted, uses the current session endpoint') and cross-provider support, adding useful context beyond the schema. It does not explicitly state read-only behavior, but 'compare' and the nature of the output strongly imply a non-mutating operation.

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

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

The description is well-structured with a summary, usage guidance, and parameter details. While it is longer than a simple two-liner, each section earns its place—especially the 'When to use' bullets and endpoint behavior. The Args section partially duplicates the schema but adds examples, making it valuable rather than repetitive.

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 an output schema, so return values are covered externally. The description covers when to use, parameter semantics, default endpoint behavior, and cross-provider capability, making it complete for a comparison tool. It lacks explicit error-handling notes or prerequisites, but these are not critical for the tool's primary use case.

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

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

Schema description coverage is 0%, so the description must compensate. It defines each parameter clearly: dataflow_id_a/b as identifiers, endpoint_a/b as optional with examples ('SPC', 'IMF', 'ECB') and explains the fallback to the session endpoint. This adds meaningful semantics beyond the bare schema titles, though it could be even more detailed about ID formats or constraints.

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

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

The description clearly states the tool 'Compare dimension structures across two dataflows to understand how they relate,' which is a specific verb+resource pair. It further details what is returned (shared dimensions, code overlap, time coverage, join columns), distinguishing it from siblings like get_dataflow_structure or compare_structures by focusing on dimensional relationships and join recommendations.

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 'When to use this tool' section explicitly lists three concrete scenarios (after find_code_usage_across_dataflows, combining datasets, checking overlap before queries). It provides clear context for when to use, though it does not explicitly state when not to use it or name alternative tools, which prevents a 5.

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

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

With no annotations present, the description carries the full burden. It explains default behaviors (version_a/b default to 'latest', structure_id_b defaults to same as A for version comparison), how agency_id uses the current endpoint's default, endpoint override semantics, and the return object's type-specific fields. It does not explicitly state that the operation is non-destructive, but 'compare' strongly implies it, and no side effects are hinted.

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 bold headers, a clear overview, per-type sections, a structured Args list, a Returns field list, and examples. It is longer than average but every section is necessary given the 8 parameters and multiple comparison modes. The core purpose is front-loaded, and the markdown formatting aids scanning.

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 complex tool with 8 parameters and multiple structure types, yet the description covers all angles: purpose, type-specific behavior, all parameters with semantics, return fields, and examples. Even though an output schema exists, the description already details the return object structure, making the agent well-prepared to interpret results.

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 types and defaults with 0% description coverage. The description's Args section compensates fully: it explains the meaning and allowed values for structure_type, clarifies that structure_id_b defaults to same as A (a key semantic not in the schema), and describes the endpoint override and agency_id defaults. The examples further illustrate parameter combinations for each type.

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 and resource: 'Compare two SDMX structures to identify differences.' It then provides specialized logic for codelists, DSDs, and dataflows, each with concrete examples like 'What codes changed between CL_GEO v1.0 and v2.0?' This clearly distinguishes it from sibling tools like get_codelist or compare_dataflow_dimensions.

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 'Perfect for:' scenarios for each structure type, telling the agent when to invoke the tool for version comparisons, cross-structure comparisons, and reference checks. It does not explicitly name alternative tools or exclusions, but the context is clear and actionable for each mode.

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?

Since no annotations are provided, the description carries the behavioral disclosure burden. It discloses that the tool performs a bulk search across all constraints in a single API call, explains the difference in behavior when dimension_id is provided vs. omitted, and explicitly notes the provider support limitation ('SPC (Actual), ECB (Allowed), and UNICEF (Actual)') and that others will return an explanatory message. It could explicitly state that the operation is read-only and non-mutating, but the context strongly implies this, making the transparency solid.

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

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

The description is lengthy but meticulously structured with headings, bullet lists, and code examples. The first line states the core purpose immediately. Every section adds value: usage scenarios, workflows, provider support, parameter explanations, and return value summary. No filler or redundancy. The format makes it easy for an agent to quickly extract the needed guidance.

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 moderate complexity (4 parameters, one required, output schema present) and no annotations, the description is remarkably complete. It covers all parameters, workflows, provider limitations, and return value structure. The output schema covers the return contract, so the description's brief mention of the result type is sufficient. The description leaves no major ambiguity about how to invoke the tool and what to expect.

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

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

Schema description coverage is 0%, so the description must compensate, and it does thoroughly. Each parameter is explained with meaning and examples: code ('the specific code to check'), dimension_id (with both provided/omitted semantics), agency_id (defaults to session endpoint), and endpoint (targeting a specific provider). The examples for code and dimension_id ('FJ', 'GEO_PICT') make usage concrete. This far exceeds the bare schema information.

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, specific statement: 'Discover all dataflows that have data for a given code.' It names the tool's resource (dataflows) and verb (find/discover), and it distinguishes itself from sibling tools like get_code_usage by positioning this as the 'starting point' for exploring data existence. The workflow examples further clarify that it searches across all constraints in a single call.

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 'When to use this tool' section provides explicit scenarios with concrete examples (e.g., Fiji, GDP) and directly references an alternative: 'then use compare_dataflow_dimensions() to check how the discovered dataflows relate.' Workflow B explains when to omit dimension_id and when to follow up with get_dataflow_structure(). Provider support limitations are also mentioned, giving clear guidance on when this tool will or won't work.

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?

With no annotations, the description carries the full burden. It explains parameter defaults (agency_id uses session endpoint if not specified, version defaults to 'latest', endpoint defaults to session's current) and the return type (dictionary with codelist information and codes). It does not disclose error behavior or side effects, but for a read-only 'get' operation, this is sufficient.

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 compact docstring with a brief summary, a clarifying sentence on codelists, then structured Args and Returns sections. Every sentence serves a purpose, and it is front-loaded with the core action.

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 output schema exists, the description need not detail return fields. It covers the tool's purpose, all parameters, defaults, and usage context. It could mention error conditions or prerequisites, but for a simple get operation 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?

The description enumerates all five parameters with meanings beyond the bare schema titles: codelist_id identifier, agency_id session behavior, version default, search_term filter, and endpoint override with examples (FBOS, ECB). This fully compensates for the 0% schema description coverage.

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

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

The description states 'Get codes and values for a specific codelist' with a clear verb and resource, and explains that codelists define allowed values for dimensions. It is unambiguous but does not explicitly differentiate from sibling tools like get_dimension_codes, so it misses a top score.

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 says 'Use this to find the exact codes needed for your data query,' providing clear context for when to use the tool. It does not mention when not to use it or name alternatives, so it lacks full usage exclusions.

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?

With no annotations, the description carries full burden. It discloses the internal optimization ('uses the Actual ContentConstraint... WITHOUT iterating through data queries'), behavior for empty codes/dimension, and default endpoint behavior. It stops short of discussing error cases or side effects, but being a read-only check, it is well covered.

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 use cases, args, returns, and examples. It is longer than minimal but each section earns its place. Slightly verbose for a simple tool, but the complexity of parameters justifies the length.

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

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

Given the 5-parameter tool with output schema, the description covers all aspects: purpose, method, use cases, parameter meanings, return structure, and examples. It is fully self-contained and leaves no major gaps for an agent to misuse the tool.

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

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

Schema descriptions are absent (0% coverage), but the Args section explains every parameter with defaults and optionality. For example, 'codes: Optional list... If empty, returns all used codes' and 'endpoint: Defaults to the session's current endpoint.' This fully compensates for 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 opens with a specific verb+resource+scope: 'check if specific codes are actually used in a dataflow's data.' It clearly distinguishes from siblings like find_code_usage_across_dataflows and get_dimension_codes by focusing on usage within a single dataflow efficiently.

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?

Provides concrete use cases with example queries and explicitly notes this avoids 'trial-and-error data requests.' It implies when to use the tool but does not name alternative sibling tools or state when not to use it, so it falls short of a 5.

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

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

With no annotations provided, the description carries the burden of disclosing behavior. It clearly states what the tool returns (endpoint name, URL, agency ID, description) and adds context about multi-user session scoping. It does not mention error cases or authentication, but for a read-only getter this is a minor gap.

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

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

The description is compact and front-loaded. The first sentence states the core purpose, followed by a clarifying example and a succinct return-value list. Every sentence contributes value without repetition 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?

Given the tool's simplicity (no parameters, output schema provided), the description is fully complete: it explains what the tool does, the session nuance, and the exact return fields. There are no complex edge cases or additional prerequisites that need explanation.

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

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

The tool has zero parameters, so the baseline is 4. The description needs no parameter explanation; it focuses entirely on return values and context, 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 opens with 'Get information about the currently active SDMX data source,' which is a specific verb+resource combination. It further clarifies by naming examples of organizations and explicitly distinguishes itself from tools like list_available_endpoints by focusing on the 'currently active' endpoint.

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 about when to use the tool: it reports the active endpoint for the current session, especially in multi-user deployments. However, it does not explicitly mention alternatives or when not to use it, such as when listing all endpoints would be more appropriate.

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?

No annotations are provided, so the description carries the full burden. It discloses the return value ('information about what data exists, including time ranges and suggestions'), explains the endpoint override behavior, and implies a read-only operation through the 'get' verb. Missing details like permissions or side effects, but these are less critical for a read-only check 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 appropriately structured with a brief context paragraph, an Args section, and a Returns line. Every sentence serves a purpose, though the Args section could be slightly more compact. Overall, it is well-organized and not bloated.

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 provides purpose, usage, parameter semantics, and return information. An output schema exists, so detailed return formatting is not necessary. The mention of avoiding empty query results and targeting a provider adds valuable context. Minor gaps include lack of error handling or example usage, but these are not essential for tool 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 input schema has no descriptions (0% coverage), so the description must compensate. It explains all four parameters: dataflow_id (the dataflow to check), filters (optional dimension=value pairs), agency_id (agency ID), and endpoint (optional provider override with default). This adds significant meaning beyond the raw 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 the verb (Get) and resource (data availability) and specifies the scope (dataflow or specific dimension combinations). It distinguishes this tool from siblings like check_time_availability and validate_query by focusing on actual data availability.

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 the tool: 'critical for avoiding empty query results' and 'check if data exists before building the final data URL.' It does not mention alternatives or exclusions, but the usage context is clear.

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

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

No annotations are provided, so the description must carry the behavioral transparency burden. It implies a read-only operation via 'Get' and explains parameter behaviors (e.g., endpoint defaults to session and can be overridden per call), but it does not explicitly state that it has no side effects, or discuss auth/rate limits. This is acceptable for a simple getter, but could be more explicit.

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

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

The description is compact, with a clear one-line purpose, a usage sentence, and a truncated Args/Returns block. It is well organized and every line adds value, though it could arguably be tightened further.

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 a simple read-only profile and an output schema, so the description does not need to detail return values. It covers purpose, usage, and parameters adequately, but lacks mention of potential errors, timeouts, or performance considerations, which is a minor gap.

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%, so the description is the only source of parameter meaning. It provides descriptions for all three parameters, with endpoint getting the most detail (optional key, examples, default behavior), while dataflow_id is only described as 'the dataflow identifier,' which is minimally informative but sufficient given the tool's purpose.

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 'Get detailed structure information for a specific dataflow,' which clearly identifies the action and target. It also enumerates the returned components (dimensions, attributes, measures, codelist references) and positions it relative to list_dataflows(), distinguishing it from sibling 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?

It explicitly states 'Use this after list_dataflows() to understand data organization,' giving a clear sequential usage guideline. It does not, however, provide when-not-to-use or alternative tools for other scenarios, so it lacks full exclusion criteria.

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?

With no annotations provided, the description carries the full burden and does a solid job: it explains pagination via limit/offset, the agency_id defaulting to the session endpoint, and endpoint targeting 'for this call only.' The read-only nature is signaled by 'Get,' though it does not explicitly state safety or permissions.

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 well-structured docstring: a one-line purpose, a brief use-case context, an Args list, and a Returns line. Every sentence contributes information, with no filler or repetition of schema details.

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 output schema exists, the return summary suffices. The description covers purpose, usage scenario, every parameter with semantics, pagination, endpoint override behavior, and the relationship to full codelists. This is complete for a 6-parameter tool with no annotations.

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 0% description coverage, so the description must compensate, and it does thoroughly. It explains all 6 parameters, including defaults (limit=50, offset=0), the meaning of agency_id and endpoint, and pagination semantics, adding substantial meaning beyond the parameter names.

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 opening line, 'Get codes for a specific dimension of a dataflow,' clearly states the verb, resource, and scope. It further distinguishes itself from siblings like get_codelist by explaining that it enables drilling down into specific dimensions without loading all codelists at once.

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 the tool: 'drilling down into specific dimensions' and 'finding valid values for a particular dimension in your data query.' It implies the alternative of loading full codelists but does not explicitly name a sibling tool or state when not to use this tool, so it stops short of a 5.

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

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

With no annotations, the description discloses important behavior: unfiltered requests too large to return are 'reported back rather than guessed at,' and supplying a key avoids that round trip. It also explains why drill_down may remain true. However, it does not mention potential errors, rate limits, or auth, though these are less critical for a read-only metadata retrieval.

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: a concise summary sentence, a brief use-case paragraph, a labeled Args list, and a Returns line. Every sentence carries useful information without fluff. The front-loaded purpose is immediately clear.

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 5-parameter tool with no annotations, the description covers all parameters, explains when to use it, describes its return value, and provides practical tips for large dataflows. The presence of an output schema reduces the need to describe return format in more detail. This is sufficiently complete for an agent to invoke correctly.

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

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

Schema coverage is 0%, but the description provides meaningful documentation for every parameter: 'dataflow_id: The dataflow to read', 'attribute_id: An attribute id from get_reference_metadata()', and especially 'key' with guidance on large dataflows. This goes far beyond the raw schema by explaining relationships and usage context.

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 and resource: 'Get every value of one reference metadata attribute, with the slice each applies to.' It clearly distinguishes this from the sibling get_reference_metadata() by explaining it is for drilling down when drill_down=true, making the purpose unmistakable.

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 states when to use: 'Use after get_reference_metadata() reports drill_down=true.' It also provides practical guidance on the 'key' parameter for large dataflows to avoid round trips, which directly informs when and how to use this tool over alternatives.

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?

With no annotations, the description carries the transparency burden. It discloses that coverage varies by provider, that channel status is reported, and that empty vs unanswerable results are distinguishable. It also includes a performance warning for large dataflows. However, it doesn't explicitly state read-only behavior or error handling, though 'get' implies a safe operation.

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

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

The description is well-structured with an intro, usage note, args list, and returns summary. It is slightly longer than necessary due to the detailed performance example, but every sentence contributes valuable information, so it remains appropriately sized.

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, the description needn't detail return format, but it still summarizes output (attributes, provenance, channel status) and covers edge cases like provider coverage and empty vs unanswerable results. It omits explicit error scenarios but is otherwise complete for this metadata retrieval tool.

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

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

Schema description coverage is 0%, so the description fully compensates by explaining each parameter in prose: dataflow_id, key (with performance example), agency_id, and endpoint (with provider examples). This adds substantial meaning beyond the bare schema definitions.

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-resource pair ('Get reference metadata for a dataflow') and lists concrete content types (source, methodology, licence, caveats). It explicitly contrasts with structural metadata ('rather than its structure'), distinguishing it from sibling tools like get_dataflow_structure.

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?

Provides explicit usage context 'Use it to explain or cite data you have retrieved' and a clear when-not distinction ('rather than its structure'). This guides the agent toward appropriate invocation contexts without ambiguity.

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?

With no annotations, the description carries full behavioral burden. It transparently explains how output adapts per artifact type, the meaning of direction, the default version/agency/endpoint behavior, and what the result contains. It does not mention side effects or error conditions, but the read-only nature is implied by 'Generate' and 'Returns'.

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

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

The description is long but well-structured with a clear summary, type-specific bullets, Args, Returns, and Examples. Each section adds necessary detail without redundancy, and the main purpose 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 tool with 7 parameters and type-dependent behavior, the description is exceptionally complete. It covers all parameter semantics, behavioral variations, output structure, and includes three diverse examples. The presence of an output schema further reduces the need to document return fields, yet the description still does.

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

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

Schema description coverage is 0%, so the description must compensate. It provides a dedicated Args section explaining every parameter, including allowed values for structure_type, defaults for version/agency_id/direction/show_versions/endpoint, and the meaning of direction. Examples further clarify parameter usage.

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 and resource: 'Generate an SDMX-aware Mermaid diagram for any structural artifact.' It further distinguishes itself from sibling tools by detailing type-specific visualization views (dataflow, DSD, codelist, concept scheme), making its unique role clear.

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, such as 'impact analysis' for codelists and 'shows complete SDG dataflow structure' in examples. However, it does not explicitly name alternative tools or state when not to use this tool, so it stops short of a 5.

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

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

Without annotations, the description carries the burden of behavioral disclosure. It explains that the tool returns a list with descriptions and status, indicates the active endpoint, and notes that the endpoint is session-specific in multi-user deployments. However, it does not explicitly state read-only behavior, auth requirements, or any side effects, though these are reasonably implied for a listing operation.

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

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

The description is well-structured and concise: it states the purpose in the first line, adds relevant usage guidance in the middle, and ends with a clear summary of returns. Every sentence provides useful information, and the overall length is appropriate for the tool's simplicity.

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 is simple (no params), and the description covers purpose, usage, return structure, and session-specific behavior. An output schema exists, but the description's return summary suffices given the simplicity. Sibling tool comparisons are addressed via the alternative usage advice, making the description complete for an agent to select and invoke correctly.

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

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

The tool has zero parameters, and the input schema is an empty object, so schema coverage is trivially 100%. With 0 params, the baseline is 4. The description adds no parameter details because none exist, but it does describe the return payload conceptually, which is not required for this dimension.

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: 'List all available SDMX data sources that can be switched to.' It specifies the resource (SDMX data sources) and the action (list), and further clarifies that it shows all configured statistical data providers and indicates the currently active one. This distinguishes it from sibling tools like get_current_endpoint, which likely returns only the current endpoint.

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 provides usage context: it explains when this tool is useful (to see available endpoints/current active) and provides an explicit alternative for a different task: 'Use compare_dataflow_dimensions(...) to directly compare dataflows from different providers.' It also notes session-specific behavior in multi-user deployments, which guides when to rely on the result.

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?

With no annotations provided, the description carries the full burden. It discloses caching behavior (the `fresh` param bypasses cache but refreshes it for others), explains endpoint fallback to session default, and mentions pagination. It could also note any permissions or rate-limit implications, but for a list operation this is largely sufficient. It adds meaningful context beyond what bare annotations would have 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?

The description is multi-paragraph but each paragraph earns its place: an overview paragraph, an alternative guidance paragraph, a full Args list, and a Returns summary. It is verbose but not wasteful; a 5 would require tighter phrasing, though the current structure is well-organized and scannable.

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

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

Given the existence of an output schema, the description needn't detail return values, and it doesn't over-explain. It covers what the tool does, when to use it, alternatives, all parameters, caching semantics, and pagination. There is no obvious missing context that an agent would need to select and invoke this 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 0%, so the description's Args section is the only parameter documentation. It thoroughly explains each parameter: keywords as string or list, agency_id defaulting to session, limit/offset for pagination, endpoint for per-call provider override, and fresh with a clear rationale for when to use it. This fully compensates for the absent schema descriptions.

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

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

The description clearly states 'List available SDMX dataflows' with a specific verb and resource, and positions it as 'typically the first step in SDMX data discovery.' It also distinguishes itself from siblings by naming an alternative (find_code_usage_across_dataflows) for when codes are already known, making the scope 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?

It explicitly says this is the first step in SDMX data discovery and provides a concrete 'instead' recommendation: 'If you already know a country code or indicator code, consider using find_code_usage_across_dataflows() instead.' This clarifies when to use this tool versus a sibling, which is exactly what usage guidelines should do.

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?

With no annotations provided, the description fully carries the transparency burden. It discloses key behaviors: uses 'lightweight probing (firstNObservations=1)' to minimize payload, returns 'status, observation count, shape, and sample data', and clarifies that agency_id is 'Required for OECD sub-agency flows' and 'ignored when data_url is'. This gives the agent concrete expectations about side effects and output.

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 intro, use-case statement, parameter list, and return description. It is somewhat verbose due to the detailed parameter explanations, but every sentence adds necessary context. It could be slightly tightened, but overall it earns its length given the tool's 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 the 10-parameter complexity and the presence of an output schema, the description is complete. It explains input alternatives, output structure, timeout defaults, endpoint selection, and special cases like sub-agency flows. The agent has all context needed to invoke the tool correctly without needing to infer from structured data.

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

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

Schema description coverage is 0%, so the description must compensate. It does so admirably, explaining all 10 parameters with relationships, examples, and edge cases. For instance, it notes data_url and dataflow_id are alternatives, clarifies agency_id usage conditions, and provides endpoint examples. This adds significant meaning beyond the raw 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 the tool 'Probe an exact SDMX data query and return whether it contains data', using a specific verb and resource. It explicitly distinguishes from sibling tools by explaining it answers the question validation and code-usage checks cannot, making its unique 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 provides clear context on when to use the tool: 'This answers the question that validation and code-usage checks cannot'. It also explains the flexible input modes (data_url or structured parameters). However, it does not explicitly name alternative sibling tools or state when not to use it, though the comparison to validation/code-usage checks implies it.

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

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

No annotations provided, so description carries full burden. It discloses HTTP probing behavior with a budget (max_probes), the relaxation strategy, and that alternatives are validated. Also explains the endpoint parameter overrides session endpoint for this call only. Lacks details on errors or side effects, but core behaviors are covered.

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?

Overview is two focused sentences, followed by a clean Args list. No fluff—every line adds functional value, and the structure is easy to scan.

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 moderate complexity and presence of an output schema, the description adequately covers input semantics, algorithm, and probing budget. It omits edge cases like invalid URLs or no-alternatives-found behavior, but for an agent deciding to invoke the tool, it provides enough context.

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

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

Schema coverage is 0%, but the Args block explains all 7 parameters with meaningful semantics: 'None = try all' for relax_dimensions, 'budget' for max_probes, 'currently only least_change' for strategy, and listed values for intent_hint. Doesn't fully explain intent_hint's effect, but covers the essentials.

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

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

Description opens with 'Suggest nearby non-empty SDMX queries when the original returns no data,' providing a specific verb and resource. It clearly differentiates from sibling tools like probe_data_url or get_data_availability by focusing on recovery suggestions for empty results.

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?

States a clear trigger condition ('when the original returns no data') and describes the approach (bounded relaxations, removing one filter at a time). This gives contextual use case, but doesn't explicitly mention when not to use it or name alternative tools.

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?

With no annotations, the description carries full burden. It states the two validation checks and the return value (errors, warnings, validated parameters), which is useful. However, it does not disclose whether the tool makes network calls to fetch dataflow structure or what side effects occur, a notable gap given it validates against a dataflow.

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

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

The description is compact and front-loaded with the primary purpose. The Args/Returns structure organizes information efficiently, and every sentence adds value 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?

The description covers purpose, all parameters, and summarizes the return type, which suffices given the output schema exists. The main missing element is side-effect disclosure (e.g., network access), preventing a perfect score.

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?

Despite 0% schema description coverage, the Args section explains all seven parameters, including nuanced details like `key` being dot-separated dimensions, `filters` being a dimension-to-code dictionary, and `endpoint` targeting a provider with a default. Some entries are terse (e.g., 'agency_id: The agency') but overall the description compensates well.

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 tool as a validator of SDMX query parameters, specifying that it checks syntax per the SDMX 2.1 spec and verifies dimension code existence. This distinguishes it from sibling tools like build_data_url or probe_data_url, positioning it as a pre-build validation step.

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 'before building the final URL' provides clear contextual timing, implying use prior to URL construction. However, it does not explicitly mention when not to use it or compare it to alternatives like probe_data_url, so it falls short of a 5.

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