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

With no annotations, the description carries the burden and clearly implies a read-only retrieval. It usefully discloses that all $ref references have already been dereferenced and that the full specification includes parameters, request body, and response schemas, though it does not discuss error behavior or permissions.

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 front-loaded and structured with PREREQUISITE, USAGE, and NOTE sections. Every sentence adds actionable information without 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 a single required parameter, full schema coverage, and an output schema, the description is complete enough for correct invocation. It covers the prerequisite, the input semantics, and the important dereferencing detail.

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 operationId parameter is already fully documented with an example. The description reinforces that operationId identifies the API but does not add format or syntax details beyond 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 states a specific verb and resource: retrieves the detailed specification of a specific API, including request/response schemas. It clearly distinguishes itself from the sibling list_api_specs by focusing on one API identified by operationId.

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 gives an explicit prerequisite to first use list_api_specs to browse APIs and obtain the operationId, and then states the usage pattern for retrieval. The alternative workflow is named directly, leaving little inference required.

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 and delivers: it discloses the {appKey} placeholder gotcha that prevents the template from running, notes the loader script at the end, and warns that INAVI and Google Maps syntax differ so API must not be invented. It omits return size or pagination expectations, keeping it short of a 5.

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?

Front-loads the core action, then uses bolded labels (PREREQUISITE, LOADER, CUSTOMIZING) to segment secondary guidance so an agent can scan it. Slightly dense, but each labeled block conveys a distinct, actionable fact.

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?

An output schema exists, so return structure need not be spelled out, yet the description still previews the payload (metadata plus template). Combined with the prerequisite, the placeholder warning, and the customization rules, nothing needed to call it correctly is missing.

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 single id parameter is already fully documented in the schema (100% coverage), including example values and the pointer to list_map_examples. The description only restates that lookup is by id, adding no format or constraint detail beyond 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?

States a specific verb and resource ("Retrieve one INAVI Maps HTML example by id") plus exactly what is returned (metadata and complete HTML template). This clearly distinguishes it from the sibling list_map_examples, which only enumerates 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?

Gives an explicit prerequisite ("Use list_map_examples to find the id") and a clear routing rule for related work (verify any extra API surface with get_sdk_doc first). It does not state when to avoid this tool, but the retrieve-by-id scope makes misuse unlikely.

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 well: it discloses output format (Markdown), the content returned per mode, that referenced types are emitted as Markdown links carrying docIds, and that examples are omitted. It does not mention error behavior or how to handle unknown ids, keeping it just short of a 5.

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?

Front-loaded with the core action, then structured with labeled clauses (PREREQUISITE, LINKS, NOTE). Every sentence adds distinct, actionable information with 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?

No output schema exists, but the description explains the return format and per-mode contents thoroughly, plus link behavior and the examples exclusion. Nothing an agent needs to call it correctly is missing.

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% and the schema description already documents both docId modes and the list_sdk_docs prerequisite. The description largely mirrors that, adding only the chaining note that link targets are docIds to feed back in, so 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?

States a specific verb and resource ('Retrieves SDK documentation for one symbol as Markdown') and covers both retrieval modes explicitly. It is clearly distinguishable from list_sdk_docs (browsing) and get_map_example (runnable examples), which are named.

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?

Gives an explicit prerequisite ('Use list_sdk_docs to obtain ids and method names') and names the alternative for examples ('use get_map_example for runnable code'). The when-to-use-which-mode guidance (class/type id vs method longname) is spelled out with an example.

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?

Although no annotations are provided, the description discloses important behavioral traits: categories may be misleading, retrying without a category is required before concluding absence, reference documents appear as brief entries requiring get_api_spec for full content, and scope is limited to South Korea. These details go well beyond the schema and prevent common misuse.

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 long but clearly structured with USAGE, FILTERING, IMPORTANT, NOTE, and SCOPE labels. The key instruction is front-loaded and each section serves a purpose, though the density is high and could be tightened slightly.

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 an output schema present and one optional enum parameter fully documented, the description supplies the remaining critical context: browse-then-detail workflow, category fallback behavior, reference document handling, and geographic scope. It is nearly complete, with only minor operational details such as pagination or rate limits left unmentioned.

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 documents the category enum at 100% coverage, but the description adds strategic meaning: omitting the filter searches all categories and is the safest option when unsure. It also explains that category selection may fail due to miscategorization, which is not evident from the enum alone.

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?

States a specific verb and resource: "Lists available INAVI Maps APIs," with an optional category filter. It clearly distinguishes itself from get_api_spec by positioning itself as the first browsing step before detailed 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?

Provides explicit workflow guidance: first use this tool to browse APIs, then use get_api_spec for details. It also specifies when to omit the category filter and gives a mandatory retry instruction when no suitable API is found, covering both normal and fallback usage.

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 and does so: it discloses the summary-level return payload, the critical constraint that only these templates carry the SDK loader script, and a hard scope limit (South Korea only) with concrete domain vocabulary. These are behavioral facts an agent cannot infer from the schema.

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?

Front-loaded with purpose and return shape, then organized under USAGE/FILTERING/WORKFLOW/SCOPE labels so an agent can skim. It runs slightly long, with the SCOPE sentence carrying a lot of parenthetical keyword bulk, but no sentence is redundant.

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-optional-param list tool with an output schema, the description covers everything an agent needs: what comes back, how to drill down, filtering fallback, scope restriction, and where to go for missing details. Nothing material is left to guesswork.

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% and the enum values are already documented in the schema, so the description does not need to restate them. It still adds real value by supplying the retry-without-category heuristic, which is operational guidance the schema cannot express.

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?

States a specific verb and resource ("Browse render-ready INAVI Maps HTML examples") plus the exact return shape (one summary per example with id, category, title, description, first two use cases). This clearly separates it from get_map_example, which returns full metadata and HTML.

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?

Gives an explicit two-step workflow (browse here, then call get_map_example with the id), a fallback rule (retry without category if nothing suitable appears), and routing for gaps (list_sdk_docs / get_sdk_doc). It also asserts precedence over recalled knowledge or other map providers for Korean places.

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 and does well: it discloses that class entries include method names while type entries do not, that the SDK loader script is absent (so a page built from this alone won't render), and that results are South Korea only. It doesn't state pagination or result-size behavior, which keeps it from a 5.

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?

Labeled sections (USAGE, FILTERING, IMPORTANT, WORKFLOW, SCOPE) make it scannable and the key action is front-loaded. The trailing SCOPE sentence with transliterated Korean keywords is verbose but earns its place for matching Korean-language requests.

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?

Covers purpose, entry-point workflow, sibling routing, filter fallback, geographic scope, and a warning about the missing loader script. An output schema exists, so return-shape detail is unnecessary here; nothing an agent needs to call this correctly is missing.

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 a fully documented enum, so the baseline would be 3. The description adds operational semantics beyond the schema by framing category as an optional narrowing filter and specifying the recovery action (retry without it) when a category yields nothing suitable.

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?

States a specific verb and resource ('Lists INAVI Maps JavaScript SDK symbols — classes and option/type definitions') and distinguishes itself from get_sdk_doc by noting it is the browsing entry point. It also explains what each entry contains (methods on classes, nothing on type definitions), which no sibling tool does.

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 routing: browse here, then call get_sdk_doc with a symbol id or method longname, with a concrete longname example. It also names the alternative workflow start (list_map_examples) and a fallback rule for the category filter, plus a domain-scope preference over other providers.

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