Nova Scotia Data Explorer

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 states the return content (column field names, data types, descriptions) and positions the tool as a prerequisite for querying. However, it does not disclose potential limitations, error conditions, or whether any side effects or permissions are involved. The safety profile is implied but not explicit, so a mid-range score is appropriate.

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

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

The description is two sentences long, with the key action and resource placed upfront. Every clause adds value: the identifier format, the return content, and the critical usage context (before query_dataset). There is no redundancy or filler.

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 metadata retrieval tool, the description covers what it does, what it returns, and why it matters (for query_dataset). It does not detail error handling or output structure, but given the simplicity of the tool and the presence of a clear usage narrative, it is sufficiently complete for an agent to invoke it correctly.

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

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

Schema coverage is 100% for the single parameter, and the schema description already includes the 8-character Socrata identifier format with an example. The description repeats the example and adds context about Nova Scotia Open Data, but it does not meaningfully extend the semantics beyond what the schema provides. This matches the baseline of 3 for high schema coverage.

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

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

The description opens with a specific verb ('Retrieve') and a clear resource ('full schema and metadata for a Nova Scotia Open Data dataset'), with a concrete identifier format. It clearly distinguishes from sibling tools list_categories, query_dataset, and search_datasets by focusing on metadata retrieval rather than data querying, searching, or category listing.

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

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

The description explicitly states when to use this tool: 'essential before calling query_dataset', and explains why (to know exact field names for $select and $where clauses). It names a specific sibling tool as the downstream consumer, providing strong contextual guidance. However, it does not explicitly mention when not to use it or compare to search_datasets/list_categories, so it stops short of the full 5.

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

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

No annotations are provided, so the description carries full behavioral disclosure burden. It states a read-only action ('Returns') but does not explicitly mention lack of side effects, data freshness, or any output format details. For a simple list tool this is adequate but not rich, leaving some behavioral aspects implicit.

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

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

Two sentences that are front-loaded with the core purpose followed by actionable usage guidance. Every sentence earns its place with no redundancy or filler.

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

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

Given the tool's simplicity (zero parameters, no output schema), the description is largely complete. It communicates the return value (categories and popular tags) and workflow. However, since there is no output schema, a brief note on response structure (e.g., 'as an array') would fully close the gap, but the current depth is sufficient for a task of this complexity.

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

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

The tool has zero parameters, so the schema provides complete coverage. The baseline for zero params is 4, and the description adds context by implying the parameters are category names (as referenced in usage guidance) without needing to detail any input structure.

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

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

The description clearly states the tool's function: 'Returns all dataset categories and popular tags available on the Nova Scotia Open Data portal.' The verb 'Returns' and specific resource distinguish it from siblings like search_datasets, which filters by categories.

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?

Explicit usage guidance: 'Use this first to discover valid category names before calling search_datasets with a category filter.' This tells the agent when to use this tool and how it relates to the alternative search_datasets, providing immediate workflow context.

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

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

With no annotations, the description carries the behavioral burden and delivers: default/maximum row counts, pagination via $offset, grouping, aggregates, and full-text search. It clearly implies a non-destructive query operation, though it does not describe the response shape or error behavior.

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?

Despite the length, every line contributes: the opening sentence states the purpose, clauses are grouped in a compact list, and three concrete examples illustrate usage. The front-loaded structure makes the syntax reference scannable.

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

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

The description is rich enough for a complex query tool with no output schema, covering syntax, limits, aggregation, and prerequisite metadata call. However, it does not mention likely failure modes or response format, leaving a small completeness gap.

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

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

Schema already covers all three parameters with 100% coverage, so baseline is 3; description adds a full SoQL clause reference and examples that clarify how to combine parameters and construct queries. It stops short of 5 because the parameter-specific descriptions in the schema already carry most of the semantics.

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 'Run a SoQL query against a Nova Scotia Open Data dataset'—a specific verb and resource. This clearly differentiates it from siblings like get_dataset_metadata, list_categories, and search_datasets.

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

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

Provides explicit instruction to 'Always call get_dataset_metadata first to find exact field names,' establishing the intended workflow. It also documents when to use each SoQL clause, but does not explicitly contrast with sibling search tools, stopping short of a 5.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses return fields and the workflow role, but does not explicitly state read-only nature, pagination behavior, rate limits, or error conditions. For a search tool this is acceptable but not rich.

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

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

Three sentences, front-loaded with the core action, no filler. Each sentence adds distinct information: action and return, prerequisite, and next steps.

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?

No output schema exists, but the description explicitly lists return fields and provides a complete usage flow with sibling tools. Parameters are well-documented in the schema. Lacks explicit error handling or pagination semantics, but these are covered by the schema's limit/offset defaults.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds workflow context by naming the three search modes (keyword, category, tag) and advising use of list_categories for valid category/tag names, meaningfully supplementing the schema.

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

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

The description clearly states the tool searches the Nova Scotia Open Data catalog by keyword, category, or tag, and explicitly lists the return types (names, IDs, descriptions, column names, portal links). It distinguishes from siblings by positioning list_categories as a prerequisite and query_dataset/get_dataset_metadata as follow-ups for returned IDs.

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

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

The description explicitly instructs users to call list_categories first to obtain valid category and tag names, and to use the returned dataset ID with query_dataset or get_dataset_metadata for further exploration. This provides a clear when-to-use and a workflow across sibling tools.

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