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

The readOnlyHint annotation already covers non-mutation, so the description's added detail about specific checks and 'strictness follows the project scale' provides genuine behavioral context. It does not describe output or failure behavior, but these are less critical given the annotated safety profile.

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

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

The description is two sentences, front-loaded with the tool's purpose, and compactly packs the artifact types and checks into a parenthetical list. Every clause carries information with no filler or repetition.

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

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

The check categories, scale sensitivity, and parameter semantics are present, and the schema fully documents paths and scale. However, there is no output schema and the description never states what the tool returns (e.g., pass/fail report, list of failures, severity counts), leaving result interpretation ambiguous for a tool whose purpose is to produce a gate decision.

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 are already fully documented in the schema (100% coverage), so the baseline is 3. The description adds extra meaning by linking the scale parameter to behavior: 'Strictness follows the project scale', which goes beyond the schema's simple 'Override the detected scale'.

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 names the tool as a 'quality gate on the project artifacts', lists the artifact types, and enumerates specific checks: unfilled placeholders, empty sections, missing sections, FR/NFR coverage, and acceptance criteria. This clearly distinguishes it from siblings like mdan_estimate_scope or mdan_trace.

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?

No guidance is provided on when to run this tool versus alternatives, and no exclusions or conditions are stated. The phrase 'quality gate' implies a gating use case, but the description never explicitly says when it should be invoked or when a sibling tool would be more 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?

Annotations already mark the tool readOnlyHint=true, which covers the safety profile. The description adds that the loaded persona carries 'layered customization and its memories,' which is useful behavioral context, but it does not disclose response behavior, side effects, or any preconditions beyond what the schema already states.

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 efficient sentence that front-loads the action ('Load an MDAN agent persona') and compresses the behavioral intent. No filler or redundant phrases are present.

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

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

For a read-only consult tool with a 31-value enum and an optional question, the description gives enough to understand the core interaction: load a persona and get an in-character answer. It does not describe an output schema (there is none) and does not clarify why the question is optional given the described purpose, but these are minor gaps.

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 100%, and the schema already explains both parameters ('Agent name (see mdan_list_agents)' and 'Question or topic to discuss'). The description adds no parameter-specific meaning beyond the schema, so the baseline 3 applies.

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

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

The description uses a specific verb ('Load') and identifies the resource ('MDAN agent persona') and the intent ('to answer in character'), so an agent can tell this is a consult/persona-loading tool. It does not explicitly differentiate from nearby siblings like mdan_customize_agent or mdan_list_agents, so it stops short of full sibling discrimination.

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 phrase 'to answer in character' implies the natural use case: ask a persona a question. However, there is no explicit guidance on when not to use it or how it relates to alternatives such as mdan_customize_agent or mdan_memory_recall, leaving the agent to infer the boundary.

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 the behavioral burden. It discloses two behaviors: persistence of the record and registration in the context graph. It does not disclose further consequences (e.g., overwrite behavior, ID defaulting, auth requirements), so it remains above a 2 but below a 4.

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?

One sentence with no filler; the key action and context are front-loaded. Every word contributes to identifying the tool's purpose and behavior.

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

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

For a 10-parameter tool with no output schema and no annotations, the description is terse. It explains the purpose and the graph side-effect but leaves nested structures like rounds and participant objects to the schema, and does not describe expected output. This is adequate but not thorough.

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 90%, and all required parameters have descriptions. The description itself adds no parameter-level meaning, but that is acceptable under the high-coverage baseline of 3.

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 'Save' and 'register' and names the resource 'decision record (DR-XXX)', making the operation concrete. It also gives the originating context ('from a debate or consensus session') and the integration target, which separates it from sibling graph/memory tools.

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

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

It identifies the triggering scenario: saving a decision after a debate or consensus session. It does not explicitly mention alternatives or exclusions, but the context is clear enough to route use cases toward this tool.

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 the full behavioral burden. It discloses that values are merged, where they are stored (_mdan/custom/<agent>.yaml vs. <agent>.user.yaml), and important traits like versioning and git-ignoring. It omits undo/failure details, so not a 5.

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?

One dense, front-loaded sentence conveys action, layer options, file paths, versioning behavior, and merge semantics. There is no filler or 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?

For an 8-parameter tool with no annotations and no output schema, the description covers the key context an agent needs: what is customized, which layers exist, where values go, and how they are applied. Optional parameter details are left to the schema, which mostly covers them adequately.

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 about 63%, and most parameters already have explanatory descriptions. The description adds the useful merge semantic but does not clarify underdocumented parameters like menu or communication_style. A middle score is appropriate.

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

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

