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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), so the description's job is to add context, which it does by revealing this is an orientation/map tool whose output reflects 'the indexed corpus' and can flag thin areas. It stops short of describing the response shape, but an output schema exists to carry that.

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 short paragraphs, front-loaded with the core purpose followed by the disambiguation and usage cues. Every clause carries information; 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 an output schema present, return values needn't be explained; the description adequately covers purpose, when to use, and the tool's non-search nature. The only meaningful gap is the undocumented 'audience' parameter.

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 there are two optional params. The phrase 'reading path fits a goal' implies the role of the 'goal' param, but 'audience' is never mentioned in the description or schema, leaving half the parameters undocumented.

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 ('Explain') and resource (the LaserData documentation organisation) and explicitly distinguishes itself from keyword-based siblings with 'This is a guided map, not a keyword search.' An agent can separate it from search_docs, list_docs, and get_doc without opening the schema.

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 clear triggering conditions: where docs live, which reading path fits a goal, which areas look thin. It also implicitly excludes search-style use via 'not a keyword search,' though it does not name search_docs as the alternative, so routing still requires a small 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 declare readOnlyHint=true, openWorldHint=false, destructiveHint=false, so the safety profile is covered. The description adds the shape of the result (doc key, title, heading, language, line number, source URL, code), which is useful context, though it largely duplicates the output schema rather than disclosing behavior like filtering or pagination limits.

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 short sentences, front-loaded with the core purpose followed by the use case. The enumerated return fields are somewhat redundant given an output schema exists, but the overall size is tight and well-ordered.

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 values need not be spelled out. The gaps are the three undocumented parameters and the lack of disambiguation from find_examples. Adequate but with clear holes for a filtering 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?

Schema description coverage is 0% across three parameters (key, language, max_snippets), so the description must compensate and does not. It never explains that key scopes to a doc, that language filters snippets, or what max_snippets caps; it only references language as a returned field, not as a filter.

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+resource: 'Return an inventory of fenced code snippets from the documentation.' An agent can tell this extracts code snippets. However, it does not differentiate from the sibling find_examples, which plausibly overlaps, so it stops short of 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?

'Use this for snippet verification and docs CI design' gives an intended use case, but there is no when-not guidance and no mention of alternatives such as find_examples or get_doc. Usage is implied rather than disambiguated.

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 carry the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the description is not obligated to restate that. It adds no behavioral context beyond purpose: nothing about result ranking, whether the corpus is the live docs index, or what happens with empty inputs. Adequate but thin given how little the annotations leave unstated.

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, no filler, with the core purpose front-loaded before the usage triggers. Every clause carries information the agent needs.

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 values need not be explained, and the annotations cover safety. What is missing is any guidance on parameter behavior: the query and language defaults are empty strings and max_results defaults to 8, none of which is documented in either the schema or 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 description coverage is 0%, so the schema alone tells an agent nothing about the three parameters. The description partially compensates by mapping query to "topic" and by enumerating language values (Python, TypeScript, Rust), which is genuinely useful since the schema has no enum. It says nothing about max_results or the empty-string default for query, so the compensation is incomplete.

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 specific verb and resource ("Find code examples in the LaserData documentation") and adds two scoping facets: topic and language. It is easy to distinguish from list_docs or get_doc, though it never explicitly contrasts itself with the closest sibling, extract_code_snippets, so the boundary between them must be inferred.

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 trigger clause ("Use this when a user asks for runnable examples, Laser SDK examples in Python, TypeScript or Rust, agent or session samples, or CLI commands"), which covers several realistic request shapes. It stops short of stating when not to use it or naming an alternative tool for overlapping needs.

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, destructiveHint=false and a closed-world hint, so the safety profile is covered. The description adds that the whole page text is returned (as opposed to snippets or summaries), but says nothing about behavior on invalid keys, rate limits, or pagination. Adequate but thin given annotations carry the main 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?

