mk-plan-master

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

Discloses writing location, ID auto-generation, return fields, and overwrite capability (though overwrite behavior could be more explicit). Without annotations, this is good but not exhaustive; e.g., no mention of idempotency or what happens on duplicate ID.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is a single paragraph that front-loads the core action, then adds context, restrictions, return, and chain. It is efficient with no fluff, though it could use bullet points for better readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 13 parameters and no output schema, the description covers the high-level workflow and constraints well but lacks detail on many parameters (score fields, labels, okr, etc.). The return object is mentioned but not fully specified. The typical chain provides some context for downstream use.

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

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

Schema description coverage is 0%, so the description should compensate. However, it only explains the 'id' parameter's auto-generation and mentions 'overwrite' in return. Most parameters (reach, impact, confidence, etc.) are not explained, leaving the agent to guess their meaning from names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool writes a new markdown_local initiative to a specific file path. It distinguishes itself from siblings by specifying the use case (capturing already-gathered ideas) and the source type (markdown_local only). The verb 'write' and resource 'initiative' are explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-to-use: 'capture an idea you already gathered via WebFetch / chat summary / customer-call notes'. Also includes when-not-to-use: 'plan-master deliberately does NOT crawl URLs; you summarize, this tool persists.' Offers alternatives: for other platforms, create the issue there. Additionally, provides a typical chain of tool usage.

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

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

Discloses key behavioral traits: the tool does not call an LLM, it loads plan-knowledge.md context, forces a SOP, and returns a structured checklist for the AI to fill inline. With no annotations provided, the description fully compensates by detailing what the tool does and does not do.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is thorough but slightly verbose; still, every sentence contributes value. It is well-structured, starting with purpose, then usage guidance, then behavioral details, then framework options, and ending with return fields.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (no annotations, no output schema), the description is remarkably complete. It covers purpose, usage, behavior, parameters, return value, and integration with other tools (add_initiative, score_initiative). An agent can correctly select and invoke this tool.

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

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

Despite 0% schema description coverage, the description explains both parameters: initiative_id (required, string), and framework (optional, with enumerated options: 'default', 'lite', 'lean_canvas' and descriptions of each). Also describes the return value structure, adding meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Describes a specific action: forcing a senior-PM analysis SOP on an initiative before scoring. Clearly distinguishes from siblings like score_initiative and add_initiative by stating it is a prerequisite step and that it does not call an LLM but scaffolds the prompt.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use: 'WHENEVER an idea originates from chat / WebFetch and lacks a thorough product analysis.' Also provides a clear sequence of next steps: after filling the checklist, call add_initiative(overwrite=true) then score_initiative.

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

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 discloses configurable label vocabularies with defaults and the return structure. However, it does not mention whether the tool is read-only, any side effects, or auth requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is three sentences, each adding meaningful information. It is front-loaded with the primary function. Slightly verbose but still efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (5 parameters, no output schema, no annotations), the description covers usage and label configuration but omits details on method scoring, limit's role, and whether the tool mutates data. It feels adequate but not fully complete.

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

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

With 0% schema coverage, the description adds value by explaining the label parameters and their defaults. However, 'method' and 'limit' are not explained beyond defaults; 'rice' as a method is an acronym without elaboration.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses specific verbs ('classify', 'surface') and identifies the resource ('top-N ranked initiatives'), clearly distinguishing it from siblings like analyze_initiative or rank_backlog. It also provides example use cases.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use the tool with example user queries ('is the roadmap balanced', 'are we starving tech debt'). It does not explicitly state when not to use it, 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.

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

No annotations are provided, so the description carries full burden. It correctly indicates a read operation ('Pull') and lists return fields, but omits details on error handling, auth requirements, or data freshness. The description is adequate but not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Two sentences, front-loaded with action and return structure. Every sentence adds value: what it does, what it returns, and how it pairs with another tool. No excessive wording.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given lack of output schema, the description compensates by listing return fields. Also pairs with score_initiative for context. However, missing usage guidelines and parameter details reduce completeness for independent use.

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

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

