Skip to main content
Glama
nikkoxgonzales

bullet-mcp

by nikkoxgonzales
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

bullet-mcp.jpg

bullet-mcp

MCP server for evidence-based bullet point summarization guidance. Validates and improves bullet lists using scientifically-validated principles from cognitive psychology and UX research.

Features

  • Score bullet lists (0-100) against 7 evidence-based rules

  • Letter grades (A/B/C/D/F) with actionable feedback

  • Research citations for each validation rule

  • Context awareness (document, presentation, reference)

  • Sections support for long documents with multiple chapters/topics

Related MCP server: verifiable-thinking-mcp

Installation

npm install bullet-mcp

Or install globally:

npm install -g bullet-mcp

Usage

Claude Desktop Configuration

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "bullet": {
      "command": "npx",
      "args": ["bullet-mcp"]
    }
  }
}

Tool: bullet

Validates bullet point lists against evidence-based cognitive research.

Input:

{
  "items": [
    { "text": "Use 3-7 items per list for optimal recall", "importance": "high" },
    { "text": "Place critical information first and last" },
    { "text": "Maintain parallel grammatical structure" },
    { "text": "Keep lines between 45-75 characters" },
    { "text": "Limit hierarchy to 2 levels maximum" }
  ],
  "context": "document"
}

Output:

{
  "overall_score": 97,
  "grade": "A",
  "summary": "Excellent bullet list following evidence-based best practices.",
  "top_improvements": ["Consider adding detail or combining with a related point"],
  "errors": [],
  "warnings": [],
  "suggestions": [...]
}

Sectioned Mode (for long documents)

For long documents with multiple chapters or topics, use the sections format. Each section is validated separately (3-7 items per section), allowing unlimited total content.

Input:

{
  "sections": [
    {
      "title": "Chapter 1: Introduction",
      "items": [
        { "text": "Define the problem scope and context" },
        { "text": "Outline key objectives and goals" },
        { "text": "Summarize the main approach taken" }
      ]
    },
    {
      "title": "Chapter 2: Methods",
      "items": [
        { "text": "Describe data collection procedures" },
        { "text": "Explain analysis methodology used" },
        { "text": "Detail validation steps performed" }
      ],
      "context": "reference"
    }
  ],
  "context": "document"
}

Output includes per-section breakdown:

{
  "overall_score": 95,
  "grade": "A",
  "section_scores": [
    { "title": "Chapter 1: Introduction", "score": 96, "grade": "A", "item_count": 3 },
    { "title": "Chapter 2: Methods", "score": 94, "grade": "A", "item_count": 3 }
  ],
  "summary": "Excellent structured summary across 2 sections."
}

Validation Rules

Rule

Threshold

Research Basis

List Length

3-7 items (5 optimal)

Miller (1956), Cowan (2001): Working memory 3-4 chunks

Hierarchy

Max 2 levels

Kiger (1984), Nielsen: 2-level structures fastest

Line Length

45-75 chars (66 optimal)

Typography research on readability

Serial Position

Important info first/last

Ebbinghaus (1885): U-shaped retention curve

Parallel Structure

Consistent grammar

Frazier et al. (1984): Faster scanning

First Words

Unique, scannable

Nielsen eye-tracking: First 2 words critical

Formatting

Consistent punctuation

Usability research

Context Options

  • document (default): Optimizes for scanning and reference

  • presentation: Warns that visuals may be 43% more persuasive

  • reference: Optimizes for quick lookup

Environment Variables

Variable

Default

Description

BULLET_STRICT_MODE

false

Treat warnings as errors

BULLET_NO_CITATIONS

false

Disable research citations in output

BULLET_NO_COLOR

false

Disable colored console output

Development

# Install dependencies
npm install

# Build
npm run build

# Test with MCP Inspector
npm run dev

Research Foundation

This tool is based on docs/bullet-study.md, a synthesis of cognitive psychology research on optimal list design including:

  • Working memory capacity (Miller, Cowan)

  • Serial position effects (Ebbinghaus, Murdock)

  • Eye-tracking studies (Nielsen Norman Group)

  • Information architecture (Kiger, Zaphiris)

  • Typography research (45-75 character optimal line length)

License

MIT

Available Tools

1 tool
bulletA

Validate and improve bullet point lists using evidence-based cognitive research.

