Server Quality Checklist

Tool Scores

• nhgis_list_extractsB
  3.3/5.0
  Behavior3/5

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

  With no annotations, the description carries the full burden. It does disclose scope ('recent') and return fields (numbers, status, timestamps), which adds some behavioral context. However, it omits details like pagination behavior, ordering, and whether this is a read-only operation (though inferable). It 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.

  Conciseness5/5

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

  The description is a single, front-loaded sentence that clearly states the purpose and return fields. Zero wasted words, easy to parse.

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

  Completeness3/5

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

  For a simple list tool with two optional parameters and no output schema, the description provides the essential return fields. However, it does not explain pagination behavior or the meaning of 'recent', and lacks any note about authentication or read-only status. It is minimally complete but leaves room for ambiguity.

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

  Parameters3/5

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

  The input schema has 100% coverage with descriptions for both `pageSize` and `pageNumber`. The description adds no parameter-specific information, so it hits the baseline for well-documented schemas.

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

  Purpose4/5

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

  The description clearly states the action ('List') and the resource ('NHGIS extract requests'), and mentions the return fields (extract numbers, status, timestamps). It is distinguishable from sibling tools like `nhgis_get_extract` (which likely fetches a single extract) and `microdata_list_extracts` (which targets microdata), though it does not explicitly name alternatives.

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

  Usage Guidelines2/5

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

  The description provides no guidance on when to use this tool versus alternatives. It does not mention that this is for tracking recent submissions, nor does it contrast with `nhgis_get_extract` or note any conditions or prerequisites.

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

• microdata_download_extractA
  3.7/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly mentions SHA-256 checksum verification and returning local file paths and verification status, which are key runtime behaviors. However, it does not disclose potential side effects like directory creation or file overwriting, though these are partially covered in the schema.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with the main action, and every word contributes. It is concise and well-structured.

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

  Completeness3/5

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

  Given 5 parameters with 3 required and no output schema, the description provides the core outcome and a mention of verification, but lacks guidance on prerequisites like needing a completed extract and the exact structure of the returned verification status. It is minimally viable but leaves clear gaps for an agent to fully understand the tool's context.

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

  Parameters3/5

  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 does not add parameter-specific meaning beyond what the schema already provides; it only generically refers to 'local directory' and 'extract files' which map to outputDir and fileTypes but add no new semantic detail.

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

  Purpose5/5

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

  The description clearly states the tool downloads completed IPUMS microdata extract files to a local directory. The verb 'download' and resource are specific, and it distinguishes itself from sibling tools like microdata_get_extract or microdata_list_extracts by focusing on file download.

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

  Usage Guidelines2/5

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

  The description provides no explicit guidance on when to use this tool versus alternatives. It does not mention 'use when extract is complete' beyond the word 'completed' and does not contrast with other extract tools, leaving usage context implied at best.

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

• microdata_get_extractA
  3.8/5.0
  Behavior3/5

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

  No annotations are present, so the description carries the transparency burden. It usefully discloses that download links appear only when the extract is complete, but it does not mention authentication requirements, potential error conditions, or what shape the response takes beyond 'status and details'.

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

  Conciseness5/5

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

  The description is a single well-formed sentence that immediately communicates the tool's purpose and a key behavioral detail. There is no redundant information or unnecessary length.

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

  Completeness4/5

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

  For a straightforward retrieval tool with only three simple parameters and no output schema, the description covers the essential purpose and an important conditional behavior (download links when complete). It could go further by mentioning status values or linking to siblings, but it is adequate for the tool's complexity.

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

  Parameters3/5

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

  Schema description coverage is 100%, and all parameters (version, collection, extractNumber) already have meaningful descriptions. The tool description adds no additional parameter-level detail, 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.

  Purpose5/5

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

  The description clearly states the tool gets the status and details of a specific IPUMS microdata extract by number, and mentions download links when complete. This distinguishes it from sibling tools like microdata_list_extracts (which lists extracts) and microdata_download_extract (which downloads).

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

  Usage Guidelines3/5

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

  The description implies usage for checking the status/details of a specific extract, but does not explicitly state when to use this tool over microdata_wait_for_extract or microdata_download_extract. No exclusions or alternative guidance are provided.

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