With 0% schema description coverage, the description adds minimal value: 'by id' merely restates the parameter name. No information on format, source of ID, or constraints beyond the schema's type string.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The verb 'Pull' and resource 'initiative by id' are specific and clear. The description distinguishes from siblings by mentioning pairing with score_initiative and implying it as a single-record fetch, unlike list_initiatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides context by mentioning pairing with score_initiative for ranking, but does not explicitly state when to use this tool vs alternatives like list_initiatives or add_initiative. Lacks when-not guidance.

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

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

With no annotations, the description fully shoulders the burden. It discloses the algorithm (greedy score-per-effort packer using RICE-per-pw ratio), the output structure (markdown with sections, capacity metrics), and parameter semantics, providing comprehensive behavioral transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is a single well-structured paragraph of about 5 sentences. It begins with the main action, then algorithm, output, parameters, and return shape—all concisely stated with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the 7 parameters, no annotations, and no output schema, the description covers most aspects: algorithm, required/optional inputs, and return structure. It lacks explanation for status and label and does not mention prerequisites or side effects, but is largely complete.

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

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

The description adds meaning to 5 of 7 parameters (capacity_engineer_months, period, okr, method, buffer_pct) by explaining units, defaults, and constraints. However, it omits status and label, which have no schema descriptions (coverage 0%), leaving a gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Pack the ranked backlog into a quarterly roadmap markdown.' It specifies the verb (pack), resource (ranked backlog), and output format (quarterly roadmap markdown with sections like P0 commitments, etc.), distinguishing it from siblings like rank_backlog.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not explicitly state when to use this tool versus alternatives. It implies the tool should be used after backlog ranking, but no direct guidance on when not to use or comparison with sibling tools like analyze_roadmap_balance is provided.

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

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

No annotations exist, so the description carries full burden. It discloses that the tool appends a `spec_generated` decision to the index (a side effect) and returns a structured object with fields like `ready_for_mk_spec_master`. This adds behavioral context beyond the schema. However, it does not mention error conditions or authorization needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is somewhat lengthy but well-structured: first sentence captures core purpose, then templates, side effect, and return fields. Every sentence adds value. Could be slightly more concise, but it remains clear and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations and no output schema, the description covers the key aspects: templates, return structure, side effect, and integration with mk-spec-master. It is missing error handling or edge-case behavior, but for a draft generator, it is adequately complete.

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

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

Schema coverage is 0%, but the description explains the two parameters: `initiative_id` (the target initiative) and `template` with its three options (default, lite, detailed) and their contents. This compensates for the schema's lack of descriptions and provides meaningful semantics for parameter selection.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool produces a markdown spec draft for one initiative with specific formatting for mk-spec-master ingestion. It names three templates (default, lite, detailed) and their contents. While it doesn't explicitly differentiate from sibling tools, the purpose is specific and actionable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for generating spec drafts but provides no guidance on when to use this tool versus siblings like add_initiative or analyze_initiative. It does not mention prerequisites or when not to use it, leaving the agent to infer context.

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

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

No annotations, so description carries full burden. It states 'scan history + index' implying read-only, but lacks explicit safety confirmation, authorization needs, or performance implications. Adequate but not detailed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Three sentences cover purpose, patterns, usage examples, and parameter. Every sentence is informative with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Describes return structure {ghost_initiatives, score_whiplash, orphan_okrs, summary} without output schema. Good for a scanning tool but could mention data scope limits or performance.

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

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

Mentions 'window_days (default 30)' in description, which adds the default but does not explain its effect on results. Schema already provides type and default, so only marginal value added.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Describes scanning for three specific chronic patterns (ghost initiatives, score whiplash, orphan OKRs) with example user queries, making the tool's purpose highly specific and distinct from siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly lists three user query examples ('which ideas keep getting punted', etc.) that trigger tool usage, but does not mention when not to use or suggest alternatives.

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

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

No annotations provided, so description carries full burden. Discloses fallback behavior, optional section filter, and return shape ({source, content}). Implies read-only; no side effects mentioned.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Three sentences: action/fallback, usage timing, parameter detail. Front-loaded and no extraneous content. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Describes return shape despite no output schema, mentions file path and fallback. Adequate for a simple read tool with one optional parameter.

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

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

