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

Adds context beyond annotations: scope limited to cacheRoot/ftp.ibge.gov.br, need for filters, dryRun default, and requirement for user consent before deletion. No contradiction with 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?

Three sentences, each essential: core purpose, scope/filters, and safe workflow. No wasted words.

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?

Fully covers all critical aspects: what it does, cache scope, required filters, default behavior, and safe usage. No gaps for effective agent selection and 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 coverage is 100%, but description adds value by highlighting the filter requirement and dryRun default, aiding correct usage beyond 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?

Clearly states 'Preview or delete selected files from the local IBGE microdata cache,' specifying verb and resource. Distinguishes from sibling tools like download and 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?

Explicitly requires at least one filter (olderThanDays, minBytes, or urlPrefix) and outlines the safe workflow: preview with dryRun=true, then set dryRun=false only after user agreement.

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

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

The description is fully consistent with annotations (readOnlyHint, idempotentHint, destructiveHint=false) and adds behavioral details: optional row counts, sample rows capped at 100, and the non-destructive nature of inspection. No contradictions.

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

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

Two sentences with no wasted words. The first sentence states the core functionality, the second provides usage guidance. Front-loaded 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?

The description covers the main functionality and return information (columns, types, row counts, samples). Given the simple nature and good annotations, it is complete enough, though it could mention the DuckDB view persistence or relation to other tools more explicitly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds little beyond schema (e.g., 'capped at 100' is in the max constraint), but clarifies the use case for 'views' parameter. Baseline 3 is appropriate.

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

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

The description clearly states the action ('Inspect local Parquet files as named DuckDB views') and the resource (Parquet files as views). It distinguishes from siblings like 'ibge_microdata_profile_parquet_views' and 'ibge_microdata_query_parquet_views' by specifying it returns columns, types, and optional samples, and positions it as a preparatory step for join queries.

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 advises using this tool 'before writing join queries' to see column names and types, providing clear context. It implies not to use it for running queries or profiling, but lacks explicit exclusions, earning a 4.

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?

All annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are present and consistent with the description. The description adds context about strict limits, only fetching directory pages, and not downloading, which goes beyond 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?

Two sentences that are front-loaded: first sentence states purpose and scope, second sentence gives usage guidance. No wasted words, every sentence is valuable.

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 discovery tool with no output schema, the description covers purpose, limits, and what it does not do. However, it does not describe the return format (e.g., directory listing structure), which might be inferred from context. Slight gap, but overall complete given 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?

Schema coverage is 100%, so baseline is 3. The description does not add additional meaning beyond the schema's parameter descriptions, which already detail defaults, caps, and behavior for each 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 uses a specific verb ('crawl') and resource ('ftp.ibge.gov.br directories') and clearly differentiates from sibling tools by focusing on discovery of microdata, data ZIPs, and documentation files. It is not a tautology and distinguishes itself from survey-specific 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?

Explicitly states when to use ('when a survey-specific convenience listing is not implemented yet') and what it does not do ('does not download microdata archives'), providing clear when-not and limitations.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds specific caching behavior: mirrors URL under cacheRoot, checks HEAD content-length, skips re-download if size matches. No contradictions.

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

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

Two paragraphs, first sentence front-loads the purpose, second adds caching details and usage guidance. No wasted words, efficient structure.

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 caching mechanism, prerequisite usage of sibling tool, and local-first approach. However, lacks description of return value (likely local path), which is a minor gap given no output schema.

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

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

Schema coverage is 100% with descriptions for both url and cacheRoot. The description adds 'mirrors the ftp.ibge.gov.br URL under cacheRoot' which is already implied by schema descriptions. It does not provide new parameter-level semantics beyond caching behavior, so baseline 3 is appropriate.

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

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

The description starts with 'Download or reuse a selected official IBGE microdata file in a local cache path,' which clearly states the verb and resource. It distinguishes itself from siblings like ibge_microdata_file_info (info before download) and extraction 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?

