lampa-mcp-server

• summarize_repo

  555445A4.8

  An exemplar description: purpose is specific with clear sibling differentiation, usage guidance is explicit (what to do/not do), and it adds behavioral depth beyond annotations (case sensitivity, empty results, error semantics, transport-only scopes). It handles the presence of an output schema elegantly by focusing on behavioral details the schema cannot convey, earning top scores across all dimensions without being unnecessarily long.

  5

  Purpose Clarity · 25%Description clearly states it summarizes a snapshot with specific items (commit metadata, top-level folders, plugins, entrypoints, npm scripts) for first-session orientation. It explicitly differentiates from siblings by naming what it does NOT do (read bytes, search contents, list files by name).

  5

  Usage Guidelines · 20%Provides explicit when-to-use (first-session orientation), what to omit for compact overview, and how to add subfolder for JS/TS listing. Clearly names alternatives (read_source, search_code, find_files) and notes error conditions (unknown folder, missing repo).

  5

  Behavioral Transparency · 20%Annotations declare readOnly/idempotent/destructive hints, but description goes beyond: specifies return format (markdown report, not JSON), case-sensitivity, empty result semantics, and transport-only PAT with no extra scopes. Even with strong annotations, this adds unique behavioral context not available in structured data.

  4

  Parameter Semantics · 15%Schema covers 100% of parameter description, but description adds crucial semantics: case-sensitivity, empty result as valid 'no files' answer, and what omitting the parameter yields. The schema only mentions casing is sensitive per description, not in schema; description enriches the parameter meaning.

  4

  Conciseness & Structure · 10%Single well-structured sentence, front-loaded with purpose then constraints. Slightly long but every clause adds value (return type, exclusions, parameter behavior, error cases). Could benefit from splitting into two sentences for readability, but stays dense.

  5

  Contextual Completeness · 10%Complete for its purpose: covers parameters, error conditions, output format, sibling tool exclusions, and environment context (LAMPA_REPO_PATH, PAT scopes). Output schema exists, so return values don't need elaboration. A one-param tool with rich descriptions and annotations is fully specified.

  params

  1 (0 required, 100% described)

  annotations

  readOnly=true destructive=false idempotent=true openWorld=false

  output schema

  yes

  cost

  0

  bytes

  1544

  hash

  eaa04abf521b3efd

• search_code

  555455A4.9

  This is an exemplary tool description that excels in all dimensions. It clearly defines purpose, provides explicit usage guidelines with alternatives, offers deep behavioral transparency beyond annotations, and is well-structured and concise. The description effectively leverages the schema and annotations while adding significant value, making it a model for tool documentation.

  5

  Purpose Clarity · 25%The description clearly states the tool searches Lampa source contents for literal or regex patterns and returns path:line plus preview. It explicitly distinguishes itself from siblings like find_files, list_catalog, and read_source, making its purpose unambiguous.

  5

  Usage Guidelines · 20%The description explicitly states when to use this tool ('when you know a symbol or pattern') and when not to, naming specific alternatives (find_files, list_catalog, read_source). It also explains how prefix and globs combine, providing clear usage context.

  5

  Behavioral Transparency · 20%The description goes beyond the annotations by detailing exact limits (100 hits, 5 per file, 200-char preview), default behaviors (case-sensitive, extensions), and edge cases (empty globs treated as omitted, invalid regex errors, no matches returns empty markdown). This is rich behavioral context not present in the annotations.

  4

  Parameter Semantics · 15%While the schema covers all parameters with descriptions, the tool description adds critical semantics about how parameters interact (prefix and globs combine) and default behaviors (case-sensitivity, extension defaults) that are not fully explicit in the schema. The description enhances understanding beyond the schema.

  5

  Conciseness & Structure · 10%The description is dense but well-structured, using paragraphs to group related information: purpose, defaults, combination logic, and limits. Every sentence adds value, and the use of backticks for code elements improves readability. No fluff.

  5

  Contextual Completeness · 10%Given the tool's moderate complexity, the description covers all necessary aspects: purpose, usage, parameters, limits, and error handling. The output schema exists, so return values are documented. The description is complete for an agent to use this tool effectively without additional context.

  params

  4 (1 required, 100% described)

  annotations

  readOnly=true destructive=false idempotent=true openWorld=false

  output schema

  yes

  cost

  1

  bytes

  2092

  hash

  d0c9621db35f52fc

