Server Quality Checklist

Tool Scores

• shared_margin_captureC
  2.3/5.0
  Behavior2/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 fails to mention any side effects, authorization needs, idempotency, or what happens to existing data. The poetic description adds no behavioral context beyond the action of saving.

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

  Conciseness3/5

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

  The description is a single sentence, making it concise, but it is vague and poetic rather than informative. It is front-loaded but at the cost of clarity, wasting the opportunity to provide useful guidance.

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

  Completeness1/5

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

  For a tool with 9 parameters, no annotations, and no output schema, the description is severely lacking. It does not explain the tool's role in the shared margin workflow, how it relates to sibling tools, or what the output looks like. The agent cannot fully understand its purpose from this description alone.

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

  Parameters2/5

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

  Schema description coverage is 44%, and the tool description does not add any parameter explanations. The description does not clarify what 'anchor', 'excerpt', or 'question' mean in the context of shared margins, nor does it help the agent understand how to populate these fields.

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

  Purpose3/5

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

  The description uses poetic language ('anchored moment', 'paused, noticed, responded, or kept wondering') that hints at capturing an interaction, but it does not clearly state that this tool creates a margin note or annotation. It vaguely implies a save operation but lacks specificity about the resource being created.

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

  Usage Guidelines2/5

  Does 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 its siblings (shared_margin_begin, export, finish, trail). The description does not specify any context, prerequisites, or alternatives, leaving the agent to guess the appropriate tool.

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

• shared_margin_exportC
  2.7/5.0
  Behavior2/5

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

  No annotations provided. Description does not disclose side effects (e.g., read-only vs destructive), permissions, or output behavior. The Markdown output is mentioned but not elaborated (e.g., structure, location).

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

  Conciseness3/5

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

  Single sentence, no unnecessary words, but it is too brief; important details are missing. Conciseness is good but at the expense of completeness.

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

  Completeness2/5

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

  Given no output schema and no annotations, the description should provide more context. It does not explain the output format beyond 'readable Markdown', nor does it specify behavior for missing sessions. Incomplete for a tool with 2 parameters.

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

  Parameters1/5

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

  Schema description coverage is 0%, and the description adds no meaning to parameters. 'sessionId' and 'outputDir' are not explained; the agent does not know they refer to a session identifier and optional output path.

  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?

  Description clearly states the tool exports one session as readable Markdown for sharing or archiving. The verb 'Export' and resource 'session' are specific, and the format and purpose are explicit. It distinguishes from sibling tools (begin, capture, finish, trail) which manage session lifecycle.

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

  Usage Guidelines2/5

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

  No guidance on when to use this tool versus other margin tools. Description does not mention prerequisites (e.g., session must exist) or exclusions. The agent must infer usage context.

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

• shared_margin_beginC
  2.9/5.0
  Behavior2/5

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

  No annotations provided, so description bears full burden. Only states action with no disclosure of side effects, response format, or prerequisites. Fails to explain what 'start' entails (e.g., creation of session record).

  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?

  Single sentence, front-loaded with purpose, no extraneous information. Efficient for agent parsing.

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

  Completeness2/5

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

  No output schema, but description does not explain return value or session behavior. Lacks integration context with sibling tools, leaving agent unsure about workflow steps.

  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 67% (2 of 3 parameters described). Description adds no parameter info beyond schema. Missing description for 'mediaType' is not compensated, but schema enum values partially clarify it.

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

  Purpose4/5

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

  Description uses specific verb 'Start' and resource 'durable co-reading, co-viewing, or mixed shared-attention session', clearly indicating the tool's function. Differentiates from siblings like shared_margin_capture and shared_margin_finish by being the initiation step, but does not explicitly highlight the distinction.

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

  Usage Guidelines2/5

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

  No guidance on when to use this tool versus alternatives. Does not provide context for session lifecycle or when to invoke sibling tools like shared_margin_capture.

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

• shared_margin_trailC
  2.9/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, so the read-only trait is covered. The description mentions listing and reading, which is consistent. However, it omits details like ordering, pagination, or what 'recent' means. No contradiction.

  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?

  Single sentence covering both modes without wasted words. Could be improved by clarifying the conditional behavior, but it is efficiently structured.

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

  Completeness2/5

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

  With no output schema and a dual-mode tool, the description is insufficient. It should explain what data is returned, ordering, and the significance of limit. The current description leaves many usage questions unanswered.

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

  Parameters2/5

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

  Schema description coverage is 0%, so the description should explain parameter roles. It does not map sessionId and limit to the listed operations. The names are somewhat indicative, but the description adds no additional meaning beyond the schema.

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

  Purpose4/5

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

  The description clearly states two distinct operations: listing sessions and reading moments from one session. However, it does not explain that the mode is determined by the presence of sessionId, leaving slight ambiguity. The verb-resource pairing is specific.

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

  Usage Guidelines2/5

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

  No guidance on when to use this tool versus siblings (begin, capture, export, finish). The read-only nature is implied but not compared with other tools. No explicit when-not or alternative instructions.

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

• shared_margin_finishB
  3.2/5.0
  Behavior2/5

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

  No annotations provided, so description carries full burden. Only mentions preservation and optional reflection, but does not disclose side effects (e.g., whether session can be reopened, data persistence, authorization needs).

  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?

  Single sentence that front-loads the main action. Efficient but could include more detail without becoming verbose.

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

  Completeness2/5

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

  No output schema, 2 parameters, and no annotations. Missing important details like return values, error cases, or what 'preserving' means for future use. Incomplete for a closing operation.

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

  Parameters2/5

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

  Schema coverage is 0%, but description only adds meaning for closingNote ('optional final reflection'), not for sessionId. Lacks explanation of how parameters relate to the overall action.

  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 action ('Close a shared-attention session') and the key behaviors ('preserving its moments and an optional final reflection'). Distinguishes from siblings like shared_margin_begin, shared_margin_capture, etc.

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

  Usage Guidelines3/5

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

  No explicit guidance on when to use this tool versus alternatives. Implies usage at end of a session, but lacks when-not-to-use or prerequisite conditions.

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