Atlas Data Exchange

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

With no annotations, the description carries the disclosure burden. It adds useful behavioral context by noting the answer is live, limiting the scope to listed domains, and summarizing the return payload (verdict, evidence, datasets, purchase path). However, it does not state whether invoking is read-only or may incur charges, how out-of-scope questions are handled, or what error behavior looks like.

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, front-loaded sentence with no filler. The examples are compact and convey both the query style and the scope, making the definition efficient and 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?

Despite clear purpose and concise wording, the definition lacks crucial operational context given there is no output schema or annotations. It does not clarify whether asking a question can initiate or surface costs through the purchase path, what bbox_source refers to in practice, or how the agent should handle unsupported question types. These gaps make it incomplete for safe and correct invocation.

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

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

The bbox parameter is described in the schema, including its order and the optional preset-box behavior. The question parameter has no schema description, and the tool description only partially compensates by listing acceptable question topics. It also references bbox_source, a field not present in the input schema, leaving some ambiguity.

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 names a specific verb and resource ('Ask a question Atlas can answer live') and enumerates concrete question categories such as seismic unusual activity, wave energy, commodity regimes, logistics safety, and alert-worthy cells. This makes the tool's purpose unmistakable and clearly distinguishes it from siblings like search_products or inspect_product.

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

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

The description provides clear context: this is for live natural-language questions that Atlas can answer, with examples of when to use it. It does not explicitly name alternatives or state when not to use the tool, so it stops 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?

With no annotations, the description carries the burden of behavioral disclosure. It explicitly says the tool does not move money, requires a session or Stripe checkout, and mentions terms, idempotency, and metering. This is significantly more transparent than a typical mutation tool description, though it does not detail error behavior or auth beyond the session note.

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 deliver dense, useful information with the main purpose front-loaded. The endpoint details, behavioral caveat, and prerequisite are all stated without wasted words.

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

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

The description covers purpose, endpoints, idempotency, metering, and the session/checkout requirement, which is good for a call with no output schema. But it does not specify how to choose between the two endpoints, what values tier accepts, or what the response contains, so it is not fully complete.

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

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

Schema description coverage is 0%, so the description must compensate. It maps the call to 'product and tier,' which aligns with the slug and tier parameters, and distinguishes one-time vs subscription paths. However, it does not explain valid tier values, endpoint selection criteria, or slug format, leaving meaningful gaps.

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 performs a purchase for a product and tier, and gives concrete endpoint paths for one-time packs and subscriptions. It is specific and not a tautology, though it does not explicitly name sibling tools to draw the distinction beyond calling itself 'the exact purchase call'.

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 clear context: this is the purchase call, with different endpoints for one-time vs subscription, and it requires a session or Stripe checkout. It does not explicitly list alternatives or exclusion conditions, but the framing strongly implies when this tool should be used.

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 burden. It discloses one behavioral trait: 'Does not move money'. However, it fails to mention other important behaviors such as whether it creates a persistent resource, requires authentication, is idempotent, or what side effects occur. This is inadequate for a mutation tool.

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, efficient sentence that front-loads the core purpose and key differentiators. There is no fluff or redundancy, making it highly concise.

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

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

Given the tool's complexity (8 parameters, no output schema, no annotations), the description is severely incomplete. It mentions a webhook contract but does not describe it, and it does not explain how parameters like tier, cohorts, signals, or min_confidence should be used. An agent would struggle to call this tool correctly with only the provided information.

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% (2 out of 8 parameters have descriptions). The description adds no parameter-level detail, only vaguely referencing 'filters given' without mapping to specific parameters. It fails to compensate for the low schema coverage, leaving most parameters unexplained.

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 it is the exact subscribe call for a watch (mode=watch), includes filters, tier, price, metering, and webhook contract, and explicitly notes it does not move money. This distinguishes it from sibling tools like buy_product and quote_watch, providing a specific verb and resource.

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 provides context that this is a subscription call and mentions 'mode=watch' and 'Does not move money', which implies it is for actually subscribing rather than quoting or purchasing. However, it does not explicitly mention when to use it over alternatives like quote_watch, nor does it state any exclusions or conditions.

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 present, the description carries the disclosure burden and does a good job: it explains auth-dependent behavior, the 10-event cap, and the presence of limit_applied/limit_max in the response. The only significant behavioral gap is the lack of explanation for the dry_run parameter and any side-effect profile, though the read-oriented phrasing mitigates this.

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

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

