ABS Data (observed)

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

With no annotations provided, the description carries the behavioral disclosure burden. It explains important behavior: dimensions up to 64 options are listed inline with labels, while larger ones only report counts and require search_options. This gives an agent realistic expectations about output size and follow-up actions, even if it does not discuss auth, caching, or failure modes.

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 with no filler. The first sentence front-loads the core output contents, and the second efficiently explains the threshold behavior and the search_options alternative. Every sentence earns its place.

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

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

For a one-parameter describe operation with an output schema, the description is nearly complete. It tells the agent what to expect, how large option sets are handled, and where to go for more. It could explicitly state that this is a metadata-only operation, but the output and sibling context make that reasonably clear.

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 single 'table' parameter is already documented as a Dataflow id in the input schema. The tool description does not add further meaning to the parameter, which is acceptable because the schema handles it. 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 identifies what the tool returns: a table's dimensions in key order, coverage dates, and observed options. It also distinguishes itself from search_options by noting that larger option sets are handled separately. It lacks an explicit action verb in the description, but the title and name supply the 'describe' action.

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

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

The description implies when to use this tool—when you need table structure and dimensions—and points to search_options for searching large option sets. However, it does not explicitly state when to use describe_table versus other siblings like search_tables, get_data, or execute. The usage context is reasonably clear but left mostly to inference.

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

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

With no annotations provided, the description carries the full behavioral burden and meets it: it discloses the sandbox isolation, the single `abs` capability, the absence of network access, CPU/call/wall-clock/result budgets, the async execution model, console.log capture, and the structured error thrown by getData. This is exactly the operational detail an agent needs before running arbitrary code.

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

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

The description is long, but the length is earned: the interface definitions and budget details are necessary for writing correct code. The first paragraph front-loads the core purpose, execution model, and constraints, while the interface block provides structured reference material rather than prose redundancy.

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

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

For a tool with no annotations and a single free-form code parameter, the description is remarkably complete: it covers what code can do, what it cannot do, operational limits, async mechanics, output expectations, and error recovery. Since an output schema exists, the description does not need to document return values, and nothing essential appears missing.

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

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

The schema already documents the `code` parameter at 100% coverage, but the description goes far beyond it by specifying the execution environment, the full `Abs` client interface, budget limits, the requirement to `return` a value, and error-handling behavior. For a code-execution tool, this is substantial added meaning that the schema alone could not convey.

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

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

The description opens with a precise statement of what the tool does: runs JavaScript in an isolated sandbox with an `abs` client, and it explicitly ties that to multi-series or multi-table analysis. This clearly distinguishes it from the sibling data-access tools, which provide direct single-purpose verbs like get_data or search_tables.

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

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

The description gives concrete usage scenarios ('multi-series or multi-table analysis', 'compute growth rates, rank capitals, join tables') and explains that the tool should return only computed results so large payloads do not reach the conversation. It does not explicitly name sibling tools as fallbacks for simple queries, but the use-case framing makes the intended boundary 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?

With no annotations, the description carries the full disclosure burden, and it delivers: live verification against ABS, the guarantee that successful calls return real data, row caps/defaults, response contents (summary and URL), and invalid-selection behavior. This goes well beyond what the schema alone provides.

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?

Five purposeful sentences move from core purpose to selection semantics, verification, output behavior, and error handling. Every sentence earns its place, and there is no filler or unnecessary repetition of schema fields.

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

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

The description is behavior-rich and, combined with an output schema, covers most of what an agent needs for a straightforward fetch. The notable gap is that the required `table` parameter is left unexplained and sibling tools are not referenced for discovering valid table identifiers or options.

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

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

The description adds real meaning for `select` (codes or labels, multiple allowed, omitted dimensions match all) and clarifies default period/maxRows behavior. However, schema coverage is only 57%, and the required `table` parameter plus `firstN`/`endPeriod` are not meaningfully described, so the compensation is incomplete.

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

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