This tool analyzes bullet lists against scientifically-validated principles for optimal recall, scanning efficiency, and comprehension. Use it to ensure your summaries follow best practices.

INPUT MODES:

  • Flat mode: Use "items" for simple lists (3-7 items recommended)

  • Sectioned mode: Use "sections" for long documents with multiple topics/chapters

    • Each section has its own title and items array

    • The 3-7 item rule applies PER SECTION, allowing unlimited total content

WHEN TO USE:

  • Before finalizing any bullet list summary

  • When creating documentation, reports, or reference materials

  • To score existing bullet content against research standards

  • For guidance on improving list structure

KEY PRINCIPLES ENFORCED:

  1. List Length (3-7 items per section, 5 optimal): Working memory limits mean more items decrease recall

  2. Hierarchy (max 2 levels): Breadth over depth for better comprehension

  3. Serial Position: Place critical info first and last (U-shaped recall curve)

  4. Line Length (45-75 chars, 66 optimal): Typography research on readability

  5. Parallel Structure: Consistent grammar enables faster scanning

  6. First Two Words: Critical for reader fixation and scanning decisions

CONTEXT AWARENESS:

  • document: Optimizes for scanning and reference (default)

  • presentation: Warns that visuals may be more effective (43% more persuasive per research)

  • reference: Optimizes for quick lookup

  • Per-section context override supported in sectioned mode

SCORING:

  • 0-100 scale with letter grades (A/B/C/D/F)

  • Per-rule breakdown with research citations

  • Per-section breakdown in sectioned mode

  • Actionable improvement suggestions ranked by impact

Returns JSON with score, grade, issues, and top improvements.

ParametersJSON Schema
NameRequiredDescriptionDefault
titleYesTitle/heading for the bullet list (e.g., "Email Thread Summary")
descriptionYesBrief summary or context about what the bullets cover
introYesIntroductory phrase before the bullets (e.g., "Here are the main topics:")
itemsNoArray of bullet items to validate (flat mode). Use this OR sections, not both.
sectionsNoFor long documents, group bullets into sections. Each section is validated separately. Use this OR items, not both.
contextNoUsage context affects recommendations. Default: document. In sectioned mode, this is the default context (sections can override).

TDQS

A4.4/5.0
Behavior4/5

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

Since no annotations are provided, the description carries the full burden. It explains the tool analyzes, validates, and improves lists, returns a JSON with score and issues, and enforces scientific principles. It does not mention destructive actions or auth needs, but as a validation tool, the behavior is clear. Could be slightly more explicit about whether it modifies input.

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 well-structured with clear sections (INPUT MODES, WHEN TO USE, KEY PRINCIPLES, etc.) and front-loaded with the main purpose. While it is lengthy, the detail is justified by the tool's complexity (6 parameters, nested objects). Each section adds value, but a few sentences could be trimmed without loss.

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?

Given the relatively complex input schema (6 parameters with nested objects) and no output schema, the description is exceptionally complete. It covers input modes, usage context, principles enforced, scoring output structure, and even per-section context overrides. An agent can fully understand how to invoke the tool and what to expect.

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%, so baseline is 3. The description adds context beyond the schema by explaining flat vs sectioned mode, the 3-7 item rule per section, and context options. This additional guidance helps the agent select the correct parameter combination, justifying a 4.

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 validates and improves bullet point lists using cognitive research. It specifies the action (validate, improve), the resource (bullet lists), and the methodology (evidence-based cognitive research). This is a specific verb+resource combination that distinguishes it from any sibling (none provided).

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 includes a 'WHEN TO USE' section with explicit scenarios like finalizing summaries, creating documentation, and scoring content. It also explains the difference between flat and sectioned modes. However, it does not explicitly state when not to use the tool or provide alternatives, missing a small opportunity for full guidance.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev1.0.6
    • First observedbullet
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.6/5.0

Scored across 1 tool

Disambiguation5/5

With only one tool, there is no risk of confusion between tools. The tool's purpose is clearly defined and distinct.

Naming Consistency5/5

With a single tool, naming consistency is not applicable; there is no pattern to violate.

Tool Count5/5

The single tool is appropriately scoped for the server's narrow purpose of validating and improving bullet lists, covering all necessary functionality.

Completeness5/5

The tool comprehensively covers the domain of bullet list validation, including multiple input modes, context awareness, scoring, and improvement suggestions, with no obvious gaps.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers