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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds substantive behavioral context beyond that: the deterministic entry-file selection order, the truncation of the entry preview to ~30 lines, the load-path-only output mode when `plugin` is omitted, and the failure behavior ('an unknown folder errors and lists available folders instead of guessing'). These are exactly the outcome-shaping traits an agent needs to predict results, and they do not contradict the idempotent/read-only hints.

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?

Both sentences are information-dense with zero filler; the purpose and report inventory are front-loaded, and sibling contrasts come immediately after. The only nit is that the second sentence crams four distinct rules (entry-file selection, directory-name constraint, omit mode, error behavior) into one long em-dash/semicolon chain, which slightly reduces scannability compared to crisp bullet points. Minor structural cost given how much genuinely useful content is packed in.

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-optional-parameter tool with 100% schema coverage, an existing output schema (so return format need not be restated), and annotations covering the safety profile, the description covers every remaining decision point: scope, report contents, sibling routing, entry-file resolution, naming rules, the no-argument mode, and error handling. Nothing an agent needs to invoke 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 description coverage is 100% — the schema already documents the case-sensitive directory-name constraint, the 'not a manifest id' clarification, examples ('online', 'iptv', 'collections'), and the omit-for-load-path-only behavior. The description reinforces these points and ties the parameter to entry-file resolution, but it adds no meaning the schema lacks. Baseline 3 applies as the schema carries the full burden.

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?

Named with a specific verb+resource+scope: 'Single-call report for one `plugins/<name>` folder,' followed by a concrete inventory of report contents (files, Lampa.* usage, Listener follow/send, settings, CSS, entry preview, plugin-loading mechanism). It explicitly distinguishes itself from three siblings: 'Unlike `list_catalog` this is scoped to one plugin, unlike `trace_symbol` it does not follow a single event/file across the repo, unlike `validate_code` it does not score conventions.' An agent can select or reject this tool without opening any 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?

The description names the exact alternatives ('list_catalog', 'trace_symbol', 'validate_code') and the conditions that route an agent away from this tool. It also gives operational guidance: the entry-file fallback chain (main.js, then <plugin>.js, then first .js), the case-sensitive directory-name requirement ('not a manifest id'), the omit-for-load-path-only mode, and the error-and-list behavior for unknown folders. This is explicit when/when-not plus usage procedures, with nothing left 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 the tool non-destructive and idempotent, but the description adds essential behavioral context: it does not write the repo, missing files produce a 'File not found' note rather than aborting, and hunks are suggested not guaranteed to apply. No contradiction with annotations exists.

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 information-dense but every sentence carries unique value: core behavior, sibling contrasts, parameter override semantics, error behavior, and a safety caution. The most important fact (no repo writes) is front-loaded.

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 an output schema, the description need not explain return values; it covers error handling, inference behavior, application risk, and proper usage with plan_context. The calls to read_source for verification complete the decision context for the agent.

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 significant meaning beyond the schema: target_files fully overrides inference and the two are never combined, inference is limited to up to 5 files, and plan_context strengthens results from request alone. This clearly explains parameter interplay and trade-offs.

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 and object: 'Returns TODO unified diffs as text only — does not write the repository.' This clearly identifies the tool's function and scope while explicitly contrasting it with plan_change and scaffold_plugin, so an agent can distinguish it from siblings without opening them.

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 gives concrete when-to-use guidance: 'Best with plan_context pasted from plan_change' and differentiates behavior from plan_change (invents concrete diff hunks) and scaffold_plugin (patches existing files rather than emitting boilerplate). It also warns to re-check against read_source before applying, which clarifies post-call workflow.

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 mark the tool read-only and idempotent, and the description adds valuable non-obvious behavior: snapshot-only, packaging reads configuration but does not execute gulp/npm, and unknown chapter returns an error listing known ids. This meaningfully extends the structured hints.

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 with the core resource and modes front-loaded before details. Every clause earns its place, and there is no filler or redundant restatement of 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?

For a multi-mode tool with five parameters, three enums, and an output schema, this description is complete: it covers mode selection, parameter interplay, error behavior, side-effect boundaries, and sibling differentiation. An agent has what it needs to 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?