• find_files

  555555A5.0

  This is a top-tier description. It not only clarifies the tool's purpose and distinguishes it effectively from siblings, but also provides concrete usage examples, edge-case behavior, and silent-mode semantics that go beyond schema and annotations. Concise and well-structured, it achieves high scores across all dimensions.

  5

  Purpose Clarity · 25%The description clearly states it 'Locate repo-relative paths by filename, Lampa feature, UI component, stylesheet, or spec' — a specific verb and resource. It explicitly contrasts with 'search_code' and 'read_source', distinguishing it from sibling tools, and provides concrete examples of modes.

  5

  Usage Guidelines · 20%The description explicitly states when to use it versus alternatives: 'Unlike search_code, this matches names/paths...; unlike read_source, it does not return file bytes.' It also gives usage examples for different modes, such as 'mode=feature query=player', and notes edge cases like ext only being honored in mode=name, making usage guidance explicit and actionable.

  5

  Behavioral Transparency · 20%The description discloses that ext is silently ignored in non-name modes, that empty matches return a list not an error, and that certain modes attach content hits (up to 20/15) — behavioral details beyond the annotations. Annotations declare readOnlyHint=true and destructiveHint=false, and the description adds nuanced behavior (silent ignoring, hit limits) without contradicting the annotations.

  5

  Parameter Semantics · 15%Schema description coverage is 100% with detailed parameter docs én the schema itself — e.g., mode's enum values with explanationscourt. The description adds a concrete example ('mode=feature query=player'), explains the ext flag interaction (only honored with mode=name), and clarifies the semantics of empty results vs error, which enriches understanding beyond the schema alone.

  5

  Conciseness & Structure · 10%The description is rich but well-organized: starts with a crisp one-line purpose, includes a distinguishing comparison, and condenses usage details with a concrete example elseif relationship. Both sentences pack essential information without redundancy, front-loading the core use case.

  5

  Contextual Completeness · 10%The tool has 3 params with 100% schema coverage roughly, an output schema, and comprehensive annotations (readOnly, idempotent, non-destructive). The description fully covers the path-finder nature, mode-specific behaviors, extension filtering nuance, silent-ignore behavior, and empty-result handling, making it complete for the complexity of this tool.

  params

  3 (1 required, 100% described)

  annotations

  readOnly=true destructive=false idempotent=true openWorld=false

  output schema

  yes

  cost

  1

  bytes

  1853

  hash

  18c9b729c5f8b3f6

• read_source

  554454A4.6

  The description is highly effective, clearly stating the tool's purpose, usage boundaries, and parameter behaviors. It leverages the schema well and adds practical guidance on defaults and error conditions. Minor improvements could include explicit mention of read-only behavior and output format, but overall it is a strong, well-crafted description.

  5

  Purpose Clarity · 25%The description clearly states the tool reads bytes from a known path, and explicitly distinguishes it from search_code and find_files by noting it returns contents of a single target. It also specifies the three kinds of targets (repo file, src/core module, src/templates template), making the purpose unambiguous.

  5

  Usage Guidelines · 20%The description provides explicit usage guidance: it tells when to use this tool (to read a specific file/module/template) and when not to (not for searching or dumping catalogs, which are handled by search_code/find_files/list_catalog). It also explains the parameter behavior for line ranges and kind-specific requirements, giving clear instructions on how to invoke it correctly.

  4

  Behavioral Transparency · 20%The description discloses key behaviors: it truncates at max_lines by default, supports line ranges, and errors on missing paths. However, it does not mention whether the tool is read-only (though annotations indicate readOnlyHint=true) or what the exact error format is. Since annotations already cover read-only and idempotent nature, the description adds value by explaining truncation and error conditions, but could be slightly more explicit about the read-only guarantee.

  4

  Parameter Semantics · 15%The schema descriptions for each parameter are already quite detailed (e.g., 'Required for kind=file', 'Ignored when start_line/end_line are set'), and the description reinforces these by explaining the default behavior and the interplay between max_lines and start_line/end_line. However, the description does not add much beyond the schema for parameters like kind and template_mode, which are already well-documented. Overall, the schema coverage is high, and the description adds marginal value, so a 4 is appropriate.

  5

  Conciseness & Structure · 10%The description is concise and well-structured, using semicolons to separate distinct points. It packs a lot of information into a single sentence without redundancy, and every clause adds value (e.g., distinguishing from siblings, explaining defaults, and noting error conditions). No fluff or unnecessary words.

  4

  Contextual Completeness · 10%Given the complexity of the tool (multiple kinds, line ranges, defaults, and error handling), the description covers the essential aspects: what it does, when to use it, and key parameter behaviors. It does not explicitly mention the output format (e.g., whether it returns raw bytes or a structured object), but since the output schema is not provided, this is a minor gap. The description is complete enough for an agent to use the tool correctly in most scenarios.

  params

  6 (0 required, 100% described)

  annotations

  readOnly=true destructive=false idempotent=true openWorld=false

  output schema

  yes

  cost

  0

  bytes

  1833

  hash

  5bc2d6a35886e11f