Schema covers 100% with description of section parameter. Description adds example (section='RICE') and clarifies partial-match, case-insensitive behavior, adding value beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Clear verb+resource: 'Read PLAN_PROJECT_ROOT/plan-knowledge.md' with fallback to built-in defaults. Distinguishes from siblings like init_plan_knowledge (write) and get_plan_source_info (different context).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly advises to call 'near the start of a planning session' to ensure consistent methodology and glossary. Does not explicitly state when not to use or alternatives, but context makes it appropriate.

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

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

With no annotations, the description carries full burden. It explains that the tool compares current snapshots to those from ~7 days ago or a configurable window_days ago, and surfaces churn and average scores. It does not detail permissions or side effects but adequately describes 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.

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

The description is concise, front-loaded with the core function, and includes examples and return structure. Every sentence adds value without unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no output schema, the description provides the return fields (snapshots_count, trend_7d, trend_30d, summary) and context about data sources (rank_backlog snapshots) and ranking method (RICE). It is sufficiently complete for a simple tool with one parameter.

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

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

The only parameter, window_days, is implied in the description ('vs window_days ago') and its default is given. Though schema coverage is 0%, the description adds meaning by connecting it to the trend periods. It could be more explicit but is sufficient for a single parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description specifies a clear verb (Return), resource (trend deltas for top-10 RICE-ranked backlog snapshots), and what it provides (snapshots_count, trend_7d, trend_30d, summary). It distinguishes from siblings by referencing rank_backlog and trend analysis.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly gives example user queries that indicate when to use this tool ('are we improving?', 'show me the trend', 'is the same idea always at the top'). It does not mention when not to use or alternatives, but the examples are clear enough.

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

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

With no annotations, the description fully carries behavioral disclosure. It explains the return shape ({active, available, version}) and that it is a read-only retrieval of the source and adapters. It does not explicitly state that it has no side effects, but the read-only nature is implied. A 5 would require explicit mention of no mutation or error handling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Two sentences with no wasted words. The first sentence states the purpose and scope, the second provides usage guidance and indicates the return format. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simplicity (no parameters, no output schema, no annotations), the description is complete. It explains the output structure, the source of the active source (env var), and the rationale for ordering. There is no missing information needed for an agent to use the tool correctly.

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

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

There are zero parameters, and the schema coverage is 100% (empty object). The description adds meaning beyond the schema by explaining what the return value contains and why it should be called first. The baseline for 0 params is 4, and the description meets it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it returns the active initiative source and all adapters built into the server. The verb 'Return' and specific resources ('active initiative source', 'all adapters') make the action unambiguous. The mention of 'PLAN_SOURCE env var' distinguishes it from sibling tools that operate on initiatives directly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly instructs to 'Call first in any session so the AI knows whether to expect markdown / Linear / JIRA / Notion semantics.' This sets a clear precondition and informs the AI about the tool's role as a session initializer. It implicitly defines when not to use (after session context is established) and provides the rationale for calling it.

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

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

Discloses what data is logged (tool name, timing, ok flag) and importantly what is NOT logged (argument values). With no annotations, description carries full burden and fulfills it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Two efficient sentences plus a return value list. Front-loaded with purpose, no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers purpose, inputs, outputs, usage guidance, and behavioral notes. No gaps given the tool's simplicity and lack of output schema.

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

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

Single parameter with default; description repeats schema info but adds no new semantic context. However, the parameter is simple and usage context implies the time window.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it aggregates tool-usage logs and lists specific metrics (most called, error rate, latency, dead surfaces). Distinguishes from sibling tools which focus on initiatives and planning.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly maps to user queries like 'what's the AI actually using' and 'which tools are slow/unused', 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.

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

With no annotations, the description discloses key behaviors: idempotency (refuses to overwrite unless overwrite=true), optional project_name to label the file, and override location via PLAN_KNOWLEDGE_FILE env var. It lacks details on error handling or permission requirements but is fairly transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description consists of two sentences, with the first sentence front-loading the core purpose and contents, and the second adding behavioral details. Every sentence is informative and there is no wasted text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers file creation, contents, and idempotency, but does not explain the return value or confirmation message. Given no output schema, this information would be helpful for the agent to understand the tool's response.

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

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