The description opens with a specific verb and resource: 'Customize an agent without editing its file.' It also adds concrete layer distinctions (team vs. personal) and file paths, making the tool's role clear and distinguishing it from sibling state/memory/run tools.

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

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

The description clearly implies when to use this tool: when an agent needs customization without directly editing configuration files. It also explains the two layer options. It does not explicitly name sibling alternatives or exclusions, so it falls short of a 5.

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?

readOnlyHint already covers the non-destructive safety profile; the description adds that the operation pages through a categorized listing. It does not disclose output shape, paging stability, or response size, but annotations lower the burden.

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?

One sentence, with the verb front-loaded and the parenthetical supplying the only necessary context. No filler or redundant restatement of the tool name.

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 tool is low-complexity: no required parameters, read-only annotation, and a clear listing purpose. With no output schema, the return shape is only described as a categorized list, but that is sufficient for this pagination tool; missing alternative routing is more a usage-guideline gap than a completeness gap.

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

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

The schema documents offset as a character offset and provides bounds/defaults; the description only adds that these are pagination controls via 'Page through'. The length parameter's meaning remains only partially specified, and the description does not clarify that pagination is character-based.

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 gives a specific action ('Page through') and resource ('MDAN ecosystem catalog'), with a parenthetical clarifying the catalog is a categorized list of known components. It does not explicitly compare itself to siblings like mdan_ecosystem_search or mdan_ecosystem_read, but the browsing/list semantics are distinguishable.

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 'use this when you need to page through the catalog' but provides no when-not conditions or alternative tools. With siblings such as ecosystem_search and ecosystem_read nearby, the routing guidance is left to inference.

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?

The annotation readOnlyHint: true already informs the agent that this is a read-only operation, and the description's use of 'read' is consistent. However, the description adds no extra behavioral context beyond that, such as whether the content is returned as raw text, size limits, or any special formatting. With the annotation covering the safety profile, a 3 is appropriate – it adds some value but not rich detail.

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, succinct sentence that front-loads the core action and resource. There is no redundant wording, and every word contributes to understanding. It is appropriately concise and well-structured.

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

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

For a simple read tool with only two parameters and a readOnly annotation, the description is nearly complete. It states the operation and the resource types. However, since there is no output schema, a note about what 'full content' means (e.g., raw text, structured data) would improve completeness. Minor gap, but overall sufficient for an agent to invoke 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?

Schema coverage is only 50% (only 'name' has a description; 'kind' has an enum but no description). The tool description does not elaborate on the parameters at all. It implies that 'kind' selects the type and 'name' identifies the entity, but it adds no meaning beyond the schema. Since coverage is below 50% and the description does not compensate, a 2 is warranted.

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 reads the full content of an installed skill, agent, or command. It uses a specific verb ('read') and identifies the resource type, making the purpose unambiguous and distinct from siblings like mdan_ecosystem_search (which likely searches) or mdan_ecosystem_catalog (which lists). This is not a tautology and provides immediate understanding.

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 usage for reading content, but there is no mention of when not to use it (e.g., 'for metadata use search'). Given the sibling list includes mdan_ecosystem_search and mdan_ecosystem_catalog, explicit differentiation would be helpful, but the purpose itself is clear enough to infer 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?

Annotations provide readOnlyHint=true, and the description adds useful behavior beyond that: matches are ranked by name/description match and the scope is limited to installed components under ~/.claude. It does not describe return format or result count, but the ranking and scope details add meaningful context.

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

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

A single sentence that is front-loaded with the action and resource, then adds the scope and ranking behavior. Every word contributes meaning, with no filler or repetition.

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

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

For a simple read-only keyword search with two required parameters and no output schema, the description covers the core information: what is searched, where (~/.claude), and how results are ordered. It omits return shape and limit behavior, but those are minor given the tool's simplicity and the readOnlyHint annotation.

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 schema already documents kind and query (67% coverage). The description reinforces that kind maps to skills/agents/commands and query maps to keywords, but it adds no additional meaning for the limit parameter, which is undocumented in the schema and description. Limit does have default/min/max constraints, so its semantics are partially recoverable from 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?

The description uses a specific verb ('Search'), a clear resource ('installed Claude Code skills, agents or commands'), and a ranking criterion ('by keywords, ranked by name/description match'). It clearly identifies what the tool does, though it does not explicitly contrast itself with sibling tools like mdan_ecosystem_catalog, mdan_list_agents, or mdan_list_workflows.

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 phrase 'by keywords' implies this is the tool to use when searching rather than listing or reading ecosystem components, but no explicit when-to-use or when-not-to-use guidance is provided. Sibling alternatives are not named, so the agent must infer routing from 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?

