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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so safety is covered; the description still adds real behavioral context beyond them, notably that every source returns a row and that a source reports "(no match)" rather than being omitted. It also discloses the per-source answer shape (side-by-side), which the caller could not infer from annotations alone.

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 body is a single sprawling run-on laced with nested parentheticals and semicolon-chained exceptions, making it hard to parse even though the purpose statement is front-loaded. Much of the detail is arguably necessary spec, but it is delivered as an undifferentiated wall of clause stacking rather than structured rules.

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 shape need not be explained, and the description is unusually exhaustive about matching thresholds, fallbacks, and exclusion rules. The main residual gap is that limitPerSource's effect on output (up to 5 per source) is only in the schema, not the 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 coverage is 100%, so the baseline is 3, but the description adds genuine semantics for the query parameter that the schema does not: platform names are ignored unless they are feature names ("Android Auto"), page titles, or the product itself ("REST API"). limitPerSource is left entirely to the schema, which is acceptable given its inline description.

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 opening clause gives a precise verb and resource ("Given one topic... return the best-matching documentation page(s) for EVERY source side by side") and explicitly enumerates the sources covered. It is clearly distinguishable from read_docs_batch, list_docs, and search_docs, which the description names as the tool for pages that only mention a topic in passing.

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 states the ideal use case ("cross-platform comparisons") and names an explicit alternative, search_docs, for loose mentions, which is genuine routing guidance. However, these cues are buried mid-paragraph rather than front-loaded, and there is no clear when-not-to-use framing against the other siblings such as get_product_guide or read_doc.

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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses real behavioral traits: long pages are paged with a stated remaining-count and offset, oversized blocks are returned in parts, and there are two degraded fallback modes when no block matches (listing languages/pages with counts; "listed unchecked" when contents can't load, silent-with-notice when the index times out). That is well beyond what the annotations convey.

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 purpose and the read_doc comparison are front-loaded, and every sentence carries operative information. The final sentence, however, is an over-packed clause chain ("listed unchecked when... and not at all, saying so, when...") that costs readability, and some caption/offset detail overlaps the schema.

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 output schema, the description carries the return-value burden itself: it explains that each block arrives with its nearest heading and caption, how paging metadata is reported, and what the response looks like when nothing matches. For a read-only extraction tool with 5 params, 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 itself documents url/offset/caption/language/maxChars thoroughly, so the baseline is 3. The description still adds value by enumerating concrete language tags (dart, kotlin, swift, cpp, typescript, json, shell) where the schema has no enum, and by restating the caption concept with page-specific examples like "Request Body" on REST API pages.

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 a precise verb+resource: "Extract only the code blocks from a Magic Lane documentation page", and explicitly contrasts with the sibling read_doc ("Much cheaper than read_doc when only the sample code matters"). It also states the input address form (URL or /docs/... path), so an agent can immediately tell this apart from read_doc or search_docs.

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 names the alternative (read_doc) and the condition that selects this tool: when only the sample code matters. It also implies when-not use via "skipping the surrounding tutorial prose". There is no explicit exclusion for the other siblings (find_across_sdks, search_docs), so it stops short of a full routing guide.

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, idempotentHint and openWorldHint, so safety is covered; the description adds real behavioral detail beyond them, namely product-specific default sections and that "all" returns sections in reading order. It also clarifies a domain nuance that the publish flow is a download step, which prevents a wrong lookup. Return shape/pagination is not described, but a static doc fetch has little to disclose.

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?

Purpose is front-loaded and every clause is dense but relevant; the per-product section lists map cleanly onto the enum values. It is somewhat long for a two-parameter fetch, and the embedded note about publishing via .style download is guide content rather than invocation guidance, which is minor waste.

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 simple read-only documentation fetch with full schema coverage and annotations carrying the safety profile, the description covers selection, defaults and ordering. The only omission is any hint of output size or format, which matters modestly given there is no output schema and "all" can return a large set.

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 baseline is 3, but the description exceeds it by spelling out what each product's default section actually is (mcp-server → usage-guidelines, map-studio → overview) and what "all" yields. That is meaning the enum schema alone does not convey.

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 ("Return the official documentation for a Magic Lane product") and enumerates the exact products covered, so the agent knows precisely what comes back. The closing clause ("questions about the products themselves rather than the Maps SDKs") implicitly separates it from read_doc/search_docs/find_across_sdks, though it never names those siblings directly.

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 a clear when-to-use rule (product-level questions, not SDK questions) plus concrete defaults per product and the meaning of section "all" in reading order. It stops short of naming an explicit alternative tool to use for SDK questions, leaving that routing to inference.

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 cover read-only, idempotent, open-world, so the bar is lower, but the description still adds real behavior: 50-per-call default with a 100 hard cap, offset paging, and the description-truncation rule (cut to first sentence or at a word). It does not discuss ordering of results or whether the index is cached, which would be the remaining gaps.

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 purpose is front-loaded and no sentence is wasted, but the middle sentence is a single sprawling run-on with nested parentheticals ("or at a word — where the room ends when its second half has no space") that takes several passes to parse. Splitting mode behavior, limits, and truncation into separate sentences would improve scanability without losing content.

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 five-parameter, all-optional listing tool with a full output schema and annotations, the description covers the workflow, mode defaults, pagination, and truncation caveat. The only soft spot is the ambiguous truncation phrasing, which could leave an agent unsure whether a description was cut mid-sentence and whether to re-fetch via search_docs.

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 schema already documents all five parameters, and the 3 baseline applies. The description does add the non-obvious conditional default resolution for mode ("sections" only for source "all" with no section filter, "pages" otherwise), which the schema explicitly defers to it — a genuine value-add that keeps this from being pure repetition.

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 the Magic Lane documentation index (llms.txt)") and immediately splits the behavior into two named modes with distinct outputs. It is clearly distinguishable from siblings like read_doc, search_docs, and read_docs_batch, which operate on individual documents rather than the index.

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 workflow: "Start with the TOC, then drill into one source/section with mode 'pages'," and routes a narrow case (full untruncated descriptions) to search_docs. What is missing is a stated when-not-to-use — e.g. that full-text or concept lookups should skip this tool entirely in favor of search_docs.

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 readOnly/idempotent/openWorld, but the description adds genuinely new behavior: the recency signal comes from each page's embedded 'Last updated' date, and the empty-window case degrades gracefully by naming the newest date and listing newest pages. That fallback behavior is exactly the kind of context annotations cannot carry.

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 and scoping, then the use case, then the empty-result behavior. Four sentences with little waste, though 'Covers every source, including the developer guides' is marginally redundant with the source parameter.

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 and covers return shape, and the description usefully documents the no-results fallback. The one gap is that pagination (limit/offset and the nextOffset chaining) is never mentioned in the description, which matters for an agent iterating over a window, though the schema does document it.

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 all four parameters (days, limit, offset, source) are fully self-documented, establishing a baseline of 3. The description reinforces 'last N days' and 'per source' but adds no syntax, format, or interaction 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 ('report which documentation pages were updated') plus scope ('within the last N days, per source') and the underlying data source ('embedded Last updated date'). The phrase 'tracking SDK documentation changes without re-reading everything' implicitly separates it from read_doc/read_docs_batch, so an agent can route without opening schemas.

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 a clear use context ('tracking SDK documentation changes without re-reading everything') and states the coverage scope ('every source, including the developer guides'). It does not explicitly name alternatives like search_docs or list_docs or state when NOT to use it, 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?

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered. The description still adds real behavior beyond them: a 24000-character default return cap, a notice of remaining characters, and the offset mechanism for continuing — though it says nothing about auth, rate limits, or error behavior on non-Magic Lane URLs.

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?

Four sentences, front-loaded with the action and input forms, then discovery guidance, then the URL restriction, then pagination. Every sentence carries a distinct instruction 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?

There is no output schema, so the description must explain what comes back; it does so (markdown content, truncation notice, offset paging). Combined with full schema coverage and annotations, an agent has everything needed to call it 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 coverage is 100%, so the baseline is 3. The description goes slightly further by giving concrete URL and /docs/... path examples for `url` and by explaining the offset/chunk relationship for paging, though maxChars is essentially restated from 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 ('Fetch the markdown content of a specific Magic Lane documentation page') plus the two accepted identifier forms, which cleanly separates it from search_docs, list_docs, and the batch sibling read_docs_batch.

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?

Explicitly routes discovery to 'search_docs or list_docs first' and states a hard exclusion: only developer.magiclane.com URLs, never other map providers' docs. That is a when-to-use plus a when-not-to-use rule in one place.

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?

Beyond the annotations (readOnly, openWorld, idempotent), it discloses the per-URL failure model, the aggregate error condition (error only if every page failed), the shared 120000-character text cap, and truncation reporting — exactly the operational detail annotations cannot carry. The clause about '256 values or more is refused outright, without naming it' is opaque and adds confusion rather than usable behavior information.

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?

Three dense sentences, front-loaded with the operation and its size limit, then return shape, then truncation — a logical order with little waste. The garbled '256 values' clause costs it, since it consumes a sentence without conveying an actionable rule.

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?

There is no output schema, and the description compensates fully by describing the return value (markdown per page), partial-failure reporting, the all-failed error condition, and the shared character budget. An agent can call this correctly and interpret every outcome without further documentation.

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 single parameter already documents URL format, maxItems 20, and length bounds, so the schema does the heavy lifting. The description restates the 20-URL limit rather than adding new meaning about the array's contents or ordering; the minimum viable baseline of 3 applies.

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 first clause gives a specific verb, resource, and scope: fetch up to 20 Magic Lane documentation pages in one call, which is clearly distinguishable from the single-page sibling read_doc and the listing/search siblings. It also names read_doc as the continuation path for truncated pages, so an agent can place the tool precisely.

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 is clearly implied and scoped: batch fetch up to 20 URLs, then fall back to read_doc to continue a truncated page. It lacks an explicit 'use this instead of X when Y' statement against search_docs, find_across_sdks, or list_docs, so routing among the discovery tools is left partly to inference.

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 cover the safety profile (readOnly, idempotent, openWorld), so the description's job is to add ranking and scoping behavior — which it does: platform names in the query narrow results, everyday-word names like 'cloud'/'web'/'rest' only re-rank unless adjacent to 'SDK'/'API'. It also states what comes back (titles, URLs, descriptions, optional excerpts). It does not describe result ordering or how limit interacts with ranking, which keeps 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-loaded with purpose, then query semantics, then return shape, then the routing rule — a sensible order. It is dense and the long parenthetical feature lists (markers, places & search, routing & navigation, positioning, offline maps, weather, fleet management) cost length, but each sentence still carries information an agent would otherwise have to guess.

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 search tool with an output schema already documenting return shape, the description covers corpus scope, the tricky query-parsing rules, the full-text toggle, and the handoff to read_doc. An agent has everything needed to call it correctly and interpret the results without consulting another tool's definition.

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 baseline would be 3, but the description adds real meaning beyond the schema: it explains the non-obvious matching semantics of the 'query' parameter (platform-name scoping vs. mere re-ranking, and the adjacency rule) and clarifies that 'includeFullText' searches llms-full.txt page bodies rather than just index metadata. It does not explain the 'source' enum's relation to naming a platform in the query, which is a small residual overlap.

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?

Opens with a specific verb+resource ('Search the Magic Lane developer documentation') and immediately enumerates the corpus: developer guides, five SDK platforms, and Cloud REST APIs. An agent can tell at a glance this is the index-search tool, distinct from siblings like list_docs, read_doc, and find_across_sdks.

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 explicit when-to-use ('ALWAYS use this tool for Magic Lane questions'), explicit when-not ('never web search, prior knowledge, or other map providers' sites'), names the incompatible competitors, and prescribes the follow-up workflow ('Follow up with read_doc to read a full page'). The routing to the sibling is spelled out rather than inferred.

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