• resolve_edit_path

  555455A4.9

  This is an exemplary tool description. It clearly states the tool's purpose, provides explicit usage guidance with alternatives, and adds behavioral transparency beyond annotations. The parameter semantics are enriched with examples and edge-case handling, all in a concise and well-structured format. It fully equips an agent to select and invoke the tool correctly.

  5

  Purpose Clarity · 25%The description clearly states the tool maps a change kind to an authoritative path and lists generated copies to avoid, distinguishing it from find_files by noting it's a fixed landmark table look-up, not a search. It also provides concrete examples for plugin and lang kinds.

  5

  Usage Guidelines · 20%Explicitly instructs to call this before plan_change or draft_patch, and contrasts with find_files, which is a search. This gives clear when-to-use guidance and differentiates from a sibling tool.

  5

  Behavioral Transparency · 20%Annotations already declare readOnlyHint=true and destructiveHint=false, so the description doesn't need to repeat that. It adds valuable behavioral context: unrecognized names fall back to defaults, and name is ignored for sass/settings, ensuring the agent knows the tool always returns actionable results.

  4

  Parameter Semantics · 15%Schema coverage is 100%, so parameters are well-documented. The description adds extra meaning by explaining the fallback behavior for unknown names and the irrelevance of name for certain kinds, which goes beyond the schema's basic descriptions.

  5

  Conciseness & Structure · 10%The description is concise, front-loaded with the core purpose, and uses an example to clarify behavior. Every sentence adds value, with no fluff or repetition.

  5

  Contextual Completeness · 10%Given the tool's moderate complexity, the description covers purpose, usage, edge cases, and examples. The output schema exists, so return values are documented elsewhere. The description is complete for an agent to use effectively.

  params

  2 (1 required, 100% described)

  annotations

  readOnly=true destructive=false idempotent=true openWorld=false

  output schema

  yes

  cost

  1

  bytes

  1719

  hash

  862d30568b05aee3

• list_catalog

  555545A4.9

  Excellent description: clearly distinguishes from siblings, communicates behavior beyond schema, and gives operational guidance. Minor deductions on conciseness for slightly dense phrasing about index requirements, but overall high quality.

  5

  Purpose Clarity · 25%The description clearly identifies the tool as a catalog dumper with specific scope ('Dump one static catalog from the Lampa snapshot per call'), and explicitly contrasts it with sibling tools like search_code, trace_symbol, explain_docs, and guide_cub, making its purpose unmistakable and well-differentiated.

  5

  Usage Guidelines · 20%The description provides explicit when-to-use and when-not-to-use guidance: 'Not a query (search_code), not a single-symbol walk (trace_symbol), not written docs (explain_docs), and not a live CUB client (guide_cub).' It also explains how to handle missing indexes (pass query or narrower topic), which is concrete and actionable.

  5

  Behavioral Transparency · 20%The annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds important context: returns markdown text not JSON, no performance cost, empty catalog returns markdown not error, and index requirement on R2. It even mentions the detail flag only affects events and scope only applies to specific topics, which matches the schema without contradicting it.

  5

  Parameter Semantics · 15%Schema coverage is high — each parameter (topic, scope, query, detail) is described in the schema. The description further clarifies query is a plain substring filter within the chosen topic, scope applies only to api_surface/events/storage, and detail only affects events, which adds beyond what the schema properties state. The example ties the parameters together.

  4

  Conciseness & Structure · 10%The description is compact and front-loaded with the core purpose, though the second paragraph bundles several caveats into one long sentence. It's efficient overall — each sentence adds distinct value (output format, performance, sibling distinctions, parameter semantics, edge cases). The R2 index note might be difficult for some agents to parse as a single run-on sentence.

  5

  Contextual Completeness · 10%Given 4 parameters all documented at 100% coverage in the schema registers, the description provides essential context: output format (markdown), cost profile, edge cases (empty catalog, R2 index requirement), and concrete example. No gaps remain for correct invocation.

  params

  4 (1 required, 100% described)

  annotations

  readOnly=true destructive=false idempotent=true openWorld=false

  output schema

  yes

  cost

  1

  bytes

  2243

  hash

  44602e022696c111