Two short sentences, zero filler, with the core action front-loaded and the key-discovery hint immediately after. The example keys are the only elaboration and they earn their space by illustrating the parameter format.

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 single-parameter read tool with an output schema already present, the description need not explain return values. It covers purpose, key format and how to obtain valid keys; the only minor gap is explicit routing versus sibling search/list tools.

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, and it does by showing concrete key shapes: 'laser-sdk/quickstart', 'laser-sdk/memory', 'python/laser_sdk/Laser'. This communicates the path-like namespace convention and points to list_docs as the authoritative key source, which is meaningfully more than the bare string schema offers.

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 the full text of one LaserData documentation page.' The scope word 'one' contrasts implicitly with the list/search siblings, though the description never explicitly names what it is not (e.g., not a multi-page search like search_docs). Clear, but sibling differentiation is left partly to inference.

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 actionable context by directing the agent to list_docs to discover valid keys before calling, which is a concrete prerequisite step. It stops short of explicit when/when-not selection rules against alternatives such as search_docs or extract_code_snippets, so no exclusions are given.

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, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely useful behavioral context by disclosing how relatedness is computed (links, backlinks, shared section, shared vocabulary), which tells the agent how much to trust results. It does not discuss result limits or ordering beyond the max_results default.

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 short sentences, front-loaded with the purpose followed by the usage cue; no filler and nothing buried.

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, return format need not be explained, and annotations carry the safety profile. Purpose, relatedness model, and usage timing are complete; only the max_results parameter's semantics and any result-limit behavior are left unaddressed.

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 there are two parameters. The phrase 'one doc key' clarifies that the required key is a document key, but max_results is never explained in the schema or the description, so the agent must guess at its meaning and behavior.

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 (Return) and resource (documentation pages related to one doc key), and enumerates the four sources of relatedness (explicit links, backlinks, shared section, shared vocabulary), which makes its output conceptually distinct from siblings like get_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?

Explicitly names the alternative and the triggering condition: 'Use this after get_doc when one page may not contain all context needed for a complete answer.' The sequencing and the reason to escalate are both stated, leaving little 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 declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuine context the annotations don't: the corpus is split into 'website' and 'python-api' halves with different keying schemes ('laser-sdk/memory' site paths vs 'python/' prefixes), which shapes what the agent will actually receive.

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 the corpus model, then the parameter behavior. Every sentence carries weight, though the keying examples ('laser-sdk/memory', 'python/') add length that could be trimmed without much loss.

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-value documentation is not required, and the description supplies the corpus taxonomy and valid source values an agent needs. It does not mention list size or pagination behavior, which is the only meaningful remaining gap for an enumeration 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?

Schema description coverage is 0% and the source property has no enum, so the description carries the full burden — and it does: it names the two values ('website', 'python-api') and explains that omitting source defaults to listing all. That is exactly the missing semantics the schema lacks.

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 ('List every LaserData documentation page, organised by section') and immediately scopes it with the two-halves corpus model. The enumeration nature implicitly separates it from single-item siblings like get_doc, but no sibling is named explicitly, so it stops short of 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 final line gives real guidance on the source parameter ('Pass source to see one alone; the default lists all'), which tells the agent how to narrow the listing. However, it never says when to prefer this tool over search_docs, find_examples, or get_related_docs, so usage relative to alternatives is only implied.

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, non-destructive, open-world), so the bar is lower. The description adds real behavioral context the annotations don't: the seven-day cache is bypassed and the operation is a no-op under a specific configuration, which is exactly the kind of idempotency detail an agent needs.

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, zero waste. The core action is front-loaded, and the caveat follows immediately. Every sentence 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?

With an output schema present and no parameters, the description needn't explain return values. It covers the action and its main caveat; the only minor gap is no explicit trigger for when a refresh is warranted.

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 takes zero parameters, so there is nothing for the description to disambiguate. Baseline of 4 applies for a parameterless tool.

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: 'Re-fetch the documentation corpus,' which is clearly distinct from the read-oriented siblings (list_docs, get_doc, search_docs). It does not explicitly name or differentiate from any sibling, but the refresh action is unambiguous.

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 a genuine when-not condition: the call is a no-op when LASER_DOCS_FILE points at a local llms-full.txt. This helps an agent decide whether calling is worthwhile, though no alternative tool is named for the stale-cache scenario.

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, destructiveHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: results are labeled by corpus, guides vs API differ in kind ('how the SDK is meant to be used' vs 'what is actually callable'), and the docs are positioned as more current than memory.

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 and scope before the usage advice; sentences are clean and purposeful. The corpus rationale paragraph is slightly expansive but each clause (corpus labeling, source filtering) carries information an agent needs, so little waste remains.

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, return values needn't be detailed, and annotations carry the safety profile, so the description's job is scope and selection — both covered well. The only shortfall is the undocumented max_results parameter, a minor gap for an otherwise complete 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 description coverage is 0%, so the description must compensate. It documents the semantic values for source ('website' or 'python-api', with the implied default of searching both) but says nothing about max_results or its default of 8, leaving one of three parameters undocumented everywhere. Partial compensation justifies the baseline 3.

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 (search) and resource (LaserData documentation) and precisely scopes it: the whole corpus spanning docs.laserdata.com pages and the Laser SDK Python surface. The whole-corpus scope implicitly separates it from page-level siblings like get_doc and list_docs, letting an agent pick it without opening another schema.

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 context for use ('Prefer this over answering Laser SDK questions from memory: the SDK moves quickly and the docs are the current truth') and explains how to narrow scope via the source value. It never explicitly names or excludes a sibling tool, so it's clear guidance rather than full when/when-not routing.

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