Both parameters (project_name and overwrite) are explained: project_name labels the file, overwrite with default false. However, the exact effect of project_name on the file content or naming is a bit ambiguous. Overall, it adds value beyond the schema, which had no descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it creates PLAN_PROJECT_ROOT/plan-knowledge.md from a starter template, listing the file's contents (methodologies, sections). It distinguishes itself from sibling tools that focus on initiatives and analysis, establishing a unique role.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions other mk-plan-master tools lean on this indirectly, implying it is a foundational setup tool. However, it does not explicitly state when to use it versus alternatives or provide exclusion criteria.

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

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

No annotations are provided, so the description carries full burden. It transparently explains how the tool behaves per adapter (e.g., globbing files, querying APIs, filtering statuses), lists optional filters, and describes the return structure. This adds significant behavioral context 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.

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

The description is relatively concise given the complexity of multiple adapters. It front-loads the core purpose, then details adapter behaviors, then lists filters and return. It is well-structured but could benefit from more succinctness or bullet points.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and three parameters, the description covers purpose, adapter-specific behavior, optional filters, and return format. It lacks error handling, prerequisites, or source activation info, but overall is fairly complete for a listing tool.

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

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

Schema coverage is 0%, but the description adds meaning by explaining each parameter: status is adapter-specific, label is a single label match, limit has default 50. This provides context that the schema alone does not, though it could be more detailed for each adapter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it enumerates product initiatives from the active source, details adapter-specific behaviors, lists optional filters, and specifies the return structure. This is specific and distinguishes it from sibling tools that add, fetch, or analyze initiatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not provide explicit guidance on when to use this tool over alternatives like fetch_initiative or analyze_initiative. It mentions 'active source' but does not clarify how to set or determine the active source, and lacks context for choosing among adapters.

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

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

No annotations provided, but the description fully compensates by disclosing deterministic behavior (pure arithmetic, no LLM call), rational breakdown, auto-archiving to history, and trend delta computation. All key behavioral traits are covered.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is concise but dense, packing many details into a single paragraph. It is front-loaded with the core purpose, but could benefit from clearer sectioning or bullet points for readability without losing content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description specifies the return format ({method, count, ranking[]}), explains deterministic behavior, and covers archiving and integration with other tools (e.g., get_planning_history). The presence of sibling tools provides context, and the description is complete enough.

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

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

Schema coverage is 0%, but the description explains defaults for method and limit, and notes that status/label filters mirror 'list_initiatives'. It adds meaning beyond the schema, though it does not explain possible values for 'method' or 'status' label ranges.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool scores initiatives and returns top-N descending, with specific verb 'rank' and resource 'backlog'. It distinguishes from siblings like 'list_initiatives' (listing) and 'score_initiative' (single) by focusing on ranking and aggregation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions optional filters that mirror 'list_initiatives', default values for method and limit, and auto-archiving. However, it does not explicitly state when to use this tool versus alternatives like 'score_initiative' or 'list_initiatives', though the purpose implies ranking use cases.

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

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

Discloses side effect of appending scored decisions to index on every call with initiative_id, and specifies tier thresholds. No annotations, so description carries burden. Lacks authorization or rate limit info, but sufficient for basic transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Concise and well-structured: first sentence states core purpose, then details mode, method, overrides, side effect, return. No redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers all essential aspects: purpose, two usage modes, parameter details, side effects, output format, tier thresholds. No major gaps for agent to use correctly.

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

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

Explains the purpose of each parameter: initiative_id for source-resolved, raw_text for ad-hoc, method enum values, overrides object with individual fields and precedence rule. Adds meaning beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly describes scoring initiatives with RICE or Impact-Effort, distinguishes two modes (source-resolved vs ad-hoc), and method options. Differentiates from siblings like add_initiative (add) and analyze_initiative (analyze).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit context for when to use each parameter combination (initiative_id vs raw_text), and mentions default method and overrides. However, does not compare with sibling tools or specify when not to use this tool (e.g., for qualitative analysis).

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