The readOnlyHint annotation already covers the non-destructive aspect. The description adds the scoping detail that it counts installed components under ~/.claude and names the categories, but it does not disclose the output format, whether counts are total or grouped, or any other behavioral nuances.

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

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

A single sentence front-loads the core action ('Count') and uses a parenthetical for categories. Every word earns its place; no filler or 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?

For a zero-parameter, read-only stats tool, the description is sufficient for an agent to invoke it correctly: it states the target location, the categories counted, and the action. The lack of an output schema is mitigated by the explicit mention of component types, which implies the returned breakdown.

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

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

The tool has zero parameters, so parameter documentation is not needed. The schema is vacuously complete, and the description's mention of counting by component type is the only semantic content that helps interpret the expected output.

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 names a specific verb ('Count') and resource ('installed Claude Code components') with a clear scope ('in ~/.claude'). It also lists the component categories (skills, agents, commands), which distinguishes it from sibling tools like mdan_ecosystem_read or mdan_ecosystem_catalog that likely perform richer data retrieval.

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?

Usage context is only implied through the word 'Count' and the tool name 'stats'; there is no explicit statement of when to choose this tool over siblings such as mdan_ecosystem_read or mdan_ecosystem_search. No alternatives or when-not-to-use conditions are 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?

Annotations already declare readOnlyHint=true, so the description does not need to repeat that this is non-mutating. It adds useful context that the decision is based on files and real downstream impact in the context graph, but it does not disclose further behavioral details such as return shape or analysis depth. No contradiction with the annotations.

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 entire description is one dense, front-loaded sentence with no filler. Every part adds semantic content: the decision outcome, the process categories, and the input sources.

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

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

For a simple read-only estimator the description conveys enough to understand the tool's basic purpose and likely output categories. However, without an output schema it could usefully state the result format, and the ambiguity around the 'files' parameter and the absence of usage boundaries leave gaps.

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 only 33%; only 'artifacts' is explained in the schema. The description partially compensates by indicating that 'description' and 'files' feed the estimation, but it leaves 'files' undefined (file paths? content?) and does not clarify how the three parameters relate or how optional they are.

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

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

The description uses a specific verb ('decide') and a concrete resource ('how much process a change needs'), enumerating the three outcome categories: oneshot quick-dev / quick-spec first / full planning. This clearly conveys the tool's decision-making role and distinguishes it from siblings such as mdan_run_workflow or mdan_graph_impact.

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 the tool should be used when a change needs process-level estimation, and states the inputs it draws on. However, it never explicitly says when not to use it or names any alternative tool, leaving the selection logic to inference.

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?

The annotations only include openWorldHint: true, so the description carries the burden of exposing behavior. It discloses that dry run is the default, that apply=true sends requests using environment variable tokens, and that re-runs update rather than duplicate. This adds meaningful context beyond the annotation without contradicting it. It does not cover failure modes or token specifics, but the core side-effects are well described.

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 with zero fluff: purpose first, then the dry-run/apply mechanism, then the idempotency behavior. Every sentence carries essential information and it is appropriately front-loaded. This is an efficient, well-structured description.

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 schema's moderate parameter descriptions and the lack of an output schema, the description covers the essential operational behavior. It clarifies the default dry-run mode, the apply flag, and the update behavior, which are critical for correct invocation. It could be more complete by specifying what the non-dry-run response looks like or authentication prerequisites per target, but the core context is sufficient for an agent to safely call the 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?

The schema already describes 5 of 7 parameters (71% coverage), leaving only target and apply without descriptions. The description adds high-level behavioral notes (dry run, apply, re-run updates) but does not detail parameter interplay or per-target requirements beyond the schema. Since schema coverage is above 80%? Actually 71%, so baseline is 3, and the description does not substantially elevate parameter understanding.

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

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

The description states a specific verb ('Export'), a specific resource ('epics/stories document'), and a specific set of destinations (CSV, GitHub Issues, Azure DevOps Boards, Jira). It effectively distinguishes the tool from all siblings (graph, memory, workflow tools), which are clearly unrelated. There is no ambiguity about what this tool does.

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

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

The description gives a clear context for use: it exports the backlog document and has a dry-run default, with an apply flag to actually send. It does not explicitly name alternatives, but there are no close siblings among the listed tools. It could be more explicit about when to choose this over another export mechanism, but the context is sufficient for an agent to infer the appropriate use case.

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 provided, the description carries the burden of behavioral disclosure. It does disclose a key behavior: cycles are rejected, which is valuable. However, it does not mention whether the operation is destructive, whether it validates node existence, whether it can overwrite existing edges, or what happens on failure. The cycle rejection is a useful addition 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.

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