• analyze_plugin

  554455A4.7

  This is an exemplary tool description. It clearly defines the tool's purpose, explicitly contrasts it with siblings, provides detailed usage guidelines including parameter constraints and error handling, and adds behavioral context beyond the annotations. The description is concise yet comprehensive, making it easy for an agent to select and invoke the tool correctly.

  5

  Purpose Clarity · 25%The description clearly states the tool's purpose: a single-call report for one plugin folder, listing files, Lampa.* usage, Listener follow/send, settings, CSS, and an entry preview. It explicitly distinguishes itself from sibling tools like list_catalog, trace_symbol, and validate_code, making its scope unambiguous.

  5

  Usage Guidelines · 20%The description provides explicit when-to-use guidance by contrasting with 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.' It also gives detailed usage instructions, including how the entry file is chosen, the exact format for the plugin parameter, and what happens if the folder is unknown.

  4

  Behavioral Transparency · 20%Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context: it explains the entry file selection logic, the error behavior for unknown folders, and the load-path-only output when plugin is omitted. It does not contradict annotations, and the added details go beyond what annotations provide.

  4

  Parameter Semantics · 15%The schema already provides a description for the plugin parameter, and the description reinforces it with examples and constraints (case-sensitive, no prefix, no nested path). It also clarifies that the parameter is optional and what happens when omitted. This adds meaning beyond the schema's basic description, though the schema coverage is already high.

  5

  Conciseness & Structure · 10%The description is dense but well-structured, front-loading the core purpose and then providing necessary details. Every sentence adds value: the first sentence summarizes the report contents, the second differentiates from siblings, and the third explains parameter semantics and error handling. No fluff or redundancy.

  5

  Contextual Completeness · 10%Given the tool's moderate complexity (one optional parameter, output schema present), the description is complete. It covers the tool's scope, usage, parameter constraints, error behavior, and output contents. The output schema likely details the report structure, so the description doesn't need to enumerate every field. The description fully equips an agent to decide when and how to use it.

  params

  1 (0 required, 100% described)

  annotations

  readOnly=true destructive=false idempotent=true openWorld=false

  output schema

  yes

  cost

  0

  bytes

  1501

  hash

  d749791c346847c0

• trace_symbol

  554445A4.6

  This is a high-quality description that clearly defines the tool's purpose, differentiates it from siblings, and provides rich usage guidance with mode-specific examples. It adds behavioral transparency beyond annotations (truncation, error handling) and parameter semantics beyond the schema. The only minor improvement would be structural formatting, but it is already excellent.

  5

  Purpose Clarity · 25%The description clearly states the tool traces one symbol (event, component, file, or provider) through the snapshot graph, distinguishing it from list_catalog and search_code. It uses a specific verb and resource, and the examples clarify the scope.

  5

  Usage Guidelines · 20%It explicitly says when to use this tool vs alternatives ('not a full catalog' and 'not raw grep'), and provides mode-specific examples and constraints (e.g., 'omit target only for api_calls', 'Missing target otherwise → error'). This is excellent guidance.

  4

  Behavioral Transparency · 20%Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description doesn't need to repeat that. It adds valuable behavioral details: truncation with explicit count, error vs. markdown note for missing target/unknown event, and deps reverse-refs cap at 20. This goes beyond annotations.

  4

  Parameter Semantics · 15%Schema coverage is 100%, so the schema already documents both parameters. The description adds extra meaning by explaining the target semantics per mode (e.g., 'deps/upgrade: repo-relative file path', 'api_calls: optional provider keyword') and the required/optional nature, which is not fully in the schema. This is a slight improvement over baseline.

  4

  Conciseness & Structure · 10%The description is a single dense paragraph but front-loaded with the core purpose and alternatives. It packs a lot of information efficiently, though it could be slightly more structured with bullet points for readability. Still, every sentence adds value.

  5

  Contextual Completeness · 10%Given the tool's complexity (5 modes, 2 params, output schema present), the description covers all necessary aspects: what it does, when to use, behavior on edge cases, and parameter semantics. The output schema handles return values, so no need to explain that. It is complete for an agent to use correctly.

  params

  2 (1 required, 100% described)

  annotations

  readOnly=true destructive=false idempotent=true openWorld=false

  output schema

  yes

  cost

  1

  bytes

  1716

  hash

  104d191aeff5896f

• plan_change

  554455A4.7

  This is a well-crafted tool description that excels in purpose clarity and usage guidelines, clearly differentiating from siblings. It adds meaningful behavioral context beyond annotations and explains parameter semantics effectively. The description is concise yet complete, making it a strong example for agent-facing tool documentation.

  5

  Purpose Clarity · 25%The description clearly states the tool's purpose: generating a step-by-step implementation plan for a Lampa change. It uses a specific verb ('Generate') and resource ('implementation plan'), and explicitly distinguishes itself from sibling tools like `draft_patch`, `trace_symbol`, and `scaffold_plugin`, making it easy to select among similar tools.

  5

  Usage Guidelines · 20%The description provides explicit guidance on when to use this tool: 'Call this before `draft_patch`'. It also clearly states what it does not do compared to alternatives ('unlike `draft_patch` it does not invent diffs', etc.), giving the agent clear context for choosing this tool over others.

  4

  Behavioral Transparency · 20%The description adds valuable behavioral context beyond the annotations: it states the tool is 'Snapshot-only — does not execute or write' and 'heuristic — not a guarantee', which complements the readOnlyHint and idempotentHint. It also mentions the affected-surface list caps at ~12 files, providing additional transparency. No contradiction with annotations.

  4

  Parameter Semantics · 15%The schema already covers both parameters with descriptions (100% coverage), so the baseline is 3. The description adds extra meaning by explaining how the parameters interact: 'request='add a sleep timer'' + `scope_hint='player'` concatenates into feature inference', and clarifies that empty inference still returns a plan. This goes beyond the schema's individual parameter descriptions.

  5

  Conciseness & Structure · 10%The description is concise and well-structured. It front-loads the core purpose in the first sentence, then uses a clear list of contrasts with siblings, and ends with important behavioral notes. Every sentence adds value, with no redundancy or filler.

  5

  Contextual Completeness · 10%Given the tool's moderate complexity (2 params, output schema present, annotations provided), the description is complete. It covers purpose, usage, behavioral traits, and parameter interaction. The output schema likely explains return values, so the description doesn't need to. The description is sufficient for an agent to use the tool correctly.

  params

  2 (1 required, 100% described)

  annotations

  readOnly=true destructive=false idempotent=true openWorld=false

  output schema

  yes

  cost

  1

  bytes

  1468

  hash

  92da5340d4101317

