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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety bar is low; the description still adds real behavior: entry-file resolution precedence (main.js → <plugin>.js → first .js), output truncation to ~30 lines, and that an unknown folder errors and lists available folders rather than guessing. The only gap is no note on output size/pagination beyond the truncation hint, which the output schema largely covers.

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 deliverable, then the sibling contrasts, then the parameter rules and error behavior — a sensible priority order with zero filler sentences. It is dense and the third clause chains three 'unlike' comparisons plus the entry-resolution and path-validation rules into one long passage, which costs some scannability.

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 full annotation coverage and an output schema, this is complete: report contents, path validation rules, entry-file fallback order, truncation, and error behavior are all stated. An agent has everything needed to call it correctly on the first attempt.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the schema description already states case-sensitivity, the 'not a manifest id' caveat, and the omit behavior, so much of the description restates it. It nevertheless adds a constraint absent from the schema ('never a plugins/ prefix or nested path') and ties the parameter to the entry-file selection logic, which is genuine added meaning.

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?

Names a specific verb+resource ('Single-call report for one plugins/<name> folder') and enumerates exactly what the report contains: files, Lampa.* usage, Listener follow/send, settings, CSS, and an entry preview. It also explicitly differentiates itself from three siblings (list_catalog, trace_symbol, validate_code), so the agent can pick it 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?

Gives explicit routing rules via 'unlike list_catalog... unlike trace_symbol... unlike validate_code', which tells the agent both when this tool wins and which alternative to use instead. It also states the omit-parameter case ('omit it for load-path-only output') and the failure mode, leaving nothing 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 read-only, idempotent, non-destructive behavior, but the description adds critical operational details: output is text-only, `target_files` fully overrides inference and is never combined with it, inference is capped at 5 files even if more are passed, missing files produce a note rather than aborting, and hunks are suggestions that should be re-checked before applying.

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 front-loaded with the key constraint ('text only — does not write the repository') and then layers useful caveats. Most sentences carry operational value, though the parenthetical cap details and the 'TODO' phrasing are slightly awkward and could be tightened.

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 format explanation is unnecessary, and the description covers the remaining decision-critical behavior: non-writing nature, precedence of `target_files`, inference limits, missing-file handling, and non-guaranteed patch applicability. Nothing substantial 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%, so the schema already documents each parameter. The description still adds meaningful semantics beyond the schema: `target_files` fully overrides inference rather than supplementing it, is capped at the first 5 entries for diff generation even if more are passed, and the summary section lists up to 6. It also explicitly characterizes inference without `plan_context` as weaker.

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 ('Returns ... unified diffs as text only') and immediately clarifies it does not write the repository. It explicitly distinguishes itself from plan_change and scaffold_plugin, so an agent can select it without opening sibling 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?

Names alternatives (`plan_change`, `scaffold_plugin`) and explains the selection conditions: plan_change produces plans, scaffold_plugin emits new-plugin boilerplate, and draft_patch patches existing files with concrete hunks. It also recommends pasting `plan_context` from `plan_change` and explains when `target_files` should be supplied.

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 cover read-only, idempotent, non-destructive and closed-world, so the bar is lower, yet the description still adds real behavioral detail: `mode=ui`/`styles` attach up to 20/15 content hits, `ext` is silently ignored rather than erroring in non-name modes, and empty matches return an empty list rather than an error. These are non-obvious behaviors an agent would otherwise discover by failure.

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 purpose and sibling contrast, then examples, then edge cases; every sentence contributes. It loses a point for mild overlap with the schema, which already states that `ext` applies only to `mode=name`.

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 no explanation, and the description covers mode semantics and failure behavior. Minor gap: it does not say whether `mode=name` results are capped or ordered the way `ui`/`styles` content hits are, so the agent cannot predict result volume in the default mode.

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 a 3 is the baseline, but the description goes beyond the schema by giving concrete `query` examples per mode, noting the built-in feature map, and explaining the silent-ignore semantics of `ext` (the schema says 'ignored otherwise' but not that it will not error). That is meaningful added semantics rather than restatement.

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 ('Locate repo-relative paths') plus the dimensions it searches (filename, feature, UI component, stylesheet, spec) and immediately frames itself as 'a path finder, not content grep.' It explicitly contrasts with the siblings `search_code` and `read_source`, so an agent can discriminate without opening a 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?

Names alternatives and the conditions that select them: use `search_code` for content grep, `read_source` for file bytes, this tool for name/path lookup. It also supplies per-mode usage examples (`mode=feature query='player'`, `mode=name query='full' ext='.js'`), 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 readOnly/idempotent/non-destructive/closed-world, but the description adds material behavior the annotations cannot express: no network calls of its own, pure snapshot read, no auth required to invoke, and markdown rather than raw JSON output. These are real operational facts an agent needs and none contradict the 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?