The description is a single sentence that is concise and front-loads the core action ('Add a relationship between two nodes') before the parenthetical constraint. It earns its place with the cycle rejection detail, though it could arguably be split into two sentences for clarity.

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

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

For a simple 3-parameter tool with no output schema, the description is adequate but has gaps. It doesn't explain what the response looks like, whether the operation is idempotent, or what 'cycles are rejected' means in practical terms (e.g., error message, no-op). Given the tool's simplicity and full schema coverage, a 3 is fair.

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 100%, so the schema already documents all three parameters (source, target, relation) with descriptions and an enum for relation. The description adds no additional parameter-level meaning beyond what the schema provides, so the baseline 3 is appropriate.

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

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

The description states a specific verb ('Add') and resource ('relationship between two nodes of the context graph'), which clearly identifies the operation. It also adds a behavioral constraint ('cycles are rejected') that helps distinguish it from other graph tools like mdan_graph_add_node, though it doesn't explicitly name that sibling.

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 context: it is for adding edges to the context graph, and the cycle rejection hints at when it might fail. However, it does not explicitly state when to use this tool versus alternatives like mdan_graph_add_node or mdan_graph_impact, nor does it mention any prerequisites such as nodes needing to exist.

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 must carry behavioral disclosure; it does state that the tool performs an upsert and records file hashes for staleness checks, which are meaningful side effects. It does not disclose overwrite scope, effects on existing edges, permissions, or return behavior, so transparency is only partial.

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 front-loaded sentence: the operation and object come first, followed by a useful parenthetical about staleness tracking. Every part adds meaning and there is no filler.

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

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

For a mutation tool with no annotations and no output schema, the description captures the core purpose and one important downstream behavior, while the schema covers parameters. It is less complete on routing guidance and on what happens to an existing node or connected edges during an update.

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 100%, so the input schema already documents all five parameters; the description adds no parameter-level meaning. The mention of hash recording hints at why path matters, but it does not add format or relationship details 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?

The description names a specific operation — add/update a node in the MDAN context graph — and ties it to hash recording for staleness checks, which separates it from siblings like mdan_graph_add_edge and mdan_graph_visualize. It loses the fifth point because it says 'artifact node' while the schema permits artifact, decision, and debate types, so the stated scope is slightly narrower than the actual tool.

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?

No explicit when-to-use or when-not-to-use guidance is provided. The description implies a graph maintenance action but does not direct agents to mdan_graph_add_edge for relationships or to mdan_state_update for other state changes.

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?

Annotations declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds that it covers both upstream dependencies and downstream impact, which is useful behavioral context beyond the annotation. However, it doesn't disclose return format, depth of traversal, or whether it includes indirect relationships.

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

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

A single concise sentence that front-loads the core purpose. It's efficient and free of fluff, though it could add a brief usage hint without becoming bloated.

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

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

For a read-only analysis tool with one well-documented parameter, the description is mostly adequate. However, with no output schema and no mention of what the result looks like (e.g., list of nodes, graph structure), an agent may not know what to expect. The readOnlyHint covers safety, but the behavioral output is unspecified.

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 100% (nodeId is described as 'Node ID to analyze'), so the schema already documents the parameter. The description adds the context that the node is an 'artifact' in the context graph, which slightly enriches meaning but doesn't add format or syntax details. Baseline 3 is appropriate.

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

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

The description states a specific verb ('analyze' implied by 'impact') and resource ('artifact in the context graph'), and clearly distinguishes from siblings like mdan_graph_visualize (visualization vs impact analysis). However, it doesn't explicitly name the sibling it is not, so it's clear but not maximally differentiated.

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 analyzing dependencies and impact, but doesn't explicitly state when to use this vs alternatives like mdan_trace or mdan_graph_stale. No exclusions or alternative routing is provided, so the agent must infer context from the tool name and sibling list.

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?

The readOnlyHint annotation already covers the safety profile, and the description adds useful behavioral context by specifying the selection criteria and output scope. It does not, however, explain how staleness is determined, what the return format is, or whether the downstream traversal has depth limits. This matches the baseline for an annotated read-only 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.

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

A single sentence that front-loads the action and resource, then adds the key downstream-review detail. Every word earns its place; there is no fluff or repetition of schema/annotation data.

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

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

For a simple, parameterless read-only tool, the description conveys the essential purpose and output category. The only real gap is the lack of detail about what 'modified since registration' means and whether the downstream list is recursive or direct, but the overall intent is clear enough for an agent to select and call it 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?