Explicitly advises to use ibge_microdata_file_info first for large files so the user understands size before downloading. This provides clear when-to-use guidance and differentiates from 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?

Annotations already declare readOnly, idempotent, nondestructive. Description adds that it extracts to a local path, which is consistent but does not disclose potential overwrite behavior or error handling.

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

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

Two sentences, front-loaded with verb and resource, no 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?

Adequate for a simple extraction tool with good annotations; does not describe return value or error conditions, but these are less critical given openWorldHint.

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 has 100% coverage with descriptions; tool description only adds example entry names (PNAD TXT, input layout) but no new parameter semantics beyond 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?

Description clearly states the verb 'extract' and resource 'local IBGE ZIP archive', and distinguishes from siblings like list_entries and batch conversion 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?

Second sentence provides explicit use case (PNAD fixed-width TXT file or input layout) and contrasts with manual unpacking, though it does not explicitly list 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by specifying that it uses HTTP HEAD (non-downloading) and returns specific metadata (size, content type, timestamp, ETag), which is beyond the annotation information.

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 extremely concise: two sentences that directly state the purpose and usage guidance. No unnecessary words 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?

Despite lacking an output schema, the description fully explains what the tool returns (size, content type, timestamp, ETag). The single parameter is well-documented, and the usage context is clear. No additional detail is needed for this simple 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 for the sole parameter 'url' is 100%, and the description in the schema already explains it. The tool description does not add meaningful extra semantics beyond restating the schema description. Baseline 3 is appropriate.

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

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

The description clearly states the action ('Fetch HTTP HEAD metadata') and the specific resource ('official IBGE microdata file URL'). It also distinguishes from sibling tools like ibge_microdata_download_file by explicitly recommending use before downloading.

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

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

The description explicitly says when to use it: 'before downloading a large file to check its size, content type, update timestamp, and ETag.' It does not explicitly mention when not to use or provide alternatives, but the context makes it 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?

Annotations already declare idempotentHint=true and destructiveHint=false. Description adds that this is an 'optimization path' but does not disclose any additional behavioral traits such as file overwrite behavior or performance characteristics.

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

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

Two sentences for the description and two for usage context. Every sentence conveys necessary information without redundancy. 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 100% schema coverage and no output schema, the description provides sufficient context: specifies the type of files (PNAD, POF), the optimization rationale, and variable selection advice. No gaps identified.

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 parameter descriptions already cover semantics. Description reinforces the ability to select variables but adds no additional meaning beyond 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?

Clearly states conversion from fixed-width IBGE microdata TXT to Parquet using an official layout. Differentiates from siblings like 'fixed_width_zip_to_parquet' by specifying local TXT files and mentioning specific surveys (PNAD, POF).

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 the tool is for repeated analysis and recommends selecting only needed variables. Implies use for fixed-width files from IBGE microdata families. Does not explicitly mention when not to use or alternatives, but sibling tool name suggests zip-to-parquet alternative.

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

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

Annotations already provide readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds that it writes a columnar file and avoids extraction, but does not disclose potential side effects like overwriting or error handling. The added value is moderate beyond 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?

Two sentences, no wasted words. First sentence states the core transformation; second sentence adds benefits and use case. Optimal length for the content.

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

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

Given the tool's complexity (6 parameters, no output schema), the description covers the key points: direct conversion from zip, avoiding extraction, and suitability for DuckDB queries over IBGE surveys. It could explicitly contrast with similar sibling tools (e.g., fixed_width_file_to_parquet) to complete the decision 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 100%, with all parameters described. The description does not add additional meaning beyond the schema's parameter descriptions, so baseline score 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?

Description clearly states the verb 'convert' and the specific resource: a fixed-width TXT entry inside a local IBGE ZIP archive to a Parquet file using an official SAS/TXT layout. This distinguishes it from siblings like ibge_microdata_fixed_width_file_to_parquet, which operates on an already extracted file.

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?

