Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@sdlc-mcp Validate this user story against our definition of ready."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that gives an AI agent your software delivery standard: artifact templates, a domain glossary, and a machine verdict on whether an artifact is ready to move on.
A prompt can tell an agent what shape a user story should have. What a prompt cannot do is tell it whether the story it just wrote is actually acceptable. That is what this server is for.
validate_artifact("US", content) -> { "verdict": "fail", "blockers": [ ... ] }Three rules hold the whole thing together:
Every task produces an artifact, and every artifact has an owning role. Roles are defaults, not requirements: a project that does not staff an architect reassigns the architect's tasks down a declared fallback chain. The task still has to happen.
Readiness is data, not opinion. Definition of Ready and Definition of Done
live in standard/rules.yaml as declarative records.
Adding a rule means editing YAML. Adding a kind of rule means writing one
function.
The standard lives in version control, so the same files that a human reviews are the context an agent reads. There is no second, prettier copy that drifts.
This is spec-driven development taken literally: the specification in the repository is the source of truth an agent implements from, and the gate it has to pass on the way out.
Related MCP server: RulesetMCP
git clone https://github.com/<you>/sdlc-mcp && cd sdlc-mcp
python -m venv .venv && . .venv/Scripts/activate # POSIX: . .venv/bin/activate
pip install -e ".[dev]"
python -m sdlc_mcp --self-check # verify the standard is consistent
python -m sdlc_mcp --overview # print the standard as a Markdown table
pytest -q # 40 tests
python -m sdlc_mcp # serve over stdio--self-check is the interesting one. It asserts that the standard does not
contradict itself: every artifact type points at a real category and a real role,
every task produces a known artifact type, every rule kind is implemented, every
template file exists, every template satisfies its own required-section rules,
and every bundled example produces the verdict it is supposed to. A standard that
contradicts itself is worse than no standard, because an agent reading it cannot
tell the difference. It runs in CI.
Claude Code (.mcp.json in your project, or claude mcp add):
{
"mcpServers": {
"sdlc": {
"command": "python",
"args": ["-m", "sdlc_mcp"]
}
}
}Cursor (.cursor/mcp.json) uses the same shape. Any MCP client that speaks stdio
will work; --transport streamable-http and --transport sse are also available.
Tool | What an agent uses it for |
| See the phases of delivery and what each must produce. |
| Get one phase in full: purpose, exit artifacts, tasks, owners. |
| See the artifact catalog with id conventions and owners. |
| Fetch the template before writing, plus the sections the rules will require. |
| Get a pass/fail verdict with blockers and warnings, at the |
| Resolve a domain term instead of inventing a meaning. On a miss, returns every known term so the agent can see what it should have asked for. |
| Given what already exists, what is still outstanding and who owns it. |
| Find the reference artifacts, each declaring its expected verdict. |
Resources: sdlc://standard/overview, sdlc://glossary,
sdlc://template/{artifact_type}, sdlc://example/{example_id}.
Prompts: draft_artifact and review_artifact - workflows that put the tools
in the right order (template first, glossary second, validate last) so the agent
does not have to be reminded every session.
examples/US-LEND-009-not-ready.md is a
deliberately bad user story. Real output:
{
"artifact_type": "US",
"gate": "ready",
"verdict": "fail",
"rules_checked": 13,
"blockers": [
{
"rule": "no_placeholder",
"message": "Placeholders left in the text mean the artifact is not ready, whoever wrote it.",
"detail": "'TODO'"
},
{
"rule": "frontmatter_enum",
"message": "front matter 'priority' has a value outside the allowed set",
"detail": "got 'high', allowed: must, should, could, wont"
},
{
"rule": "section_min_items",
"message": "A story with fewer than two acceptance criteria is a title, not a requirement.",
"detail": "found 1"
}
],
"warnings": [
{
"rule": "section_forbids_text",
"message": "Unfalsifiable acceptance criteria cannot be tested and cannot be implemented by an agent.",
"detail": "found: 'as appropriate', 'etc.'"
},
{
"rule": "section_required",
"message": "required section 'Open questions' is missing"
}
]
}Blockers fail the gate. Warnings do not - they are the things worth arguing about rather than the things worth refusing.
The Python in src/ contains no process knowledge. Fork the repository, edit the
YAML in standard/, and you are serving your own standard over the
same protocol:
File | What it defines |
Phases of delivery, their exit artifacts and their tasks. | |
The artifact catalog: owning category, owner role, id convention, template. | |
Roles and the fallback chain used when one is not staffed. | |
Definition of Ready and Definition of Done, per artifact type. | |
The domain terms and their agreed meaning. | |
One Markdown template per artifact type. |
Run python -m sdlc_mcp --self-check after editing. It will tell you what you
broke.
Kind | Fields | Checks |
|
| The key exists and is not empty. |
|
| The value matches a regex - used for id conventions. |
|
| The value is one of an allowed set. |
|
| A section with that heading exists (case- and punctuation-insensitive). |
|
| The section has at least N list items or table rows. |
|
| The section avoids named weasel phrases. |
|
| No |
| - | Outbound artifact references resolve against the ids you pass in. |
Every rule carries a severity (blocker or warning) and an optional message
that replaces the generic one. The messages in rules.yaml are written to be read
by whoever has to fix the artifact, human or otherwise.
Adding a kind: write a checker in
validation.py and register it in
KNOWN_RULE_KINDS. An unregistered kind referenced from YAML is reported by
--self-check and, at runtime, degrades to a loud warning rather than a silent
pass.
standard/ the standard itself, as data
templates/ one Markdown template per artifact type
examples/ filled-in reference artifacts in a demo domain
src/sdlc_mcp/
markdown.py front matter, sections, list items, references
validation.py the rule engine: kinds, findings, verdicts
catalog.py loads the standard, answers questions, self-checks
model.py immutable value types
server.py MCP tools, resources and prompts
tests/ 40 tests, no network, no fixtures beyond the repolinks_resolve does nothing when you pass no ids. Without a universe of
known artifacts there is nothing to resolve against, and reporting every
reference as broken would teach callers to ignore the rule. Pass known_ids and
it starts working.
Unknown rule kinds warn, they do not pass quietly. A typo in the standard should be visible at the point of use, not discovered when a bad artifact reaches implementation.
Templates are validated against their own rules. A template that cannot pass the gate teaches the agent to produce failures, which is a subtle and expensive way to break a standard.
The owner fallback is transitive and terminates. If nobody in the chain is staffed, the default role is returned unchanged: the task still belongs to somebody, which is exactly the conversation the fallback is meant to force.
No Markdown library. Artifacts follow the bundled templates, so heading and list detection is sufficient; a parser would be a dependency for no gain.
The glossary and examples describe BookLoop, a fictional community
book-lending platform. It exists only to make the artifacts concrete - loans,
copies, branches and due dates are small enough to hold in your head and rich
enough to show what a real use case and a real ADR look like. Replace
standard/glossary.yaml and examples/ with your own and nothing else changes.
The standard shipped here is a generic reference implementation written for this repository.
MIT - see LICENSE.
Return the Markdown template for an artifact type, together with the sections its readiness rules require. Use this before writing the artifact.
| Name | Required | Description | Default |
|---|---|---|---|
| artifact_type | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the behavioral transparency burden. It does indicate that the tool returns a template and readiness sections, implying a read-only operation, and 'before writing' reinforces this. However, it does not disclose error behavior for unknown artifact types, exact output structure, or whether any side effects occur.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, each earning its place: the first defines the output and the second gives the usage timing. No redundant phrasing or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool, the description covers the purpose and usage well, and the sibling tool list_artifact_types hints at a way to discover valid values. However, the absence of any parameter guidance or explicit pointer to list_artifact_types leaves a notable gap for correct invocation. No output schema exists, so more parameter context would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not compensate. The only parameter, artifact_type, is simply restated in the description ('for an artifact type') without explaining valid values, format, or how to discover them. An agent cannot determine what string to pass for artifact_type from this definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Return') and identifies a clear resource: the Markdown template for an artifact type, plus readiness-rule sections. This clearly distinguishes it from siblings like list_artifact_types (which lists types), validate_artifact (which validates an artifact), and get_work_category (which gets a category).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: 'Use this before writing the artifact.' This gives a clear usage context. It does not explicitly name alternatives or exclusions, but the 'before writing' timing is strong enough guidance for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Describe one work category in full: purpose, exit artifacts, and the tasks with their default owning role. Accepts an id such as '02' or a key such as 'requirements'.
| Name | Required | Description | Default |
|---|---|---|---|
| category | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It clearly states the operation returns a full description of one category and identifies the specific content fields, which is sufficient for a simple read-style lookup. It does not cover error/not-found behavior, but the core behavior is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. It front-loads the tool's purpose and output content, then gives parameter examples. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter getter with no output schema, the description provides enough to call it correctly: what it returns and what the parameter accepts. It could be more complete by explicitly routing between list_work_categories and get_work_category, but nothing essential for invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description compensates by explaining that the single 'category' parameter accepts either an id ('02') or a key ('requirements'). This gives the agent concrete guidance on how to populate the required parameter, though it does not enumerate all accepted key formats.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies a clear verb and resource: 'Describe one work category in full' and names the specific content dimensions (purpose, exit artifacts, tasks with default owning role). This distinguishes it from sibling list_work_categories, which likely enumerates categories rather than describing a single one.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it: when full details of one work category are needed, rather than a list. However, it does not explicitly name alternatives or state when not to use it, leaving some inference to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every artifact type in the standard: owning category, default owner role, id convention and what the artifact is for.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It states the tool returns every artifact type within the standard, which implies a read-only, comprehensive listing, but it does not explicitly mention read-only behavior, potential size limits, or any special considerations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, dense sentence that front-loads the core action ('List every artifact type') and then enumerates the relevant returned attributes. Every word adds value, with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter list tool with an output schema, the description is complete: it identifies the resource, the scope ('every artifact type in the standard'), and the content of each returned item. No additional calling context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is no parameter burden for the description to carry. The schema is empty and the description adds no parameter-specific detail, which is appropriate and sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: listing all artifact types in the standard, and enumerates the exact fields returned. It differentiates from sibling tools by focusing on artifact types rather than work categories or templates, though it does not explicitly name those alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool — when you need a comprehensive list of artifact types with their owning category, owner role, id convention, and purpose. It provides no explicit comparison or when-not-to-use guidance relative to sibling tools, but the scope is reasonably inferable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the bundled example artifacts. Examples are filled-in reference documents in a fictional demo domain; read one before writing your own.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the burden. It discloses that examples are bundled, filled-in reference documents in a fictional demo domain, and the verb 'List' makes the read-only nature apparent. It does not cover limits or ordering, but the output schema covers return shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The core action is front-loaded, and the second sentence adds only the necessary context about what examples are and how to use them.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless listing tool with an output schema, this is complete: it says what is listed, what the examples represent, and why to use them. Nothing needed for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and 100% schema description coverage, so the description has no parameter burden. The baseline for a parameterless tool is appropriately 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'List the bundled example artifacts.' It further clarifies that examples are filled-in reference documents in a fictional demo domain, which distinguishes this tool from siblings like list_artifact_types and list_work_categories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: read an example before writing your own artifact. It does not explicitly name sibling alternatives or state when not to use the tool, but the intended scenario is evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the work categories of the SDLC standard, with their purpose and the artifacts each one must produce before it is complete.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. The verb 'List' and the focus on returned information make the read-only nature clear, and it adds what the result contains (purpose and artifacts). It does not need to detail side effects because none are implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence, front-loaded with the action and resource, and every clause adds useful information (SDLC standard, purpose, required artifacts). No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter listing tool with an output schema, the description is complete: it names the resource, the scope (SDLC standard), and the semantic content of the result. The output schema covers the return shape, so no further detail is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema leaves nothing to explain and the description is not required to document arguments. The baseline of 4 applies here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'List the work categories of the SDLC standard', and further specifies the returned content (purpose and required artifacts). This clearly distinguishes it from sibling tools such as get_work_category (singular) and list_artifact_types (different resource).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'List' framing implies use when an agent needs the full set of SDLC work categories rather than a single category or artifact types, but the description never explicitly states when to choose it over a sibling. No exclusions or alternative conditions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up a domain term in the project glossary. Matches the term, its aliases, and finally the definition text. Use this instead of guessing what a domain word means.
| Name | Required | Description | Default |
|---|---|---|---|
| term | Yes |
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 usefully discloses the matching behavior: term, then aliases, then definition text. However, it does not state the return format, whether matching is exact or fuzzy, or how errors or missing terms are handled.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. The action and resource are front-loaded, followed by matching behavior and usage guidance. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter lookup tool, the description covers purpose, use case, and matching behavior. However, there is no output schema, and the description does not state what a successful lookup returns or how results are formatted, leaving a meaningful gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 partially does by clarifying that the term is a domain term and that the lookup considers aliases and definition text. Still, it does not explain accepted input format, case sensitivity, or what exact value should be passed beyond 'term'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('look up') and a clear resource ('domain term in the project glossary'). It is clearly distinct from the listed sibling tools, though it does not explicitly name a sibling alternative or differentiate itself from one.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: use this tool when you need the meaning of a domain term, and it explicitly says to use it instead of guessing. It does not discuss exclusions, but no sibling tool appears to overlap with glossary lookup.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Given a work category and the artifact types that already exist, return the tasks still outstanding and who owns them. Pass staffed_roles to have owners reassigned through the fallback chain when a role is not on the project.
| Name | Required | Description | Default |
|---|---|---|---|
| category | Yes | ||
| staffed_roles | No | ||
| existing_artifact_types | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It reveals useful logic: existing artifact types determine outstanding tasks, and staffed_roles triggers owner reassignment via a fallback chain. However, it does not clarify whether this operation is read-only, what the fallback chain precisely does, or what happens when staffed_roles is omitted, leaving some ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler. The core purpose is front-loaded, and the optional staffed_roles behavior is stated in a separate clause. Every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with three parameters, no output schema, and no annotations, the description is nearly complete: it explains the inputs, the conditional behavior, and what is returned. Minor gaps remain around output format, read-only guarantees, and fallback chain details, but an agent can infer correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must add meaning, and it does: 'work category' maps to category, 'artifact types that already exist' maps to existing_artifact_types, and staffed_roles is explained as triggering owner reassignment. It covers all three parameters semantically and explains their role in the computation, though it doesn't enumerate value formats.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('return'), a clear resource ('tasks still outstanding'), and states who owns them. It clearly distinguishes itself from sibling tools like list_work_categories or list_artifact_types by focusing on next tasks rather than listing categories or artifact types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 the tool: when you have a work category and existing artifact types and need outstanding tasks. It also explains when to pass staffed_roles. However, it does not explicitly name alternatives or state when not to use this tool versus siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate artifact content against the Definition of Ready or Definition of Done for its type. Returns a pass/fail verdict with blockers and warnings. Blockers must be fixed before the artifact moves on. Pass known_ids (the ids of artifacts that exist in your project) to have outbound references checked; omit it and reference checking is skipped.
| Name | Required | Description | Default |
|---|---|---|---|
| gate | No | ready | |
| content | Yes | ||
| known_ids | No | ||
| artifact_type | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavior disclosure. It reveals the return structure (pass/fail with blockers and warnings), the consequence that blockers block progression, and the conditional behavior of known_ids (reference checking skipped if omitted). This is strong disclosure, though it does not address side effects or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each with a distinct purpose: state the core function, describe the return value, and explain the optional parameter. There is no filler or redundant information, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a validation tool with no annotations and no output schema, the description covers purpose, output structure, and conditional behavior. Some details like valid artifact_type values and content formatting are left to the schema or discoverable via sibling tools such as list_artifact_types, but overall the description is complete enough for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description compensates meaningfully: known_ids is fully explained with its effect, gate is mapped to Definition of Ready/Done, and artifact_type is contextualized as determining the standard to validate against. Content receives only generic treatment and no valid type values are listed, but the essential semantics are covered.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource ('Validate artifact content against the Definition of Ready or Definition of Done for its type'), which clearly defines the tool's function. It also mentions the pass/fail verdict with blockers and warnings, further distinguishing it from sibling lookup/list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool by stating 'Blockers must be fixed before the artifact moves on', giving a concrete gate-keeping context. It also explains the optional known_ids behavior, so an agent can decide whether to include it. It does not explicitly name alternatives, but no sibling tool offers validation, so context is adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_artifact_templateget_work_categorylist_artifact_typeslist_exampleslist_work_categorieslookup_glossary_termnext_tasksvalidate_artifactScored across 8 tools
Each tool targets a distinct operation: category lookup, artifact type/template retrieval, validation, glossary lookup, task planning, and example listing. The list/get pairs are clearly separated by singular detail vs. plural overview.
Most tools follow a clear verb_noun pattern such as get_work_category, list_artifact_types, validate_artifact, and lookup_glossary_term. The outlier is next_tasks, which is not verb-led and breaks the otherwise consistent naming convention.
Eight tools is a well-scoped size for an SDLC standard assistant. Each tool covers a meaningful part of the workflow without redundancy or bloat.
The core standard, template, validation, glossary, and task-planning capabilities are present. However, the set tells agents to read example artifacts before writing their own, yet only offers list_examples with no way to retrieve a specific example, leaving an obvious gap in that workflow.
Pre-execution governance for AI agents. Deterministic PASS/FAIL/REVIEW verdicts, replayable proof.
Preflight QA for AI-agent deliverables with structured verdicts and repair guidance.
Deterministic validation for AI-generated artifacts: JSON Schema, OpenAPI response, SQL syntax.
Your team's shipping standards, org map and delivery metrics, inside your coding agent.