• nhgis_get_data_tableA
  3.8/5.0
  Behavior2/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It only states what the tool does but does not reveal any behavioral traits such as being read-only, requiring authentication, or any side effects. The added detail about 'all variable descriptions' provides some output context, but overall it lacks transparency about behavior.

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

  Conciseness5/5

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

  The description is a single, focused sentence with no redundancy. It efficiently conveys the tool's purpose and output without wasting words.

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

  Completeness4/5

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

  The tool is simple (2 params, no output schema), and the description adequately covers its main outcome: returning information about a data table including variables. It does not mention error cases or return format, but given the low complexity and full schema coverage, the description is sufficiently complete.

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

  Parameters3/5

  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 both parameters. The description does not add extra semantic meaning beyond what is in the schema—it only rephrases the identifiers. Baseline of 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.

  Purpose5/5

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

  The description clearly states the tool's purpose: 'Get detailed information about a specific NHGIS data table within a dataset, including all variable descriptions.' It uses a specific verb ('Get'), identifies the resource ('data table'), and specifies the context ('within a dataset'), distinguishing it from sibling tools like listing or searching tables.

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

  Usage Guidelines4/5

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

  The description implies the use case: when you need detailed variable descriptions for a specific table. It does not explicitly mention alternatives or when not to use it, but the clear scope provides adequate context for an agent to decide when to invoke it.

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

• nhgis_list_time_series_tablesA
  3.8/5.0
  Behavior3/5

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

  With no annotations, the description carries the burden of behavioral disclosure. It adds useful context about the temporal and geographic consistency of the tables, but it does not disclose pagination behavior, whether truly all tables are returned in a single call, or the output format. This is a minimal but not comprehensive disclosure.

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

  Conciseness5/5

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

  The description is two concise sentences: the first states the primary action and the second provides meaningful context. There is no redundancy or wasted wording.

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

  Completeness4/5

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

  For a simple listing tool with only pagination parameters and no output schema, the description provides adequate context: it explains what the tool lists and characterizes the nature of time series tables. It could mention pagination caveats, but the overall intent and scope are clear.

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

  Parameters3/5

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

  The input schema already provides descriptions for both parameters ('Results per page' and 'Page number (1-based)'), covering 100% of parameter semantics. The description adds no additional parameter information, 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.

  Purpose5/5

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

  The description begins with a specific action: 'List all available NHGIS time series tables.' It clearly identifies the resource (time series tables) and distinguishes it from sibling tools like nhgis_list_data_tables by emphasizing the multi-year, consistent-geography nature of these tables.

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

  Usage Guidelines3/5

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

  The description gives context that these tables span multiple census years with consistent geographic definitions, which hints at when this tool is appropriate. However, it does not explicitly mention when to use this tool versus alternatives such as nhgis_search_time_series_tables or nhgis_list_data_tables, nor does it state any exclusions.

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

• generate_ipums_citationA
  4/5.0
  Behavior3/5

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

  With no annotations, the description carries the burden. It discloses the output contents (author list, DOI, link) and mentions where the version number appears, but does not clarify whether the template is static, if network access is required, or the exact return format. Partial behavioral disclosure, but not comprehensive.

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

  Conciseness5/5

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

  Two concise sentences that front-load the main action and provide essential details without unnecessary fluff. Every sentence adds value.

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

  Completeness4/5

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

  For a simple one-parameter tool, the description is adequate: it explains what the output contains and where to find the current version. It does not describe the return type, but given the simplicity and lack of output schema, this gap is minor.

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

  Parameters3/5

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

  Schema description coverage is 100% with the 'collection' parameter already having a description and examples. The tool description does not add further parameter-specific meaning, so the baseline of 3 applies.

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

  Purpose5/5

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

  The description clearly states the tool returns a formatted citation template for an IPUMS dataset, using a specific verb 'Return' and resource. It distinguishes from sibling tools, which all focus on data listing/extraction, not citation generation.

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

  Usage Guidelines4/5

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

  The description implies usage for generating citations and explains what is included (author list, DOI, link). It doesn't explicitly state when not to use it, but since there are no alternative citation tools among siblings, the context is clear.

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