The description opens with 'Fetch observations,' a concrete verb and resource, and immediately establishes the ABS data context. This makes it easy to distinguish get_data from the search/describe siblings, even though no explicit sibling names are used.

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 ABS observation context and selection semantics imply this is the tool for pulling data once a dataset is known, but it never explicitly states when not to use it or routes to search_tables/search_options for finding valid tables or options. The 'asked to choose from the valid ones' hint suggests an iterative workflow but does not name alternatives.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly describes the isolated sandbox, no-network execution, async function context, in-scope `catalogue` object, JSON-serialisable return requirement, and captured console.log output. This gives an agent an accurate model of side effects and execution environment.

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 prose is front-loaded with the core purpose and the code block is well structured. The description is long, but nearly every line is necessary for an arbitrary-code tool; the three examples add clarity though one or two might have sufficed.

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 single-parameter code-execution tool, the description provides everything needed: when to use it, what is in scope, exact data shapes, and output/return behavior. The reference to `abs.searchOptions in execute` is slightly cryptic, but the overall contract is complete.

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

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

The input schema only says the parameter is JavaScript and must return a value. The description compensates with the complete Catalogue interface, including table shapes, dimension structures, codelist maps, and frequency/coverage fields. This goes far beyond schema coverage and enables an agent to write realistic code.

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

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

The description states a specific verb and resource: run JavaScript against the whole catalogue document. It distinguishes itself from the fixed-verb siblings by explaining it exists for questions those tools make awkward, and it provides concrete examples. The title and description align cleanly.

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

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

It explicitly says to use this tool when the fixed verbs make a question awkward and gives three representative query shapes. It does not name the sibling tools directly or say exactly which one each example would replace, but the intended usage context is unambiguous.

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

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

No annotations are provided, so the description must carry the behavioral burden. It communicates a read-only lookup and the purpose of the returned codes, but does not disclose matching semantics such as partial vs exact matches, case sensitivity, trimming, or what happens when many or no matches occur. Some credit is given because the tool's non-mutating nature is evident from 'Find' and 'Returns codes'.

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

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

The description is compact and well structured. The main action is front-loaded, the example adds clarity, and the final sentence provides meaningful downstream guidance for using the result, with no filler 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?

The description and output schema together are mostly adequate for a simple lookup tool, but it lacks guidance on matching behavior and the limit parameter. Because there are no annotations and schema coverage is low, these gaps make the description only partially complete for an agent deciding whether and how to call it.

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

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

Schema description coverage is only 25%, with only 'query' documented, and the description does not fully compensate. It adds meaning for table and dimension by saying the search is scoped to one table and one dimension, but it says nothing about the 'limit' parameter, and only the schema's existing line covers query matching.

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, resource, and scope: finding option codes by label within one dimension of one table, with a concrete suburb/geography example. It also differentiates the tool by explaining the result is for use in get_data's select, setting it apart from generic search or search_tables.

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

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

The description gives a clear context: use this when you need option codes for a dimension within a specific table, and it positions the result as an input for get_data. It does not explicitly say when not to use sibling search tools, but the scoping language ('within one dimension of one table') is enough to make selection clear.

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

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

No annotations are provided, so the description carries the full burden. It discloses key behaviors: matching includes option labels (e.g., 'rent' finds 'Rents' in CPI), collapsed Census tables with familyGeographies, and that results are confirmed to serve data (not from documentation). It could mention pagination or sorting, but the provided details are valuable and go beyond a simple statement.

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 but rich, with a clear flow: what it searches (topics, geography, frequency), how it matches (including options), a special behavior (collapsing geographies), a guarantee (confirmed data), and a routing suggestion. Each sentence adds value, and the key purpose is front-loaded.

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

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

Given the tool has an output schema, the description doesn't need to explain return format. It covers the main search dimensions, edge cases (option labels, family geographies), and sets expectations (results are confirmed). With 4 optional parameters and an output schema, the description is sufficiently complete for an agent to call it correctly.

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

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

Schema description coverage is 75%, and the remaining gaps are covered by the description to some extent. The description elaborates on the query parameter (searching across various fields) and the geography filter (for family geographies). It doesn't detail frequency semantics beyond the schema's enum, but the schema already provides that. The description adds meaningful context for query and geography, so it helps compensate for the uncovered 25%.

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

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

The description clearly states the tool's purpose: finding ABS statistical tables by topic, geography, or frequency. It specifies the resources (dataflows/tables) and differentiates it from siblings like search_options and describe_table by mentioning 'matches table names, topics and dimension names, and also option labels inside dimensions' and suggesting 'Start here, then describe_table.'

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

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

The description gives explicit guidance on when to use this tool: 'Start here, then describe_table.' It also explains a behavior that helps filtering: 'Census tables published at several geography levels are collapsed to one result with familyGeographies listing the others (use the geography filter to pick one).' This provides clear context for usage, though it doesn't explicitly mention when not to use it, but the context is strong.

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