• draft_patch

  554445A4.6

  This is a well-crafted description that clearly defines the tool's purpose, differentiates it from siblings, and provides rich behavioral context beyond the annotations. It effectively explains parameter interactions and edge cases, making it highly actionable for an AI agent. The only minor improvement could be a more explicit statement about non-mutating behavior, but that is already covered by annotations and the first sentence.

  5

  Purpose Clarity · 25%The description clearly states the tool's purpose: 'Returns TODO unified diffs as text only — does not write the repository.' It uses a specific verb ('draft') and resource ('patch'), and explicitly distinguishes itself from siblings like plan_change and scaffold_plugin, making it easy to select among similar tools.

  5

  Usage Guidelines · 20%The description provides explicit guidance on when to use this tool: 'Best with plan_context pasted from plan_change' and contrasts it with alternatives: 'unlike plan_change, this invents concrete diff hunks; unlike scaffold_plugin, it patches existing files rather than emitting new-plugin boilerplate.' It also explains the trade-off between using plan_context vs. relying on request alone, giving clear usage context.

  4

  Behavioral Transparency · 20%The description adds significant behavioral context beyond the annotations: it clarifies that the tool is read-only (consistent with readOnlyHint=true) and idempotent (consistent with idempotentHint=true), but also discloses important nuances: 'Missing files get a 'File not found' note instead of aborting' and 'the @@ hunks are suggested, not guaranteed to apply.' It also explains the cap on target_files and the override behavior, which are not evident from annotations. The only minor gap is not explicitly stating that it does not modify the repository, but that is already implied by readOnlyHint and the first sentence.

  4

  Parameter Semantics · 15%The schema already provides descriptions for all three parameters (100% coverage), so the baseline is 3. The description adds value by explaining the interaction between parameters: 'target_files, when given, fully overrides inference (the two are never combined)' and clarifies the cap behavior ('capped at the first 5 entries'). It also explains the relative strength of plan_context vs. request, which is not in the schema. This goes beyond the schema, justifying a 4.

  4

  Conciseness & Structure · 10%The description is a single paragraph but packs a lot of information efficiently. It front-loads the core purpose and then provides usage guidance and edge-case behavior. While it is longer than the ideal, every sentence adds value, and the structure is logical: purpose, usage, parameter behavior, and caveats. It earns a 4 for being dense but not bloated.

  5

  Contextual Completeness · 10%Given the tool's moderate complexity (3 params, 1 required, no enums, no nested objects) and the presence of an output schema, the description covers all necessary aspects: purpose, usage, parameter semantics, and edge cases (missing files, hunk reliability). It also provides sufficient guidance for an agent to decide when to use it and what to expect. The description is complete for the tool's scope.

  params

  3 (1 required, 100% described)

  annotations

  readOnly=true destructive=false idempotent=true openWorld=false

  output schema

  yes

  cost

  1

  bytes

  1829

  hash

  70b6442fd369b9e9

• scaffold_plugin

  554455A4.7

  This is a high-quality tool description that clearly explains the tool's purpose, usage guidelines, and behavioral nuances. It effectively differentiates from siblings and provides comprehensive guidance for each kind, making it easy for an agent to select and invoke correctly.

  5

  Purpose Clarity · 25%The description clearly states the tool generates Lampa plugin, setting, or hook text, with specific verbs and resource types. It distinguishes from sibling tools by explicitly noting it does not write to the repository and is not a patch, contrasting with draft_patch.

  5

  Usage Guidelines · 20%The description provides explicit when-to-use guidance for each kind (plugin, setting, hook) and specifies required parameters for each. It also mentions follow-up with validate_code, giving clear context on the workflow.

  4

  Behavioral Transparency · 20%Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description doesn't need to repeat safety. It adds behavioral context by stating it returns markdown only, does not write the repository, and errors on missing required combos, which is valuable beyond annotations.

  4

  Parameter Semantics · 15%Schema description coverage is 100%, so the schema already documents all parameters. The description adds value by explaining how parameters interact per kind (e.g., plugin_kind applies only to plugin, type=toggle aliases trigger), which is not fully captured in the schema.

  5

  Conciseness & Structure · 10%The description is concise and well-structured, with each sentence serving a purpose. It front-loads the key point (returns markdown only) and then systematically covers each kind, making it easy to scan.

  5

  Contextual Completeness · 10%Given the tool's complexity (11 parameters, 3 kinds, conditional requirements), the description is complete. It covers all kinds, required parameters, error behavior, and follow-up steps. The output schema exists, so return values are not needed in the description.

  params

  11 (1 required, 100% described)

  annotations

  readOnly=true destructive=false idempotent=true openWorld=false

  output schema

  yes

  cost

  1

  bytes

  2626

  hash

  ace1cd807651fd73