Description explains that this tool avoids extracting the full TXT first and is useful before running repeated DuckDB queries, providing clear context. However, it does not explicitly state 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?

Annotations already declare the tool as readOnly, idempotent, and non-destructive. The description adds that it returns structured variable metadata, which is useful beyond annotations. There is no contradiction between description and annotations.

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

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

The description is two sentences: first sentence states the core functionality, second provides usage guidance. No unnecessary words or repetition. Highly 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?

The description explains the return content (variable names, positions, etc.) even though there is no output schema. It covers the primary use case well. Could mention the limit and search parameters, but they are documented in the schema.

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

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

Schema coverage is 100%, so parameters are fully documented in the schema. The description does not add additional semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states 'Parse a local official IBGE SAS/TXT input layout and return variable names, positions, widths, types, and descriptions.' This is a specific verb-resource combination and distinguishes from sibling tools like ibge_microdata_fixed_width_file_to_parquet which does the conversion.

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

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

The description explicitly says 'Use this before converting fixed-width microdata to Parquet so you can choose selectedVariables without opening the full dictionary manually.' It provides clear context for when to use the tool, though it does not explicitly state when not to use it or list 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?

Annotations already declare readOnlyHint and idempotentHint. Description adds that it only reads local cache and supports pagination via limit/offset, enhancing transparency. No contradictions.

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

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

Two concise sentences. First sentence states the core purpose, second provides usage context and details about returned data. No extra words.

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 description covers purpose, usage, behavior, and parameter roles. Annotations provide safety info. No output schema, but description lists return data types. Sufficiently 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 100%, and each parameter is described in the schema. The description mentions limit/offset for pagination but adds no new semantics beyond what the schema provides. Baseline 3 is appropriate.

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

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

Description clearly states the verb 'list' and resource 'local IBGE microdata cache'. The title also reinforces this. It distinguishes itself from siblings like download_file and cleanup_cache by focusing on listing cached files.

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 to use after download_file calls to avoid hitting IBGE again, providing clear context. No mention of when not to use, but the use case is well-defined.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds that it only lists links and does not download, which provides useful behavioral context beyond 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?

Two concise sentences with no wasted words. The first sentence states the core action, the second provides usage context and limitations.

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 listing tool with one parameter and no output schema, the description covers purpose, usage context, and limitations. It could optionally mention the return format, but it's sufficient for an agent to use 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?

Only one parameter (url) with schema description covering its purpose. The description reinforces the URL domain but does not add extra details beyond the schema. Given 100% coverage, baseline 3 is appropriate.

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

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

Clearly states the tool lists downloadable files in an official IBGE FTP directory. The description explicitly distinguishes it from survey-specific convenience tools, making the purpose precise and unambiguous.

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

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

Explicitly says to use this tool for IBGE microdata families without a survey-specific convenience tool, and clarifies it only lists links, not download file bodies. This gives clear guidance on when and when not to use it, and hints at 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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructiveHint. The description adds value by clarifying it lists URLs only (no downloads) and specifies return scope for POF (edition-level archives). No contradictions.

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

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

Three sentences with no fluff. First sentence states core purpose. Second provides concrete examples. Third adds a behavioral qualifier (no download). Every sentence adds 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?

Given the tool has no output schema, the description could detail return format (e.g., array of URLs) but it sufficiently conveys it returns URL listings. The examples and qualifier make it usable. Sibling tools are more complex, but this description is complete for a simple list 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%, so baseline is 3. The description adds significant meaning: explains how 'survey' and 'year' interact (year required for PNAD, not for POF) and lists exact editions for POF. This exceeds schema-level 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 explicitly states the tool lists official IBGE microdata download files for supported surveys, with specific examples for PNAD Contínua and POF. It clearly distinguishes from sibling tools like ibge_microdata_download_file by noting it lists URLs only and does not download.

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 usage context with parameter examples (survey='pnadc_trimestral' with year, survey='pof' without year). It implicitly distinguishes from download tools but does not explicitly state when not to use or list 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering behavioral traits. The description adds the specific note 'This tool does not download data,' reinforcing safety. No contradictions.

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: one for purpose and one for usage guidance. 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?

