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 search scope and return fields, but does not detail search semantics (e.g., case sensitivity, fuzzy matching), pagination behavior, error handling, or potential rate limits. The description gives a basic behavioral overview but lacks depth beyond the obvious read-only search nature.

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

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

The description is two sentences long, front-loaded with the primary action, and contains no filler. Every sentence contributes useful information—what it does, what it returns, and how the output is used.

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 search tool with a full input schema and an output schema present, the description is complete. It provides the purpose, the output fields, and the downstream usage context (get_constraints), leaving no critical gaps for an agent to invoke it 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?

The schema covers 100% of parameters with descriptions (query and limit). The tool description adds the workflow context that the datastructure id is used for get_constraints, but it does not add new meaning to the parameters themselves. Baseline 3 is appropriate given the high schema 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 clearly states a specific purpose: 'Search ~4,700 available ISTAT statistical datasets (dataflows) by keywords.' It distinguishes this tool from siblings by focusing on the discovery step and specifying the return fields (dataflow id, Italian name, datastructure id), which directly supports downstream use with get_constraints.

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 indicates when to use this tool by stating the output is 'to feed into get_constraints,' providing a clear workflow context. It does not explicitly mention exclusions or alternative tools, but the context is sufficient for an agent to understand this is for discovering dataflows before retrieving constraints.

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. 'Inspect' implies a read-only operation, but it does not explicitly state there are no side effects, whether diagnostic state is refreshed, or if certain permissions are required. It names what is inspected but omits behavioral details.

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

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

The description is a single, well-structured sentence that front-loads the key action ('Inspect cache diagnostics') and appends the supporting details. Every word earns its place, with no redundancy or fluff.

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

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

Given the zero-parameter nature and the existence of an output schema, the description adequately scopes the tool's purpose. It lists the three diagnostic areas covered, which is sufficient for an agent to decide when to use it 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?

There are zero parameters, so schema coverage is trivially 100%. The description correctly omits parameter details since none exist, and no additional semantics are needed for this parameterless tool.

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

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

The description uses the specific verb 'Inspect' and names a clear resource: cache hit/miss diagnostics, disk usage, and downloaded files list. This clearly distinguishes it from sibling tools that focus on constraints, concepts, dataflows, structure diagrams, and data retrieval.

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 what data is returned (cache diagnostics, disk usage, files list), making it straightforward to know when to use this tool. It does not explicitly name alternatives or exclusions, but the subject matter is distinct from 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?

No annotations are provided, so the description carries the full burden. It indicates a non-mutating read operation ('Get'), but it does not disclose error handling, length limits, or the behavior when concept_id is omitted (though this is partially covered by the schema). For a simple read tool, this is adequate but not rich.

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

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

The description is a single, front-loaded sentence that immediately states the action and target. It contains no filler words and is optimally concise for a simple read operation.

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 (one optional parameter), an output schema, and a clear description, the context is mostly complete. It could mention that omitting concept_id returns the full ConceptScheme, but that detail is already in the schema, so the description suffices.

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

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

The schema already describes the single parameter completely (100% coverage), including the default behavior and examples. The tool description adds no new information beyond repeating the examples, so it meets the baseline for high schema 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 clearly states the tool retrieves semantic definitions for ISTAT SDMX concept IDs, with concrete examples (REF_AREA, FREQ). This specific verb+resource combination distinguishes it from sibling tools like get_data or get_constraints.

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 purpose implies when to use the tool (when you need concept definitions), but there is no explicit guidance on when not to use it or which sibling tool to choose instead. A brief note on exclusion would improve clarity.

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 that the call is a single query, returns three kinds of data (dimensions, codes, labels), and notes that the parameter name changed from 'id_dataflow' in earlier versions. This is useful behavioral context, though it does not mention error conditions 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 three sentences long, with the main purpose in the first sentence, differentiation in the second, and usage direction in the third. Each sentence adds distinct 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 tool has only one required parameter and an output schema, so the description doesn't need to detail return formats. It covers the tool's role in the workflow ('before get_data'), the parameter source (in schema), and replaces older tools. A slight gap is that it doesn't explain how to construct the key_filter, but that is likely beyond the tool's scope.

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

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