Although schema coverage is 100%, the description adds interaction semantics not present in the schema: chapter vs query when chapter is omitted, omitting both gives the TOC, lang is en or ru, and pattern requires the pattern enum. This materially improves correct invocation.

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 ('Read written Lampa guides') and enumerates three distinct modes, immediately differentiating itself from list_catalog and search_code. An agent can tell exactly what this tool covers 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 explicit when-to-use guidance per mode and names alternatives not to use: 'Not a live API catalog (list_catalog) and not grep (search_code)'. It also explains chapter/query fallback behavior, the TOC case, lang default, and the pattern requirement, so selection and invocation conditions are concrete.

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 signal read-only, idempotent, non-destructive behavior, and the description adds meaningful runtime behavior beyond them: content-hit limits for ui/styles modes, no file bytes returned, ext being ignored outside mode=name, and empty-match handling. This gives an accurate model of what the tool will actually do.

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?

Every sentence earns its place: the first defines scope, the second differentiates from siblings, the third gives two concrete usage examples and a failure-mode note. Dense but highly informative, with the most important scoping information front-loaded.

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 rich annotations, a complete input schema, an output schema, and explicit sibling differentiation, the description covers everything needed for correct selection and invocation. It explains edge cases, mode-specific behavior, and return expectations sufficiently.

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?

Input schema coverage is 100%, so the baseline is 3. The description adds value with concrete examples tying query/mode/ext together and clarifies the built-in feature map for mode=feature. The schema already documents the per-mode behavior, but the examples and constraints improve usability.

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 clear, specific verb ('Locate') and resource ('repo-relative paths') and immediately distinguishes the tool from search_code and read_source by saying what it matches and what it does not return. The modal examples make each mode's purpose explicit.

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 explicitly contrasts the tool with search_code ('matches names/paths... not content grep') and read_source ('does not return file bytes'), giving an agent clear routing criteria. It also explains when ext applies, how mode=feature behaves, and notes that empty matches return a list rather than an error.

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/destructiveHint; the description reinforces and expands this with 'pure snapshot read' and 'makes no network calls of its own', and documents per-topic ignore/require behavior that annotations cannot convey. No contradiction with annotations was found.

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?

At roughly 150 words it is dense, but each clause covers one of the six topic modes and front-loads the core purpose and safety. No filler; the semicolon-delimited topic map is the most efficient way to convey the matrix of valid parameter combinations.

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 six topics and seven parameters, the description enumerates every topic's valid inputs and ignored fields, plus the tool's relationship to external docs and related tools. Given an output schema exists, not describing return values is acceptable; nothing needed to invoke 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 covers all 7 params, so baseline is 3, but the description adds high-value cross-parameter constraints: `endpoint` requires `path` and ignores `category`/`search`, `auth` reads only `auth_focus`, `sync` takes no parameters, and `timeline_hash` reads only `example`. These interdependencies are not inferable from individual property descriptions.

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 'Document how Lampa talks to CUB from source' – a specific verb and resource – and immediately separates it from `list_catalog` topics and cub.rip/developer, making the tool's CUB-specific scope unmistakable. It clearly distinguishes this from sibling tools without needing to open 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?

It gives explicit when-not guidance ('not a substitute for cub.rip/developer') and contrasts with the sibling `list_catalog` topic=mirrors/socket, making alternative selection concrete. The per-topic parameter rules also tell the agent exactly which parameters to provide for each mode, reducing guesswork.

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 destructiveHint=false. The description adds meaningful behavioral context beyond that: it is curated from a separate repository, not the Lampa app source, and it never returns API keys/tokens/passwords, only identity, auth mechanism, and storage key names. No contradiction with annotations.

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 every sentence earns its place: scope, exclusions, security boundary, and parameter routing. It is front-loaded with the core purpose and avoids filler or repetition of schema 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?

Given the annotations cover safety, the output schema exists, and the schema covers all parameters, the description provides complete context for selecting and invoking the tool. It also notes the provenance and security boundary, which are important contextual facts an agent would otherwise not know.

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 adds value by explaining the operational meaning of each topic value: providers lists/searches, provider_detail requires provider, and proxy_pattern takes no parameters and explains the shared design once. This goes slightly beyond the schema's property descriptions.

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 ('Document') with a clearly bounded resource: third-party content/ratings/torrent-indexer/media-server APIs used by Lampa plugins. It explicitly enumerates the covered providers and distinguishes itself from guide_cub and list_catalog, so an agent can disambiguate it 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?