For a simple listing tool with no parameters and no output schema, the description is fully sufficient. It tells the agent when to use it, what it does, and what it does not do.

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 the baseline is 4. No parameter documentation is needed, and the description does not attempt to document parameters.

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

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

The description explicitly states the action ('List') and the resource ('IBGE microdata families'), and distinguishes from other tools by clarifying it does not download data. It also mentions the server is 'local-first,' adding context.

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 clearly advises 'Use this first when deciding whether the server can help,' providing direct guidance on when to invoke this tool versus others. It implicitly contrasts with tools that download or process data.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint as true or false. The description adds that it operates on a small predefined set of variables, which is behavioral context beyond annotations. No contradiction.

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

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

Two concise paragraphs, front-loaded with the core action. Every sentence adds value without redundancy. No wasted words.

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

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

Given the tool's complexity (3 params, no output schema) and strong annotations, the description is mostly complete. It explains workflow position and limitations. Lacks explicit description of the output format, but 'predefined summary' is implied.

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 all parameters have descriptions. The tool description does not add further parameter-specific meaning beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the tool analyzes a PNAD Contínua fixed-width TXT file using a SAS/TXT input layout. It distinguishes itself as a convenience helper for a predefined variable set, differentiating it from siblings like ibge_microdata_pnadc_analyze_zip (zip analysis) and generic query 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?

Explicitly states when to use: after downloading/extracting PNAD microdata locally when the predefined summary matches the task. Also provides an alternative: for custom workflows, prefer converting to Parquet and using generic tools. This gives clear 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description adds value by stating it 'avoids extracting the full microdata TXT first' and works with a 'predefined set of variables,' which are behavioral traits not fully captured by annotations. These details inform the agent about the tool's limited scope and non-destructive 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 three concise sentences. The first sentence states the core function. The second explains its niche value and alternatives. The third provides usage context. Every sentence is necessary and contributes to clarity 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 4 parameters, no output schema, and the description explains its purpose and when to use it. However, it does not specify which 'predefined set of variables' is analyzed, leaving a gap for the agent. It also does not describe the return format or results of the analysis. While adequate given annotations and sibling context, the missing variable list and output details reduce completeness.

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 100% description coverage, so the schema already explains the four parameters. The description mentions 'predefined set of variables' but does not enumerate them, nor does it add formatting or constraints beyond the schema. Baseline 3 is appropriate as the schema carries the semantic burden.

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 analyzes a PNAD Contínua fixed-width TXT entry inside a local ZIP archive. It specifies it's a PNAD-specific convenience helper for a small predefined set of variables, distinguishing it from siblings like 'ibge_microdata_pnadc_analyze_file' (which analyzes an extracted file) and 'ibge_microdata_fixed_width_zip_to_parquet' (which converts). The verb 'analyze' and resource 'ZIP entry' are specific and unambiguous.

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

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

The description provides explicit usage guidance: 'Use it after downloading a PNAD ZIP and extracting or otherwise providing the official input layout when this predefined summary matches your task.' It also advises when not to use it: 'For custom public workflows, prefer converting selected variables to Parquet and using the generic query or weighted-distribution tools.' This clearly distinguishes when to use this tool versus alternative 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?

Annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false) already declare safe behavior. The description adds context about what the tool does with the dictionary file (parse and return structured data), complementing annotations without contradicting them. No extra behavioral details beyond what annotations cover, but the description is appropriate.

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

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