• microdata_create_extractA
  4/5.0
  Behavior3/5

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

  With no annotations, the description carries the full burden for behavioral disclosure. It mentions the return value ('Returns the new extract number and initial status') and hints at the next step, but does not disclose potential side effects, authentication requirements, asynchronous processing, or other behaviors that might be expected for a create operation.

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

  Conciseness5/5

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

  The description is three sentences long, front-loaded with the purpose, and every sentence contributes value (what it does, what it returns, and the next recommended step). There is no redundancy or filler.

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

  Completeness4/5

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

  Given the lack of an output schema, the description adequately explains the return value and mentions a relevant follow-up tool. It does not explicitly mention asynchronous processing or how to track the extract, but it is reasonably complete for a create operation with related sibling tools available.

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

  Parameters3/5

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

  The schema description coverage is 100%, so the structured schema already documents all parameters. The description text only lists a subset of parameters (collection, samples, variables, output format) without adding deeper semantic detail beyond what the schema provides, so a baseline of 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the action ('Submit a new IPUMS microdata extract request') and the resource ('IPUMS microdata extract'), with a specific verb and scope. It also lists key inputs and the return value, distinguishing it from sibling tools like nhgis_create_extract by specifying 'IPUMS microdata'.

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

  Usage Guidelines4/5

  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: to submit a new extract request. It also gives follow-up guidance ('Once submitted, use microdata_extract_to_code...'), but does not explicitly mention when not to use it or name alternatives like nhgis_create_extract, though the tool name and IPUMS qualifier imply that distinction.

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

• microdata_list_extractsA
  4/5.0
  Behavior3/5

  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 states the return content (extract numbers, status, basic metadata) but does not mention pagination behavior, ordering, or the exact time range for 'recent'. It is not misleading, but it leaves some behavioral details implicit.

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

  Conciseness5/5

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

  The description is one concise sentence, front-loaded with the primary action and purpose. Every word adds value, and there is no redundant information.

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

  Completeness4/5

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

  For a simple list operation, the description covers the purpose and return content sufficiently. It lacks explicit details about pagination defaults or 'recent' semantics, but the schema provides pageSize/pageNumber, and the operation's simplicity reduces the need for deeper context. An output schema is absent, so the description must disclose return fields, which it does.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema fully documents each parameter. The description adds only an example list of collection values, which overlaps with the enum in the schema. It does not enhance parameter understanding beyond the schema.

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

  Purpose5/5

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

  The description clearly states the tool lists recent extracts for an IPUMS microdata collection, with examples (usa, cps, ipumsi). This specific verb+resource+scope distinguishes it from sibling tools like microdata_create_extract or microdata_get_extract, which have different actions.

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

  Usage Guidelines4/5

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

  The description implies when to use this tool (to list extracts and see their status) but does not explicitly mention alternatives or when not to use it. The sibling context provides clear alternatives, but the description itself only hints at the use case.

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

• microdata_list_samplesA
  4/5.0
  Behavior3/5

  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 implies a read-only operation but does not explicitly state that. It hints at the return content by saying 'find the correct sample ID' but omits details about pagination, response structure, or that results are time-series years. Some behavioral context is given, but not comprehensive.

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

  Conciseness5/5

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

  The description is highly concise: two sentences that front-load the purpose and then provide a usage tip. Every word earns its place, with no filler or redundant information.

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

  Completeness4/5

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

  For a simple list tool with no output schema, the description covers the essential aspects: what it lists, why you would use it, and the typical workflow (before creating an extract). Pagination is implied by the schema parameters. Minor gaps like not describing the exact response format are acceptable given the tool's simplicity.

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

  Parameters3/5

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

  Schema description coverage is 100%, so parameters are already well-documented (collection enum, version, pagination). The description adds a bit of context by noting 'e.g. all ACS, CPS, or Census years' for the collection parameter, but does not add significant 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.

  Purpose5/5

  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 available samples for an IPUMS microdata collection' with concrete examples (ACS, CPS, Census years). The verb 'List' specifies the action, and 'samples' as the resource distinguishes it from sibling tools like microdata_list_extracts or microdata_search_variables.

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

  Usage Guidelines4/5

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

  The description provides explicit usage guidance: 'Use this to find the correct sample ID before creating an extract.' This tells the agent when to invoke the tool. It does not explicitly mention alternatives or exclusions, but the context is clear enough for most cases.

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