The description is three tight sentences with the core definition front-loaded before the mode-specific details. Every sentence carries distinct information and there is no 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 read-only change-feed tool, the description covers the essential invocation modes, the endpoint, and key response fields despite the absence of an output schema. Minor omissions—dry_run semantics and cursor format—prevent full completeness, but an agent can still invoke the tool correctly in either mode.

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 0%, so the description must compensate. It adds meaning for since (cursor), api_key (switches between modes), and slug (path parameter in the feed endpoint), but it does not explain dry_run or the expected cursor format/type. This partial compensation merits a mid-range score.

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 a specific operation: fetching change events since a cursor, and further distinguishes anonymous preview behavior from authenticated subscription feed behavior. It references the concrete endpoint (GET /api/feeds/{slug}/changes), making an agent confident about what resource is being accessed.

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?

Usage context is clearly split into two cases: anonymous callers get a limited latest-day preview, while authenticated callers use an api_key to access their subscription feed. It does not explicitly list sibling alternatives or say when not to use the tool, so it falls 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?

With no annotations, the description carries the full burden for behavioral disclosure. It describes what information the call reports, but it does not mention whether the operation is read-only, what authentication or API key scoping is required, error behavior, or response shape.

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, compact sentence that front-loads the resource and then lists the reported fields. There is no filler or redundant restatement of the tool name.

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?

Although the output fields are useful, an agent still lacks critical invocation context: the meaning of slug/days/resolution, any usage guidance, and any annotation-derived safety or side-effect information. This is not enough for a four-parameter tool with an empty schema coverage and no output schema.

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

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