The input schema already provides 100% coverage for dataflow_id, including an example and note about the previous parameter name. The description itself does not add additional parameter-level semantics beyond that, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool 'retrieves dimensions (with their position), valid constrained code values, and human-readable Italian/English labels' for an ISTAT dataset. It distinguishes this tool from siblings by noting it replaces get_structure and get_codelist_description and by emphasizing 'Single-Call'. This makes 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 explicitly instructs 'Call this before get_data to build the key_filter', giving a clear temporal usage context. It also names the separate tools it replaces, effectively telling the agent which older alternatives to avoid. This provides both a when and a when-not.

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 and discloses key behaviors: automatic switch from inline to file download based on payload size or force_file_download, the requirement for key_filter as a dotted SDMX string (not a dictionary), and timeout risks with long time series. This gives the agent a clear behavioral model before invocation.

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 three tight sentences, front-loaded with the core purpose, then the output behavior, then two critical parameter tips. Every sentence earns its place; there is no fluff or repetition.

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 8 parameters and an existing output schema, the description covers the essential operational decision (inline vs file), the key_filter syntax pitfall, and the timeout issue, all in a compact form. The output schema and rich parameter descriptions handle the remaining details, so the description is complete for its role.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds operational depth beyond the schema: it explains the file-download trigger threshold, elaborates on the key_filter format with a concrete example, and contextualizes last_n_observations as a timeout mitigation for specific dataflows. Some information duplicates the schema, but the added usage context justifies a 4.

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 'Fetch statistical data from ISTAT', a specific verb and resource, and clearly distinguishes from sibling metadata tools (get_constraints, get_concepts, discover_dataflows) by targeting actual data retrieval. It also includes scope details like inline vs file output, making 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 provides clear contextual usage guidance: small queries return inline text, large datasets auto-download to a file, and force_file_download=True forces file output. It also gives an explicit troubleshooting tip (pass last_n_observations=1 for long time series to avoid timeouts). However, it does not explicitly name when-not-to-use alternatives, 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?

No annotations are provided, so the description carries responsibility for disclosing behavior. The verb 'Generate' implies a read-only operation, and the output is described as a Mermaid.js diagram, but no details are given about potential side effects, permissions, or edge cases. With no annotations, this is minimal but not misleading.

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

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

A single, front-loaded sentence states the tool's purpose and output format with no filler or repetition. Every word contributes to understanding, making it highly concise while retaining key 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?

The tool is simple with one parameter, a high-coverage schema, and an output schema, so the description does not need to explain return values. The only gap is the lack of explicit usage alternatives, but given the self-explanatory nature of generating a structural diagram, the description is sufficiently complete for an agent to select and invoke 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 coverage is 100% with one parameter, dataflow_id, fully described including an example and a note about a previous parameter name. The tool description itself adds no parameter-level information, so it relies entirely on the schema, which is sufficient at the baseline level.

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 'Generate' and clearly identifies the resource as a Mermaid.js diagram showing dataset dimensions, codelists, and hierarchies. This distinguishes it from sibling tools like get_data or get_constraints, which retrieve raw data or constraints rather than a structural diagram.

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 when a visual structural overview of a dataset is needed, but it does not explicitly state when to use this tool over alternatives like get_constraints or get_concepts. There is no when-not guidance or explicit mention of prerequisites, though the schema hints that dataflow_id comes from discover_dataflows.

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 behavioral disclosure. It adds key traits: offline operation, case-insensitive search, and the ability to match by three fields (name, REF_AREA, ISTAT). It also gives a concrete example that illustrates expected input/output behavior. It does not mention error handling or edge cases, but for a simple lookup tool this is a reasonably transparent description.

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

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

The description is exceptionally concise: two sentences that convey the tool's purpose, scope, matching behavior, and a worked example. There is no filler or repetition; every clause adds information. The example is well-placed and illustrative.

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, the complete parameter schema, and the presence of an output schema, the description is fully adequate. It explains what the tool does, how it matches, and what one can expect from a query. No critical information is missing for an agent 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?

The schema already covers all three parameters with descriptions (100% coverage), so baseline is 3. The description adds value by clarifying that 'search' can match on name, REF_AREA code, and ISTAT code, and by providing a concrete example that ties 'search' and 'level' together. This goes slightly beyond the schema's individual descriptions.

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

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

The description clearly states the tool performs an offline lookup for ISTAT territorial codes, enumerates the levels (Comuni, Province, Regioni, Ripartizioni), and gives an example. It distinguishes itself from sibling tools (which handle constraints, concepts, dataflows, etc.) by specifying a concrete lookup resource and scope.

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

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

The description implies when to use this tool: any time a user needs to resolve or search territorial names or codes. It provides context with the example and mentions case-insensitivity and the optional level filter. However, it does not explicitly state when not to use it or directly reference alternatives among sibling tools, so it misses full exclusionary guidance.

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