The tool has zero parameters and an empty schema, so the description has no parameter burden to carry. The baseline of 4 applies because there is nothing for the description to clarify about inputs.

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

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

The description uses a specific verb ('List') and identifies the exact resource: artifacts modified since registration plus the downstream artifacts that need review. This clearly differentiates it from sibling tools like mdan_graph_visualize or mdan_graph_add_node without needing to inspect the schema.

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 context is implicit: an agent can infer it should call this when reviewing stale artifacts and their downstream impact. However, it does not explicitly state when not to use it, name alternative tools, or provide exclusion criteria. The guidance is adequate but not fully explicit.

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?

Annotations already declare readOnlyHint: true, which the description is consistent with — no contradiction. The description adds one behavioral fact beyond the annotation: the output is Mermaid markup, which tells an agent the result can be embedded in markdown. It does not mention diagram scope (all nodes vs. filtered), size limits, or rendering needs, but for a no-parameter read operation the annotation plus format 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.

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

Eight words with zero filler, and the most decision-relevant fact (output is Mermaid diagram markup) is front-loaded. Nothing could be cut without losing meaning, and no redundant restatement of the tool name or annotations is present.

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

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

For a zero-parameter read-only tool with no output schema, the name plus description cover the essentials: a read-only operation producing a Mermaid representation of the context graph. The minor gap is that 'context graph' is not defined and its relationship to the memory/graph siblings is left implicit, but the tool's low complexity keeps this from being a significant omission.

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

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

The tool has zero parameters, so the 100% schema coverage is vacuous and there is nothing for the description to document. Consistent with the baseline for parameter-less tools, the description correctly omits parameter details; no meaning is lost.

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 is a noun phrase ('Mermaid diagram of the context graph') with no verb stating what the tool does — generate, render, or return. It does convey the output format and subject, and the Mermaid format differentiates it from analysis siblings like mdan_graph_impact and mdan_graph_stale, but the action itself is only implied by the tool name, leaving the purpose somewhat vague.

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?

No guidance is given on when to use this tool versus alternatives. With four graph-related siblings (mdan_graph_add_node, mdan_graph_add_edge, mdan_graph_impact, mdan_graph_stale), the description does not state which scenarios call for visualization versus impact analysis or staleness checking, forcing the agent to infer the use case.

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?

Annotations already declare readOnlyHint=true, covering the safety profile. The description adds the scope ('all installed') and return content ('with their roles'), which is useful but minimal. No contradictions found.

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

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

A single front-loaded sentence with zero waste. Every word contributes: the action, the resource, the scope, and the output 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?

The tool is simple — no parameters, read-only annotation, clear purpose. The absence of an output schema means the return structure is not fully specified, but the description does state that agents and their roles are returned, which is adequate for a low-complexity 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?

There are zero parameters, so the description bears no obligation to explain parameter semantics. The schema coverage is trivially 100%, and the description's mention of what gets returned is enough context for a parameterless tool.

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

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

The description states a specific verb ('List'), resource ('all installed MDAN agents'), and scope ('with their roles'). It is distinguishable from sibling mdan_list_workflows by the resource type, though it does not explicitly name sibling alternatives.

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

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

Usage is implied through the clear purpose — if you need to enumerate installed agents and their roles, this is the tool. No explicit when/when-not guidance or alternatives are named, but for a simple read-only list tool the context is reasonably inferable.

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?

The description is consistent with the readOnlyHint=true annotation, stating a list operation. It adds useful scope ('all installed') and return content ('with their descriptions'), but does not disclose other behavior such as ordering, filtering, pagination, or error conditions. No contradiction.

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 concise sentence that front-loads the verb and object while adding the relevant detail about descriptions. There is no redundant or 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?

For a zero-parameter, read-only listing tool, the description adequately states what the agent will get: installed workflows and their descriptions. It does not describe output format or distinguish from sibling list tools, but the low complexity makes this acceptable.

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

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

The tool has zero parameters and an empty input schema, so there is no parameter burden for the description to carry. Baseline 4 applies.

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

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

The description uses a specific verb ('List') and names the exact resource ('all installed MDAN workflows') plus the included detail ('with their descriptions'). This clearly distinguishes it from siblings like mdan_list_agents and mdan_run_workflow.

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?