Two sentences: first defines what the tool does, second provides usage context. No unnecessary words or repetition. Ideal conciseness for a tool with clear purpose and well-documented schema.

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 adequately lists what is returned (record sheets, mapped data entries, record lengths, variable layouts). For a manifest inspection tool, this is sufficient. Could mention that it also handles search or dataZipPath, but those are already in the schema. Overall 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 100%, with all parameters having clear descriptions (e.g., 'search' as optional case-insensitive search). The description does not add new meaning beyond the schema; it focuses on overall purpose. Baseline 3 is appropriate since the schema already documents parameters 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 uses a specific verb 'Parse' and resource 'POF Excel variable dictionary', and lists what it returns (record sheets, mapped TXT data entries, record lengths, variable layouts). The title 'Inspect POF Dictionary Manifest' reinforces the purpose. It clearly distinguishes from sibling tools, none of which mention POF dictionary or manifest.

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 second sentence explicitly says to use this tool 'after downloading/extracting the POF documentation ZIP' and to 'understand which POF record to convert and which variables to select'. This provides clear context and implies alternatives (other tools for conversion). Could be improved with explicit when-not-to-use, but the guidance 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?

The description explains that the tool converts, maps, applies decimal scaling, and writes a Parquet file. Annotations indicate idempotent and non-destructive behavior, and the description does not contradict them. It adds context about POF-specific processing beyond what annotations provide.

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

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

The description consists of two efficient sentences. The first states the core action, and the second elaborates on the specific POF logic. Every word contributes meaning 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?

Given the complexity (6 parameters, no output schema), the description adequately covers purpose, usage context, and outcome (creating a Parquet file). It could mention output file overwriting behavior, but overall it is sufficient for an agent to understand what the tool 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?

The input schema has 100% coverage, but the description adds meaning by explaining how parameters like 'recordName' map to sheets like 'DOMICILIO.txt' and that decimal scaling is applied. This goes beyond the 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 specifies a specific verb ('Convert'), resource ('POF fixed-width TXT record inside a local Dados ZIP'), and context ('using the POF Excel dictionary workbook'). It distinguishes the tool from siblings like ibge_microdata_fixed_width_zip_to_parquet by calling it 'the POF-specific optimized path' and mentioning POF-specific details.

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 using this tool for POF data instead of generic alternatives by stating 'This is the POF-specific optimized path'. However, it does not explicitly state when not to use it or name alternatives, though the sibling list provides context.

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

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

Adds detail beyond annotations by listing reported statistics (row counts, column types, null/non-null counts, optional numeric summaries, frequent values, sample rows) and mentions bounded exploration. No contradiction with 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?

Two short paragraphs, four sentences total. Every sentence adds value: first defines purpose and output, second gives usage guidance and defaults. No 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?

Covers purpose, output components, usage timing, default behavior, and options. Could be more complete by describing the return format explicitly, but given no output schema, the description is fairly comprehensive.

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 baseline is 3. Description provides no additional param-specific details beyond schema descriptions; it reiterates overall behavior but does not enrich parameter understanding.

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 clearly states the tool profiles local Parquet files as DuckDB views and returns bounded exploratory statistics. It distinguishes from sibling tools like query or describe by specifying the context 'after converting... and before writing custom SQL'.

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?

Directly advises 'Use this after converting IBGE fixed-width microdata to Parquet and before writing custom SQL.' Also explains default column behavior and alternative to pass specific columns. However, it does not explicitly mention when not to use 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds 'bounded' and query constraints (semicolons rejected), but beyond that, it does not significantly expand on behavioral traits like error handling or performance specifics.

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

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

The description is two sentences, front-loaded with the core action in the first sentence and usage context in the second. No unnecessary words.

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 full schema coverage and annotations covering safety and idempotence, the description provides sufficient context for use after conversion. It lacks explicit description of return format but that is somewhat implied by the SQL query nature.

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 description adds no additional parameter semantics beyond what is in the schema. The description mentions the 'microdata' view name, which is also implied in the schema text for `sql`.

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 runs a read-only DuckDB SELECT/WITH query over local Parquet files, specifying the bounded nature. It gives a specific use case (post-conversion) but does not explicitly differentiate from the sibling `ibge_microdata_query_parquet_views`, though the context implies a distinction.

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

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