One dense but well-ordered paragraph: identity/scope first, then the non-substitute warning, then a topic-by-topic parameter map. Every clause carries routing or semantics information; nothing is 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 7 parameters, 5 enums, a required topic, and an output schema already in place, the description covers the remaining risk area — which params apply to which topic and what happens when they don't — and confirms the return format. Nothing material is left to inference.

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 would be 3, but the description goes further by defining the cross-parameter applicability matrix per topic (e.g. `endpoint` requires `path` and ignores `category`/`search`), which the flat schema cannot express. Example values like `bookmarks/dump` reinforce the format.

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 ('Document how Lampa talks to CUB from source') and immediately scopes what it is not (a substitute for cub.rip/developer). It also distinguishes itself from the sibling tool `list_catalog` topic=mirrors/socket, so an agent can route correctly 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 enumerates each `topic` value and states exactly which parameters it honors (catalog→category/search, endpoint→path, auth→auth_focus, models→model, sync→none, timeline_hash→example). It even states the failure-tolerance rule ('silently ignored, never an error'), which is explicit when/when-not 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=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 establish readOnly, idempotent, non-destructive, and closed-world behavior, but the description adds important context beyond them. It discloses that output is markdown rather than JSON, that cost is one tree walk, that an empty catalog is not an error, and that full-tree events/storage on R2 may require a prebuilt index.

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 front-loads purpose, then covers sibling alternatives, parameter constraints, an example, and edge-case behavior. It is dense but appropriately sized for a catalog tool with multiple topics and operational caveats.

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, annotations cover safety, and schema descriptions are complete. The description still adds useful index-missing guidance and clarifies empty-result behavior, so an agent has enough information 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?

Schema description coverage is 100%, so the baseline is 3. The description adds that query is a plain substring filter and gives an example combining topic, query, and detail, but most scope/detail/topic semantics are already fully documented 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?

It states a specific action and resource: dumping one static catalog from the Lampa snapshot. It immediately distinguishes the tool from four sibling behaviors: search_code, trace_symbol, explain_docs, and guide_cub. An agent can recognize this as static catalog retrieval rather than search, tracing, documentation, or live CUB access.

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 what the tool is not and names the alternatives, giving clear routing guidance. It also explains when to use query or a narrower topic if the R2 index is missing, and provides a concrete example with topic=events, query='player', and detail=true.

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 cover the safety profile (readOnly, idempotent, closed-world, non-destructive), and the description adds behavior beyond that: no filesystem walk or content search, graceful fallback on unrecognized `name` so the call 'always returns something actionable', and silent ignoring of `name` for sass/settings. These are exactly the traits an agent needs to predict outcomes.

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 critical routing constraint ('call before plan_change/draft_patch') and the contrast with find_files are front-loaded, and every sentence carries information. It is slightly dense with examples and edge-case clauses packed into one long paragraph, which costs a point against a tighter structure.

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 two-parameter, read-only lookup with an output schema (so return values needn't be described), the description covers ordering relative to siblings, fallback behavior, and kind-specific edge cases. Nothing essential for calling 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%, so the baseline is 3, but the description adds real semantics beyond the schema: it enumerates what each `kind` maps to with two worked examples, states `name` has no effect for `kind=sass` and `kind=settings`, and clarifies the fallback for unknown names. That is meaning the 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?

The description states a specific verb ('Map') and resource ('a change kind ... to the authoritative src/ or plugins/ path'), lists the exact enum values, and explicitly contrasts itself with `find_files` as a fixed landmark look-up rather than a search. An agent can distinguish it from every sibling 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?

It gives an explicit precondition ('Call this before `plan_change` or `draft_patch`') and a negative rule ('unlike `find_files`, this is a fixed landmark table look-up ... not a search'). The two concrete examples (kind=plugin vs kind=lang) further pin down intended use.

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 readOnly/idempotent/non-destructive and closed-world, so the safety profile is covered structurally. The description adds genuinely useful disclosure beyond that — default match mode, case-sensitivity, extension defaults, empty-globs equivalence, prefix+globs interaction, hard limits (100 hits, 5/file, 200-char preview), and the invalid-regex / no-match behaviors. Those limits and edge-case semantics are real added value, though return shape is mostly delegated to the output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and sibling routing before defaults/limits, and each sentence carries distinct information. It is dense but not padded; the backtick-heavy prose is slightly harder to scan than necessary.

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, yet the description still characterizes the hit format (path:line plus preview) and truncation size. Combined with defaults, limits, and failure modes, an agent has everything needed to call it correctly and interpret the result bounds.

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 is 3. The description goes beyond it on two points the schema does not state plainly: an empty `globs` array is treated as omitted rather than 'no extensions', and `prefix` and `globs` combine rather than override. The regex wording largely restates the schema's own note about no implicit `i`.

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 contents) and resource (Lampa source), and explicitly distinguishes itself from three siblings — find_files, list_catalog, read_source — by naming what each of those does instead. An agent can route correctly 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?