There is no guidance about when to use this tool versus alternatives such as mdan_list_agents, mdan_ecosystem_catalog, or mdan_ecosystem_read. The intended use is implied by the name and description, but no explicit context or exclusions are 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 are provided, so the description carries the full transparency burden. It discloses the key side effects: counting the session, applying memory decay, and recording relationships and decision outcomes. It does not cover reversibility or permissions, but the core mutating behavior is clearly communicated.

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, front-loaded sentence that conveys the action and all key effects without repetition or filler. Every phrase—'count the session', 'apply memory decay', 'record relationships and decision outcomes'—contributes distinct information.

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 is adequate for selecting the tool and understanding its main effects, but it omits details an agent may need for reliable invocation, such as what a successful closure returns and what 'count the session' concretely produces. Since there is no output schema, some of that burden falls on the description, which it does not fully meet.

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

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

Schema description coverage is 0%, and the description only loosely refers to 'participating agents' and the relationship/decision data involved. It does not explain the required structure of each agent entry, the meaning of the enum values, or how to supply the data, leaving the schema to do essentially all parameter-level work.

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

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

The description uses a specific verb and resource: it clearly states that the tool closes a session for participating agents, and it lists the concrete operations involved: counting the session, applying memory decay, and recording relationships and decision outcomes. This makes it distinguishable from siblings like mdan_memory_remember, mdan_memory_forget, and mdan_create_decision_record.

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?

There is no explicit guidance about when to use this tool versus alternatives, such as mdan_memory_remember or mdan_create_decision_record. The phrase 'Close a session' only implies end-of-session usage; it does not state exclusions or recommend 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?

The destructiveHint annotation already signals that this is a destructive operation, and the description does not contradict it. It adds only mild context by specifying that exactly one memory is removed from an agent sidecar, but it does not mention permanence, confirmation, 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.

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

One short sentence that front-loads the operation and contains no filler. It is appropriately concise for a simple deletion tool.

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 is adequate for recognizing the core purpose but not complete enough for confident invocation: the agent parameter is undocumented, no return or error behavior is described, and there is no usage guidance relative to memory siblings. The destructive annotation covers safety but not selection or parameter details.

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 schema documents the id parameter as a memory id from mdan_memory_recall, but the agent parameter has no description. The phrase 'from an agent sidecar' loosely suggests agent ownership, yet the description does not explain how to supply or format the agent value, failing to compensate for the 50% schema coverage 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?

States a clear action and target: 'Delete one memory' from an agent sidecar. The verb 'delete' and resource 'memory' make the operation unambiguous and semantically distinguish it from memory siblings like remember, recall, and list.

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?

No guidance is given about when to use this tool instead of mdan_memory_end_session, mdan_memory_recall, or mdan_memory_remember. The description implies deletion but does not state prerequisites, exclusions, or alternative-avoidance conditions, so selection is left to inference.

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?

The readOnlyHint annotation already declares this as a safe read operation, and the description is consistent with that. It adds the selection criterion of 'memory sidecar' but gives no further behavioral detail such as return format, pagination, or how sidecar presence is determined.

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, front-loaded sentence with no filler: 'List agents that have a memory sidecar.' Every word earns its place.

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

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

For a parameterless, read-only list tool, the description names the output object, and the annotation covers the safety profile. The lack of an output schema leaves the exact return shape unspecified, but 'List agents' is sufficient for a straightforward invocation.

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

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

The tool has zero parameters, so the description has no input semantics to explain. The schema is trivially complete, and naming what the tool lists satisfies the requirement.

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

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

The description uses a specific verb ('List') and names a specific resource ('agents that have a memory sidecar'), making its target clear. It does not explicitly distinguish itself from the likely similar sibling mdan_list_agents, so it stops short of a 5.

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?

No guidance is given about when to use this tool instead of mdan_list_agents or the memory_* family. The phrase 'agents that have a memory sidecar' implies a filtering use case, but alternatives and exclusions are never mentioned.

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?

The description is consistent with the readOnlyHint=true annotation (recall is a read operation), so there is no contradiction. It adds useful behavioral context beyond annotations: results are scoped to previous sessions and ordered by confidence. However, it does not disclose failure modes (e.g., empty results), whether the search is fuzzy or exact, or the response format; with the safety profile already covered by annotations, a mid score is appropriate.

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

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

A single sentence that front-loads the primary outcome (recall) and packs in scope ('from previous sessions') and ordering ('highest confidence first') without waste. Every word earns its place.

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

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

For a 4-parameter retrieval tool with no output schema and a confusingly similar sibling (mdan_memory_list), the description omits important information: how this differs from memory_list, what the type filter values mean, and what the caller receives back. The core calling pattern (agent required, optional filters) is inferable, but the gaps are material for correct tool selection and invocation.

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

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

