DaedalMap UN Sustainable Development Goals

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

Annotations already declare readOnlyHint=true, so the description's focus on 'Returns the list' does not contradict that or add much beyond the annotation. The phrase 'live agent-ready data packs' adds context about what data is available, but does not disclose additional behavioral traits such as pagination, rate limits, or response structure.

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, clear sentence that communicates purpose and key context ('Free discovery', 'live agent-ready data packs') without wasted words. It is appropriately sized for the tool's simplicity.

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 parameterless, read-only listing tool, the description adequately states what it returns and the domain (DaedalMap). There is no output schema, but the return type ('list') is stated. Combined with the sibling context, this is sufficient 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.

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

The tool has zero parameters, so the description does not need to explain parameter semantics. The schema already documents this fully (schema description coverage 100%), and the baseline for zero-parameter tools is 4.

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 ('Returns') and resource ('list of live agent-ready data packs available on DaedalMap'), clearly distinguishing it from siblings like get_pack and query_dataset. The 'Free discovery' phrase clarifies it's a zero-cost listing operation.

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 use for discovering available data packs ('Free discovery'), but does not explicitly state when to use this tool versus alternatives like get_pack or query_dataset. It provides some contextual hint but lacks explicit when-to-use or when-not-to-use guidance.

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?

Annotations already state readOnlyHint=true, and the description adds meaningful behavioral context: it is a free discovery action, returns canonical tool guidance, and helps assess coverage limits. It does not contradict annotations and adds useful info beyond safety.

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, front-loaded with 'Free discovery,' and every clause adds value: what it returns, when to use, and why. No 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?

Despite no output schema, the description enumerates the key return elements (metadata, coverage, freshness, tool guidance, examples) and the context for use. It fully serves the agent's need for a 1-parameter discovery tool.

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 covers pack_id fully with a description and examples. The description adds minimal semantic value (e.g., 'one pack'), but it does not explain the parameter further; it relies on the schema's 100% 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 clearly states the tool returns detailed metadata, coverage, freshness, tool guidance, and first-query examples for a single pack. It distinguishes from siblings by focusing on one pack's metadata rather than catalog listing or data querying.

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 call before querying a new pack, providing clear context and rationale (see time shape, coverage limits, first query). It implies its role as a precursor to query_dataset, though it does not explicitly name alternatives or 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?

The description goes well beyond the readOnlyHint annotation by detailing what the tool returns: 'when to use it, what it refuses, a working example, effective access limits, important outputs, provenance fields, recommended next calls, and the shared natural-language-to-strict-JSON interaction contract.' It also discloses its 'blind-caller' nature, adding useful behavioral context.

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 concise sentences. The first sentence lists the key informational outputs, and the second provides a clear usage workflow. Every word earns its place, 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 tool is simple (one required parameter, read-only, no output schema) and the description is exceptionally thorough. It explains purpose, usage, return content, and even the recommended sequence with tools/list. The description fully compensates for the lack of an output schema by enumerating the expected outputs.

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 provides a clear description of the single parameter ('Exact tool name from tools/list'), giving 100% coverage. The description adds value by instructing to use tools/list to discover names, reinforcing the parameter's expected value and context, so the baseline 3 is exceeded.

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: providing 'guidance for one tool' visible on the MCP facade. It distinguishes itself from siblings (get_catalog, get_pack, query_dataset) by focusing on tool-facilitation rather than data retrieval, with a specific verb ('returns') and resource ('guidance for one tool').

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 explicit usage context: 'Use tools/list to discover names, then call this before an unfamiliar tool.' This clearly indicates when to use the tool (before unfamiliar tools) and implies a workflow. It doesn't explicitly state when not to use it, but the alternative (tools/list) is named, earning a 4.

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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful context by referencing the POST /api/v1/query/dataset contract and categorizing packs into free and paid groups. It does not detail error handling, rate limits, or output format, but the annotation plus the contract reference provide sufficient transparency beyond the annotation.

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 that are front-loaded with the core purpose ('Generic structured query') and packed with essential information about access mode and pack lists. Every word earns its place, with no fluff 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?

Given the tool's moderate complexity (8 parameters, nested objects) and lack of an output schema, the description provides a solid overview but leaves the exact return structure to the referenced API contract. It explains the free/paid pack landscape and the direct access model, which is sufficient for an agent to get started, though it could be more explicit about output format.

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 has 100% description coverage for all 8 parameters. The description adds value by clarifying the two primary access modes (source_id vs pack_id) and enumerating all valid pack identifiers, which goes beyond the schema's example list. This helps the agent understand how to choose between the key 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 clearly states the tool's function: a generic structured query for direct access via source_id or pack_id. It distinguishes itself from sibling tools like get_catalog and get_pack by specifying that it performs the query itself, not just catalog or pack metadata retrieval.

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 have a known source_id or pack_id and need to query data. It provides an explicit list of available free and paid packs, giving clear context for selection. However, it does not explicitly mention alternatives like get_catalog for discovering packs or get_pack for metadata, so it lacks explicit exclusions.

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