The description explicitly names sibling tools it is unlike (guide_cub for Lampa→CUB only, list_catalog for Lampa's own surface) and provides routing rules for the three topic values. It also states a hard constraint: never return secret values. This gives clear when-to-use and 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 declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds meaningful behavioral context: it returns a fixed reference document, does not read this repo's snapshot, and never writes files. It also discloses that content is curated from the lampa-plugins repo rather than the Lampa app source, which is not inferable from annotations.

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 dense sentences, front-loaded with the core purpose, then source provenance, sibling differentiation, and side-effect clarification. Every sentence earns its place with no filler or redundant restatement.

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 small parameter surface, full schema coverage, and provided annotations, the description is complete: it explains scope, source, behavior, constraints, and sibling boundaries. An agent can confidently decide to invoke this tool and with which topic.

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 covers the single topic parameter fully (100%) with an enum and per-value descriptions, so the baseline is 3. The description reinforces that each topic returns a fixed reference document but does not add deeper meaning beyond what the schema already provides.

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 action ('Document how the separate lampa-plugins repository turns plugin source files into the live catalog'), names the covered topics, and explicitly contrasts itself with validate_code and scaffold_plugin. This makes the tool's purpose unmistakable and differentiates it from siblings.

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 says this tool covers packaging and distribution 'once the plugin already works' and names the sibling tools it is not (validate_code, scaffold_plugin). This gives clear when-to-use and when-not-to-use guidance, with alternatives called out.

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, and non-destructive behavior. The description adds valuable context beyond those annotations: this operates on a static snapshot rather than a live client, empty results render as markdown rather than error, and full-tree events/storage may require a prebuilt index on R2. No contradiction with annotations.

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 well-structured: a clear lead sentence, sibling exclusions, parameter semantics, a concrete example, and edge-case behavior. Every clause earns its place, and the most important information is front-loaded.

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 four parameters, two enums, output schema, and fifteen siblings, the description covers all essential decision points: what the tool does, how it differs from alternatives, parameter interactions, empty-result behavior, and the R2 index caveat. Nothing critical is left ambiguous.

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 100%, so the baseline is 3. The description restates the schema's parameter constraints (scope only for api_surface/events/storage, detail only for events, query scoped to topic) and provides a small example, but it does not add substantial new meaning beyond what the schema already documents.

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: 'Dump one static catalog from the Lampa snapshot per call.' It then actively differentiates itself from four siblings (search_code, trace_symbol, explain_docs, guide_cub), so an agent can immediately tell what this tool is and is not.

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 gives explicit when-not-to-use guidance by naming alternatives, and it provides conditional usage advice for R2 when the prebuilt index is missing. It also clarifies that query is a scoped filter, not a repo-wide search, which prevents misuse.

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 annotations already indicate read-only, non-destructive, idempotent behavior, and the description adds meaningful context beyond that: snapshot-only, no execution/writes, heuristic not a guarantee, and affected-surface list capped at ~12 files. No contradiction exists between the description and annotations.

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?

Every sentence in the description carries distinct information: purpose, usage order and exclusions, parameter behavior, and operational caveats. It is dense but well-structured, with the core purpose front-loaded before supporting details.

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 description is complete for a planning tool of this complexity. Since an output schema exists, return-value details are not required, and the description covers usage order, sibling distinctions, parameter semantics, and behavioral limitations in enough depth for an agent to invoke 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?

Input schema coverage is 100%, so request and scope_hint are documented. The description adds valuable semantic context: how request and scope_hint concatenate into feature inference and that empty inference still produces a plan rather than an error.

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 begins with a specific verb and resource: generating a step-by-step implementation plan with inferred targets, a reverse-ref sample, and coupling risks. It is immediately distinguishable from siblings through explicit contrasts with draft_patch, trace_symbol, and scaffold_plugin.

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 explicitly says to call this tool before draft_patch and explains what it does not do compared to draft_patch, trace_symbol, and scaffold_plugin. It also covers behavior like empty inference still returning a plan, so an agent knows when the tool remains usable.

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 mark the tool as readonly and idempotent, and the description adds valuable behavioral details: full-file truncation at max_lines, the range behavior ignoring max_lines, the missing-path error, and the kind-dependent behavior. These details are not inferable from the 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 description is dense but every clause earns its place: scope is front-loaded, sibling distinctions come next, and then concrete behavioral rules and error handling. There is no filler or redundant restatement of the title or 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?

For a 6-parameter read tool with rich annotations, an output schema, and several sibling tools, the description covers selection, parameter interactions, defaults, and error outcomes. An agent has everything needed to invoke it correctly without needing additional context.

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%, but the description still adds meaning beyond the schema: it documents the default max_lines of 300, the precedence of start_line/end_line over max_lines, the file-required rule for kind=file, and the omit-file listing behavior. This goes well beyond the individual parameter descriptions.

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 sentence clearly states the tool reads bytes/contents from one known path: a repo file, a src/core module, or a src/templates template. It also differentiates itself from search_code/find_files and explicitly warns against list_catalog, so an agent can identify its exact purpose.

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 explains when to use this tool versus alternatives: it returns a single target's contents, unlike search_code/find_files, and should not be used to dump catalogs. It also provides per-kind invocation rules, such as kind=file requiring a file and omitting file with core/template to list.

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, and non-destructive behavior, so the bar for additional disclosure is lower. The description adds valuable behavioral details: it is a fixed landmark lookup with no filesystem walk, and unrecognized names fall back to defaults so the call 'always returns something actionable.' These traits go beyond annotations and meaningfully shape invocation expectations.

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 compact and front-loaded: purpose first, usage second, then a concrete example plus edge-case behavior. Every sentence earns its place without repetition or 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?

Given a rich annotation set, full parameter schema coverage, and an output schema, the description covers the remaining needs: when to call, what differentiates it, and a non-obvious fallback behavior. There is no critical missing context for correct tool selection and 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 for parameters is 100%, yet the description still adds meaning beyond the schema: it explains how kind+name interact via concrete examples (plugin 'tracks' vs lang 'en') and documents the fallback behavior for unknown names. This is exactly the kind of pragmatic detail an agent needs.

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 'Map' and a clear resource: change kinds to authoritative src/ or plugins/ paths, including listing public/build copies to avoid. It also explicitly contrasts itself with find_files, making it easy to distinguish from sibling tools.

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 gives explicit usage timing: 'Call this before plan_change or draft_patch.' It also states what this tool is not ('unlike find_files... not a search'), helping the agent select it over 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?

Even though annotations already mark the tool as read-only and idempotent, the description adds valuable behavioral detail: it returns markdown only, errors on missing required combinations, and offers best-matching hook selection. These are operational traits an agent needs that annotations do not fully 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 description is dense but well-structured, front-loading the safety-critical fact that it does not write files before explaining each kind. Every sentence carries 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?

Given an output schema exists and annotations cover safety, the description completes the picture by specifying required parameter combos, error behavior, and the recommended follow-up validation step. An agent can correctly invoke this tool across all three kinds without further clarification.

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%, but the description adds crucial grouping semantics by kind, required parameter combinations, and the toggle/trigger alias. It explains that plugin_kind applies only to kind=plugin, which is not clear from the schema 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?

The description opens with a clear statement that the tool returns markdown and does not write the repository, then defines the three distinct kinds of scaffold output. It explicitly distinguishes itself from draft_patch, so an agent can tell which tool produces text versus patches.

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 gives explicit per-kind guidance: which parameters are required, when plugin_kind applies, and that validate_code should be used as a follow-up. It also states when this tool is not appropriate by naming draft_patch, making the decision boundaries clear.

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 destructiveHint false, so the description adds real behavioral detail beyond them: default literal/case-sensitive matching, regex compilation without implicit flags, default extension set, hit/line/preview limits, and error behavior for invalid regex and empty results. Nothing contradicts the annotations.

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 tight block: one purpose sentence, one usage/routing sentence, one defaults sentence, one prefix/globs sentence, and one limits/error sentence. Every sentence earns its place and important facts are front-loaded.

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 four-parameter search tool with output schema and many siblings, the description covers purpose, alternatives, parameter interactions, defaults, limits, and error cases. An agent could select and invoke this tool correctly without needing additional details.

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 describes all four parameters at 100% coverage, so this is above baseline; the description reinforces semantics by adding the default extension list and explicitly stating that prefix and globs combine rather than override, while noting regex gets no implicit flags. This is useful extra meaning even though much of it is already in 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?

Opens with a specific verb and resource: 'Search Lampa source contents for a literal or regex and return path:line plus a preview.' It explicitly names sibling tools find_files, list_catalog, and read_source as things it is not, so an agent can distinguish it from alternatives.

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?

Directly says 'Use this when you know a symbol or pattern; do not use it to list files by name..., dump catalogs..., or read one known path...' and then details how prefix and globs combine. That is explicit when-to-use and 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 declare readOnly, idempotent, and non-destructive behavior, and the description goes well beyond them: it discloses that an empty result is valid, unknown folders or missing repos error, and that stdio requires LAMPA_REPO_PATH while the Worker PAT is transport-only. No contradiction exists between the description and annotations.

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 every sentence earns its place: purpose, exclusions, parameter behavior, error semantics, and environment requirements. The key scoping information is front-loaded before the technical details.

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 already present, the description need not explain return values. It covers when to use the tool, how to choose between overview and recursive modes, error conditions, environment setup for stdio, and authorization constraints for the Worker PAT. This is complete for the tool's complexity.

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 documents subfolder with 100% coverage, but the description adds valuable semantics: subfolder produces a recursive JS/TS-only listing on top of the same overview, and an empty result is meaningful rather than an error. This supplements the schema without merely repeating it.

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 ('Summarize') and resource ('Lampa snapshot'), enumerates what is included (commit metadata, top-level folders, plugins, entrypoints, npm scripts), and states the intended use ('first-session orientation'). It also explicitly distinguishes itself from sibling tools by naming read_source, search_code, and find_files as tools not to use instead.

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 explicit when-to-use context, names the alternatives to avoid, and explains the conditional subfolder parameter behavior. The guidance about omitting subfolder for the compact overview and adding it for a recursive JS/TS listing leaves no ambiguity about how to invoke the tool.

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 destructiveHint, and the description does not contradict them. It adds useful behavioral detail beyond annotations: missing target causes an error, unknown event produces a markdown note instead of crashing, and deps reverse-refs are capped at 20. These are exactly the kind of edge-case behaviors an agent needs to know.

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 efficient: purpose is front-loaded, the exclusions are one clause, examples are compressed into a semicolon list, and edge-case behaviors are stated compactly. Every segment carries necessary information for a tool with five modes.

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 output schema exists and annotations cover the safety profile, the description covers all needed call context: mode semantics, target requirements, error behavior, and a result cap. Nothing essential for selecting or invoking the tool 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 description coverage is 100%, so the baseline is 3, but the description adds significant semantic value. It explains target semantics per mode, clarifies that deps/upgrade expect repo-relative paths (not API names), and specifies that api_calls takes an optional provider keyword. This goes well beyond the schema field descriptions.

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-resource pairing: 'Follow one event, component, file, or provider through the snapshot graph.' It explicitly contrasts itself with list_catalog and search_code, so an agent can immediately distinguish this from siblings 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?

The description names the alternatives it is not ('not a full catalog (list_catalog) and not raw grep (search_code)') and provides concrete per-mode examples with target formats. It also states the key usage rule: omit target only for api_calls, otherwise target is required. This leaves no ambiguity about when or how to use the tool.

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 destructiveHint, and the description adds important behavioral details beyond those: build does not execute, grep is not a shell, missing plugin errors list folders, and show_missing is ignored when key is set. These disclosures fully inform the agent of side effects and failure modes.

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 every sentence adds value, with exclusions front-loaded and mode details organized by mode. There is no filler or repetition of schema content; the structure efficiently communicates complex conditional behavior.

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 multi-mode tool with six parameters, the description covers every mode, every parameter's applicability, error behavior, and exclusions. The presence of an output schema means return-value details need not be explained, so 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%, but the description still adds crucial mode-to-parameter mappings: checks only for grep, show_missing only for i18n coverage, goal only for build, and target required for plugin. It also explains conditional behaviors like default checks and ignored show_missing, which go beyond the raw schema descriptions.

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 ('Run checks and hints') and defines four concrete modes with distinct outcomes: plugin scoring, grep snapshot scans, i18n key/coverage lookup, and build command hints. It explicitly excludes sibling tools like list_catalog and plan_change, making the tool's scope 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 when-to-use guidance per mode, including exclusions ('not a shell', 'does not run it') and alternative tools it is not. Mode-specific parameter constraints further clarify which arguments apply in each scenario, so an agent can choose correctly without guessing.

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