Schema description coverage is only 25% (only 'query' is described), so the description must compensate. It partially does: 'an agent's memories' clarifies that 'agent' identifies whose memories are retrieved, and 'highest confidence first' explains result ordering. However, the meaning of the 'type' enum (observation, preference, context, decision) is left entirely to inference, and 'limit' behavior is not contextualized.

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 names a specific verb (recall) and resource (an agent's memories from previous sessions), plus a distinguishing ordering trait (highest confidence first). It is clearly a read/retrieval operation, differentiating it from siblings like mdan_memory_remember and mdan_memory_forget, though it does not explicitly differentiate from mdan_memory_list.

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?

No guidance is given on when to use this tool versus the closely related mdan_memory_list, which also retrieves memories, or mdan_consult_agent. There are no stated exclusions, prerequisites, or selection conditions, so an agent must infer appropriateness from the tool name alone.

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 provided, the description carries the full burden of behavioral disclosure. It does reveal one important behavioral trait: 'Identical memories are reinforced, not duplicated', which informs idempotency and deduplication behavior. However, it does not disclose other potential side effects, such as whether existing memories are updated, how confidence affects reinforcement, or any failure modes (e.g., unknown agent). The description adds some value beyond the schema but leaves significant gaps.

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

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

The description is two sentences long and every word contributes. It front-loads the core action and then adds a critical behavioral nuance. There is no fluff or redundancy, making it an exemplar of concise, structured documentation.

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?

Despite being a relatively simple tool with 5 parameters, the description omits essential context: it does not explain when to use this over sibling tools, it does not describe the meaning or constraints of 'tags' or 'content', and it does not clarify the effect of 'confidence' beyond the schema's terse hint. An agent would have to infer or experiment to understand the full contract, which is inadequate for a tool with multiple parameters and no 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?

The schema description coverage is only 40% (only 'agent' and 'confidence' have descriptions). The description compensates partially by listing the allowed memory types, which mirrors the enum for 'type', but it does not explain the meaning of each type, nor does it describe 'tags' or 'content'. Since the schema leaves these parameters underdocumented, the description should have provided more detail; it does not, leaving the agent to guess at the semantics of key parameters.

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

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

The description uses a specific verb ('Store') and a clear resource ('memory in an agent's persistent sidecar'), and enumerates the accepted memory types (observation, preference, project context, decision) which match the schema enum. This clearly distinguishes it from sibling tools like mdan_memory_recall, mdan_memory_forget, and mdan_memory_list, so an agent can immediately understand what this tool does.

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 no explicit guidance on when to use this tool versus alternatives. It does not mention that this is the write operation for persistent memories, nor does it contrast it with mdan_create_decision_record or other storage-like siblings. An agent must infer usage from the verb 'store' and the context of other memory tools, which is insufficient for clear decision-making.

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?

Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds that sessions can be discussion, debate, or consensus, and that debate is linked to a decision record, but it doesn't disclose whether a session is ephemeral, whether it returns a transcript/report, or whether the decision record is actually persisted. The 'start' wording is mildly side-effect-like but not a clear contradiction of the read-only hint.

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?

Single, tightly-wound sentence with a front-loaded verb and a compact mode list. No filler or duplicated schema 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?

All three parameters are covered either by schema or description, and the read-only annotation supplies the safety model. However, there is no output schema and the description never says what a session returns or what 'start' implies in terms of execution, so an agent may not know what to expect after invocation.

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

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

The schema documents topic and agents but leaves the mode enum undocumented; the description compensates by explaining what each mode means ('free discussion', 'structured debate (-> decision record)', 'consensus'). With 67% schema coverage, this is meaningful additional value for the key 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 uses a specific verb ('Start') with a clearly defined resource ('a multi-agent session') and enumerates three session modes, so an agent can tell it apart from more general session or workflow tools. It doesn't explicitly name a sibling, but the multi-agent scoping and mode list make the purpose unmistakable.

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 communicates the general use case—launching a multi-agent discussion, debate, or consensus—but gives no explicit guidance on when to choose it over alternatives such as mdan_consult_agent or mdan_run_workflow, nor any exclusions. Usage must be inferred from the mode list.

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?

The readOnlyHint annotation already signals a safe read operation, and the description stays consistent by saying 'load' and 'return instructions.' It adds useful behavioral context beyond the annotation: the workflow comes with rules, a resume point, existing artifacts, and produces step-by-step instructions.

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 entire description is one well-structured sentence that front-loads the core action and includes the most important behavioral nuance—returning instructions rather than executing them. There is no filler or 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?

For a read-only tool with a constrained enum and a single optional topic, the description tells the agent what gets loaded, what is preserved, and what the tool returns. There is no output schema, but the main return value is described well enough for an agent to select and invoke the tool appropriately.

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 100%, so both name and topic are already documented at the parameter level. The main description does not add extra parameter details, but it does frame that the loaded workflow is associated with a topic; this meets the baseline without exceeding 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 states a clear action—load an MDAN workflow with its rules and progress—and a specific deliverable: return step-by-step execution instructions. It clarifies that this is a preparation tool rather than an execution tool, which distinguishes it from the surrounding workflow and state tools.

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

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

The overall purpose implies when to use it, and the schema's name parameter points to mdan_list_workflows for available workflow names. However, the description itself does not give explicit when-to-use or when-not-to-use guidance, nor does it name alternatives or conditions for choosing a sibling tool.

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 the behavioral disclosure burden. It discloses the write nature and the side-effect that completed artifacts are registered in the context graph. However, it does not explain state transitions, whether 'start' resets existing progress, or whether 'complete' validates artifacts.

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 compact sentence that front-loads the core purpose and then enumerates the lifecycle actions. Every element earns its place, with no filler or repetition.

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

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

For a six-parameter state-update tool with no output schema and no annotations, the description covers the main invocation semantics and the notable graph side-effect. Minor gaps remain, such as allowed action ordering and return behavior, but the core usage is sufficiently 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 67%, so the description must add some meaning beyond schema descriptions. It usefully explains the action enum values and the role of artifacts at completion, but it adds little for step, summary, stepFile, or workflow beyond what the schema already states.

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 identifies the tool as recording workflow progress, with distinct lifecycle actions ('start', 'step', 'complete') and a mention of artifact registration. It does not explicitly contrast with siblings like mdan_run_workflow, so differentiation is implied rather than stated.

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

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

The description gives explicit trigger conditions for each action: start/resume a workflow, step when moving to a step, complete with produced artifacts. It lacks explicit exclusions or named alternatives, but the action-specific usage context is clear enough for selection.

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?

Annotations already declare readOnlyHint=true, covering the safety profile, and the description does not contradict it. The description adds the scope of the status output but discloses no deeper behavioral traits, such as whether the status is live or cached, whether it derives from persisted workflow state, or whether an active workflow is required.

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 front-loaded clause, 'Project status:', followed by a compact enumeration of the five content categories. Every item earns its place and there is no filler or repetition of schema information, though the structure is a noun phrase rather than a complete sentence.

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

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

For a zero-parameter read-only tool with no output schema, the description covers the key output categories an agent needs to judge usefulness. It is slightly thin on whether the status reflects live or cached state and what grounds the 'recommended next step,' but the tool's simplicity keeps these gaps minor.

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

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

The tool has zero parameters and schema coverage is trivially 100%, so there is nothing for the description to compensate for. Baseline 4 applies because parameter semantics are a non-issue; the description correctly spends no space on them.

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 identifies the resource — project status — and enumerates its contents: current workflow and step, completed workflows per phase, artifacts, decisions, and the recommended next step. This clearly distinguishes it from granular siblings like mdan_list_workflows and mdan_list_agents, and it is not a tautology. However, it lacks an explicit action verb like 'get' or 'fetch,' so the operation is implied rather than stated.

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 content list implies the use case — obtain an aggregate project status overview — which separates it in scope from the more specific sibling tools. But there is no explicit when-to-use or when-not-to-use guidance, no alternative tool is named, and no selection conditions are given, so the agent must infer the routing from the content list alone.

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 present, so the description carries the full burden. It does disclose the optional side effect of writing nodes/edges into the context graph, which is valuable behavioral transparency. However, it does not describe what the gate decision means, whether the operation is reversible, or what happens to existing graph data when register is true.

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 compact sentence that front-loads the tool's core purpose and includes only substantive content. It wastes no words and remains readable.

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

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

For a tool with one optional boolean and no output schema, the description adequately names the core deliverable and side-effect option. However, it does not describe the shape of the returned matrix, how coverage is calculated, or what a gate decision looks like, leaving some ambiguity for the agent.

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 100%, and the register parameter is already clearly described in the schema as adding nodes and edges to the context graph. The description's phrase 'optionally writes it into the context graph' reinforces the parameter meaning but adds little 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.

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

The description clearly states the tool's domain and output: a traceability matrix linking requirements (FR/NFR) to stories and tests, plus coverage and gate decision. It uniquely identifies this as a traceability tool, though it lacks an explicit main verb like 'generate' or 'compute', so it falls just short of a 5.

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 reference to coverage and gate decision implies the tool is used when assessing requirements-to-test traceability and release readiness, but there is no explicit guidance on when to use it versus alternatives such as mdan_check or mdan_graph_impact. No exclusions or alternative routing are provided.

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