• nhgis_create_extractA
  4/5.0
  Behavior3/5

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

  With no annotations, the description carries the burden of behavioral disclosure. It reveals that the tool returns an extract number and initial status, implying asynchronous processing. It does not cover permissions, side effects, or validation behavior, but the core create-and-return semantics are communicated.

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

  Conciseness5/5

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

  The description is three sentences, front-loaded with the primary action, and every sentence adds value: what the tool does, what it returns, and the recommended next step. No wasted words.

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

  Completeness4/5

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

  The input schema is rich with nested objects and 100% parameter descriptions, and the description covers the essential orientation: what to specify, return value, and follow-up. It does not explicitly note that all parameters are optional, but the schema's required fields (none) already convey that. For a complex tool with strong schema support, this is adequately complete.

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

  Parameters3/5

  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 lists the main parameter categories (datasets, time series tables, shapefiles, output format) but adds no syntax or structural detail beyond what the schema already provides.

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

  Purpose5/5

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

  The description uses the specific verb 'Submit' and clearly identifies the resource as 'NHGIS extract request'. It distinguishes from siblings like microdata_create_extract by naming NHGIS and lists the key inputs (datasets, time series tables, shapefiles, output format), establishing a distinct purpose.

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

  Usage Guidelines4/5

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

  The description provides clear context for NHGIS extract creation and explicitly points to nhgis_extract_to_code as the follow-up step, which guides sequential usage. However, it does not explicitly mention alternatives or exclude microdata_create_extract, though the NHGIS naming makes the scope clear.

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

• nhgis_get_datasetA
  4/5.0
  Behavior3/5

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

  With no annotations, the description carries the transparency burden. The verb 'Get' implies a read-only operation, and it describes the kind of data returned, but it does not disclose potential errors, required permissions, or response formatting. This is adequate but not rich for a getter.

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

  Conciseness5/5

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

  The description is a single sentence that states the action, resource, and key content areas without any fluff or repetition. Every word contributes meaningful information.

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

  Completeness4/5

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

  For a simple one-parameter read tool with no output schema, the description gives a solid idea of what will be returned ('data tables, geographic levels, breakdown values, and years'). The lack of an output schema means the description partially compensates by listing content categories, though it does not describe response structure.

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

  Parameters3/5

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

  The input schema already provides 100% parameter coverage with a clear description and examples for 'dataset' (e.g., '2000_SF1a'). The tool description adds no parameter-specific semantics beyond labeling it as a 'specific' dataset, so it does not exceed the schema baseline.

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

  Purpose5/5

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

  The description clearly states the tool's action ('Get full details') and resource ('a specific NHGIS dataset'), and enumerates the scope of details returned ('data tables, geographic levels, breakdown values, and years'). This distinguishes it from siblings like nhgis_list_datasets (listing all datasets) and nhgis_get_data_table (getting a specific table).

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

  Usage Guidelines4/5

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

  The phrase 'for a specific NHGIS dataset' implies the tool is used when you already have a dataset identifier, contrasting with list/search siblings. However, it does not explicitly mention alternatives or when not to use it, so it stops short of fully explicit guidance.

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

• nhgis_list_data_tablesA
  4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly mentions that results are paginated and lists return fields (table identifiers, descriptions, universe), which informs the agent about the response structure and the need to potentially paginate. This is meaningful beyond the schema, though it omits details like rate limits or auth requirements.

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

  Conciseness5/5

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

  The description is exactly two sentences, front-loaded with the main action, and every word is informative. No unnecessary elaboration or repetition of schema details.

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

  Completeness4/5

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

  For a simple listing tool with two well-documented parameters and no output schema, the description adequately covers the return values and pagination behavior. It does not explain how to handle multi-page results or what 'universe' means, but that is likely acceptable for this low-complexity tool.

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

  Parameters3/5

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

  Schema coverage is 100% with both pageSize and pageNumber having descriptions. The tool description adds context about pagination ('paginated list') but does not provide additional parameter-specific meaning beyond what the schema already documents. Baseline 3 applies.

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

  Purpose5/5

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

  The description clearly identifies the verb ('List'), the resource ('NHGIS data tables'), and the scope ('all available across all datasets'). It distinguishes from sibling tools like nhgis_list_time_series_tables and nhgis_list_shapefiles by focusing on data tables specifically.

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

  Usage Guidelines3/5

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

  The description implies usage when the agent needs an unfiltered enumeration of all data tables, but it does not explicitly mention when to avoid this tool or direct users to alternatives like nhgis_search_data_tables for filtered queries. The context is reasonably clear but lacks explicit exclusions.

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

