DaedalMap CIA World Factbook

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

Description adds context beyond the readOnlyHint annotation by describing the tool as 'Free discovery' and specifying the source (DaedalMap), though it does not disclose additional behavioral details.

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?

Single sentence efficiently conveys purpose and scope with zero 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?

Given no parameters and no output schema, description fully covers the tool's behavior: returns a list of available data packs.

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?

No parameters exist; description adds no parameter info, but baseline for zero-param 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?

Description clearly states the tool returns the list of live agent-ready data packs available on DaedalMap, distinguishing it from siblings like get_pack (retrieving a specific pack) and query_dataset (querying within a pack).

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 explicit when-to-use or alternatives, but context implies it's a discovery tool to be used before accessing specific packs or datasets.

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?

Annotation readOnlyHint=true already declares this a safe, non-mutating operation; the description does not contradict it. It adds useful behavioral context beyond the annotation — that this is 'Free discovery' and that it returns a 'paste-ready first query' — clarifying what the call actually yields and how it behaves.

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, front-loaded with the purpose and return contents, followed by concrete usage guidance. The listing of five return categories is slightly dense but each item earns its place; 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?

With only one fully-documented parameter, a readOnlyHint annotation, and no output schema, the description compensates well by detailing the return content (metadata, coverage, freshness, canonical tool guidance, first-query examples) and the call timing. Stronger response-format detail would push this higher, but nothing essential is missing for 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?

Schema coverage is 100%, with pack_id fully described in the schema ('Pack identifier from get_catalog'). Per the baseline, since the schema documents the only parameter completely, the description need not add more; it references 'one pack,' aligning with the single pack_id parameter without adding deeper 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 states a specific verb and resource: 'Returns detailed metadata, coverage, freshness, preferred canonical tool guidance, and first-query examples for one pack.' It enumerates exactly what is returned and is clearly distinct from siblings: get_catalog lists the catalog, get_tool_help offers help, and query_dataset executes queries, while this fetches per-pack metadata.

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?

'Call this before querying a new pack so you can see time shape, coverage limits, and the paste-ready first query' explicitly names when to use it, tied to the workflow of using query_dataset. It gives a clear trigger condition, though it does not explicitly state when not to use it or contrast with get_catalog/get_tool_help as 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?

The readOnlyHint annotation already signals safety, and the description adds behavioral detail without contradicting it. It transparently enumerates what the help response includes: refusals, access limits, provenance fields, recommended next calls, and the interaction contract. It does not mention its own operational limits, but the read-only nature lowers the burden.

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 dense but efficiently structured: first sentence defines the core purpose, second lists the returned contents, third gives a direct usage pointer. It is not overly long for the rich information it conveys, though the second sentence is a long list that could arguably be split for readability.

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, read-only help tool with no output schema, the description is thorough. It spells out the output categories, the prerequisite tools/list discovery step, and the recommended invocation timing. The agent gets enough context to understand what the tool returns and how to call it successfully.

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 already provides 100% coverage for tool_name, including the instruction 'Exact tool name from tools/list.' The description reinforces this by saying to discover names via tools/list, but it adds no new parameter syntax or format details. With full schema coverage, 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 states a specific verb+resource: 'get tool help' / 'guidance for one tool visible on this MCP facade.' It clearly differentiates from siblings like get_catalog and query_dataset by focusing on meta-guidance rather than data retrieval. The list of returned content (when to use, refusals, example, limits) makes the function unmistakable.

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 is a clear when-to-use directive. It doesn't explicitly mention when-not-to-use or compare with sibling tools, but the workflow is unambiguous and actionable.

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?

注解已提供 readOnlyHint=true，覆盖了只读属性；描述额外列出了付费包并提及付费代币 (x402 Base USDC)，暗示调用付费包可能产生费用，但未明确说明调用此工具是否会触发交易或消耗。总体行为细节（如分页、错误处理）未披露，但在注解覆盖下，3分是合理基线。

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?

描述由两句组成，第一句开门见山说明用途和契约，第二句列出可用包，信息密度高且无冗余。包列表虽然较长，但属于必要信息，整体结构紧凑且前端加载了核心意图。

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?

该工具包含 8 个参数和多个嵌套对象，且无输出模式，描述仅提供用途和包列表，未说明如何组合参数（如 filters、metrics 的用法）、返回格式或使用示例。虽然 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 中所有 8 个参数均有描述，覆盖率为 100%，因此描述无需重复参数含义。描述通过列举免费/付费包为 source_id 和 pack_id 提供了可用的值域示例，但未对 sort、filters、metrics 等嵌套对象给出额外用法说明，因此仅停留在基线水平。

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?

描述明确说明了该工具是用于按 source_id 或 pack_id 进行直接访问的通用结构化查询，并引用了 POST /api/v1/query/dataset 契约，这清晰地定义了它做什么。与兄弟工具 get_catalog、get_pack 相比，它明显是数据查询工具，区别基本可以推断，但未显式点名替代工具，所以未达到满分的清晰区分。

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?

描述列举了免费和付费的包，提供了使用背景；但未说明何时该用此工具而非 get_pack 或 get_catalog，也没有明确排除条件。缺少'当只需获取包元数据时使用 get_pack'之类的指引，使用场景全凭推断。

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