DevFlow MCP Server

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v4.43.0
Disambiguation4/5
Most tools have distinct purposes, but the large number of closely related tools (e.g., knowledge_check_drift, knowledge_check_flow, knowledge_check_resolve, and multiple wiki getters) could cause some confusion. Descriptions help differentiate, but overlap remains.
Naming Consistency4/5
The vast majority of tools follow a consistent verb_noun snake_case pattern (e.g., flow_create, adr_list). Minor deviations like 'idea_prompts_get' vs 'ideas_get' and long names like 'discipline_tokens_auto_emit' slightly break consistency, but overall it's good.
Tool Count2/5
65 tools is very high for any server. While the domain is broad (ADRs, flows, wiki, knowledge, tasks, releases, etc.), this number overwhelms agents and makes selection difficult. Many tools could be consolidated or split into separate servers.
Completeness3/5
The tool set covers most major lifecycle operations for flows, ADRs, documents, and wiki. However, notable gaps exist: no delete tools for flows, ADRs, or releases, and no user/project management tools beyond bootstrap. Coverage is broad but not fully complete.
Average 4.1/5 across 65 of 65 tools scored. Lowest: 2.9/5.
See the Tool Scores section below for per-tool breakdowns.
- 0 of 1 community issues answered or closed in the last 6 months
- 10 commits in the last 12 weeks
- Last stable release on July 28, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only states it returns nodes+edges and allows filtering. It does not mention that the operation is read-only, any side effects, authorization needs, or performance implications. A more complete description would add safety traits.
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, zero waste. Every phrase contributes meaning: purpose, what is returned, optional filtering. Well-front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, the description is too sparse. It lacks usage guidelines, behavioral transparency, and full parameter coverage. The return format (what nodes/edges look like) is not described, which is needed when no output schema exists.
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 67% (projectId lacks description). The description adds 'Optional type filter to limit which asset types appear,' covering the types parameter but not tags. This adds marginal value over the schema but does not fully compensate for the missing projectId description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a local knowledge graph (nodes + edges) around a project, with optional type filtering. This is a specific verb-resource combination that distinguishes it from sibling tools like wiki_get_page or wiki_search, though it doesn't explicitly differentiate from other graph-related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., wiki_get_flow_context, wiki_get_project_context). The description does not mention prerequisites, limitations, or preferred scenarios, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It reveals the return data (ADR content + affects_paths) and instructs the agent on subsequent steps, suggesting a read-only operation. However, it does not explicitly state whether the tool has side effects, requires permissions, or any rate limits.
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 front-loaded with the purpose and clearly structured. It uses bullet-like steps for agent actions without being overly verbose. Each sentence contributes value, though the numbered list could be slightly more concise.
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 tool that simply fetches ADR data for the agent to process, the description is complete. It specifies the return structure, handles the empty affectsPaths edge case, and outlines the expected agent workflow. No output schema exists, but the description adequately covers what the tool provides.
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 input schema has two parameters: 'projectId' (undocumented) and 'adrNumber' (documented as 'ADR number to check'). With schema description coverage at 50%, the tool description adds no extra meaning for 'projectId' and fails to compensate for its lack of documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Check whether an ADR has drifted from the actual codebase.' It specifies the return (ADR content + affects_paths) and outlines the agent's follow-up actions. However, it does not explicitly differentiate this tool from siblings like knowledge_check_flow or knowledge_check_resolve.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It only contains post-call instructions for the agent, such as comparing the ADR to code and returning a drift report, but lacks before-use context or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry behavioral disclosure. It describes the tool as returning information, implying no side effects, but does not explicitly state read-only behavior or other traits.
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 two sentences and front-loads the purpose, but it omits parameter details, which would be expected even in a concise format.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a single parameter with zero schema coverage, no output schema, and no annotations, the description is incomplete. It explains the output but not the input, and does not cover error conditions or usage nuances.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the tool description does not mention the single parameter 'projectId' at all. No explanation of its purpose, format, or behavior if omitted.
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 it returns a brief overview of project knowledge, listing specific contents (assets per type, top-tagged categories, recent updates). The phrase 'project primer' distinguishes it from sibling tools like wiki_get_briefing or wiki_get_flow_context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Useful as a project primer' implies when to use (quick overview), but there is no mention of when not to use or explicit alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/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 only states the return content but does not disclose whether the tool is read-only, has side effects, or requires permissions. For a read operation, this is a significant gap.
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 is two sentences with no extraneous information. The first sentence defines the tool's purpose, and the second provides a use case. It is front-loaded and efficient.
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?
The input schema is simple (one param), and no output schema exists. The description lists the returned items but does not hint at the output structure (e.g., list format, object shape). It is adequate for a simple tool but could be more complete regarding output details.
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 one parameter (flowId) with no description and 0% schema coverage. The description does not explain the parameter's meaning or expected format beyond the name 'flowId'. Since the tool is about flow context, the parameter is somewhat self-explanatory, but more guidance would be helpful.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Return') and the resource ('compact context briefing for a flow') and specifies the contents (outgoing wiki links, backlinks, tags). It differentiates from siblings like wiki_get_briefing by focusing on flow context, but the distinction is not explicit.
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 explicitly says 'Use this before writing a plan to pull relevant ADRs/Patterns automatically,' providing a clear when-to-use scenario. However, it does not mention when not to use it or suggest alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It only mentions that all fields are optional for partial updates, but omits details like what happens if docId is missing, error handling, or whether the update is idempotent. The description is insufficient for an update operation.
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 is extremely concise with just three sentences, each serving a distinct purpose: stating the action, clarifying optional fields, and providing a prerequisite. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 5 parameters with no output schema and no annotations. The description covers only the basic update functionality and the need to find docId, but does not explain return values, error conditions, or the effect of omitting projectId. Lack of output schema and behavioral details makes this incomplete for an agent to fully understand the tool's behavior.
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?
The input schema has 100% description coverage for all 5 parameters, so the schema already defines parameter semantics. The description adds the note 'All fields are optional', which reinforces that only docId is required, but does not provide additional meaning beyond what is in the 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?
The description clearly states 'Update an existing documentation page' with a specific verb and resource. It distinguishes from siblings like doc_page_create, doc_page_delete, doc_page_get, and doc_page_list in the context signals.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises 'Use doc_page_list first to find the page ID', providing a prerequisite hint. However, it does not specify when to use this tool versus alternatives like doc_page_create when the page doesn't exist, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full behavioral burden. It only states the status change but fails to disclose permissions, reversibility, side effects, or validation of transitions.
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 concise sentences: first states purpose and allowed transitions, second gives usage context. No superfluous information.
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?
The tool is simple but incomplete: no output schema description, no mention of transition validation (e.g., can status skip steps?), and no error conditions. The presence of sibling adr_accept suggests missing usage nuance.
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 50% (only status described). The description adds the transition path for status but does not clarify adrId format or constraints, partially compensating for the coverage gap.
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 'Change' and resource 'ADR status', and explicitly lists the allowed transitions (proposed → accepted → deprecated → superseded), making the tool's purpose clear and distinct from siblings like adr_accept.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides when to use ('when an architectural decision is formally accepted, deprecated, or replaced') but does not mention alternatives or when not to use it (e.g., adr_accept might be simpler for pure acceptance).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes validation requirements and rejection behavior (structured 400). No annotations provided, so description carries burden. Missing output or side-effect details like created flow ID or notifications.
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?
Concise, well-structured with bullet points for requirements. Every sentence adds value. No fluff.
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?
Covers validation rules, default state, and prerequisite. Missing output description (no output schema), and the projectId contradiction reduces completeness. Adequate but not robust.
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?
Adds context on metadata triple and practical tips beyond schema. However, description says 'Requires a projectId' while schema lists projectId as optional, creating a contradiction that undermines trust.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it creates a flow in a project and lists use cases (feature requests, bug reports, tasks). It is specific but does not distinguish from sibling 'task_create', which may cause confusion.
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?
Provides explicit instructions on when to use, default state ('idea'), and character limits for fields. Also advises to use 'project_list' to find projectId. Lacks exclusion criteria or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fails to disclose important behavioral traits such as whether the update is a full replacement or partial patch, idempotency, prerequisites, or side effects. It merely restates that it 'change[s]' fields, adding little beyond the 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 is exceptionally concise with two sentences: one stating the action and one listing the modifiable fields. No extraneous information, and the purpose is front-loaded.
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 the complexity (5 parameters, no output schema), the description adequately differentiates from siblings but lacks information about return values or behavior after update. It is minimally complete for a simple update tool, but could be improved with output hints.
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?
The input schema has 100% coverage, so the description needs only to add value beyond the schema. It lists the same fields as the schema without providing additional format or constraint details, resulting in no net gain.
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 'Update an existing release' and lists the specific fields (name, description, status, target date) that can be changed, making the tool's purpose unambiguous and distinct from sibling tools like release_create or release_get.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for updating release properties but does not explicitly provide when-not-to-use scenarios or alternatives. The presence of sibling tools suggests differentiation, but no direct guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It fails to mention whether the task is created immediately, validation rules, idempotency, or errors. It also does not describe the return value or side effects.
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 a concise paragraph followed by bullet points. It is front-loaded with purpose and clear. However, some redundancy with the schema could be trimmed without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description does not explain the tool's response or output behavior. Since there is no output schema, the agent lacks information on whether the created task is returned or just a success indicator. It also omits details like required permissions or flow existence checks.
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?
The input schema covers 100% of parameters with descriptions. The description adds minimal extra meaning beyond listing fields (e.g., 'Summary (required)') and restates schema info. The 'Parent task' note is already in the schema's parentId 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 clearly states 'Create a new task under a flow,' specifying the action and resource. It differentiates from sibling tools like task_list and task_update by focusing on creation.
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 advises using the tool to 'break down a flow into smaller, trackable steps' and adds a best practice about creating tasks before implementation. However, it does not explicitly compare to alternatives or specify when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It discloses that the tool returns the full release with specific fields, implying a read-only operation, but it does not explicitly state side effects, permissions, or behavior on invalid IDs.
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 no wasted words; purpose and return fields are front-loaded and clear.
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 simple get-by-ID tool with one parameter and no output schema, the description covers the main purpose and return fields. However, it could mention error handling or existence of the release.
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%, and the description does not add any additional meaning beyond the schema's parameter description. Baseline 3 is appropriate.
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 verb 'Get' and resource 'release', and the list of return fields differentiates it from sibling tools like 'release_list' and 'release_update'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It only states 'Delete,' which is implied by the name, but does not disclose any behavioral traits such as irreversibility, permissions required, or side effects.
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, no redundancy. Each sentence adds value: the first states the purpose, the second provides a usage hint.
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 simple 2-parameter delete tool with no output schema and no annotations, the description is minimally adequate. It states the purpose and provides a prerequisite hint, but could elaborate on consequences of deletion.
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?
The description adds no parameter details beyond what the input schema provides, and schema coverage is 100%. Baseline score of 3 is appropriate.
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 'Delete a documentation page,' which is a specific verb-resource pair. It distinguishes itself from sibling tools like doc_page_create, doc_page_get, doc_page_list, and doc_page_update.
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 a usage hint: 'Use doc_page_list first to find the page ID.' This guides the agent on a prerequisite step, though it does not explicitly state when not 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It mentions that files become visible in the DevFlow UI and accessible to other agents, and that kind='plan' links the file. However, it omits details on idempotency, overwriting behavior, error handling, and how current flow is determined when flowId is omitted.
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?
Description is well-structured: a single clear sentence followed by bullet points of common use cases. It is not overly verbose, though some redundancy could be trimmed.
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?
No output schema is present, yet the description does not mention what the tool returns (e.g., a success flag or object ID). It also lacks details on error scenarios. For a simple upload tool, the description is mostly adequate but leaves some gaps.
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%, baseline 3. The description adds value by explaining each enum value for 'kind' and noting that flowId defaults to current flow. This provides more context than the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool uploads a file as an attachment to the current flow and lists supported file types. However, it does not differentiate from the similarly named sibling 'flow_upload_file', which could cause confusion.
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?
Provides explicit use cases for different 'kind' values (plan, summary, design, decision, notes). The agent can easily determine when to use this tool for text-based files. It lacks guidance on when not to use it (e.g., for binary files) or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full burden. It only states basic functionality (list drafts with optional filter) but does not disclose any behavioral traits like authentication requirements, return format, or side effects. As a read operation, minimal disclosure is acceptable, but more detail would help.
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 is two sentences long, front-loads the core action, and contains no extraneous words. Every sentence earns its place.
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 simple list tool with two parameters and no output schema, the description covers the essential use case. However, it lacks details about the return format (e.g., what fields are in each draft) and pagination, which would improve completeness.
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 0%, but the description adds meaning beyond the schema by explaining the status filter's purpose and usage context. However, it does not explain the projectId parameter's format or necessity, leaving some ambiguity.
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 'List knowledge drafts for a project' using a specific verb and resource. It distinguishes from sibling tools like knowledge_draft_create, knowledge_draft_accept by focusing on listing existing drafts.
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 explicitly advises using this tool before proposing new drafts to avoid duplicates, providing clear contextual guidance. However, it does not explicitly state when not to use it or compare with other listing tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It only states the action without disclosing side effects, prerequisites, or what happens to existing connections. For a mutation tool, more transparency is needed.
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 concise sentences, first providing the action and second the usage context. No fluff, every sentence adds value.
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 simple tool with fully described parameters, the description covers purpose and usage adequately. It lacks return value info but that is acceptable without an output schema.
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%, so the schema itself documents parameters well. The description adds little extra meaning beyond stating the overall action, not elaborating on parameter roles or interactions.
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 'Connect' and identifies the resource 'this project to DevFlow'. It clearly distinguishes from siblings like devflow_disconnect and devflow_init by focusing on linking the current directory to a DevFlow project.
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 'Use when you want to start using DevFlow in this directory', providing clear context for use. However, it does not explicitly exclude cases or name alternatives, leaving a slight gap in guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description outlines what the tool does (pulls runbooks, ADRs, recent flows, etc.) and mentions a 'briefing-Markdown' output. However, it lacks disclosures about behavior when no matches are found, required permissions, or side effects. With no annotations, this is an average level of transparency.
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 relatively concise and front-loaded with the purpose. It uses a title-like opening and then guidelines. However, it includes jargon like 'DF-316' and 'devflow-error-investigator skill' that may not be universally understood. Overall, it is well-structured but could be slightly more streamlined.
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 5 optional parameters and no output schema, the description adequately explains when and why to use it. It mentions the output type ('briefing-Markdown') but does not detail the structure or content of the response. With no output schema, more detail on return values would improve completeness.
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?
The input schema has 80% description coverage for parameters, so the bar is higher. The description adds context by implying that errorMessage and stackTrace are used for matching, but does not elaborate on parameter formats or constraints beyond what the schema already provides. It meets the baseline.
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's purpose as an 'Error-Driven Wiki Lookup' that pulls relevant wiki signals such as matching runbooks, ADRs, and recent flows when an error occurs. It distinguishes itself from sibling wiki tools by focusing specifically on error context.
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 explicitly tells agents to call this tool first when encountering an unexpected error, referencing a specific skill (devflow-error-investigator). It also provides a post-usage guideline about writing a runbook if none match. However, it does not explicitly compare with alternatives or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral transparency burden. It states the tool returns data (flow text + ADR snapshots + instructions) and does not create drafts, implying read-only behavior. However, it does not explicitly confirm that no data is modified, leaving some uncertainty.
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 is three sentences, front-loaded with the action and purpose, followed by key details. Every sentence adds value without redundancy or unnecessary words.
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?
The description covers the tool's purpose, usage, and return types (flow text, ADR snapshots, instructions). However, without an output schema, it does not detail the format of the returned data, and the single parameter is not explained. For a simple one-parameter tool this is acceptable but leaves room for improvement.
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 input schema has 0% description coverage, so the description should compensate for the parameter 'flowId'. The description mentions 'Run a knowledge check on a flow' but does not define what a flowId is or how to obtain one, leaving the agent to infer its meaning.
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's action: 'Run a knowledge check on a flow' specifying it spots drift and identifies missing knowledge. It distinguishes from siblings like knowledge_check_drift by combining both analyses and explicitly noting no draft creation.
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: 'Use before submitting a flow to review.' It also clarifies what the tool does not do ('no draft creation'), implying when not to use it, but does not name specific alternative tools for draft creation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 covers the basic update behavior but omits potential side effects, authorization needs, or error scenarios. The description is adequate but not comprehensive.
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 concise with bullet points and front-loaded main purpose. The last sentence is slightly redundant with a bullet point, but overall well-structured.
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 mutation tool with 6 parameters and no output schema, the description covers common use cases but lacks details on return values, error handling, or state changes. It is sufficient but not fully complete.
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?
All 6 parameters are described in the schema (100% coverage). The description adds context like 'Mark tasks as completed when done' but mostly repeats schema information. Baseline 3 is appropriate.
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 'Update a task's status or details' and provides specific bullet points for common use cases, distinguishing it from sibling tools like task_create and task_list.
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 explicitly lists when to use the tool with 'Use this to:' bullet points, but does not mention alternatives or when not to use it. The sibling list implicitly provides contrast.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description conveys a read-only operation but lacks details on whether all backlinks are returned, pagination, or data freshness. Since no annotations are provided, the description carries the full burden, and more behavioral context would be beneficial.
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, no fluff, directly to the point. Every sentence adds value.
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 and a simple 2-param input, the description adequately explains the tool's purpose but omits return value details. For a low-complexity tool, this is acceptable but could be more complete.
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?
Only assetType has a description in the schema (listing allowed values), but assetId is left undocumented. The tool description does not explain assetId format or provenance, leaving a gap for agents.
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 defines the tool as a reverse lookup to find assets linking to a given asset, and provides concrete examples (ADRs, Patterns). It distinguishes itself from siblings like wiki_graph_neighbors and search.
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 indicates usefulness for seeing where an ADR or Pattern is referenced, implying when to use it. However, it does not explicitly state when to avoid this tool or mention alternatives among the many sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses logging to an active session, supports levels, and default behavior. However, it does not specify error handling (e.g., invalid session ID) or any side effects, which are minor gaps for a logging 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?
The description is concise with three short, well-structured paragraphs. Every sentence adds information: purpose, usage context, and parameter details. No fluff or redundancy.
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 simple logging tool with full schema coverage and no output schema, the description adequately covers purpose, usage, and parameters. It does not discuss return values or error scenarios, but these are not critical for this tool's function.
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%, and the description adds value by explaining the meanings of each log level ('info: General progress updates', etc.) beyond the enum definitions in the schema. This helps the agent choose the appropriate level.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Log a message to an active agent session' and explains use cases (record progress, decisions, issues). However, it does not explicitly distinguish from sibling tools like agent_session_complete or agent_session_create, though the purpose is self-evident.
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 context for when to use the tool ('use this to record progress, decisions, or issues during a work session') and explains log levels with examples. It lacks explicit guidance on when not to use it or alternatives, but the provided context is sufficient for a simple logging tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It describes what is returned but does not disclose any behavioral traits such as permissions needed, side effects, error cases, or read-only nature. The word 'Get' implies a read operation, but it could be more explicit.
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 a clear introductory sentence and a bullet list of return fields. It is concise enough to be easily parsed, but the bullet list adds some length. Still, it is efficient for the information provided.
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 tool has one parameter and no output schema, the description adequately covers the return fields and usage context. It could mention potential errors (e.g., flow not found) but is otherwise complete for a straightforward retrieval operation.
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 required parameter 'flowId'. The schema itself already describes it as 'The flow ID (e.g., "abc123" or full ID)'. The description adds no additional value beyond what is in the schema, so baseline score applies.
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 it retrieves detailed information about a specific flow, listing the exact fields returned (summary, description, acceptance criteria, etc.). This distinguishes it from sibling tools like flow_list (list all flows) and flow_create (create a new flow).
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 explicitly advises to use this tool before starting work on a flow to understand requirements. It provides clear context for when to use it, though it does not mention when not to use it or provide explicit alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the output structure (name, icon, counts, prompt) and a usage flow (user pastes prompt into chat). However, it omits behavioral traits such as side effects, authorization needs, or behavior when projectId is omitted, limiting transparency.
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 mostly concise with two sentences and a list of area components. The inclusion of 'DF-318 — Idea-Prompt-Garage' adds minor noise but does not significantly impair readability. The key action is front-loaded.
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 tool has one optional parameter and no output schema, the description provides a solid overview of return value usage. It lacks explicit details on output format or filtering, but overall it is sufficient for a simple retrieval tool.
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% for the single parameter (projectId), so the schema already documents its meaning. The description does not add any additional parameter semantics, such as default behavior or impact, which is acceptable at baseline 3.
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 returns curated prompts per area with wiki-evidence, specifying the exact purpose: to provide grounded next-step ideas instead of brainstorming from scratch. The resource (prompts per area) and action (returns) are specific and differentiate it from siblings like 'ideas_get'.
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 offers usage guidance by recommending use 'to find well-grounded next-step ideas instead of brainstorming from scratch.' However, it does not explicitly state when not to use the tool or compare it to alternative tools like 'ideas_get', so it lacks full situational context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility. It reveals an important behavior: 'Automatically uses the linked project if no projectId is provided.' However, it does not mention other behaviors like potential side effects, permissions, or return values, which is a gap but keeps the description minimally viable.
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, no wasted words. The main action and key behavior are front-loaded, and the description is efficient. Every sentence earns its place.
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?
The description covers the creation intent and the project fallback behavior. However, it omits any mention of what the tool returns (e.g., the created release object) since no output schema is provided. Given the lack of output schema and the presence of 4 parameters, the description is adequate but could be more complete.
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%, so each parameter is already documented. The description adds value only for projectId by explaining automatic project fallback. Other parameters (name, description, targetDate) rely solely on the schema. This minor addition maintains the baseline of 3.
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 'Create a new release for a project' and specifies it is used to 'plan a new version or milestone.' This is a specific verb+resource pair, and the sibling tools (release_get, release_list, release_update) are distinct actions, making the tool's purpose unambiguous.
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 explicitly says 'Use this to plan a new version or milestone,' providing clear context for when to use the tool. It does not mention when not to use it or point to alternatives like release_update, but the intent is well-defined and sufficient for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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. It describes the output (curated set of related items) but does not explicitly state that the tool is read-only or disclose any side effects, permissions, or rate limits. The name implies a get operation, but the description lacks explicit behavioral notes beyond the output content.
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 two paragraphs: first explaining what the tool does, second giving usage guidance. It is front-loaded with the core purpose. The code prefix 'DF-310' may be unnecessary for an agent, but overall it is efficient and well-structured with minimal waste.
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 simple single-parameter input and no output schema, the description adequately explains the return content (ADRs, patterns, runbooks, intents, parallel work, knowledge gaps). It references the UI tab for additional context. For a retrieval tool of this complexity, the description is sufficiently complete, though it could mention any pagination or size limits.
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?
The only parameter 'flowId' is fully documented in the schema with description 'Flow id to build the briefing for' (100% coverage). The description does not add any extra semantics like format, examples, or constraints beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns a curated set of related items (ADRs, patterns, etc.) for a specific flow, with a clear verb 'get' and resource 'briefing'. It mentions that this is the same data as the UI's Knowledge-Tab, which provides context, but doesn't explicitly differentiate from sibling tools like wiki_get_flow_context or wiki_get_project_context, though the usage hint helps.
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?
The description explicitly says 'Use this in planning + before review→done' and explains the purpose: to make sure the flow's plan respects the existing wiki and to find gaps that should be closed, preferably via 'extend' referencing knowledge_check_resolve. This provides clear when-to-use guidance and an alternative action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It mentions returning the asset with backlinks, but does not disclose error behavior, authentication needs, or rate limits. It does not contradict any annotations.
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 short, front-loaded sentences that convey the core purpose and parameter options without excess. Every word earns its place.
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, the description should explain the return value more fully. It says 'return it with backlinks' but omits structure, which is insufficient for a tool that resolves multiple asset types.
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 50% (only 'raw' has a description). The description adds concrete examples of valid values (slug, title, display_id), increasing clarity beyond the schema. However, it does not describe 'projectId'.
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 resolves a wiki reference (slug, title, or display_id) to a concrete asset and returns it with backlinks. This distinguishes it from siblings like wiki_search, doc_page_get, and wiki_backlinks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides examples of what 'raw' can be (slug, title, display_id), which implies when to use this tool, but it does not explicitly compare with alternatives like doc_page_get or adr_get, nor does it specify when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility. It discloses key behaviors: auto-assignment of next ADR number, copying frontmatter, linking back to the flow, and idempotency. These go beyond the minimal expectation for a creation 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?
The description is three sentences, each adding distinct value: purpose, behavior, and idempotency guarantee. No unnecessary words or redundancy.
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 simple acceptance tool with no output schema, the description covers the core workflow and idempotency. It lacks details on return format but is sufficient for basic understanding. A brief mention of error cases would improve completeness.
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 75%, with three parameters having descriptions in the schema. The description does not add new meaning to the parameters beyond what the schema provides, and the undocumented projectId parameter is not clarified. Baseline 3 is appropriate.
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 specific action ('Accept a decision.md flow-attachment as an official ADR'), which distinguishes it from sibling tools like adr_get, adr_list, and adr_update_status. The verb-resource combination is precise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (to convert a flow attachment to an ADR) but provides no explicit guidance on when not to use it or what alternatives exist. Given multiple related sibling tools, more context would help.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description carries burden. It states the tool completes a session (mutation), but lacks details on side effects (e.g., whether session is archived, if logs are affected). Adequate but minimal.
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 concise sentences: action, usage guidance, parameter note. No wasted words, front-loaded with purpose.
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?
Covers purpose, usage, and parameters adequately. No output schema or annotations, so the description is sufficient for agent to select and invoke correctly.
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% with descriptions. The description adds 'Optionally provide a summary' which clarifies optionality, but doesn't add much 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?
The description clearly states 'Complete an active agent session' with a specific verb and resource, distinguishing it from siblings like create, list, log.
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?
Provides explicit guidance: 'Use this when you're done with a unit of work to mark the session as finished.' It implies when to use but doesn't directly exclude alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It states returns include status, timing, and summary, which adds value. However, it does not disclose pagination, sorting, rate limits, or potential side effects, which are common for list operations.
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, each adding value: first states action, second clarifies output and usage. No redundant information.
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 simple input schema and no output schema, the description provides key output fields and usage context. It lacks error handling info, but for a listing tool, it is sufficiently complete.
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% for the single parameter flowId, providing its purpose. The tool description does not add extra detail beyond that, meeting the baseline of 3.
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 lists agent sessions for a flow, which is a specific verb-resource pair. It distinguishes from siblings like agent_session_create or agent_session_log by focusing on listing all sessions.
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?
It explicitly says 'Use this to review past work sessions on a flow,' providing clear context. No alternatives or when-not-to-use are mentioned, but the usage is unambiguous given sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It states the operation is a get and lists return fields, but does not mention side effects, error behavior, or permissions. For a simple read tool, this is adequate but minimal.
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, front-loaded with the action. Every sentence adds value: what it does, what it returns, and how to prepare. No wasted words.
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 simple get tool without output schema, the description covers return fields and a prerequisite step. It is complete enough for the agent to understand inputs and outputs, though it could mention error cases.
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%, so baseline is 3. The description does not add extra meaning beyond the schema; it repeats 'page ID' but gives no format or validation details.
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 'Get a single documentation page with its full content', specifying the verb and resource. It lists return fields (title, section, content, tags, metadata), distinguishing it from sibling tools like doc_page_list which list pages.
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?
Provides explicit guidance: 'Use doc_page_list first to find the page ID.' This tells the agent the prerequisite step, though it does not mention alternative tools or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It explains the context and importance of feedback but does not state whether the operation is read-only, any side effects, or authentication requirements. It implies a safe read operation but does not explicitly confirm.
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 is three sentences long and front-loaded with the core purpose. Every sentence adds value: the first defines the action, the second specifies when to use, and the third provides actionable guidance. No unnecessary words or fluff.
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 tool's simplicity (single parameter, straightforward purpose), the description adequately covers the context of use and the expected action upon receiving feedback. It does not detail the return format, but given the absence of an output schema, this is acceptable. The description is sufficient for an agent to decide when and how to use the tool.
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?
The schema covers the single parameter flowId with a description. The tool description adds context about why the flow ID is used (to retrieve feedback) but does not add additional semantic meaning beyond the schema. Since schema coverage is 100%, a baseline score of 3 is appropriate.
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's purpose: retrieving user feedback for a flow. It specifies the resource ('flow') and the action ('get feedback'). It further distinguishes usage scenarios by mentioning specific phases (implementation plan approval, code review rejection), which helps differentiate it from other tools like flow_comments_get.
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 guidance on when to use the tool: at the start of a session, and for specific feedback types. It also instructs the agent to address feedback before continuing. However, it does not mention alternatives or situations where the tool should not be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It explains the output format (prefilledSummary and prefilledDescription) and that it is a read operation. However, it does not explicitly state read-only or discuss side effects, permissions, or limitations. Adequate but could be more explicit.
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 relatively long but well-structured with bullet points and front-loaded purpose. Every sentence provides value and is informative without being wasteful.
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 no output schema, the description sufficiently explains the content and purpose of the tool. It covers what each item contains (prefilledSummary + prefilledDescription) and the context of use, making it complete for an agent to understand and apply correctly.
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%, so baseline is 3. The description does not add additional meaning to the projectId parameter beyond what the schema already provides. No extra value added.
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 aggregates 5 organic idea sources from the wiki into a curated pipeline, listing each source and explaining its purpose. It is specific and distinguishes itself from sibling tools like idea_prompts_get.
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 explicitly states to use this tool to pick the next thing to work on without staring at a blank page, and mentions the output is ready for flow_create. It implies when to use but does not explicitly exclude alternatives, though it is clear enough given context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the burden. It discloses that rejected drafts are remembered and dedup avoids re-proposing, but doesn't mention side effects, permissions, or reversibility.
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 concise sentences: first states purpose, second adds key behavioral context. No wasted words.
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 simple tool with 2 params and no output schema, the description covers core purpose and a key behavioral effect. Lacks return value details but is fairly complete.
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?
With 100% schema coverage, the description adds minimal value beyond the schema (e.g., notes are optional). Baseline 3 is appropriate.
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 verb 'Reject' and the resource 'a draft', and adds a behavioral note about dedup that distinguishes it from siblings like accept or create.
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?
It explains when to use (reject a draft with optional notes) and implies the dedup behavior, but does not explicitly state when not to use or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must carry the burden. It does not disclose any behavioral traits such as read-only nature, permissions, rate limits, or error conditions. The description focuses on output structure but lacks safety or side-effect info.
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?
Extremely concise: two sentences plus key info about output fields. Front-loaded with purpose and grouping, no redundant words.
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 simple tool with one optional parameter and no output schema, the description adequately lists output fields. Lacks pagination or filtering details, but completeness is high given tool simplicity.
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% with parameter description for projectId. The description does not add extra semantics beyond the schema, meeting baseline expectation.
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 returns a hierarchical TOC grouped by lifecycle_stage, listing specific fields. It distinguishes itself from sibling wiki_get_briefing as the global counterpart.
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 says 'Use this for what does the wiki actually contain' and contrasts with wiki_get_briefing (per-flow), providing clear when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only states the action and return format, omitting whether the operation is read-only, idempotent, or requires specific permissions. However, as a list operation, it is likely safe, but this is implicit.
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 concise sentences front-load the main purpose and return shape. Every word is informative.
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 no output schema, the description adequately explains the return fields. It lacks details on pagination, error cases, or sorting, but for a simple listing tool, the information is largely sufficient.
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?
The description elaborates on the documentType parameter by listing allowed values, adding value beyond the schema's example. However, it does not describe projectId, leaving its purpose unclear. With schema coverage at 50%, the description partially compensates.
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 states that the tool lists all wiki assets of a specific document_type, enumerating valid types (adr, pattern, runbook, customer_context, glossary) and the returned fields (id, title, slug, verified_state). This clearly distinguishes it from sibling tools like wiki_search or adr_list.
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 clearly indicates when to use the tool (to list wiki assets by type) but does not explicitly contrast with sibling tools or state when not to use it, such as preferring adr_list for ADRs or wiki_search for broader search.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses technical detail (SQLite FTS5 with prefix matching) and return format (title + snippet). However, does not mention read-only nature, rate limits, or permissions. Adequate but could be more comprehensive.
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: purpose and scope, technical detail, usage guidance. Each sentence adds essential information with no redundancy. Efficient and well-organized.
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?
No output schema; description explains return values ('title + snippet') and covers assets searched. Does not detail pagination or ordering, but limit parameter is in schema. Sufficient for a search tool with good schema coverage.
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% with descriptions for all three parameters. Description adds context for 'q' by stating full-text search over wiki assets, but does not significantly enhance parameter understanding beyond schema. Baseline score of 3 is appropriate.
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 performs full-text search over specific wiki assets (flows, doc_pages, reviews, releases). It uses precise verb 'search' and lists the resource types, distinguishing it from sibling tools like 'wiki_get_page' or 'search'.
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?
Provides explicit when-to-use scenarios ('when the user asks what we know about X', 'to find relevant ADRs/Patterns/Runbooks before planning'). Does not mention when not to use or compare to alternatives like 'search', but gives clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that the tool creates a session and returns its ID, but does not mention side effects, permissions, or error conditions. For a creation tool, this is adequate but not comprehensive.
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 is three concise sentences: purpose, concept explanation, and usage guidance with return info. Every sentence adds value without redundancy.
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 simplicity of the tool (2 params, no output schema), the description covers the purpose, usage context, and return value. It explains the lifecycle (start, log, complete) sufficiently for an agent.
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%, so the schema already describes both parameters (flowId required, type optional). The description adds context about the session tracking purpose but no additional parameter detail beyond the 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?
The description explicitly states 'Create a new agent session for a flow', which is a specific verb+resource combination. It clearly differentiates from sibling tools like agent_session_complete and agent_session_log by focusing on creation.
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 advises using this tool 'at the start of a work session to log what you're doing', providing direct when-to-use guidance. It also mentions subsequent calls (log, complete), implying when not to use it (e.g., after work is done).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the mutation (sets status, links flow) and the effect on pending_work/planning_context. However, it does not cover reversibility, error handling, or permissions, which would be helpful for a mutation tool.
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 two paragraphs, the first sentence is direct. Some background on forward-intents is included but it is relevant for understanding. It is efficient without being overly verbose.
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 complexity of the domain (forward-intents, flows) and no output schema, the description provides sufficient context: explains what forward-intents are, when to use, and the effect. It could mention error cases but overall is complete.
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?
Input schema already has 100% coverage with descriptions. The description adds value by clarifying that flowId is 'typically your current flow' and that pageId comes from pending_work, plus explaining the optional note. This goes beyond the 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?
The description clearly states the tool's action: 'Close a forward-intent page' and specifies the effect ('Sets frontmatter.status='resolved' and links the resolving flow'). It distinguishes from sibling tools like doc_page_update and pending_work by explaining the specific intent-closing functionality.
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 explicitly advises when to use: 'When your current flow actually delivers that follow-up, call this tool so the loop is closed.' It also tells where to find the pageId ('via pending_work → openIntents'). It does not include explicit 'when not to use' but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 states the return format (completion status, hierarchy) and implies a read operation, but lacks details on pagination, limits, or authentication requirements.
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 is concise (three sentences), front-loaded with the main action, and contains no superfluous information.
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 simple list tool with one parameter and no output schema, the description covers purpose, return type, and relationship to flows completely. No further information is needed.
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% with a clear description for flowId. The tool description does not add additional meaning beyond the schema, so baseline score of 3 is appropriate.
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 verb 'list', the resource 'tasks for a flow', and the returned data (completion status and hierarchy). It distinguishes from sibling tools like task_create and task_update.
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 clear usage context: list tasks for a flow. It does not explicitly mention when not to use or alternatives, but as the only tool for listing tasks, the guidance is implicit and adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses it returns mutation events within a time window, default 30 days, max 365. No annotations provided, but description is clear about its read-only nature.
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?
Concise, three sentences, front-loaded with purpose, no unnecessary words.
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?
Lacks output format details; no output schema provided. Adequate for low complexity tool but missing return value description.
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?
Adds context for 'days' parameter (default and max), but does not explain 'projectId'. Schema coverage 50%, description partly compensates.
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?
Clearly states it is a chronological mutation feed of the wiki, lists specific mutation types, and distinguishes from sibling tools like wiki_get_page.
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?
Describes when to use ('what's been happening to the wiki recently' driving the Activity-Tab), but does not specify when not to use or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It adds the auto-linking project behavior, which is helpful. But it does not mention side effects, permissions, or what happens if a page with the same title exists, leaving some uncertainty.
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 is concise at 4 sentences, with no wasted words. It is front-loaded with the main purpose.
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 creation tool, the description covers the essentials: what it creates, how pages are organized, and the auto-linking behavior. It lacks an explicit statement about return value or error conditions, but given the high schema coverage, it is reasonably complete.
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 each parameter already has a description. The description adds value by giving examples of section names and stating content is in markdown, going beyond the 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?
The description clearly states the action (create), resource (documentation page), and context (in a project). It is specific and distinguishes from sibling tools like doc_page_get, doc_page_update, etc.
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 explains when to use the tool ('add new knowledge, guides, or documentation') and includes a key behavioral note about automatically using the linked project if projectId is omitted. However, it does not explicitly state when not to use or list alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
In the absence of annotations, the description thoroughly discloses behavioral traits: output is a Markdown table, conventions (star prefix for user's flows, lock marker for active sessions), default hiding of done-flows, and ordering logic. This fully compensates for missing annotations.
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 concise with two short paragraphs. The first line immediately states the purpose. The second paragraph adds necessary convention details without fluff. It could be slightly more concise but is well-structured.
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?
Despite no output schema, the description specifies the output format (Markdown table with columns). It covers defaults, filtering options, ordering, and usage intent. For a list tool, this provides sufficient context for correct invocation.
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 description coverage, baseline is 3. The description adds value by explaining the Markdown table format and the default behavior of includeDone (hidden by default). It also reinforces the meaning of the 'mine' parameter with the star prefix convention.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that this tool 'List flows as a Markdown table' with specific columns. It distinguishes itself from other tools like flow_get or flow_create by focusing on listing, but does not explicitly differentiate from sibling listing tools.
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 explicitly states 'Use this to find flows to work on or to brief the user on the backlog.' This provides clear usage context. It also mentions the default hiding of done-flows and the includeDone parameter, but does not exclude alternatives or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that only existing tags are suggested to avoid tag proliferation (tag-wildwuchs), and returns suggestions ranked by confidence with matchedTokens. This provides sufficient behavioral insight for a suggestion 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?
The description is three sentences long, each serving a clear purpose: stating the algorithm and constraint, giving usage context, and clarifying a parameter's purpose. It is front-loaded with the most important information and contains no filler.
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?
The description covers the input parameters (through schema), usage context, and return format (ranked suggestions with confidence and matchedTokens). It lacks details on edge cases like empty tag pools or low-confidence results, but overall it is sufficient for an AI agent to invoke the tool correctly.
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%, so the schema already documents all parameters. The description adds value by explaining the role of existingTags in excluding already-applied tags, but other parameters (content, projectId, limit) are already well-described in the schema. Thus, it adds moderate value beyond the 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?
The description clearly states it suggests project tags using TF-IDF against the existing pool, and explicitly says it never invents new tags. This provides a specific verb and resource, and differentiates it from sibling tools like knowledge_harvest or search.
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 advises using it when writing new doc-pages, ADRs, or flow summaries for consistent tagging. It also explains passing existingTags to exclude already-applied tags, offering clear usage context. It does not explicitly state when not to use it or mention alternatives, but the guidance is adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses return data: 'Returns the flow + existing ADRs + related drafts + instructions.' However, it does not state whether the tool is read-only or if it has side effects. The lack of annotation or explicit safety info keeps this at a mid score.
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 is concise (two sentences plus a decision directive), front-loaded with purpose, and every sentence adds value. No redundant information.
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 tool's simplicity (single param, no output schema), the description is largely complete. It explains when to use, what it returns, and next steps. A minor gap is the lack of detail on 'harvest' mechanics, but this is sufficient for the workflow context.
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?
The only parameter 'flowId' has full schema description coverage (100%) with the note 'must be in done state'. The tool description adds no additional meaning beyond the schema, so baseline 3 is appropriate.
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's purpose: 'Harvest knowledge from a single done-flow.' It specifies the action (harvest), resource (knowledge from a done-flow), and implicitly distinguishes from siblings like knowledge_draft_create by framing it as a preceding step.
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?
Explicit when to use: 'Call this right after flow_update transitions a flow to done.' Also provides decision guidance: 'Decide: does this flow warrant a new draft? If yes, call knowledge_draft_create. If the theme is already covered, skip.' This clearly indicates when to use alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given no annotations, the description transparently states the tool returns full content, status, supersedes chain, and originated flow. It does not disclose missing details like authentication, but as a read-only operation, the disclosure is adequate.
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 is extremely concise with two sentences, no redundant words. It efficiently conveys purpose, return data, and a usage hint.
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 simple read tool with no output schema, the description fully explains what is returned and when to use it. No additional information is necessary given the tool's simplicity.
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 50%, with only the 'number' parameter having a description. The description reinforces that the tool retrieves by number but does not explain the optional 'projectId' parameter, leaving a gap. Baseline 3 is appropriate.
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 it retrieves a single ADR by its number, listing specific return fields (full content, status, supersedes chain, originated flow). It effectively distinguishes from sibling tools like adr_list, adr_accept, and adr_update_status.
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 a clear usage context: 'Use this to pull the full rationale of a specific decision before planning changes.' While it does not explicitly list when not to use it, the context is sufficient for an AI agent to infer appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description explains each action's behavior (e.g., status shows version/auth/project/heartbeat, reconnect refreshes token). No contradictions.
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?
Concise, well-structured with header and bullet points. Every sentence adds value.
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?
Complete for a status/management tool with no required params and full schema coverage. No output schema needed.
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 covers both parameters with descriptions. Description adds meaning by grouping actions and noting projectId is for link action.
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 clearly states the tool shows DevFlow MCP connection status or manages the connection, listing specific actions. It distinguishes from siblings like devflow_connect and devflow_init.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Notes it works without devflow_init, but does not explicitly state when not to use or suggest alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It transparently states that the tool does NOT return raw tokens, only metadata fields (id, skillName, createdAt, expiresAt, evidence). No behavioral ambiguities or contradictions.
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, front-loaded with purpose, followed by guidance. No unnecessary words or redundancy.
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 simple nature (single parameter, no output schema), the description adequately covers purpose, return content, and usage context.
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% with a single parameter 'flowId' described as 'Flow id'. The description adds minimal additional meaning beyond that, so baseline of 3 is appropriate.
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's purpose: listing active tokens for a flow, and explicitly distinguishes itself from emitting tokens by mentioning 'deciding whether to emit a fresh one.' It uses a specific verb and resource, differentiating from siblings like devflow_token_emit.
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 clear guidance on when to use this tool: 'Use this to check what a flow already has before deciding whether to emit a fresh one.' It implies not to use it if raw tokens are needed, but does not explicitly name an alternative or list exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/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 discloses the return content and the automatic project association behavior, which is useful context for an agent.
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 concise sentences with the key action front-loaded. No wasted words; every sentence provides relevant information.
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 simple list tool, the description covers what it does, what it returns, and the default project behavior. Without an output schema, it adequately describes the return fields.
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% and the description essentially restates the schema's parameter description about default behavior, adding no new information beyond the 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?
The description clearly states the tool lists all releases for a project, specifying the return fields and distinguishing it from siblings like release_create, release_get, and release_update.
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?
It provides guidance on automatically using the linked project when no projectId is provided, but does not explicitly state when to use alternatives like release_get for individual releases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/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 implies the tool is a read-only report by stating it returns health findings and warns not to delete entries. Although it doesn't explicitly declare read-only or discuss rate limits/auth, the context makes the behavior clear enough.
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 efficient with two paragraphs: first defines the purpose, second gives usage advice. It includes a minor internal reference ('DF-312') that is not essential, but overall it is well-structured and front-loaded. Nearly every sentence adds value.
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 tool has two parameters, no output schema, and no annotations, the description covers the main use cases and constraints. It explains the three issue categories and provides resolution guidance. However, it lacks details on the output format and could better explain the projectId parameter.
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 only 50% (staleDays has a description, projectId does not). The description clarifies that 'stale' entries are 'release-stage entries older than N days', connecting to staleDays, but does not explain projectId. This adds some value but not enough to fully compensate for the missing 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?
The description clearly states the tool returns a health report of the wiki covering three specific categories: stale, orphan, and contradictions. It uses specific verbs ('get lint') and distinguishes from sibling tools like wiki_get_index or wiki_get_page.
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?
Explicit guidance is provided: 'Use periodically (or before a major refactor) to keep the wiki clean.' It also advises against deleting entries and directs the user to a specific skill for resolving findings, effectively telling 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description discloses behavior: lists records and returns specific fields. No hidden behavior implied, adequate for a simple list 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, front-loaded with main purpose, no wasted words. Efficiently conveys all necessary information.
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?
Covers purpose, parameters, and return format. Lacks pagination or sorting details, but sufficient for a typical list operation without output schema.
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?
Description adds allowed status values (proposed, accepted, deprecated, superseded) beyond schema, which only says 'Filter by status'. ProjectId is implied by 'for a project', compensating for 50% schema coverage.
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?
Clearly states verb (List), resource (Architecture Decision Records), and scope (for a project). Includes optional filter and return fields, distinguishing it from siblings like adr_get.
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?
Provides clear context for use (listing all ADRs) but does not explicitly mention when not to use or alternatives. However, the purpose is sufficiently distinct.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/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 discloses the API endpoint, that tokens are stored in the DB, and that a subsequent flow_update will pass via implicit self-approval. However, it does not mention any potential side effects or authorization requirements, slightly reducing transparency.
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 front-loaded with the core purpose and endpoint, and uses a clear structure: main action, preferred alternative, fallback scenario. It is somewhat long due to the inclusion of ticket numbers and field details, but each sentence adds value for an AI agent deciding whether to use the tool.
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 tool has only 2 parameters and no output schema, the description is complete. It covers the purpose, usage context, fallback rationale, and the effect on subsequent flow_update calls. No further context is necessary for correct 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 coverage is 100% and both parameters are documented in the schema. The description adds minimal extra meaning beyond what the schema provides—it implies that targetState is the transition for which tokens are needed, but does not elaborate on the enum values or the format of flowId. Baseline 3 is appropriate.
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 that the tool performs 'bulk auto-emit of all discipline-tokens required for a target transition' and provides the HTTP endpoint. It distinguishes itself from sibling tools like flow_update by explicitly stating a preferred alternative (DF-435 body fields on flow_update) and positioning itself as a fallback.
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?
The description gives explicit guidance on when to use this tool: as a fallback when the body-field path is not available (e.g., older backend) or when a token is missing after a 403 discipline_incomplete error. It also states when not to use it—preferring the flow_update body fields when possible.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 clearly indicates a read-only operation ('Snapshot') and explains the contents of each of the four buckets with specific status criteria. It does not mention pagination, rate limits, or authentication requirements, but the core behavior is well covered.
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 is well-structured, starting with a clear summary sentence, followed by a bulleted list of the four buckets with definitions, and ending with usage guidance and filter details. Every sentence is informative and earns its place. It is concise yet comprehensive.
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 there is no output schema, the description adequately explains what each bucket contains and the filtering capabilities. It does not discuss result ordering, limits, or default behavior when projectId is omitted (though the schema description mentions linking). Overall, it provides sufficient context for an agent to understand and use the tool effectively.
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?
The input schema covers all four parameters with descriptions (100% coverage as given). The description adds value by explaining the purpose of the optional filters ('narrow the result to your area') and providing an example use case for excludeFlowId ('to exclude the flow you are currently planning for'). This extra context aids in correct parameter usage.
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 ('Snapshot') and resource ('open work across the project') and clearly distinguishes itself from sibling tools by aggregating four distinct types of pending work (inFlightFlows, openIntents, proposedAdrs, pendingDrafts). This makes its purpose unambiguous and unique.
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 explicitly states when to use the tool: 'BEFORE starting planning so you don't propose something already in flight or already captured as an intent.' It also provides practical usage tips for filters and excludeFlowId. However, it does not mention situations when the tool should not be used or suggest alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses returned content types, token budget, and priority-scoring. Does not mention latency or failure modes but is transparent about what it does.
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 concise paragraphs, first sentence a clear action, second sentence lists contents, second paragraph provides usage instructions. No wasted words.
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 one required param, no output schema, and no enums, the description covers return format, usage, and applicability. Some minor gaps like error handling, but overall adequate.
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?
Single parameter flowId is described in schema with sufficient detail. Tool description adds no extra semantic info beyond schema, so baseline 3 applies given 100% schema coverage.
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 'Get a compact context bundle for planning a flow' and lists specific contents (ADRs, parallel open flows, etc.). It distinguishes from siblings by advising to use this instead of scattering multiple calls.
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 says 'Call this AT THE START of planning instead of scattering wiki_search/adr_list/flow_list calls.' Provides clear when-to-use guidance and how to use the output.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/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 states it returns 'the full timeline of status transitions with user, timestamp and optional note,' which clearly explains the output. As a read operation, this is sufficient and does not contradict any annotations.
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, each with a clear purpose: first states the action, second describes the return value, third provides usage guidance. No redundant information, and the key points are front-loaded. Every word 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?
Given the simplicity of the tool (one parameter, no output schema, no nested objects), the description covers purpose, return value, and usage context completely. It leaves no ambiguity about what the tool does or when to use it.
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?
The only parameter 'adrId' has schema description 'Internal ADR id (not the display number).' This adds important context beyond the schema by clarifying what the ID represents, indicating it is not a public display number. With 100% schema coverage, the description adds meaningful additional information.
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 'Get the audit log (status change history) for an ADR.' It specifies the resource (ADR) and the exact data returned. This distinguishes it from siblings like adr_get (which likely returns the ADR itself) and adr_update_status (which changes status).
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 says 'Use this to understand why a decision moved from proposed → accepted or was later deprecated/superseded.' This gives clear context for when to use the tool. While it does not explicitly exclude scenarios or name alternatives, the examples provide sufficient guidance and imply its differentiation from other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes concrete effects: removes .devflow.json and stops heartbeat. No annotations to contradict.
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, no wasted words, front-loaded purpose.
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 parameterless tool with no output schema, the description fully covers purpose, behavior, and re-enable option.
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?
No parameters; description adds context beyond schema (empty schema) by explaining the tool's effect.
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?
Clearly states verb 'disconnect' and resource 'project from DevFlow'. Distinguishes from sibling devflow_connect by mentioning re-enable.
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?
Explicitly mentions when to use (disconnect) and alternative (devflow_connect for re-enable). Does not list contraindications but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses the tool's behavior: it returns the same Markdown section as flow_get, marks resolved comments with [✓ resolved], and leaves wikilinks raw. This gives clear expectations for the agent.
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 is brief yet comprehensive, with a clear opening sentence followed by bullet points listing use cases. Every sentence adds value, and the structure is front-loaded and easy to parse.
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 simplicity of the tool (single parameter, no output schema), the description covers all necessary context: what it returns, how it differs from flow_get, and special notes about resolved comments and wikilinks. It is fully sufficient for an agent to correctly invoke the tool.
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?
The schema already describes the sole parameter 'flowId' with 100% coverage. The description adds minimal extra meaning beyond confirming the parameter is a flow ID. According to the rubric, baseline is 3 for high coverage.
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 verb ('reload'), the resource ('discussion/comments for a flow'), and the output format ('Markdown section'). It also distinguishes itself from the sibling tool 'flow_get' by emphasizing that it only fetches comments, not the entire flow.
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 use cases: refreshing comments without re-fetching the full flow and viewing resolution status. It also explains that wikilinks remain raw. However, it does not explicitly mention when not to use this tool (e.g., when full flow context is needed).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden. It discloses auto-derivation of agentStatus, mandatory fields for approval/review, commit append behavior, and the docsUpdate blocking condition. This is substantial beyond the schema, though it doesn't cover side effects or failure modes.
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 is well-structured with bullet points and an IMPORTANT section, front-loading the primary purpose. Every sentence adds value with no redundancy.
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 tool's complexity (19 params, nested objects, no output schema), the description covers the main use cases, required fields, and key behavioral constraints. It does not explain return values or error scenarios, but the schema covers parameters thoroughly.
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 coverage is 100%, but the description adds crucial context beyond the schema: which parameters are required for which state transitions, and the auto-derived nature of agentStatus. It also clarifies behavior for commits (appending, review blocking) and testingInstructions requirements.
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 explicitly says 'Update a flow's state or submit deliverables' and enumerates specific uses: changing state through the defined pipeline, submitting an implementation plan, and submitting an agent summary. This clearly distinguishes it from siblings like flow_create and flow_get.
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?
It provides clear context on when to use the tool (state transitions, deliverables) and which parameters are required for specific transitions. However, it does not explicitly exclude alternatives or mention when other tools should be used instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description does not explicitly state non-destructive behavior or authorization needs. However, it clearly describes the tool as a preparatory read operation and outlines the expected flow, which provides substantial transparency.
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 is well-structured with a clear purpose statement and bulleted workflow steps. Every sentence adds value, and it is front-loaded with the core purpose. It is concisely written despite its length.
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 lacking annotations and an output schema, the description fully compensates by explaining the tool's role, its output components, and the subsequent steps the agent must take. It is complete for the tool's complexity.
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 two parameters, with the description adding no additional semantic information beyond what the input schema already provides. Baseline score of 3 is appropriate.
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 that the tool prepares a knowledge backfill run for a project, contrasting with the keyword heuristic and listing the exact output (done-flows, existing ADRs, instructions). It effectively differentiates from sibling tools like knowledge_harvest by specifying its role as an MCP-first alternative.
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?
The description provides an explicit 5-step workflow detailing when to call the tool, how to process its output, and when to invoke knowledge_draft_create. It includes cautionary advice ('Be conservative'), effectively guiding the agent on usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, but description discloses idempotent behavior, output contents (subsystem list, dedup-list), and side effects (creating pages/drafts). Could add permissions or error cases.
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?
Concise (~80 words), front-loaded purpose, then output summary, then usage note. No wasted sentences.
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?
No output schema, but description fully explains return value (prompt with lists and instructions). Parameters are well-documented. Complete for a bootstrap tool.
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 covers both params; description adds useful default behavior for subsystems field and lists defaults, enhancing schema info.
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?
Clearly states verb 'bootstrap' and resource 'knowledge base of a project', specifying it audits code. Uniquely identifies its function among many sibling tools.
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?
Explicitly says to call once per new project and notes idempotency with dedup-list. Lacks explicit when-not or alternatives, but context makes it clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description transparently describes that the tool returns matching items with type, title, and content snippet, indicating a read-only operation without hidden behaviors.
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 is three concise sentences, front-loaded with purpose, and every sentence adds value without redundancy.
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?
The description fully covers the tool's functionality given no output schema, explaining what is returned and that filtering is supported, making it complete for an agent to use.
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%, and the description adds meaning by explaining that q is a search query and type filters by entity types (flow, task, project), going beyond schema descriptions.
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 specifies the verb 'Search' across specific resources 'flows, tasks, and projects in DevFlow', and distinguishes it from sibling tools like wiki_search by indicating the broad scope.
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 states when to use ('find items by keyword, title, or content') and supports filtering by type, but does not explicitly mention when not to use or suggest alternative tools for more specialized searches.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behaviors: validates and loads flow, locks it exclusively, creates a session, returns full context. With no annotations, it covers essential actions, though it could mention handling of already-locked flows or session duration.
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?
Front-loaded with a clear one-liner, followed by a bullet list and a call to action. While detailed, every sentence adds value; minor trimming could improve conciseness.
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 no output schema, the description adequately describes the return value (full context: flow details, feedback, tasks, etc.) and sets expectations for a session initialization tool. Covers prerequisite behavior and optional use of flowId.
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% with one optional parameter. The description adds meaning by explaining that omitting flowId shows available projects and flows, which clarifies the parameter's behavior beyond the 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?
The description clearly states the tool initializes a DevFlow work session for a flow, using specific verbs like 'Initialize' and listing concrete actions (validates, locks, creates, returns). It distinguishes itself from sibling tools by noting it must be called before most others.
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 it must be called before any other tools except flow_list and flow_create, and that all tools are blocked without it. Also advises calling at the start of every work session, providing clear when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility. It discloses that the tool is read-only (listing pages) and describes the return format. It could explicitly state no side effects, but the word 'list' implies safety. The automatic project linking is a useful behavioral detail.
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 compact with three to four sentences. It front-loads the core purpose and then adds return details and usage advice. Efficient, though could potentially combine the last two sentences.
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?
All relevant aspects are covered: what the tool does, what it returns, when to use it, and how to call it (with optional projectId). No output schema exists, but the description sufficiently conveys the return structure. No gaps.
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% with a clear description for projectId. The description adds value by restating the automatic linking behavior in natural language, which reinforces understanding. This goes beyond the schema's baseline.
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 'List all documentation pages for a project, grouped by section' and specifies the return structure (title, id, section, sortOrder). It uses a specific verb and resource, and distinguishes itself from sibling tools like doc_page_create or doc_page_update.
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 advises to use this tool 'before creating or updating pages', giving a concrete use case. It also explains the automatic project linking behavior when projectId is omitted, providing clear context for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description must disclose behavior. It explains file reading, mime-type detection, multipart/form-data with auth, and kind='plan' linking. However, it omits error handling and return value 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?
Concise, front-loaded with main purpose, uses bullet-like list for use cases. No wasted sentences.
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?
Covers key aspects (size limit, mime, auth, distinction from sibling). Lacks return value info and edge case handling, but sufficient for typical use given no output schema.
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% (baseline 3). Description adds value by explaining filePath as absolute path, mime detection, default flowId (current flow), and kind='plan' linking.
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 attaches a file from disk to the current flow, specifying resource, action, and file size limit. It distinguishes from sibling flow_upload by noting different content types.
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 when to use (images/PDFs/large files up to 50 MB) and when not to use (agent-written text content, prefers flow_upload). Includes common use cases for further clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility. It discloses the core action (creating an ADR or doc_page and marking accepted) and that it is a commit step. However, it lacks details on potential error cases or prerequisites like permissions, preventing a perfect score.
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 no wasted words. The first sentence states the main action, the second explains the effect, and the third provides usage guidance. Information is front-loaded and well-structured.
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?
The description adequately explains the outcome for a simple accept action, but since there is no output schema, it does not mention what the tool returns (e.g., the created document ID or status). This is a minor gap given the tool's straightforward nature.
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% with a single parameter 'id'. The description adds value by clarifying that 'draftId' is also accepted as an alias, which aids agents in understanding parameter flexibility beyond the 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?
Clearly states the verb 'accept' and the resource 'draft', and explains that it creates an ADR or doc_page while marking the draft accepted. Distinguishes itself from siblings like knowledge_draft_reject by specifying it is the commit step.
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 advises to use only when certain the draft is good to merge, and notes that the tool exists for autonomous workflows while users normally use the UI. This provides clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description fully discloses behavior: it describes the 400 error when dismissing with an extend-target, the effect of each resolution type, and the backend enforcement of the Iron Law. This compensates for the lack of annotations.
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 bullet points for resolution types, making it easy to scan. However, it is somewhat long; a few sentences could be tightened without losing clarity. Nonetheless, every sentence provides necessary information.
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 tool's complexity (9 parameters, no output schema), the description is comprehensive. It covers usage, parameters, error handling, and the Iron Law. No gaps are evident for an agent to correctly invoke the tool.
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 coverage is 100%, but the description adds significant value by explaining the meaning of each enum value, the conditions for 'extend' requiring 'body' and 'rationale', and the specific use of 'horizon' for intent_defer. This goes beyond the schema's descriptions.
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 resolves a knowledge-check warning manually, differentiates from the auto-resolve hook, and explains the Iron Law and resolution types. It goes beyond a simple verb+resource, providing precise scope and context.
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 says 'Use this manual tool only for surgical overrides' and explains when auto-resolve should be used. It provides detailed guidance on resolution types, their order of preference, and conditions for each, such as when 'dismiss' is blocked.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that the signed token is returned only once, backend stores only the hash, and advises to keep it in session memory. Explains verification and rejection conditions. No annotations provided, so description carries full burden and meets it.
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?
Every sentence adds unique value. Starts with the core action, then defines terms, then usage context, then integration steps. No redundant phrases. Appropriately sized for the complexity.
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?
Covers the entire lifecycle: when to emit, what the token is, how to pass it later, and conditions for acceptance. Without output schema, description adequately explains return behavior (returned once). Complete for a tool with this complexity.
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?
Adds significant meaning beyond the 100% schema coverage. Explains evidence shapes per skill in detail, clarifies required fields, and ties parameters to the overall workflow. Schema alone would not convey this level of domain-specific context.
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?
Clearly states the tool emits a discipline-token for a flow and skill, differentiating it from sibling tools like devflow_tokens_list or discipline_tokens_auto_emit. Provides specific details about the token being an HMAC-signed proof and its purpose.
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 says 'Use this at the END of a discipline-skill run' and lists applicable skills. Describes the subsequent use in flow_update with conditions. Gives clear when-to-use and how-to-use guidance, including prerequisites for the gate-check.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behaviors: automatic dedup merging sourceFlowIds, safe to call repeatedly, constraints on title length, body format, rationale purpose. No annotations exist, so description fully covers behavioral traits.
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?
Highly efficient: first sentence states purpose, followed by context, then bullet-pointed rules. Every sentence adds value with no redundancy.
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 no output schema, the description fully covers purpose, usage, parameters, and behavioral nuances. It is complete for an agent to select and invoke the tool correctly.
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?
Adds meaning beyond input schema: explains draftType enum values, title rules ('deklarativ, max 60 chars, no prefix'), body format (2-6 paragraphs), rationale purpose, and sourceFlowIds as grouping. Schema coverage is 100%, but description enriches each parameter.
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 'Create a new knowledge draft' with specific verb and resource. It distinguishes from sibling tools like knowledge_draft_list, knowledge_draft_accept, etc., by explaining the creation context and dedup behavior.
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 describes when to use: after knowledge_backfill_request or standalone when identifying a flow worth documenting. Includes dedup details and rules, though no explicit 'when not to use' is needed given clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![devflow-mcp MCP server](https://glama.ai/mcp/servers/KlausFreiberufler/devflow-mcp/badges/card.svg)](https://glama.ai/mcp/servers/KlausFreiberufler/devflow-mcp)

Score Badge

Copy to your README.md:

[![devflow-mcp MCP server](https://glama.ai/mcp/servers/KlausFreiberufler/devflow-mcp/badges/score.svg)](https://glama.ai/mcp/servers/KlausFreiberufler/devflow-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/KlausFreiberufler/devflow-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server