burn-mcp-server
Server Quality Checklist
Latest release: v2.1.2
- Disambiguation3/5
Several tools have clear boundaries (e.g., move_flame_to_spark vs move_flame_to_ash), but get_bookmark and get_article_content are explicitly identical, and list_vault/search_vault plus list_sparks/search_sparks overlap heavily. The descriptions help, but the duplicate is a direct ambiguity.
Naming Consistency4/5Most tools follow a consistent verb_noun snake_case pattern (search_vault, list_sparks, create_collection). Minor deviations exist: 'get_collections' is actually a list operation, and 'fetch_content' uses a different verb than 'get_article_content', but these are small and do not undermine the overall consistency.
Tool Count2/5With 26 tools, the count exceeds the 25+ threshold for being too heavy. Many operations are repetitive (e.g., individual moves vs batch_triage) and could be consolidated, making the surface feel bloated for what is essentially a bookmark management domain.
Completeness2/5The lifecycle (Flame to Spark to Vault to Ash) is well covered, but there is no explicit 'create bookmark' tool since fetch_content only fetches and doesn't necessarily save. Additionally, there are no update or delete operations for bookmarks, and no way to remove a bookmark from the Vault or delete collections, leaving significant gaps.
Average 3.8/5 across 26 of 26 tools scored. Lowest: 3.2/5.
See the Tool Scores section below for per-tool breakdowns.
- 0 of 1 community issues answered or closed in the last 6 months
- 13 commits in the last 12 weeks
- Last stable release on
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
This repository includes a glama.json configuration file.
This server has been verified by its author.
Add related servers to improve discoverability.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the burden of behavioral disclosure. It uses 'burn' to imply a destructive or irreversible action, but it does not explicitly state whether the bookmark is permanently removed, whether the operation is reversible, or what side effects occur. The metaphor is vague and could mislead about the actual consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with a clarifying parenthetical, achieving maximum conciseness. It is front-loaded with the action and includes no extraneous words, making it efficient and straightforward.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the tool is simple with one parameter and no output schema, the description lacks essential context for a mutation operation. It does not explain what 'Ash' represents in the system, whether the action is reversible, or any prerequisites/consequences. The rationale 'not valuable enough to vault' offers partial context but is insufficient for a tool that likely changes bookmark state.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the only parameter (id as 'Bookmark UUID') with 100% coverage. The description adds no additional parameter semantics, such as required permissions or format expectations, so it does not exceed the baseline provided by the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Burn a Spark bookmark to Ash' with a parenthetical rationale. It identifies the specific resource (Spark bookmark) and destination (Ash), distinguishing it from moving to Vault. However, the verb 'burn' is metaphorical and relies on the tool name 'move' for full clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The parenthetical 'not valuable enough to vault' provides a contextual criterion for when to use this tool, implying it should be used when a Spark bookmark doesn't warrant being saved to Vault. However, it does not explicitly name alternative tools or state when not to use it, leaving room for ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It indicates a read-only 'List' operation but does not mention pagination behavior, default limit, ordering, or whether the result is a flat array. The default for limit is only in the schema, not in the description. Minimal behavioral context is provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence. It front-loads the action ('List'), specifies the resource ('bookmarks in your Vault'), and adds one optional modifier. There is zero filler or repetitive content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two optional parameters and no output schema, the description is minimally adequate. It states the purpose and filtering capability, and the schema covers parameter details. However, without output schema or annotations, there is no information about the return format, ordering, or pagination behavior, leaving some gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 no meaning beyond the schema: 'optionally filtered by category' is already in the category parameter's description. Neither parameter gains additional context from the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists bookmarks in the Vault, with an optional category filter. This distinguishes it from sibling tools like search_vault (search) and list_sparks (sparks). The verb 'List' is specific and the resource is well-defined.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like search_vault. It does not mention any exclusions, prerequisites, or scenarios where another tool would be more appropriate. The usage context is only implied by the tool's purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full disclosure burden. It offers only a metaphor ('Burn... to Ash') and a value judgment ('not worth keeping'), without stating whether the action is reversible, destructive, or what side effects occur (e.g., deletion of associated content, state changes, permissions required). This is insufficient for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately conveys the core action. It is front-loaded with the verb 'Burn' and the resource, with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool's simplicity, the description omits critical context about the Ash state—whether it is a permanent discard, a separate category, or recoverable. There is no output schema, and no annotations clarify behavior. The agent is left uncertain about the consequences of moving a bookmark to Ash, making the description incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with clear descriptions for both parameters ('Bookmark UUID' and 'Why this was burned'). The tool description adds no extra parameter meaning beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Burn') and clearly identifies the resource (Flame bookmark) and destination state (Ash). It distinguishes from sibling tools like move_flame_to_spark by indicating a discard action, and the parenthetical 'not worth keeping' clarifies the tool's intent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage is implied by 'not worth keeping,' suggesting the tool is for discarding bookmarks with low value. However, it does not explicitly contrast with alternative move operations (e.g., move_flame_to_spark) or provide clear conditions for when to use this tool versus others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does not disclose whether this is a destructive move (removing from Spark), what side effects occur, or any permissions required. The term 'promote' suggests non-destructive, but 'move' in the name implies otherwise, leaving ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no waste. Every word contributes to understanding the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is relatively simple, but without annotations or an output schema, the description should explain more. It omits what happens to the original Spark bookmark, whether the operation is reversible, and what the return value is. This leaves significant gaps for an agent to invoke it confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both 'id' and 'vault_category' having meaningful descriptions. The description adds no parameter details, but per rubric the baseline is 3 when schema covers all parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('promote'), the resource ('Spark bookmark'), and the destination ('permanent Vault storage'). It effectively distinguishes from sibling tools like move_spark_to_ash by specifying the target location.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended usage is implied by the action—promoting a bookmark to permanent storage—but there is no explicit guidance on when to use this over alternative move tools (e.g., move_spark_to_ash) or any exclusions. The context is clear but not elaborated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for safety disclosure. It states 'Remove' which implies mutation, but fails to mention whether removal is reversible, what happens if the collection becomes empty, permissions required, or response format. This is a significant gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded with the action and object, with no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations and output schema, and the mutation nature of the tool, the six-word description is insufficient. It doesn't disclose effects, error behavior, or return value, leaving the agent without critical context for a mutation operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters have descriptions ('Collection UUID', 'Bookmark UUIDs to remove'), so the schema carries the parameter semantics. The description adds nothing beyond that, earning the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Remove') and identifies the resource ('bookmarks') and container ('Collection'), clearly distinguishing this from sibling tools like add_to_collection and create_collection. It precisely states the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance or exclusions are provided; the tool's purpose implies usage but does not explicitly state alternatives or conditions, so it performs at the 'implied usage' level.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description carries full responsibility. It describes a mutation ('Create') without disclosing side effects, naming constraints, authorization needs, or what happens with duplicate names. The description provides only the basic action and purpose, lacking behavioral depth beyond what is obvious from the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence: 'Create a new Collection to group related bookmarks together.' Every word contributes to the core purpose, making it appropriately sized and front-loaded with the action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, but the description leaves gaps: it does not mention the optional bookmark_ids parameter (though the schema does), nor does it clarify the return value or creation behavior with duplicate names. For a create operation, this is adequate but not fully complete; the description could have briefly noted optional initial bookmarks or what happens on server response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: the 'name' parameter is described as 'Collection name' and 'bookmark_ids' as 'Initial bookmark UUIDs to include'. The description does not add extra meaning beyond the schema, but it aligns with the purpose. Since the schema handles parameter semantics fully, a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create'), the resource ('a new Collection'), and the purpose ('to group related bookmarks together'). It distinctly differentiates from sibling tools like get_collections (listing) and add_to_collection (modifying existing collections) by explicitly using 'new'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a new collection is needed, but it does not explicitly state when to use this tool versus alternatives such as add_to_collection for adding to an existing collection. There is no mention of exclusions or alternative tool names, leaving the guidance implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full burden. The verb 'Write' implies mutation, but the description does not disclose whether it overwrites an existing overview, requires specific permissions, or triggers any AI generation process. It only describes the content structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with the action, includes key components in a compact parenthetical. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is somewhat minimal. It does not mention prerequisites (e.g., collection must exist), overwrite behavior, or how errors are reported. However, the schema covers parameter details, so basic usage is clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides full descriptions for both parameters and nested properties (100% coverage). The description's parenthetical list echoes these fields without adding additional semantic detail, so it stays at baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Write' and clarifies the object is an AI-generated overview for a Collection, listing components (theme, synthesis, patterns, gaps). This clearly distinguishes it from read-only tools like get_collection_overview.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the use case of writing an overview but does not explicitly state when to use this tool versus alternatives such as get_collection_overview or create_collection. It provides no exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the core behavior (new posts auto-appear on scrape) but omits details like duplicate handling, validation errors, permission requirements, or reversibility. The description provides baseline transparency but lacks depth for a mutation-style tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the purpose and includes a meaningful behavioral outcome. Every word contributes value with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is relatively simple (3 params, no nested objects, no output schema) and the description covers the essential purpose and effect. It doesn't explain what happens on duplicate adds or the return value, but the schema and sibling tool names (list_watched_sources, remove_watched_source) fill in much of the surrounding context. Overall it is adequately complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already fully documents each parameter with type and examples. The description restates the source types (X, RSS, YouTube) but adds no new meaning beyond the schema. Per the rubric, the baseline is 3 when schema coverage is high, and the description does not go beyond it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'Watch' to indicate adding a source, and specifies the resource types (X user, RSS feed, YouTube channel). It clearly conveys the action and scope, though it doesn't explicitly use the word 'add' or contrast with sibling tools like list_watched_sources or remove_watched_source. The effect ('new posts auto-appear in Burn Flame') adds helpful context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The behavior description ('new posts auto-appear in Burn Flame on each scrape') implies this tool is used to set up ongoing monitoring, which gives some usage context. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions or prerequisites. Guidance is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the core effect (each decision moves a bookmark to Spark or Ash) but does not address error handling, partial-failure behavior, atomicity, reversibility, or any side effects. For a batch mutation tool, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exactly two short sentences, front-loaded with the verb and resource. The second sentence clarifies the effect without redundancy. No unnecessary details or filler, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite high schema coverage, the tool has no annotations and no output schema. The description leaves unanswered questions such as whether the batch operation is atomic, what happens if a bookmark ID is invalid, whether partial successes occur, and what the return value is. These gaps are significant for a batch mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter (including the nested objects) having clear descriptions. The description's line about moving to Spark or Ash redundantly restates the action enum but adds no new semantic meaning beyond the schema. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'triage' and clearly identifies the resource ('multiple Flame bookmarks') and the outcome ('moves a bookmark to Spark or Ash'). The phrase 'at once' distinguishes this batch tool from the single-move sibling tools (move_flame_to_spark, move_flame_to_ash), making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for batch triage via 'multiple Flame bookmarks at once', providing clear context for when to use this tool. However, it does not explicitly mention alternatives or exclusions (e.g., for a single bookmark, use the individual move tools), so it stops short of a full when/when-not comparison.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It adds useful context about the 30-day lifespan and that results include insight and expiry date, but it does not clarify whether expired Sparks are included or how the limit parameter affects results. These gaps make it adequate but not richly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loaded with the primary action and a parenthetical definition. No filler or redundant wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one optional parameter and no output schema, the description covers the essential semantics: what a Spark is, what the list contains, and a key field. However, it omits mention of the limit parameter's behavior and possible inclusion of expired items, so it is not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents the single 'limit' parameter with its default (20), achieving 100% schema description coverage. The description does not repeat or expand on this, so it adds no parameter-level meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('your Sparks'), and clarifies what Sparks are ('bookmarks you have read, with 30-day lifespan'), distinguishing them from sibling tools like list_vault. It clearly conveys the tool's scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus search_sparks or list_vault, nor are there any exclusions or alternative suggestions. The description only states what the tool does, not when it is preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description carries the burden. It discloses the proxy bypass for X.com and the cache-first fetching order, but does not mention auth, rate limits, error handling, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with purpose, and every sentence adds value—supported sites, proxy/cache behavior, and the fetch action. No padding or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a single parameter and no output schema, so the description covers core behavior but omits return formats, failure modes, or prerequisites. For a fetch tool with broad support, more detail on output and errors would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'url' is already fully described in the schema ('The URL to fetch content from'), and the description adds no additional syntax or format details. With 100% schema coverage, the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Fetch article/tweet content from a URL') and specifies supported platforms (X.com, Reddit, YouTube, etc.), distinguishing it from sibling tools by mentioning the proxy bypass and Supabase cache behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for fetching content from listed platforms and any web page, but does not explicitly mention when to use this tool over alternatives like get_article_content or scrape_watched_sources. No exclusion criteria are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states what the tool fetches, without mentioning side-effect-free behavior, error conditions, permissions, or return format details. This is a significant gap for a tool with no annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the key information: what is retrieved and what is included. No redundant or extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one parameter), but there is no output schema, so the description is responsible for explaining return values. It names the components (AI overview, linked bookmarks metadata) but not their structure or behavior (e.g., not found cases). This is adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents the single 'name' parameter with a clear description. The tool description adds minimal extra meaning beyond restating 'by name', so the baseline of 3 applies because schema coverage is 100%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' and clearly identifies the resource (a Collection by name) and the return payload (AI overview and linked bookmarks metadata). This distinguishes it from sibling tools like get_collections, which likely lists collections.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a clear use case: retrieve a single collection's overview and linked bookmarks by name. It does not explicitly mention when not to use it or name alternatives, but the context is sufficient for an agent to infer appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description holds the full burden of disclosure. It does reveal an important behavioral trait: duplicates are silently ignored. Yet it omits other potentially relevant behaviors like handling of invalid IDs, permission requirements, or return values, leaving gaps in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that immediately conveys the core action and a key behavioral detail. It is appropriately sized with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple add operation, the description covers the essential purpose and a notable behavior (duplicate handling). The schema covers parameter semantics, and no output schema is expected. However, it could mention side effects or error conditions for edge cases like non-existent collection IDs, so it is not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters clearly described in the schema. The description does not add extra meaning beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Add') and resource ('bookmarks to an existing Collection'), clearly distinguishing it from sibling tools like create_collection and remove_from_collection. The inclusion of 'existing' clarifies it operates on pre-created collections.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for adding bookmarks to a collection that already exists, which provides some usage context. However, it does not explicitly state when to prefer this over alternatives or mention exclusion criteria, such as not using it for creating collections.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. 'Get' implies a read-only operation, and the expected output is disclosed. However, it does not explicitly state that the operation is safe/non-destructive, nor mention any prerequisites or limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the core purpose and adds a useful relationship note. Every word earns its place, and there is no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description covers the essential return content and how to identify the target. It lacks detailed caveats like error handling or authentication, but those are not critical for a straightforward get-by-ID tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully describes the `id` parameter as 'Bookmark UUID' (100% coverage). The description adds that the ID corresponds to a bookmark and the tool returns article content and analysis, but this is expected and does not significantly enhance the schema's meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Get full article content and AI analysis') and identifies the resource ('a bookmark by ID'). The parenthetical 'same as get_bookmark' further clarifies its relationship to a sibling tool, removing ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is an alias for get_bookmark, offering some context, but it does not explicitly specify when to use this tool versus alternatives or mention any exclusions. There is no guidance on choosing between this and fetch_content or other retrieval tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It implies a read-only operation via 'List' but does not disclose potential behaviors like sorting, pagination, or whether categories are user-specific or global. It adds little beyond the obvious, but for a simple listing tool, this is minimally adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that conveys the action and key output detail. It is concise, well-structured, and free of unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no output schema, no annotations), the description is mostly complete. It states what is listed and that counts are included. Some ambiguity remains about the return structure, but the low complexity makes this sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema is trivially covered. The baseline for 0 params is 4, and no additional parameter information is needed in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and a precise resource ('Vault categories'), and adds the detail 'with article counts' which clarifies the output. It clearly distinguishes itself from sibling tools like list_vault or list_sparks by focusing on categories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives such as list_vault or search_vault. The description simply states what the tool does, without mentioning any preferred context, exclusions, or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It adds useful context by disclosing that the search covers title, tags, and AI takeaway. However, it does not disclose return format, pagination behavior, or explicitly confirm that the operation is read-only and has no side effects, which would be expected for a search tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It presents the core action and scope immediately, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search tool, the description and schema together provide adequate context. The description clearly defines the search target and fields, while the schema covers the parameters. However, because there is no output schema, the description could be slightly more complete by mentioning what the tool returns (e.g., a list of matching bookmarks), but this is a minor omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for both parameters (query and limit), so the schema already explains them. The description adds marginal value by indicating what fields the keyword searches, but it does not provide additional syntax or format details beyond the schema, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Search') on a specific resource ('your Burn Vault for bookmarks') with clear scope ('by keyword (searches title, tags, AI takeaway)'). It distinguishes itself from sibling tools like search_sparks by explicitly targeting bookmarks in the Burn Vault.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for searching bookmarks by keyword, which is clear, but it does not explicitly state when to use this tool versus alternatives like search_sparks or list_vault, nor does it mention exclusions or contexts. No usage guidance beyond the core purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does disclose that the response includes AI analysis and extracted content, which is valuable and goes beyond the name. However, it does not mention safety characteristics (read-only), error behavior, or requirements beyond the ID, leaving some uncertainty for a read operation without annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the purpose and includes key details without any wasted words. It is appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema, no annotations), the description covers the essential purpose and the notable contents of the response. It could mention error cases or authentication, but for a straightforward get-by-ID tool, this is largely sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents the single parameter 'id' with 100% coverage ('Bookmark UUID'). The description adds no additional parameter semantics, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get'), the resource ('a single bookmark'), and the scope ('full details including AI analysis and extracted content'). It distinguishes from sibling list/search tools by emphasizing 'single' and the specific contents of the response.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that this tool is for retrieving full details of one specific bookmark, implying when to use it (when you have a bookmark ID). However, it does not explicitly name alternatives or state when not to use it, such as for listing bookmarks (list_vault) or searching (search_vault).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It describes the returned content (full details, article content, AI analysis, reading guidance), but does not explicitly state whether the operation is read-only, requires authentication, or has any side effects. This leaves some behavioral ambiguity for a tool with no annotation safety hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, with the primary purpose front-loaded and usage guidance following. Every word contributes value, and there is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description summarizes the response contents reasonably well by listing key components (article content, AI analysis, reading guidance). However, 'full details' could be more specific about metadata fields, but for a complex tool the description provides adequate contextual completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage for the single parameter 'id' with a description ('Bookmark UUID'), so the description adds no additional parameter semantics. The baseline score of 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('Get') and resource ('Flame bookmark'), and explicitly lists the included content types (extracted article content, AI analysis, reading guidance). This differentiates it from sibling tools like get_bookmark or get_article_content, which likely focus on narrower aspects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear usage context: 'deep-read a bookmark before deciding its fate.' This implies when to use the tool, but it does not explicitly state when not to use it or mention alternative tools, so it lacks full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the 30-day Spark lifespan, which is a useful behavioral detail. However, with no annotations, it omits other side effects such as whether the bookmark is removed from Flame, idempotency, or return behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action, no filler. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple state-transition tool with two well-documented params, the description covers the core behavior and a key side-effect. However, it doesn't describe return values or error conditions, which might be expected for a mutation with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are fully documented in the schema (100% coverage). The description's phrase 'mark as worth reading' provides context for spark_insight but doesn't add new semantic details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool moves a Flame bookmark to Spark, with the purpose 'mark as worth reading'. This differentiates it from siblings like move_flame_to_ash by specifying the target state and intent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It describes exactly when to use (when a bookmark is worth reading) but does not explicitly mention alternatives or exclusions. The sibling name move_flame_to_ash implies the alternative, but the description itself doesn't provide that comparison.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosure. It states the core behavior (fetch and add new items) and implies idempotency via 'new content', but it does not disclose potential side effects such as duplicates, failure behavior, or prerequisites like pre-configured watched sources. This is acceptable but not highly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two succinct sentences clearly convey purpose and usage without extraneous information. Every word adds value, and the structure is front-loaded with the key action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple parameter set and lack of output schema, the description covers the essential purpose and usage well. It could benefit from a note on expected return values or behavior when no new content exists, but these are not critical for a basic scraping tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameter semantics are fully documented. The description reinforces the parameter's meaning but adds no extra detail beyond the schema. The baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: fetching new content from watched sources and adding it to Burn Flame. It specifies the resource (watched sources) and the action (fetch and add), and distinguishes itself from siblings like fetch_content or list_watched_sources by describing the scraping behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly recommends calling on a schedule or on demand, providing clear context for usage. It does not explicitly discuss alternatives or exclusions, but given the uniqueness of this tool among siblings, the guidance is sufficient for most cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of disclosing behavior. It does reveal which fields are searched, which is useful. However, it does not mention return format, sorting, pagination, or read-only nature, leaving the agent without a full picture of what to expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys all essential information without redundancy. It earns its place and is optimally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search tool, the description is adequately complete: it explains the search scope and fields. Since there is no output schema, it would be improved by mentioning what is returned, but the context of sibling tools and the nature of search make this a minor gap. It is complete enough for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for both parameters (query and limit). The description adds the field list (title, tags, etc.), which is not in the schema, but it does not significantly enhance understanding of the parameters themselves. Baseline 3 is appropriate given the comprehensive schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: searching Sparks by keyword, explicitly listing the searched fields (title, tags, AI takeaway, spark insight). This distinguishes it from sibling tools like search_vault and list_sparks, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that this tool is for searching within Sparks, as opposed to listing all Sparks (list_sparks) or searching the vault (search_vault). However, it does not explicitly state when not to use it or name alternative tools, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must convey safety and behavior. 'List' implies a read operation, and 'all active' adds the behavioral constraint that inactive sources are excluded. However, it provides no details on return format, ordering, or pagination, leaving some gaps for a list tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that immediately states the action and scope. Every word adds value, no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple zero-parameter list operation, the description is sufficiently complete: it identifies the resource (watched sources), the filter (active), and the types included. An output schema is absent, but for a basic list tool, this level of detail is adequate—though it could benefit from mentioning whether the returned items are just names or include metadata.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4 as per guidelines. The description is not required to explain parameters, and the schema confirms no parameters exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('all active watched sources'), and explicitly enumerates the source types (X users, RSS feeds, YouTube channels). This clearly distinguishes it from sibling tools like add_watched_source or scrape_watched_sources, which perform different actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates the tool is for listing all active watched sources, which is the primary use case. It does not explicitly state when not to use it or mention alternatives, but the operation is unambiguous and siblings are distinct actions, so context is clear without exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the action and directs the user to find the ID, but does not disclose side effects, reversibility, or any operational caveats. For a simple removal tool this is adequate but not rich in behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with the primary action front-loaded. Every word adds value—the first sentence states the purpose, the second provides a necessary prerequisite—without any redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with a single parameter and no output schema, the description sufficiently covers the action and how to obtain the required input. It does not describe the return value or postconditions, but these are less critical for a simple removal operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides a description for the single parameter 'id', achieving 100% coverage. The description adds value by specifying that the ID comes from list_watched_sources, clarifying the expected source and format beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Stop watching a source' uses a specific verb and resource, clearly indicating the action. It distinguishes itself from sibling tools like add_watched_source and list_watched_sources by focusing on removal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The instruction to 'Use list_watched_sources to find the source ID' provides a clear prerequisite for usage. It implies this tool is for stopping watch operations, but does not explicitly mention when not to use it or alternatives beyond finding the ID, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior, and it does add a key behavior: merge semantics, preserving existing data. It also clarifies that the agent performs the analysis (not the tool). However, it doesn't mention potential side effects, permissions, or error conditions, so the behavioral transparency is moderate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, efficiently front-loaded with the primary purpose. It avoids repeating schema details and earns its place by adding the merge behavior and agent workflow context. There is no unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (nested object with multiple optional fields) and the absence of an output schema, the description provides sufficient context: it clarifies the write intent, the merge behavior, and the agent's role. It could mention validation or return behavior, but for a write tool, the current description is largely adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides detailed descriptions for both parameters and all nested fields (100% coverage). The description adds value by explaining the merge semantics, which clarifies that only provided fields in the 'analysis' object are written, and existing fields are retained. This goes beyond the schema's per-field descriptions and is critical for correct usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb and resource: 'Write AI analysis results into a bookmark.' It further distinguishes itself by explaining the agent workflow ('Agent analyzes content with its own LLM, then writes structured results back to Burn'), which is unique among the sibling tools and clarifies the tool's role in the system.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: after the agent has analyzed content, it writes the results back. It also gives an important usage guideline: 'Only provided fields are merged — existing data is preserved,' indicating partial updates. While it doesn't explicitly name alternatives, the sibling list shows this is the only write-analysis tool, so the usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses what the output includes (article counts, AI overview themes) but does not explicitly state side effects, authentication, or scope limitations (e.g., read-only). For a list tool, the mutability is implied as low, but the description could be more explicit about any filters or pagination.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single, well-formed sentence that leads with the action and includes the key output aspects. No wasted words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter list tool without an output schema, the description is fully complete. It states what the tool returns (all collections with counts and themes) and is sufficient 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.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so schema coverage is 100% by definition. The description adds no parameter details but is not required to; the baseline of 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('all your Collections') with concrete output details ('article counts and AI overview themes'). It clearly distinguishes from siblings like get_collection_overview by indicating the scope is all collections rather than a single one.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates this tool is for listing all collections, providing clear context for when to use it. It does not explicitly mention alternatives or exclusions, but the scope 'all your Collections' implies the primary use case and differentiates it from collection-specific tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of disclosure. It discloses key behavioral traits: the 24-hour countdown, the AI triage fields (strategy, relevance, novelty, hook), and time remaining. It doesn't explicitly state read-only, but the action 'list' is inherently non-mutating and the added detail goes beyond the minimum.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero fluff. The main action and key context are front-loaded, and every part adds meaningful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers what the tool does, what information it shows, and when to use it. It also explains the output contents (triage info and time remaining), which compensates for the lack of an output schema. For a simple list tool with one optional parameter, it is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%—the only parameter (limit) is fully described in the schema with default value. The description adds no extra parameter detail, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' with a defined resource ('bookmarks in your Flame inbox'), and clearly distinguishes this from siblings like list_vault or list_sparks by highlighting the 24h countdown and AI triage info.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a clear use case: 'Use this to see what needs attention before it burns to Ash.' While it doesn't name alternatives explicitly, the context of the Flame inbox and the urgency implied by the countdown gives strong situational guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Fisher521/burn-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server