• validate_code

  555445A4.8

  The description is thorough and well-structured, explicitly differentiating this tool from six siblings and giving mode-specific parameter semantics. It fully compensates for the 6-parameter schema by detailing per-mode requirements and defaults, though the density of mode-specific rules makes it better suited for a reference table than quick scanning.

  5

  Purpose Clarity · 25%The description clearly states that the tool runs checks and hints across four modes (plugin, grep, i18n, build), and explicitly contrasts itself with siblings like list_catalog, analyze_plugin, and trace_symbol. It names the verb ('validate', 'score', 'lint') and the resources (plugin, snapshot, i18n keys, build commands), making the intent unmistakable.

  5

  Usage Guidelines · 20%The first sentence explicitly states when NOT to use this tool (not catalogs, not edit plans, prefer analyze_plugin for descriptive reports, trace_symbol for dependency graphs). The second paragraph gives concrete mode-specific usage rules and error behavior (e.g., 'missing target for mode=plugin → error naming the requirement'), which is strong guidance for selection.

  5

  Behavioral Transparency · 20%Annotations provide readOnlyHint=true, idempotentHint=true, destructiveHint=falseholistic safety profile. Despite that, the description adds valuable behavior: it explicitly states the tool 'never runs it', 'not a shell', 'never describes structure', and details error conditions. This goes beyond the annotation baseline and provides significant incremental behavioral disclosure.

  4

  Parameter Semantics · 15%With 100% schema coverage, the baseline is 3-distinguishing. The description adds meaningful cross-parameter semantics (defaults for checks, ignored parameters when mode doesn't apply, default behavior for i18n without key), which goes beyond the schema's per-parameter notes. Missing explicit examples of full parameter combinations slightly reduce the score.

  4

  Conciseness & Structure · 10%The description is dense but front-loaded with the most important distinction (what it is not), followed by mode breakdown and an example. It is longer than typical but each sentence earns its place; a slight trimming of the second example could improve conciseness.

  5

  Contextual Completeness · 10%With six parameters at 100% schema coverageوفاة and an output schema, the description adds crucial mode-specific constraints, error behavior, and default values (e.g., 'checks only applies to grep, default all five'). It covers all modes adequately and aligns with the annotations.

  params

  6 (1 required, 100% described)

  annotations

  readOnly=true destructive=false idempotent=true openWorld=false

  output schema

  yes

  cost

  1

  bytes

  2639

  hash

  8aa4b4a4339c2627

• explain_docs

  554455A4.7

  This is an exemplary tool description that clearly defines purpose, provides explicit usage guidance with sibling differentiation, and adds behavioral context beyond annotations (snapshot-only, no execution). It effectively explains parameter interactions and error handling, making it highly actionable for an AI agent. The only minor gap is not detailing the output format, but the output schema covers that.

  5

  Purpose Clarity · 25%The description clearly states the tool reads written Lampa guides across three specific modes (plugin_docs, pattern, packaging), each with a distinct resource. It explicitly distinguishes from siblings by naming list_catalog and search_code as alternatives, making the purpose unambiguous.

  5

  Usage Guidelines · 20%The description provides explicit when-to-use guidance: it names alternatives (list_catalog for live API catalog, search_code for grep) and gives concrete examples of parameter combinations (chapter vs query, omitting both for TOC). It also clarifies mode-specific requirements like pattern requiring the pattern enum, and notes error behavior for unknown chapters.

  4

  Behavioral Transparency · 20%Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable context: it states the tool is snapshot-only and that packaging reads gulpfile.js/package scripts without executing gulp or npm, which is critical for setting expectations. It also mentions error behavior for unknown chapters. This goes beyond annotations without contradicting them.

  4

  Parameter Semantics · 15%Schema description coverage is 100%, so the schema already documents each parameter's purpose. The description adds cross-parameter semantics: it explains how chapter and query interact (chapter takes precedence, query used when chapter omitted, both omitted for TOC), and clarifies that pattern is required for mode=pattern. This adds meaning beyond individual parameter descriptions.

  5

  Conciseness & Structure · 10%The description is a single, dense paragraph that front-loads the core purpose and then efficiently covers usage nuances, examples, and exclusions. Every sentence adds value, with no filler or repetition of schema details. It is appropriately sized for the tool's complexity.

  5

  Contextual Completeness · 10%Given the tool's moderate complexity (5 params, 3 modes, enums), the description covers all essential aspects: mode selection, parameter interactions, language options, error behavior, and non-execution guarantee. The output schema exists, so return values need not be described. The description is complete for an agent to select and invoke correctly.

  params

  5 (1 required, 100% described)

  annotations

  readOnly=true destructive=false idempotent=true openWorld=false

  output schema

  yes

  cost

  1

  bytes

  1969

  hash

  754886704b95424e

• guide_cub

  554445A4.6

  This is an exemplary tool description. It clearly defines the tool's purpose, provides explicit usage guidelines with alternatives, and transparently discloses behavioral traits beyond the annotations. The parameter semantics are enriched with conditional logic, and the description is both concise and comprehensive, making it highly effective for an AI agent.

  5

  Purpose Clarity · 25%The description clearly states the tool's purpose: 'Document how Lampa talks to CUB from source' and emphasizes it is a read-only snapshot, distinguishing it from siblings like `list_catalog` and `guide_external_api`. It specifies the resource (CUB cloud APIs) and the action (guide/document), making it unambiguous.

  5

  Usage Guidelines · 20%The description explicitly states when to use this tool ('not a substitute for cub.rip/developer') and contrasts it with `list_catalog` topic=mirrors/socket, which is CUB-specific. It also provides detailed per-topic usage instructions, including which parameters apply to each topic and that irrelevant parameters are silently ignored, giving clear guidance on when and how to use it.

  4

  Behavioral Transparency · 20%Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable context: it makes no network calls, requires no auth, returns markdown text (never raw JSON), and silently ignores irrelevant parameters. This goes beyond the annotations, though it could mention the output schema's structure, but that is already provided.

  4

  Parameter Semantics · 15%Schema description coverage is 100%, so the schema already documents each parameter's purpose. The description adds significant value by explaining how parameters interact with topics (e.g., `endpoint` requires `path` and ignores `category`/`search`; `auth` reads `auth_focus` only). This clarifies conditional usage beyond the schema's static descriptions, earning a score above baseline.

  4

  Conciseness & Structure · 10%The description is a single dense paragraph, but it is front-loaded with the core purpose and then systematically covers each topic. It is efficient with no fluff, but the density might make it slightly harder to parse quickly. Still, every sentence earns its place, so it is appropriately concise.

  5

  Contextual Completeness · 10%Given the tool's complexity (7 parameters, 6 topics, conditional parameter usage), the description is remarkably complete. It explains the tool's scope, limitations, return type, and per-topic parameter behavior. The output schema exists, so return values are covered. The description fully compensates for the complexity, leaving no major gaps.

  params

  7 (1 required, 100% described)

  annotations

  readOnly=true destructive=false idempotent=true openWorld=false

  output schema

  yes

  cost

  1

  bytes

  2645

  hash

  8580f130911afa12

• guide_external_api

  554445A4.6

  This is an exemplary tool description. It clearly defines the tool's purpose, distinguishes it from siblings, provides explicit usage guidelines, and adds behavioral context (no secrets returned) beyond the annotations. The parameter semantics are well-covered by both schema and description, and the structure is concise yet complete. It scores high across all dimensions.

  5

  Purpose Clarity · 25%The description clearly states the tool documents real-world third-party APIs used by Lampa plugins, listing specific providers and the CORS-proxy pattern. It explicitly distinguishes itself from sibling tools `guide_cub` and `list_catalog`, making its purpose unambiguous.

  5

  Usage Guidelines · 20%The description provides explicit guidance on when to use this tool versus alternatives: it is curated from the lampa-plugins repository, not the Lampa app source, and contrasts with `guide_cub` (Lampa→CUB backend only) and `list_catalog` (Lampa's own API surface). It also explains the three topics and their parameter requirements, giving clear usage context.

  4

  Behavioral Transparency · 20%Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable context: it never returns secret values (API keys, tokens, passwords) and explains that it only provides provider identity, auth mechanism, and Lampa.Storage key names. This goes beyond annotations by clarifying the tool's non-sensitive output nature.

  4

  Parameter Semantics · 15%Schema description coverage is 100%, so the schema already documents all parameters. The description adds value by explaining the `topic` enum values in more detail (e.g., 'providers=list/search all providers') and clarifying that `provider` is required for `provider_detail` and ignored otherwise. It also notes that `proxy_pattern` takes no parameters, which is not explicitly in the schema.

  4

  Conciseness & Structure · 10%The description is dense but well-structured, with a clear first sentence stating the tool's scope, followed by a security note and topic-specific usage. It is slightly long but every sentence adds value, and the front-loading of the main purpose is effective.

  5

  Contextual Completeness · 10%Given the tool's complexity (multiple providers, three topics, security constraints) and the presence of a rich output schema, the description is complete. It covers the source of information, the distinction from siblings, the security boundary, and the parameter behavior for each topic. No significant gaps remain.

  params

  3 (1 required, 100% described)

  annotations

  readOnly=true destructive=false idempotent=true openWorld=false

  output schema

  yes

  cost

  1

  bytes

  2235

  hash

  95fb5da291823a93

• guide_plugin_catalog

  554455A4.7

  This is an exemplary tool description that clearly defines its purpose, distinguishes itself from siblings, and leverages annotations effectively. It is concise yet comprehensive, with no contradictions. The only minor gap is that it could elaborate on the content of each topic, but the schema already provides that detail, making this a top-tier description.

  5

  Purpose Clarity · 25%The description clearly states the tool documents how the lampa-plugins repository turns plugin source files into the live catalog, covering specific aspects like schema, obfuscation, routing, and publishing checklist. It explicitly distinguishes itself from sibling tools `validate_code` and `scaffold_plugin`, making its purpose unambiguous.

  5

  Usage Guidelines · 20%The description explicitly states when to use this tool (for packaging and distribution once the plugin works) and contrasts it with `validate_code` (lints code) and `scaffold_plugin` (emits boilerplate), providing clear alternatives. It also notes the tool is curated from the repo's scripts/ and functions/, not the Lampa app source, which helps set expectations.

  4

  Behavioral Transparency · 20%Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that each topic returns a fixed reference document, does not read the repo snapshot, and never writes files, which reinforces the read-only and idempotent nature beyond the annotations. It does not mention any potential side effects or limitations, but given the strong annotation coverage, this is sufficient.

  4

  Parameter Semantics · 15%The schema already provides 100% coverage with a detailed description for the `topic` parameter, including enum values and their meanings. The description adds context by explaining that each topic returns a fixed reference document, but it does not elaborate on the content of each topic beyond what the schema provides. Since the schema is comprehensive, the description adds marginal value, but the baseline is high.

  5

  Conciseness & Structure · 10%The description is two sentences long, front-loaded with the core purpose, and every sentence adds value. It efficiently covers the tool's scope, sources, and behavioral constraints without redundancy. The structure is clear and easy to parse.

  5

  Contextual Completeness · 10%Given the tool's complexity (covering multiple topics) and the presence of a rich output schema (not shown but indicated), the description is complete. It explains the tool's scope, sources, and limitations, and the schema covers the parameter details. The description does not need to explain return values because the output schema exists, and the tool's behavior is well-defined.

  params

  1 (1 required, 100% described)

  annotations

  readOnly=true destructive=false idempotent=true openWorld=false

  output schema

  yes

  cost

  1

  bytes

  1744

  hash

  eb5699985a303748

No deterministic findings: every hard gate and checklist item passes.

The badge shows the overall tier and score, and links here. The JSON is the same report the CLI's hosted mode prints.

[![TDQS](https://tdqs.dev/reports/qfx61dm6h0/badge.svg)](https://tdqs.dev/reports/qfx61dm6h0)

The same check from a terminal, a CI job or a script, with an API key from your account. Submitting spends one of the account's daily calls; reading the result spends nothing.

export TDQS_API_KEY=tdqs_...

# exit code 1 below B, so the command is the gate; uvx runs the same command from PyPI
npx mcp-tdqs score --file tools.json --hosted https://tdqs.dev --fail-under B

curl https://tdqs.dev/api/v1/reports \
  -H 'Authorization: Bearer tdqs_...' \
  -H 'Content-Type: application/json' \
  -d @tools.json

# poll the report it names until "status" is "completed"; this one is
curl https://tdqs.dev/api/v1/reports/qfx61dm6h0 \
  -H 'Authorization: Bearer tdqs_...'

import { requestHostedReport } from 'mcp-tdqs';

const report = await requestHostedReport({
  apiKey: 'tdqs_...',
  hostedUrl: 'https://tdqs.dev',
  serverName: 'lampa-mcp-server',
  tools, // the tools/list result
});

if (report.score === null || !['A', 'B'].includes(report.score.serverScore.overallTier)) {
  throw new Error(`TDQS ${report.score?.serverScore.overallTier ?? 'failed'}: ${report.url}`);
}

from tdqs import parse_tool_definitions, request_hosted_report

parsed = parse_tool_definitions(tools_list)  # the tools/list result
report = request_hosted_report(
    api_key="tdqs_...",
    hosted_url="https://tdqs.dev",
    server_name="lampa-mcp-server",
    tools=parsed.tools,
)
tier = report.score.server_score.overall_tier if report.score is not None else None

if tier not in ("A", "B"):
    raise SystemExit(f"TDQS {tier or 'failed'}: {report.url}")