Skip to main content
Glama

story_lint

Read-onlyIdempotent

Deterministic structural quality linter for user stories - a sibling to ticket_lint but scoped to story-writing concepts any team recognizes: narrative completeness (As-a/I-want-to/So-that/Summary), acceptance criteria presence, duplicate/unknown dependency IDs, a "Manage X" story with no CRUD split, list stories missing a pagination mention. An OPTIONAL rate_config unlocks team-specific checks (screen-vs-narrative match, hour-rate-per-screen tolerance, required risk level by story type, milestone-code format, required companion story types per milestone) - omit it and only the universal checks run. No house rates or milestone conventions are hardcoded. POST one story or a batch (max 50). Deterministic, no LLM.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "story_lint"
  }
}

Input Schema

NameRequiredDescriptionDefault
storyNoOne user story. Missing fields ARE findings.
storiesNoAlternative: batch of up to 50 stories. Dependency/duplicate/required-companion checks are evaluated across the whole batch.
rate_configNoOptional. Enables team-specific checks, all off by default.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed8 schema fields changed
    • addedInput schema / properties / rate_config / properties / rates / additionalProperties
      Added value: +{
      +  "properties": {
      +    "hours_field": {
      +      "description": "Key in story.hours to check.",
      +      "type": "string"
      +    },
      +    "hours_per_screen": {
      +      "description": "Expected hours per screen.",
      +      "type": "number"
      +    },
      +    "tolerance": {
      +      "description": "Allowed fractional deviation. Default 0.15.",
      +      "type": "number"
      +    }
      +  },
      +  "type": "object"
      +}
    • addedInput schema / properties / rate_config / properties / required_companion_types / items / properties / label / description
      Added value: +"Name used in the finding. Default: type."
    • addedInput schema / properties / rate_config / properties / required_companion_types / items / properties / type / description
      Added value: +"Required type_label."
    • addedInput schema / properties / stories / items / additionalProperties
      Added value: +{
      +  "description": "See story."
      +}
    • addedInput schema / properties / stories / items / description
      Added value: +"Same fields as story."
    • addedInput schema / properties / stories / maxItems
      Added value: +50
    • changedInput schema / properties / story / description
      Previous value: -"One story: {id, title, story: {as_a, i_want_to, so_that, summary, type_label?, on_screen?}, acceptance_criteria, dependencies?: [id], screen?, hours?: {<field>: number}, risk?, milestone_code?}. Missing fields ARE findings."New value: +"One user story. Missing fields ARE findings."
    • addedInput schema / properties / story / properties
      Added value: +{
      +  "acceptance_criteria": {
      +    "description": "A list, or one string with one criterion per line.",
      +    "items": {
      +      "type": "string"
      +    },
      +    "type": [
      +      "string",
      +      "array"
      +    ]
      +  },
      +  "dependencies": {
      +    "description": "Ids of stories this depends on; must exist in the batch.",
      +    "items": {
      +      "type": "string"
      +    },
      +    "type": "array"
      +  },
      +  "hours": {
      +    "additionalProperties": {
      +      "type": "number"
      +    },
      +    "description": "Estimate per field, e.g. {\"fe\": 6}.",
      +    "type": "object"
      +  },
      +  "id": {
      +    "description": "Story id; what dependencies refer to.",
      +    "type": "string"
      +  },
      +  "milestone_code": {
      +    "description": "e.g. \"M2-07\"; the part before the first \"-\" is the milestone group.",
      +    "type": "string"
      +  },
      +  "risk": {
      +    "description": "Risk level, checked against rate_config.risk_levels.",
      +    "type": "string"
      +  },
      +  "screen": {
      +    "description": "Screens touched, one per line; the line count is the screen count.",
      +    "type": "string"
      +  },
      +  "story": {
      +    "description": "The narrative. as_a, i_want_to, so_that and summary are all expected.",
      +    "properties": {
      +      "as_a": {
      +        "description": "The user role.",
      +        "type": "string"
      +      },
      +      "i_want_to": {
      +        "description": "The capability.",
      +        "type": "string"
      +      },
      +      "on_screen": {
      +        "description": "Screen name, compared to screen when check_screen_match is on.",
      +        "type": "string"
      +      },
      +      "so_that": {
      +        "description": "The benefit.",
      +        "type": "string"
      +      },
      +      "summary": {
      +        "description": "Plain summary of the story.",
      +        "type": "string"
      +      },
      +      "type_label": {
      +        "description": "Story type; keys rate_config.rates and risk rules.",
      +        "type": "string"
      +      }
      +    },
      +    "type": "object"
      +  },
      +  "title": {
      +    "description": "Story title.",
      +    "type": "string"
      +  }
      +}
  2. First observed

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the bar is lower; the description still adds real value by stating it is deterministic with no LLM, that missing fields ARE findings, that config-gated checks are all off by default, and that no house rates or milestone conventions are hardcoded. It stops short of describing what a returned finding looks like, which matters since there is no 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.

Conciseness4/5

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

Purpose is front-loaded and the optional-vs-universal config distinction is stated early, with the config-gated checks parenthetically enumerated. It is dense and long for a description, but every clause carries information and nothing is repeated from the schema.

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 nested three-parameter linter with no output schema, the description covers both input modes, the batch cap, the deterministic/no-LLM guarantee, and config gating well. The remaining gap is the shape of the response (finding structure, severity, count), which the description never sketches despite there being no output schema to fall back on.

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% and the nested rate_config keys are all documented inline, so the schema does the heavy lifting and baseline 3 applies. The description does add framing beyond the schema by describing the universal checks that run with no config (Manage-X without CRUD split, list story missing pagination), which are not derivable from any parameter 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?

"Deterministic structural quality linter for user stories" gives a specific verb+resource, and the description explicitly positions it against the sibling ticket_lint ("scoped to story-writing concepts"). It then enumerates the concrete checks (narrative completeness, acceptance criteria, dependency IDs, CRUD split, pagination) so an agent knows exactly what class of defect it surfaces.

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?

Clear operational guidance: POST one story or a batch of max 50, and rate_config is optional with universal checks running when omitted. The ticket_lint sibling is named but the routing rule (stories vs generic tickets) is only implied by "scoped to story-writing concepts" rather than stated as an explicit when-to-use/when-not rule.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.