• nhgis_list_shapefilesA
  4/5.0
  Behavior3/5

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

  With no annotations, the description carries the full burden. It discloses that the operation is a read-only list and specifies the return value. However, it does not mention pagination behavior despite the presence of pageSize and pageNumber parameters, nor any other behavioral nuances. This is a notable gap.

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

  Conciseness5/5

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

  The description is concise, consisting of two sentences. It is front-loaded with the verb and resource, and every sentence adds meaningful information without redundancy.

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

  Completeness4/5

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

  Given the simplicity of the tool (no output schema, two optional parameters), the description adequately conveys the tool's purpose and return value. It lacks explicit mention of pagination, but overall it is sufficiently 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.

  Parameters3/5

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

  The input schema provides 100% coverage of both parameters with descriptions. The tool description adds no additional semantic meaning beyond what the schema already conveys, 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.

  Purpose5/5

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

  The description clearly states the specific action ('List all available NHGIS shapefiles') and the resource (shapefiles/boundary files). It also distinguishes itself from sibling tools by specifying that it returns identifiers for census geographies usable in extracts, making its purpose unambiguous.

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

  Usage Guidelines4/5

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

  The description implies a use case: to obtain identifiers for inclusion in extracts. It does not explicitly mention alternatives or exclusions, but the tool's name and the mention of using identifiers in extracts provide sufficient context for when to select this tool over other list tools.

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

• nhgis_search_time_series_tablesA
  4/5.0
  Behavior4/5

  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 tool internally fetches all ~400 time series tables and then filters by keyword, which is a useful behavioral detail. However, it does not mention performance implications, return structure, or error cases, so it's informative but not exhaustive.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with the purpose and a supporting clarification. Every sentence adds value, with no wasted words.

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

  Completeness4/5

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

  Given the low complexity (1 parameter) and lack of output schema, the description adequately explains the tool's operation and the nature of time series tables. It doesn't specify the exact return format, but it's sufficient for a search tool. Some might want more detail, but it's largely complete.

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

  Parameters3/5

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

  The schema description covers the keyword parameter fully with case-insensitive matching explanation. The tool description adds the phrase 'name or description' but that essentially mirrors the schema. With 100% coverage, the baseline is 3, and the description adds minimal extra value.

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

  Purpose5/5

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

  The description clearly states 'Search NHGIS time series tables by keyword' with a specific verb and resource. It distinguishes from sibling tools like list (which likely returns all) and get (which fetches a specific table) by focusing on keyword-based filtering.

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

  Usage Guidelines3/5

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

  The description implies a use case (searching with a keyword) but does not explicitly compare to alternatives such as nhgis_list_time_series_tables or nhgis_get_time_series_table. It does not state when to use this tool instead of others, so while the context is clear, exclusions or alternative references are missing.

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

• microdata_wait_for_extractA
  4.2/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden and does well by disclosing the polling nature, default timeout (90s), early return behavior with status and a command to check back later, and the inclusion of downloadLinks upon completion. It could mention error handling or polling mechanics, but the essential behavioral traits 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.

  Conciseness5/5

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

  The description is three sentences, front-loaded with the core purpose, and includes the most critical behavioral nuance (timeout/early return) without extraneous details. Every sentence earns its place.

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

  Completeness4/5

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

  Given the tool's moderate complexity (5 parameters, no output schema), the description explains the return value (final extract object with downloadLinks) and the early-return fallback. It could describe the interim status object or failure modes, but the description is largely complete for the intended use.

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

  Parameters3/5

  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 some behavioral context around timeoutSeconds (e.g., not blocking conversation) but does not add additional semantic meaning to the individual 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.

  Purpose5/5

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

  The description uses a specific verb 'Poll' with a clear resource 'microdata extract' and a defined outcome ('until it completes or fails'). It clearly distinguishes this from sibling tools like get_extract by emphasizing the waiting/polling behavior and that it returns the final object with downloadLinks.

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

  Usage Guidelines4/5

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

  The description implies the tool should be used when you need to wait for an extract to finish, and notes it returns early under timeout to avoid blocking. It does not explicitly name alternative tools or conditions for when not to use it, but the context is clear enough from the behavior described.

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

