Server Quality Checklist

Tool Scores

• generate_personal_summaryA
  3.8/5.0
  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 adds crucial context that the tool builds a 'prompt package' rather than generating the summary directly, which prevents confusion about return values. However, it lacks details about the prompt structure, caching behavior, or what the output format looks like given the absence of an output schema.

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

  Conciseness5/5

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

  The description consists of two efficient sentences with zero waste. The first sentence front-loads the core functionality (building prompt packages), while the second provides usage constraints, making it easy for an agent to quickly grasp both purpose and context.

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

  Completeness3/5

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

  For a tool with three parameters and no output schema, the description adequately explains the high-level mechanism but remains incomplete regarding input requirements and return values. Given the complexity of 'prompt package' construction, additional details about the output structure or parameter interactions would strengthen completeness.

  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?

  The schema has 0% description coverage, requiring the description to compensate significantly. While the text mentions 'highlights alone,' implying the highlights parameter, it does not explicitly document the title or author parameters or describe expected formats (e.g., whether highlights should be raw strings or formatted text). This leaves substantial gaps in parameter understanding.

  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 'builds a prompt package for the host model to generate a personal book memory summary,' specifying the verb (builds), resource (prompt package), and scope (from highlights alone). This effectively distinguishes it from siblings like parse_kindle_clippings and push_to_notion, which handle parsing and external system integration rather than summary generation.

  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 provides explicit usage context with 'Use this when processing a single book manually,' which helps identify when to select this tool over bulk-processing siblings like process_kindle_export. However, it does not explicitly name alternatives or state exclusion criteria (e.g., 'do not use for batch processing').

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

• push_to_notionA
  4/5.0
  Behavior3/5

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

  No annotations provided, so description carries full burden. 'Push' implies write/create operation, and 'structured page' hints at the data format. However, lacks disclosure on failure modes, authentication requirements, whether it overwrites existing pages, or rate limiting 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/5

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

  Two sentences with zero waste. First sentence front-loads the core action (what), second sentence provides critical workflow timing (when). Every word earns its place in a compact, scannable format.

  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 complex nested summary object and lack of output schema, the description adequately establishes the tool's role in the workflow pipeline. Missing explicit success/failure behavior disclosure, but the tight integration with sibling tool references (process_kindle_export, generate_personal_summary) provides sufficient context for invocation.

  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%, providing detailed structure for the summary object and noting notionDatabaseId is provided by process_kindle_export. Description adds workflow context but no additional parameter syntax or validation rules beyond 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?

  Specific verb 'Push' + resource 'Notion database' + format 'structured page' clearly defines the operation. The phrase 'generated book summary' distinguishes this from sibling parse_kindle_clippings (raw data) and aligns with generate_personal_summary (content creation step).

  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?

  Explicit sequencing guidance 'Call this once per book after generating each summary' establishes workflow order relative to generate_personal_summary. Mentions 'once per book' implying idempotency expectation. Lacks explicit 'when not to use' or alternative export paths.

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

• initialize_notion_databaseA
  4.3/5.0
  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 specifies the database name ('Kindle Book Summaries') which hints at schema intent, but fails to disclose idempotency behavior, required permissions, what happens if the database already exists, or what the tool returns. It meets minimum expectations for a creation tool but lacks safety/reversibility details.

  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?

  Two sentences with zero waste: first states the action, second states the trigger condition and input source. Information is front-loaded with the core purpose, followed by procedural context. Every word serves the agent's decision-making process.

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

  Completeness3/5

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

  Given no output schema exists, the description should ideally disclose return values (likely the database ID needed for subsequent push_to_notion calls). The workflow integration is well-explained, but the missing output specification leaves a gap for an agent orchestrating the full pipeline from initialization to content pushing.

  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?

  With 100% schema coverage, the baseline is 3. The description adds value by specifying the semantic source of the parentPageId ('created by the Notion MCP tool'), guiding the agent on which specific ID to use rather than accepting any arbitrary page ID. This contextualizes the parameter beyond the schema's technical definition.

  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 ('Creates') with a specific resource ('Kindle Book Summaries database') and location context ('under a given parent page'). It clearly distinguishes from siblings like push_to_notion or parse_kindle_clippings by establishing this as the structural initialization step rather than content processing.

  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?

  Provides explicit conditional guidance: 'Call this automatically when process_kindle_export returns status='setup_required''. This establishes a clear workflow trigger and prerequisite condition. It also specifies the parameter source ('page ID created by the Notion MCP tool'), guiding the agent on how to obtain valid input.

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

• process_kindle_exportA
  4.5/5.0
  Behavior4/5

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

  With no annotations provided, the description carries full burden of behavioral disclosure. It explains that the tool returns 'prompt packages plus explicit instructions' rather than final data, and mandates a specific multi-step workflow (generate internally → push to Notion). Lacks details on error handling or malformed input 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/5

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

  Three sentences with zero waste. Front-loaded with 'PRIMARY TOOL' to establish hierarchy among siblings. Each sentence serves distinct purposes: (1) capability definition, (2) mandatory workflow instructions, (3) output constraints. Efficient and actionable.

  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?

  Despite missing annotations and output schema, the description provides sufficient context for an AI agent to execute correctly. It compensates for the lack of structured output description by explaining the return type (prompt packages + instructions) and the critical post-call orchestration sequence involving sibling tools.

  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 coverage is 100% for the single 'rawText' parameter, which is well-described in the schema itself. The description essentially restates the schema's content ('Given the raw content...'), meeting the baseline expectation for high-coverage schemas without adding significant semantic depth.

  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 uses specific verbs (parses, returns) and clearly identifies the resource (Kindle HTML export or My Clippings.txt). It distinguishes from sibling 'parse_kindle_clippings' by explicitly handling both formats (HTML and txt), positioning itself as the comprehensive option.

  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?

  Provides explicit workflow instructions: 'After calling this tool, you MUST follow the returned instructions exactly' and mandates subsequent calls to sibling 'push_to_notion'. Includes clear exclusions: 'Do not display summaries in chat — only report the Notion page URLs', defining exactly when and how to use the tool.

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

• parse_kindle_clippingsA
  4.7/5.0
  Behavior4/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 successfully explains the grouping logic (by book) and the raw/unprocessed nature of the output. It could explicitly state this is a read-only/idempotent operation, but 'Parse' implies this adequately for a single string input 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/5

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

  Two sentences with zero waste: the first states purpose and I/O, the second provides usage guidance. Information is front-loaded and every sentence earns its place.

  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 single-parameter parsing tool with no output schema, the description is complete. It compensates for the missing output schema by describing the return structure ('highlights grouped by book') and clarifies the input domain despite the schema already documenting the parameter.

  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 100%, establishing a baseline of 3. The description adds value by specifying the two acceptable file formats ('HTML export' vs 'My Clippings.txt') for the rawText parameter, helping the agent understand what content to provide beyond the generic schema description.

  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 ('Parse') with clear resources ('Kindle HTML export or My Clippings.txt') and output format ('highlights grouped by book'). It effectively distinguishes from sibling 'generate_personal_summary' by explicitly stating this returns 'raw highlights without generating summaries', clarifying its 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?

  Provides explicit when-to-use guidance ('Use this when you only need the raw highlights without generating summaries'), implicitly identifying when NOT to use it and naming the alternative (generate_personal_summary). This gives the agent clear decision criteria for tool selection.

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