Gives an explicit positive trigger ('when you know a symbol or pattern') and three explicit exclusions with the correct alternative named for each. Nothing about tool selection is 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?

Beyond the read-only and idempotent annotations, the description discloses that the result is a single markdown report rather than JSON, that `subfolder` triggers a recursive JS/TS-only listing, that matching is case-sensitive, and that an empty result is a valid answer rather than an error. It also covers error cases and transport/auth constraints that the annotations do not provide.

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 return format are front-loaded, and every clause carries useful information. The description is dense and semicolon-heavy, which slightly reduces readability, but it does not waste space on redundant or irrelevant 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 covers the tool's purpose, return format, parameter behavior, error cases, and auth/transport constraints. With a rich output schema and annotations already present, this is complete enough for an agent to call 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 substantial meaning beyond the schema: omitting `subfolder` produces the compact overview, while supplying it adds a recursive JS/TS-only listing under a case-sensitive path prefix. It also clarifies that unknown folders or missing repos produce errors and that empty results are valid.

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 and resource: "Summarize the Lampa snapshot," and enumerates the exact contents: commit metadata, top-level folders, plugins, entrypoints, and npm scripts. It clearly distinguishes the tool from `read_source`, `search_code`, and `find_files`.

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 intended use case as "first-session orientation" and explicitly lists when not to use it, naming the sibling tools for reading bytes, searching contents, and listing files. It also explains how to choose between the compact overview and the `subfolder` listing.

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 read-only, idempotent, non-destructive, closed-world; the description adds behavior they don't cover: truncation with an explicit count and no silent pagination, missing-target → error, unknown event → markdown note rather than a crash, and a 20-item cap on deps reverse refs. That is exactly the failure-mode context 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?

Front-loaded with the scope and the sibling disambiguation, then mode examples and behavioral caveats — no sentence is filler. It is densely parenthetical, though, and the clipped example fragments take a second read, costing a point on structure.

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 described, and the description correctly points at it while covering the things the schema can't: truncation, error vs. soft-note behavior, and per-mode targeting. 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 coverage is 100%, so the enum and target rules are largely already documented; the description still adds value by pairing each mode with a concrete example target and clarifying that `upgrade` expects a repo-relative path rather than an API name. It mostly mirrors the schema, hence 4 rather than 5.

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 object ('Follow one event, component, file, or provider through the snapshot graph') and explicitly names the two siblings it is not: `list_catalog` (full catalog) and `search_code` (raw grep). An agent can distinguish it 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?

Gives per-mode usage examples (event/lifecycle/deps/upgrade/api_calls), states the exclusion 'omit target only for api_calls', and warns that `upgrade` takes a file path 'not an API name'. When-to-use and when-not-to-use are both covered, plus routing to 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?

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely new behavior: no shell and no code execution in `grep`, `build` never runs npm/gulp, and specific error semantics (missing plugin lists folders; missing `target` errors naming the requirement). These are exactly the side-effect and failure details annotations cannot express.

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?

Content is front-loaded with purpose and sibling routing before mode details, and every clause carries information. However the em-dash run-ons and stacked parentheticals make some sentences dense enough to require re-reading.

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, annotations covering the safety profile, and 100% schema coverage, the description supplies the remaining missing layer: mode selection, parameter conditionality, and error behavior. Nothing an agent needs to invoke any of the four modes correctly is absent.

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 goes beyond per-field docs by stating cross-parameter conditionality: `checks` applies only to grep (default all five), `show_missing` only to i18n coverage and is ignored once `key` is set, `goal` only to build, `target` required only for plugin. That conditional logic is not derivable 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 opening sentence states a specific verb and resource ("Run checks and hints") and explicitly negates the two most confusable siblings (`list_catalog`, `plan_change`) while naming the better alternatives `analyze_plugin` and `trace_symbol`. An agent can pick this tool over any sibling without opening a 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-to-use for each of the four modes (`plugin` scores pitfalls, `grep` scans snapshot, `i18n` looks up key/coverage, `build` returns a command) plus explicit when-not-to-use by routing descriptive/graph work to `analyze_plugin` and `trace_symbol`. Two concrete invocation examples are supplied.

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