• nhgis_get_extractA
  4.2/5.0
  Behavior4/5

  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 reveals that download links are included only when the extract is complete, which is a key conditional behavior. It does not detail error states or permissions, but these are less critical for a read-only status endpoint.

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

  Conciseness5/5

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

  The description is two sentences with no wasted words. It front-loads the core purpose and then adds a useful conditional detail in the second sentence.

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

  Completeness4/5

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

  For a one-parameter status-retrieval tool with no output schema, the description covers the purpose, the target resource, and the key behavioral outcome (download links when complete). It does not explain the exact return structure, but that is not essential for this simple tool.

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

  Parameters3/5

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

  The input schema already fully describes the single parameter (extractNumber) and its meaning. The description adds no extra semantic value beyond restating 'by its number,' so it meets the baseline for schema coverage but does not go further.

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

  Purpose5/5

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

  The description clearly states the tool gets the status and details of a specific NHGIS extract by its number. The verb 'Get' plus the resource and identifier make the purpose unambiguous and distinguish it from sibling tools like nhgis_list_extracts and microdata_get_extract.

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

  Usage Guidelines4/5

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

  The description implies when to use the tool: when you have a specific extract number and need its status/details. It does not explicitly name alternatives or exclusions, but the context is clear enough for a simple retrieval tool.

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

• nhgis_list_datasetsA
  4.2/5.0
  Behavior4/5

  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 pagination behavior ('Returns paginated list') and the exact fields returned, clearly indicating a read-only metadata listing. It does not cover auth or rate limits, but for a simple browse tool this is a reasonable level of transparency.

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

  Conciseness5/5

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

  The description is extremely concise, with only two sentences: the first states the purpose, the second states the output. Every word contributes value, and it is front-loaded with the primary verb and resource.

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

  Completeness4/5

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

  For a simple list tool with two optional parameters and no output schema, the description covers the essential aspects: what it does, what it returns, and the pagination behavior. It could mention default page size or that it returns only metadata, but these are minor gaps given the tool's simplicity.

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

  Parameters3/5

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

  The schema already provides descriptions for both parameters ('Results per page' and 'Page number (1-based)'), and the description adds no additional parameter-level detail beyond noting pagination. Since schema coverage is 100%, baseline 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the tool's action ('Browse') and resource ('available NHGIS datasets'), and specifies the return content (dataset identifiers, names, years, geographic levels). This distinguishes it from sibling tools like nhgis_list_data_tables or nhgis_search_datasets, which have different scopes.

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

  Usage Guidelines4/5

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

  The description gives clear context for browsing datasets ('Browse available NHGIS datasets'), but it does not explicitly mention alternatives or when not to use it. It lacks the explicit exclusions or alternative tool references seen in higher-scoring examples, but the context is unambiguous.

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

• nhgis_search_datasetsA
  4.2/5.0
  Behavior4/5

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

  With no annotations, the description carries the burden. It discloses a key behavioral trait: 'Fetches all available datasets and returns those whose name, group, or description match,' which hints at a broader fetch-then-filter approach. It does not cover pagination or return format, but for a simple read-only search, this is adequate.

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

  Conciseness5/5

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

  The description is two sentences long, front-loaded with the action, and every sentence adds value. The first sentence defines the operation and matching logic, the second provides usage guidance. No wasted words.

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

  Completeness4/5

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

  The tool is simple (1 parameter, no output schema), and the description fully explains what it does, what it matches on, and when to use it. It doesn't describe return values, but that is not required given the lack of a complex output schema and the simplicity of a search operation.

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

  Parameters3/5

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

  The schema already covers the keyword parameter with a description identical to the tool's explanation: 'Search term to match against dataset name, group, and description (case-insensitive).' The tool description adds no new semantic details beyond what the schema provides, so baseline 3 applies.

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

  Purpose5/5

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

  The description clearly states 'Search NHGIS datasets by keyword' with a specific verb and resource. It further specifies the matching criteria (name, group, description) and distinguishes itself from sibling tools like nhgis_search_data_tables by mentioning 'before drilling into specific data tables.'

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

  Usage Guidelines4/5

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

  It provides explicit usage context: 'Use this to find which datasets cover a topic or census year before drilling into specific data tables.' This implies it is a discovery-first tool, though it does not explicitly name alternative tools or state when not to use it.

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

