Server Quality Checklist

Tool Scores

• intakeA
  4.4/5.0
  Behavior5/5

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

  With no annotations provided, the description carries the full burden and excels. It discloses critical behaviors: never deletes records (sourceGone instead), treats failed source reads as non-confirmatory, advises checking sourceStatus in the response, and warns about lazy expiry/drip housekeeping side effects. This goes far beyond a basic summary and gives the agent a clear picture of consequences and edge cases.

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

  Conciseness5/5

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

  The description is front-loaded with the core purpose in the first sentence, then methodically explains behavior and caveats. Every sentence conveys useful information—there is no fluff or repetition. Despite its length, it remains tightly structured and easy to parse.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given there is no output schema, the description does a solid job of indicating response expectations by mentioning sourceStatus and explaining sourceGone behavior. It also flags the housekeeping side effect for context. However, it does not fully enumerate the response structure or all return values, so it leaves some room for improvement, especially for a tool with this level of complexity.

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

  Parameters3/5

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

  The input schema has one optional 'source' parameter with a thorough description covering browser names and source IDs, totaling 100% schema coverage. The tool description adds no additional parameter semantics beyond the schema, so the baseline of 3 is appropriate—the schema already does the heavy lifting.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states a specific action: 'Scan browser bookmarks (via bookmarks-mcp) and merge them into the lifecycle.' It identifies the resource (browser bookmarks) and the process (new URLs to inbox, existing ones reconciled). While it doesn't explicitly name siblings, the function is unique and unambiguously distinct from list_layer, today, decide, stats, restore, and undo.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description implies usage: it's for pulling in newly saved bookmarks and syncing them into the lifecycle. It provides clear context about when the tool is appropriate (when there are new bookmark URLs to merge) and what to expect. However, it does not explicitly state 'use this when X' or 'don't use this when Y', nor does it name alternative tools, so it stops short of the highest mark.

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

• restoreA
  4.4/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries full burden. It opens with 'MUTATING TOOL' and discloses a subtle side effect: 'This call may first persist lazy expiry/drip housekeeping (see README) even if you only meant to read.' It also notes the clock reset, which is behavioral. It could be more comprehensive, but the disclosed side effects are significant and well-stated.

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

  Conciseness5/5

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

  The description is three sentences, front-loaded with 'MUTATING TOOL'. Each sentence serves a distinct purpose: state the action, specify applicable conditions and alternative, and disclose side effects. No wasted words.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the tool's mutation side effects and conditional applicability, the description covers the key operational context: what it does, when it works, alternative for other states, and a warning about housekeeping writes. It doesn't mention return values, but no output schema exists, so that's not required. It could mention the `undo` capability as a safety net, but overall it is well-rounded.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the baseline is 3. The tool description does not add additional parameter semantics beyond the schema; the schema already explains `ids` (from today/list_layer output, max 25) and `actorClaim` (attribution claim, not proof of consent). The description's mention of 'resetting their 24-hour clock' indirectly supports `ids`, but no extra value beyond the schema.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states 'Move one or more `lapsed` items back to `pending`, resetting their 24-hour clock', which is a specific verb+resource+scope. It also distinguishes from sibling `undo` by specifying that it only works on `lapsed` items, not `kept`/`watching` items.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description provides explicit when-to-use: 'Only works on items currently `lapsed`'. It also gives an explicit alternative: 'for `kept`/`watching` items that need reverting, use `undo` instead'. This fully covers usage guidance.

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

• statsA
  4.4/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries full responsibility. It explicitly discloses a non-obvious side effect: the call may persist lazy housekeeping ('may first persist lazy expiry/drip housekeeping') even for a read. It also clarifies the timezone basis ('local calendar day on the machine running this server'), adding meaningful behavioral context.

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

  Conciseness5/5

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

  The description is concise, consisting of two sentences. The first sentence front-loads the core counting purpose, while the second adds a crucial behavioral caveat. Every phrase adds value, and the README references are appropriate for follow-up details.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a tool with no parameters and no output schema, the description covers the essential aspects: the data reported (counts per layer, inbox pending), the time window, and the potential write side-effect. It does not detail the return format, but that is not critical given the simple question-and-answer nature of the tool.

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

  Parameters4/5

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

  The tool has zero parameters, so the schema contains no parameter information. The description does not discuss parameters (none exist), but per the rubric, a 0-parameter tool gets a baseline of 4. The description adds no parameter details because there are none to add.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description uses a specific verb ('Counts') and clearly identifies the resource ('per layer', 'inbox'). It explains what is counted (decisions landed today) and the time window ('local calendar day'), which distinguishes it from sibling tools that likely provide individual records or different views.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description gives clear context for when to use this tool: to obtain daily lifecycle counts and pending inbox volume. It does not explicitly state alternatives or exclusions, but the scoped purpose ('per layer', 'today') implies the intended usage without ambiguity.

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

• list_layerA
  4.6/5.0
  Behavior5/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 discloses several important behaviors: the potentially large response size (megabytes), the meaning of sourceGone:true (record never deleted), and the side effect that the call may persist lazy expiry/drip housekeeping even on a read. This is strong 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/5

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

  The description is three sentences, front-loaded with the core purpose. Each sentence adds essential context: purpose, pagination behavior, sourceGone semantics, and side-effect warning. No waste.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a tool with no annotations and no output schema, the description covers most important operational details: purpose, pagination limits, a field semantic, and a side effect. It lacks an explicit description of the response shape, but that is not critical for a listing tool.

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

  Parameters4/5

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

  Schema description coverage is 0%, so the description must compensate. It explains the limit parameter's default and advises against raising it unnecessarily, and it mentions the lapsed layer value. However, it does not explain the offset parameter or enumerate all layer values beyond lapsed, leaving some work to the schema.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool lists the contents of a layer ('See what's in one layer'), explicitly including the 'lapsed' layer to answer 'what did I let go of'. This distinguishes it from sibling tools like stats or undo, which are clearly different operations.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Provides clear context on when to use it (to inspect any layer) and cautions about pagination: 'default limit 50, raise it only if you actually need more in one call.' It also warns about the large unpaginated JSON and the housekeeping side effect, but does not explicitly name alternative tools or state when not to use it.

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

