query_imported_datasetUse this paid read-only tool after sample_imported_dataset confirms the data is suitable. Returns up to 100 normalized rows from a published snapshot with bounded pagination, one exact-match filter, freshness, and provenance.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | ||
| skip | No | ||
| dataset_id | Yes | ||
| filter_field | No | ||
| filter_value | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: the tool is paid, returns at most 100 rows, has bounded pagination (skip max 5000), supports exactly one exact-match filter, and provides normalized rows with freshness and provenance. These details help the agent predict behavior without contradiction, giving strong transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence. It front-loads the usage condition ('Use after sample_imported_dataset'), then lists key functional traits. There is no redundancy or filler; every phrase contributes to the agent's understanding. Concise yet informative.
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 5 parameters, no output schema, and a decent level of complexity, the description covers the essential context: when to use it, what it returns, and its limitations (pagination, filter). It does not detail the output row schema or error behaviors, and the filter semantics are left somewhat open. However, given that the agent is expected to have interacted with sample_imported_dataset, the missing details are partially mitigated. It is strong but not exhaustive.
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 0%, so the description must compensate. It explains that 'top' and 'skip' relate to bounded pagination (max 100 and 5000), and mentions 'one exact-match filter' which maps to filter_field and filter_value. However, it does not explain what filter_field should contain (e.g., a column name) or how to obtain dataset_id, leaving significant semantic gaps. It adds moderate meaning beyond the bare schema but is not comprehensive.
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 ('query'), a resource ('imported dataset'), and key output characteristics (normalized rows, bounded pagination, one exact-match filter). It also distinguishes itself from siblings by referencing sample_imported_dataset as a precursor and implying a different purpose than aggregate_imported_dataset. The purpose is unambiguous and not a tautology.
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 instructs to use this tool after sample_imported_dataset confirms data suitability, providing a clear sequencing condition. It implies that this is for retrieving actual rows rather than sampling or aggregating, but does not explicitly exclude other alternatives like aggregate_imported_dataset or mention when not to use it. The guideline is present and actionable but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
Each tool maps to a distinct lifecycle stage: discovery, materialization, sampling, querying, aggregation, and payment. The main ambiguity is between search_public_datasets and search_discovered_datasets, plus some overlap between get_coverage_status and list_official_sources, but the descriptions provide enough guidance for most selections.
All tools use a consistent verb_object snake_case pattern with clear verbs: get_, list_, query_, request_, sample_, search_, and aggregate_. State-changing actions uniformly use request_, and status reads uniformly use get_.
With 14 tools, the server is well within the ideal range and each tool earns its place across the data lifecycle: discover, materialize, sample, query, aggregate, and manage access. The count feels complete without being padded.
The set covers discovery, materialization, sampling, querying, aggregation, coverage status, and paid access, with provenance embedded throughout. Minor gaps exist around the 'insights' promised in the server name and lifecycle operations like cancellation or removal, but agents can generally complete core workflows.