• nhgis_extract_to_codeA
  4.3/5.0
  Behavior4/5

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

  With no annotations, the description carries the burden. It discloses that the tool 'Fetches the extract definition by number and emits code that re-submits the same request,' clarifying it does not itself submit the extract but only generates code. This is a key behavioral nuance beyond the input schema.

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

  Conciseness5/5

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

  The description is three sentences, leading with the primary purpose. No filler or repetition. Every sentence adds value: what it does, how it works, and when to use it.

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

  Completeness5/5

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

  The tool is a simple code generator: given an extract number and optional language, it returns ready-to-run code. The description covers the output's purpose and usage context. Without an output schema, the description adequately conveys the functional scope; no critical behavioral gaps remain.

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

  Parameters3/5

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

  Schema coverage is 100%: both language and extractNumber have descriptive text in the schema. The description does not add parameter semantics beyond what the schema already provides, so the baseline 3 applies.

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

  Purpose5/5

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

  The description opens with a specific verb+resource: 'Generate ready-to-run R (ipumsr) and/or Python (ipumspy) code to reproduce an NHGIS extract.' It clearly differentiates from sibling microdata_extract_to_code by explicitly naming NHGIS and the relevant R/Python packages.

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

  Usage Guidelines4/5

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

  The description says 'Use this after nhgis_create_extract to capture a reproducible workflow,' providing explicit when-to-use context. It does not mention when-not-to-use or name alternatives explicitly, but the NHGIS qualifier and relationship to create_extract imply exclusion of non-NHGIS contexts.

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

• nhgis_get_time_series_tableA
  4.3/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the full burden of behavioral disclosure. It transparently states key output content (years, geographic levels, variable descriptions) and implies a read-only lookup via 'Get'. It does not discuss error conditions or permissions, but for a simple retrieval tool this is adequate and informative.

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

  Conciseness5/5

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

  The description is a single sentence that is front-loaded with the action and resource, followed by a concise enumeration of what 'full details' includes. No filler or redundant content.

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

  Completeness5/5

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

  For a one-parameter getter tool with no output schema, the description is well-rounded: it states the input scope (specific table) and the expected return categories (years, geographic levels, variable descriptions). This gives an agent enough context to invoke the tool correctly without extra elaboration.

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

  Parameters3/5

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

  Schema description coverage is 100%: the 'table' parameter has a clear description, pattern, and example. The tool description does not add additional parameter context, so it relies entirely on the schema. Per the baseline for high coverage, this is acceptable at a 3.

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

  Purpose5/5

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

  The description uses a specific verb ('Get full details') with a clear resource ('NHGIS time series table') and explicitly lists what details are included (years, geographic levels, variable descriptions). This distinguishes it from siblings like nhgis_list_time_series_tables (list discovery) and nhgis_search_time_series_tables (search).

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

  Usage Guidelines4/5

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

  The description provides clear context: use this when you need full details for a specific time series table. It does not explicitly name alternatives like search or list, but the 'specific table' wording implies that discovery tools should be used to find table identifiers first, making the intended usage reasonably clear.

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