• todayA
  4.7/5.0
  Behavior5/5

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

  With no annotations provided, the description carries full disclosure. It candidly warns that the call 'may first persist lazy expiry/drip housekeeping even if you only meant to read,' revealing potential write side effects. It also clarifies the meaning of remainingMs and hasEverIntaken, adding valuable behavioral context.

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

  Conciseness5/5

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

  The description is concise and front-loaded with the core purpose. Every sentence adds distinct value: definition, item semantics, caveat, usage context, and side-effect warning. No redundant or filler content.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a tool with no parameters and no annotations, the description is remarkably complete. It covers meaning of results, behavior on empty lists, prerequisite actions, and potential side effects. The reference to daily_triage and README provides additional context without overburdening the description.

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

  Parameters4/5

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

  The tool has zero parameters, so there are no parameter semantics to describe; the baseline of 4 applies. However, the description enhances understanding by explaining the meaning of the returned fields (remainingMs, hasEverIntaken), which is helpful given the lack of an output schema.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  Clearly states the tool's function: 'The 24-hour layer, oldest first — the actual to-do list.' This differentiates it from siblings by specifying the layer type and ordering. Also highlights its role as 'where daily_triage starts,' making its purpose and position among related tools 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/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Provides explicit guidance on when to use this tool versus alternatives: 'This is where daily_triage starts' and 'call intake first' when hasEverIntaken is false. While it doesn't explicitly say 'don't use list_layer,' the contextual cues are strong enough to guide correct selection.

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

• undoA
  4.7/5.0
  Behavior5/5

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

  With no annotations provided, the description carries the full burden and succeeds: it flags mutating behavior, reveals that undo appends a new history entry rather than erasing, and discloses the side-effect that lazy expiry/drip housekeeping may persist even for read-like calls. This is strong, honest behavioral disclosure.

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

  Conciseness4/5

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

  The description is a single, front-loaded paragraph that opens with the key purpose and mutating nature. Each sentence adds a distinct detail (constraints, selection methods, preview, history behavior, side effects), and there is no filler, though it is somewhat dense.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a complex tool with 5 parameters, no output schema, and nested filter objects, the description covers the essential return signal (`not-latest-event`), side effects, and usage patterns. It does not spell out all possible response fields, but the provided detail is enough to use the tool safely and effectively.

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

  Parameters4/5

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

  Schema coverage is 80%, so baseline is 3, but the description adds meaning beyond the schema by explaining how `eventIds` come from any tool's `history[].eventId` and how `filter` selects events across items via source/time/attribution. It also contextualizes `preview` as a way to see changes first. Only the `note` parameter receives no added explanation, but the schema covers the main semantics.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description opens with 'MUTATING TOOL. Revert an item to whatever it was immediately before one of ITS OWN history events', a clear and specific verb+resource statement. It distinguishes itself from the sibling tool `restore` by noting undo works for `kept` and `watching` as well as `lapsed`, which clarifies scope.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description explicitly states when undo is appropriate, the constraint that only the latest event can be undone, and alternatives like using `filter` for batch operations or `preview` to dry-run. It also references `restore` as the alternate tool for lapsed-state reverts, giving clear when-to-use vs. when-not-to-use guidance.

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

• decideA
  4.9/5.0
  Behavior5/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 openly declares itself a mutating tool, requires explicit consent, warns of potential housekeeping writes even on read intent, and explains that `drop` never deletes bookmarks or lifecycle records and is fully undoable. It also discloses the `actorClaim` caveat (not proof of consent, cannot be verified, `ai` rejected unless env var set).

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

  Conciseness5/5

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

  The description is dense yet highly efficient. It opens with a bold 'MUTATING TOOL' warning and packs consent requirements, state transitions, side effects, error behavior, and attribution caveats into five purposeful sentences. No filler; every clause contributes critical information.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a complex mutation tool with no annotations and no output schema, the description covers prerequisites, allowed transitions, error responses, reversal path via `undo`, housekeeping side effects, and consent/attribution limitations. It even points to the README for deeper details, making it fully actionable for an agent.

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

  Parameters4/5

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

  The input schema has 100% description coverage, so the baseline is high. The description adds behavioral nuance beyond the schema: it clarifies the side effects of `drop`, the 30-day window for `watch`, and the consent limitations of `actorClaim`. While it doesn't restate each parameter, it enriches understanding of how those values operate in context.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's function: it moves items to `kept`, `watching`, or `lapsed` states, and the title specifies 'pending/watching items'. It distinguishes from siblings by defining the state machine explicitly and referencing `undo` as the reversal tool, 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 Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description gives explicit when-to-use and when-not-to-use guidance: it must only be called after explicit user confirmation of exact item IDs and action, unless trusted autonomous-approval mode is enabled. It also specifies state-dependent rules (from `pending` all actions allowed, from `watching` only `keep`) and directs readers to `undo` for reversing decisions, clearly separating this tool from alternatives.

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