Schema description coverage is 0%, so the description must explain the parameters, but it only echoes api_key as the subject and says nothing about slug, days, or resolution. The output-field list provides some context for the tool overall but does not map to any input parameter's meaning.

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 identifies the resource (an api_key's entitlement) and enumerates the returned data: tier, credit quota, used, remaining, projected request cost, and reset date. It is clear enough to distinguish from the sibling tools, though it expresses the action implicitly rather than with an explicit verb.

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?

There is no guidance on when to use get_entitlement versus any alternative, and no mention of prerequisites or typical query context. An agent can infer the basic use case from the name and fields, but the description never states it or excludes other tools.

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

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

With no annotations, the description carries the full behavioral burden. It enumerates the output fields comprehensively, providing insight into what the tool returns. However, it does not explicitly state that the operation is read-only or non-destructive, nor does it mention error conditions or rate limits. The behavior is largely transparent through the output description, but lacks explicit safety declarations.

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 sentence with a colon-separated list of fields, which is compact and front-loaded with the core purpose. It is slightly dense but avoids extraneous wording. The structure effectively communicates the tool's scope in one breath.

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 that there is no output schema, the description thoroughly explains what the tool returns, covering pricing, quality, SLOs, provenance, and limitations. It leaves little ambiguity about the tool's capabilities. The only missing aspect is explicit mention of the parameter, but that is a minor gap compared to the richness of the output description.

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%, and the description does not mention the parameter 'slug' at all. The schema only indicates a required string, leaving the meaning of 'slug' ambiguous. The description fails to compensate for the schema's lack of documentation, so the parameter's semantics are unclear beyond the obvious product identifier inference.

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 the tool as retrieving the full machine-readable commercial contract of a product, listing specific fields (pricing ladder, credit multipliers, etc.). It distinguishes itself from siblings like search_products or sample_product by focusing on comprehensive contract details. The verb 'inspect' and resource 'product' are explicit.

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 usage when an agent needs the full contract details, but it does not explicitly mention when to prefer this over alternatives such as search_products or sample_product. There is no when-not-to-use guidance or mention of other tools for partial or summary views. The usage context is inferred from the detailed output list.

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 clearly states the return contract: ranked products, cheapest fitting tier, estimated records/credits, cost, and the exact purchase call, which signals this tool prices rather than executes a purchase. It does not mention persistence or side effects, but the stated behavior is materially transparent.

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 one compact sentence with no filler. The action is front-loaded, parameter groups are listed efficiently, and the return value is stated at the end. Every part 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?

Given 10 optional parameters and no output schema, this description is too thin. It tells the agent what the tool returns but leaves important usage gaps: whether at least one filter is required, whether region and bbox are mutually exclusive, how resolution/window_days/max_age_hours interact, and how this quote tool differs from quote_watch.

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 10% (only bbox is described), so the description must compensate. It lists all parameter names and hints at grouping (text/keywords/category and region/bbox), but it does not explain meaning, constraints, interaction, or which filters are required for a valid quote request. This adds only marginal value over the parameter names.

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

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

The description uses a specific verb ('Quote') and resource ('a dataset need') while enumerating accepted criteria and return contents, so an agent can tell what the tool does. It does not explicitly distinguish itself from the sibling quote_watch, preventing a 5.

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 phrase 'Quote a dataset need' provides implied usage context: use this when you want a quote for data matching certain criteria. However, there is no explicit guidance about when to choose quote_request over quote_watch, search_products, or sample_product, and no stated exclusions.

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 and does disclose key behavior: it ranks products, selects the cheapest tier meeting needs, respects budget, estimates events/credits, and notes that watch events cost 5 credits. It does not mention side effects or authorization, but the quote nature and pricing details provide solid 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 dense sentence that packs in inputs, transformation, and output characteristics without filler. It is front-loaded with the core purpose and every clause adds relevant information, though the long arrow chain is somewhat unwieldy.

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 7 parameters and no output schema, the description covers the main output and pricing behavior but leaves gaps such as parameter value formats for cohorts/signals, whether any inputs are effectively required, and how this quote relates to actually creating a watch. It is adequate but not fully complete for confident invocation.

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

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

Schema description coverage is low (29%), and the description compensates by naming all major filters and the budget concept, but it does not explain the meaning or accepted values for cohorts and signals. It adds grouping and intent but stops short of fully documenting parameter 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 identifies a specific action (quote a watch/signal feed) and a distinct resource, and clarifies that the output is a ranked product with pricing tiers. It references quote_request as a comparison, which helps orient the tool among siblings, though it does not explicitly define the boundary between quote_watch and quote_request.

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 explains what inputs are needed and what the output contains, but it does not state when to use this tool versus alternatives such as quote_request or create_watch. There is no when-to-use/when-not-to-use guidance or explicit alternative routing.

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

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

The description adds behavioral context beyond the schema by mentioning k-anonymisation, data_through, and contract version. However, with no annotations, it does not disclose whether the operation is read-only, requires authentication, or what the response format looks like. The added details are useful but incomplete.

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 concise sentence with no wasted words. It front-loads the core action and resource. The only minor issue is that phrases like 'where applicable' and 'contract version' are vague but not verbose.

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?

With no annotations, no output schema, and a single undocumented parameter, the description leaves out important context: when to use the tool, what the output looks like, and the meaning of 'contract version'. It is too minimal to fully guide an agent in selecting and invoking the tool 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 0%, so the description carries the full burden for parameter semantics. It only implies that 'slug' identifies a product, but does not explain the slug format, how to obtain it, or any constraints. This is insufficient compensation for an undocumented parameter.

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

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

The description states a specific action ('sample rows') and resource ('product'), and it differentiates from siblings like search_products and inspect_product by focusing on sampling data rows. However, the word 'Free' is ambiguous (cost vs. sample) and the description lacks a standard verb like 'retrieve' or 'get', which slightly reduces clarity.

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?

No guidance is provided about when to use this tool versus the sibling tools. There is no mention of alternatives, conditions, or prerequisites, leaving the agent to infer usage from the tool name alone.

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?

There are no annotations, so the description carries the full transparency burden. It discloses the semantic matching behavior, ranking by profile fields, and a rich result payload including matched terms, product limitations, temporal/spatial coverage, cheapest satisfying tier, quality status, and contract URL. It does not cover auth, rate limits, or pagination, but for a discovery tool this is strong disclosure.

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 dense sentence with no filler, and the core concept is front-loaded. It is somewhat run-on, but every enumerated element adds decision-relevant detail about behavior and output.

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?

Behaviorally, the description is rich, but it is incomplete for invocation: there are no parameter descriptions, no output schema, and no annotations, leaving limit, category, and flagships_only underspecified. It also lacks explicit guidance on when to prefer this tool over siblings.

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%, and the description only indirectly explains the 'text' parameter via 'describe the need in plain words.' It provides no meaning or constraints for limit, category, or flagships_only, so an agent cannot confidently determine valid values or effects for those parameters.

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

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

The description opens with 'SEMANTIC product discovery' and specifies the action: describe a need in plain words and get products ranked by profile match, with a detailed list of output facets. This clearly identifies the resource (products) and distinguishes it from sibling tools like buy_product, sample_product, and answer_question.

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 clear usage context: use plain-language needs across industry, infrastructure type, hazard, or question to discover products. It does not explicitly name alternative tools or state when not to use this tool, so it falls short of full exclusionary guidance.

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