biz.dfch.SpecMgr

Overview Schema Source Related Servers Discussions Admin

List problem statements

list_prb

Lists problem statement IDs, titles, statuses, and refs one page at a time, with optional glob and language filters, so you can locate a statement before retrieving it by ID.

Instructions

Ids, titles, statuses, and refs of problem statements in the configured problem statement base directory, one page at a time, for context before addressing one by id. 'ref' is an opaque, extensionless identifier -- not a filename to read from disk -- for documents that have no assigned id; use it with the get_prb tool instead. An optional glob pattern (e.g. 'dead*') filters the listing to the problem statements whose id matches it, case-insensitively; glob=None (the default) lists everything, and an empty string matches nothing. max_results/offset control paging (default page size 25, capped at 100); out-of-range values are clamped, not errored. The optional language parameter (default 'en') selects the directory scanned: omitted/'en' = the flat docs/prb/ directory (the default behavior, unchanged); any other ISO 639-1-shaped lowercase two-letter code (e.g. 'de') = only that language's docs/prb/{language}/ subdirectory, listing exactly the existing variants of that language (there is deliberately no 'all languages' mode). The language is shape-validated before any file access (an invalid-shaped value is a ValueError, like an invalid id), and a shape-valid language without a packaged heading-mapping table is rejected up front with an actionable ValueError.

Input Schema

Name	Required	Default
`glob`	No
`offset`	No
`language`	No	en
`max_results`	No

Output Schema

Name	Required	Description	Default
`total`	Yes
`offset`	Yes
`results`	Yes
`truncated`	Yes
`error_count`	No
`max_results`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.38.0Nov 2, 2026

addedInput schema / properties / language

Added value: +{
+  "default": "en",
+  "title": "Language",
+  "type": "string"
+}

First observedv0.36.0Oct 17, 2026

TDQS

A4.7/5.0

Behavior4/5

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

With no annotations, the description carries the full disclosure burden and does so well: it documents paging defaults and caps, that out-of-range values are clamped rather than errored, and that invalid language shapes and unbacked languages produce ValueErrors before any file access. The one meaningful omission is result ordering — for a paginated list, an agent cannot tell whether offset pages are stable or what the sort key is.

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 purpose sentence is correctly front-loaded and nearly every clause is load-bearing, but the remainder is delivered as one long semicolon-chained paragraph with nested parentheticals, which pushes it toward reference-manual density. Splitting the glob, paging, and language semantics into discrete structure would preserve the content while improving scanability.

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?

Output schema exists, so return-field documentation is not required, and the description covers the remaining surface: all four parameters, the default directory behavior, the language subdirectory behavior, and the error paths. For a filtered, paginated listing tool that is complete.

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

Parameters5/5

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

Schema description coverage is 0%, so the description must do all the work, and it does: glob is explained with syntax example, case-insensitivity, and the non-obvious boundary cases (None lists all, empty string matches none); offset/max_results get defaults and the 100 cap with clamping; language gets its default, its directory-mapping semantics, and its validation rules.

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?

Opens with a specific verb and resource ('Ids, titles, statuses, and refs of problem statements'), states the scope ('in the configured problem statement base directory'), and immediately distinguishes the tool from get_prb by explaining that a 'ref' must be resolved via get_prb rather than read from disk. An agent can tell what this returns and what it does not without opening the schema.

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?

Explicitly states the use case ('for context before addressing one by id') and routes the agent to the correct sibling for the one gap it creates: refs must go through get_prb. It also closes off a plausible wrong assumption by noting there is deliberately no 'all languages' mode, and explains when to omit language versus when to pass a code.

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

Deploy Server