• microdata_extract_to_codeA
  4.4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the behavioral burden. It clearly discloses that the tool 'fetches the extract definition by number' and 'emits code that re-submits the same request,' implying a read-only code-generation behavior. It does not detail side effects, authentication requirements, or error scenarios, but the core behavior is transparent.

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

  Conciseness5/5

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

  The description is three sentences, each earning its place: first states the purpose, second explains the mechanism, third provides workflow timing. It is front-loaded with the core action and contains no filler.

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

  Completeness4/5

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

  Given no output schema and no annotations, the description adequately covers the tool's role in the workflow (after create, before download), names the supported languages, and clarifies that it produces re-runnable code. It does not describe return format or edge cases, but these are not critical for using the tool correctly.

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

  Parameters4/5

  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 meaning by mapping 'R (ipumsr)' and 'Python (ipumspy)' to the language enum and explaining 'extract number' as the identifier for reproducing a request. This goes slightly beyond the schema's own descriptions.

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

  Purpose5/5

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

  The description opens with a specific verb+resource: 'Generate ready-to-run R (ipumsr) and/or Python (ipumspy) code to reproduce a microdata extract.' It clearly states the tool's function and distinguishes it from sibling tools like microdata_get_extract (which returns metadata) or microdata_download_extract (which downloads data), focusing on code generation for reproducibility.

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

  Usage Guidelines4/5

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

  The description explicitly says 'Use this after microdata_create_extract to capture a reproducible workflow,' giving a clear sequential context. However, it does not name alternative tools or explicitly state when not to use it, so there is room for stronger guidance relative to siblings.

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

• microdata_search_variablesA
  4.4/5.0
  Behavior4/5

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

  With no annotations, the description carries the burden. It discloses the source (scraped from usa.ipums.org), the 827-variable scope, and notes that sample IDs are representative (not exhaustive). It does not explicitly state read-only behavior, but the nature of a search tool makes that implicit. The 'scraped' caveat adds useful transparency about data freshness.

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

  Conciseness5/5

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

  The description is four sentences, front-loaded with the core action and return fields, then usage guidance, and a final data-source caveat. No redundant filler; every sentence adds value. It is compact yet complete.

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

  Completeness4/5

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

  For a search tool with no output schema, the description adequately lists return fields and usage context. It does not explicitly mention partial-match behavior for the query parameter, which is implied by 'search' but could be clearer. Given the 5 parameters and no output schema, it is mostly complete but leaves a tiny gap.

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

  Parameters3/5

  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 minimal parameter-specific meaning beyond the schema—it does explain the 'sample' field in output and cross-references microdata_list_samples, which indirectly clarifies the sample parameter, but does not dive into syntax or edge cases. Thus 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the tool searches IPUMS USA harmonized variable mnemonics by name or label and returns specific fields (label, record type, thematic group, sample IDs). It distinguishes itself from sibling tools like microdata_list_samples by focusing on variable discovery and explicitly cross-referencing that sibling.

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

  Usage Guidelines5/5

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

  Explicitly states 'Use this to discover variable names before building an extract' and advises cross-referencing with microdata_list_samples for sample IDs. This gives clear when-to-use guidance and points to an alternative, fulfilling the dimension fully.

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

• nhgis_search_data_tablesA
  4.7/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden of disclosing behavior. It reveals the scan limit (up to 2,500 tables), the matching criteria, and that specifying a dataset yields comprehensive results. It stops short of detailing return format or pagination, but the provided behavioral context is strong for a search tool.

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

  Conciseness5/5

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

  The description is concise, front-loaded with the core purpose, and each sentence adds critical value: what it does, how scope changes behavior, and a concrete recommendation. No redundant wording.

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

  Completeness5/5

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

  Given no output schema, the description provides enough context for an agent to decide when to invoke and what to expect: searchable fields, scope limitations, and a recommended alternative workflow. It fully covers the tool's complexity and fits well within the sibling-tool ecosystem.

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

  Parameters4/5

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

  Schema coverage is 100%, and both parameters are already described. The description adds meaningful context beyond the schema: the 'dataset' parameter's impact on comprehensiveness and the keyword's matching scope. This enhances understanding of parameter usage, especially the recommended workflow.

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

  Purpose5/5

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

  The description uses a specific verb ('Search') with a clear resource ('NHGIS data tables'), and immediately differentiates from sibling tools by focusing on data tables rather than datasets or time series tables. It also specifies matching fields (description and universe), leaving no ambiguity about the tool's function.

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

  Usage Guidelines5/5

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

  The description provides explicit guidance: without a dataset it scans up to 2,500 tables, and it recommends using nhgis_search_datasets first to scope the search. This directly addresses when to use this tool vs. alternatives and gives a clear workflow.

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