The description explicitly says to use this tool after converting IBGE fixed-width microdata to Parquet for repeated summaries or tabulations. It provides when-to-use context but does not mention when not to use or compare with alternatives directly.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds that the query is bounded (maxRows), uses DuckDB, and rejects semicolons/write keywords, providing valuable context beyond annotations.

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

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

The description consists of two sentences: one terse functional statement and one with use case. Every sentence earns its place, and the key action is front-loaded with no wasted words.

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

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

Given the tool's complexity, schema coverage, and annotations, the description explains the purpose and use case adequately. It mentions boundedness and read-only behavior but does not describe the output format, which might be inferred. Siblings like profile/describe tools are addressed elsewhere.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds high-level usage context and examples of view names, but does not elaborate on parameters beyond what the schema already provides.

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 runs bounded read-only DuckDB SELECT/WITH queries over multiple named local Parquet views, specifying the verb, resource, and constraints. It distinguishes from siblings like ibge_microdata_query_parquet by emphasizing multiple views and joining.

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 advises use for relational microdata workflows, especially POF, with examples of views to join. It does not explicitly mention when not to use or contrast with alternatives, but the context and name provide implicit differentiation.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds behavioral context: it creates views temporarily, ranks units, computes statistics, and handles ties proportionally. No contradiction with annotations. Adds useful detail beyond the safety profile.

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, front-loading the purpose and then providing usage details. No wasted words; each sentence adds value. Structure is logical 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?

While the description covers main functionality and parameters, it lacks explicit output structure details (e.g., JSON format, column names) because no output schema exists. For a 7-parameter tool, it is fairly complete but could elaborate on return format and error constraints.

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 baseline is 3. The description adds meaning by explaining unitSql as a read-only query returning specific columns, and clarifying defaults for topPercents and maxGroups. This adds moderate value over the schema alone.

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

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

The description clearly states the tool computes weighted distribution summaries and top-bracket shares over local IBGE Parquet views. It specifies the input (unitSql) and outputs (total weight/value/mean, group shares, top brackets). This distinguishes it from sibling tools like generic query or profile 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 explicitly states when to use: after converting microdata to Parquet when distribution statistics are needed without manual SQL. It implies non-use for other purposes and provides workflow context, though it does not name alternative sibling tools directly.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds key behavioral context: it lists entries 'without extracting the archive' and targets 'local IBGE ZIP archive', implying a read-only operation. This goes beyond annotations and clarifies the non-destructive 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 concise: two sentences, front-loaded with the primary action, no extraneous words. Every sentence adds value—first defines the tool, second gives usage context.

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 has one parameter, no output schema, and strong annotations, the description is fairly complete. It explains the purpose, workflow, and outcome (discovering file names). However, it could briefly mention the output format (e.g., list of filenames) for full completeness.

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 a clear description for zipPath. The description does not add new semantics beyond the schema (it reinforces the purpose but doesn't elaborate on path format or constraints). Per guidelines, baseline 3 is appropriate since the schema does the heavy lifting.

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 exactly what the tool does: 'List file entries inside a local IBGE ZIP archive without extracting the archive.' It uses a specific verb ('list') and resource ('file entries inside a local IBGE ZIP archive'). It distinguishes from sibling tools like ibge_microdata_extract_zip_entry by noting it does not extract, and it mentions the use case of discovering exact TXT, documentation, or table names.

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 advises when to use the tool: 'Use this after ibge_microdata_download_file to discover the exact TXT, documentation, or table names inside official IBGE microdata ZIPs.' This provides clear context and a recommended workflow, though it does not explicitly mention when not to use or compare with alternatives beyond extract_zip_entry.

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